feat(cli): add codex init templates (sync / async / temporal)

[declan-scale]

Summary

Final slice of #425. Adds the codex agentex init templates across all three tiers.

• New default-codex, sync-codex, temporal-codex template dirs.
• Wires DEFAULT_CODEX, SYNC_CODEX, TEMPORAL_CODEX into init.py (enum, project-files map, prompts). TemplateType is now complete at 19.
• Scaffolded code imports CodexTurn from the agentex.lib.adk facade.

Test plan

• pytest tests/lib/cli/ — 66 passed (all 19 template types render to valid Python)
• full stack reconstructs refactor(harness)!: post-merge cleanup + init templates for the unified harness surface (PR 10) #425 exactly, modulo the intended OpenAI facade-export improvement

Notes

Stacked on #435. Retarget to next after the chain merges.

🤖 Generated with Claude Code

Greptile Summary

This PR completes the Codex CLI harness templates slice by adding default-codex, sync-codex, and temporal-codex scaffolds and wiring them into agentex init. All three tiers share the same CodexTurn + UnifiedEmitter harness pattern used by the sibling claude-code templates.

• All previously flagged issues from the stacked review have been addressed: @openai/codex is installed in every Dockerfile, OPENAI_API_KEY is mapped in every manifest and .env.example, subprocess cleanup uses try/finally with process.kill() + process.wait() in all three acp.py templates, and the temporal workflow serializes concurrent signal handlers with asyncio.Lock().
• The temporal Dockerfile-uv variant is missing ENV PYTHONPATH=/app that is present in the non-uv counterpart and in the default-codex uv variant — a minor inconsistency that is unlikely to cause runtime failures given the current import structure but is worth aligning.

Confidence Score: 5/5

Safe to merge; all blocking issues from previous review rounds have been resolved and the new code follows established harness patterns.

All previously raised issues (subprocess leaks, wrong credential in manifests, missing CLI install, concurrent-turn state forking, undefined notebook variable) are demonstrably fixed in the current diff. The remaining note is a minor inconsistency between two Dockerfile variants that does not affect runtime behaviour.

temporal-codex/Dockerfile-uv.j2 — missing PYTHONPATH alignment with its non-uv sibling.

Important Files Changed

Filename	Overview
src/agentex/lib/cli/commands/init.py	Adds DEFAULT_CODEX, SYNC_CODEX, TEMPORAL_CODEX to TemplateType enum and wires them into the project-files map and interactive prompts — clean, pattern-consistent addition.
src/agentex/lib/cli/templates/default-codex/project/acp.py.j2	Async ACP handler with CodexTurn + UnifiedEmitter; subprocess cleanup correctly guarded by try/finally with process.kill() + process.wait(), multi-turn thread ID persisted via adk.state.
src/agentex/lib/cli/templates/sync-codex/project/acp.py.j2	Sync streaming handler yields events via yield_turn; subprocess cleanup correctly wrapped in try/finally inside the async generator, process killed before wait on any exception or client disconnect.
src/agentex/lib/cli/templates/temporal-codex/project/workflow.py.j2	Temporal workflow with asyncio.Lock() serializing signal handlers to prevent concurrent turns from reading the same stale codex thread ID.
src/agentex/lib/cli/templates/temporal-codex/project/activities.py.j2	Temporal activity running codex subprocess; try/finally guarantees process.kill()+wait() even if auto_send_turn raises.
src/agentex/lib/cli/templates/temporal-codex/Dockerfile-uv.j2	Installs codex CLI via npm and uses dynamic uname -m detection for tctl arch; missing ENV PYTHONPATH=/app present in the non-uv sibling.
src/agentex/lib/cli/templates/temporal-codex/Dockerfile.j2	Installs codex CLI via npm; dynamic tctl architecture detection with uname -m correctly handles amd64/arm64; ENV PYTHONPATH=/app present.
src/agentex/lib/cli/templates/default-codex/manifest.yaml.j2	Credentials correctly map OPENAI_API_KEY matching what codex exec reads.
src/agentex/lib/cli/templates/sync-codex/manifest.yaml.j2	Correctly maps OPENAI_API_KEY; acp_type is sync matching the template purpose.
src/agentex/lib/cli/templates/temporal-codex/manifest.yaml.j2	Temporal workflow config enabled, OPENAI_API_KEY mapped with comment, REDIS_URL included for the async event push path.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant UI
    participant ACP as ACP Server (FastACP)
    participant Handler as on_task_event_send / on_message_send
    participant Codex as codex exec subprocess
    participant Redis
    participant State as adk.state

    UI->>ACP: task/event/send (user message)
    ACP->>Handler: dispatch params
    Handler->>State: get ConversationState (thread_id)
    Handler->>Codex: asyncio.create_subprocess_exec codex exec json
    Handler->>Codex: write prompt to stdin, close stdin
    loop CodexTurn streaming
        Codex-->>Handler: stdout JSON line
        Handler->>Redis: UnifiedEmitter event push
        Redis-->>UI: real-time token stream
    end
    Handler->>Codex: process.kill() + wait() finally
    Handler->>State: update codex_thread_id
    Handler-->>ACP: return / generator exhausted

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant UI
    participant ACP as ACP Server (FastACP)
    participant Handler as on_task_event_send / on_message_send
    participant Codex as codex exec subprocess
    participant Redis
    participant State as adk.state

    UI->>ACP: task/event/send (user message)
    ACP->>Handler: dispatch params
    Handler->>State: get ConversationState (thread_id)
    Handler->>Codex: asyncio.create_subprocess_exec codex exec json
    Handler->>Codex: write prompt to stdin, close stdin
    loop CodexTurn streaming
        Codex-->>Handler: stdout JSON line
        Handler->>Redis: UnifiedEmitter event push
        Redis-->>UI: real-time token stream
    end
    Handler->>Codex: process.kill() + wait() finally
    Handler->>State: update codex_thread_id
    Handler-->>ACP: return / generator exhausted

Loading

Comments Outside Diff (1)

1. src/agentex/lib/cli/templates/default-codex/manifest.yaml.j2, line 599-613 (link)

   LITELLM_API_KEY credential won't satisfy codex exec

   The active credentials entry maps LITELLM_API_KEY into the container, but codex exec reads OPENAI_API_KEY directly from the environment. When a user scaffolds this template and deploys, the Kubernetes secret for litellm-api-key is mounted but OPENAI_API_KEY is never set, so every codex exec invocation will fail with an auth error. The credential name (and the env: entry below it) should reference OPENAI_API_KEY / openai-api-key to match what the CLI actually consumes. The same issue is present in sync-codex/manifest.yaml.j2.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/agentex/lib/cli/templates/default-codex/manifest.yaml.j2
   Line: 599-613
   
   Comment:
   **`LITELLM_API_KEY` credential won't satisfy `codex exec`**
   
   The active credentials entry maps `LITELLM_API_KEY` into the container, but `codex exec` reads `OPENAI_API_KEY` directly from the environment. When a user scaffolds this template and deploys, the Kubernetes secret for `litellm-api-key` is mounted but `OPENAI_API_KEY` is never set, so every `codex exec` invocation will fail with an auth error. The credential name (and the `env:` entry below it) should reference `OPENAI_API_KEY` / `openai-api-key` to match what the CLI actually consumes. The same issue is present in `sync-codex/manifest.yaml.j2`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

_{Reviews (17): Last reviewed commit: "fix(cli): wire OPENAI_API_KEY and serial..." | Re-trigger Greptile}

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[declan-scale]

@greptile review