veritas-kanban/docs/CODEX-INTEGRATION.md

OpenAI Codex Integration Roadmap

Release target: Veritas Kanban v4.3

This roadmap tracks the first-class OpenAI Codex integration work for Veritas Kanban. v4.3 now includes local codex exec execution, SDK-backed local Codex sessions, GitHub-native Codex Cloud delegation, Codex-backed workflow-engine steps, Codex review actions, richer Settings health checks, provider adapters, Codex event mapping, and mocked runner coverage.

Companion docs:

• SOP: OpenAI Codex Integration
• Codex Workflow Examples
• Optional Independent Code Review
• AGENTS.md Template

Product Goal

Veritas Kanban should become the local-first command center for Codex-backed software work:

• Start Codex on a Veritas code task from the UI or API.
• Run Codex inside the task worktree with tracked status, logs, outputs, and telemetry.
• Use Codex in workflow-engine agent steps.
• Let Codex use the Veritas MCP server and project instructions.
• Support advanced Codex SDK sessions and optional cloud delegation.
• Preserve Veritas guardrails, task history, attempts, deliverables, and review flows.

Integration Modes

Codex CLI Provider

The first implementation path uses codex exec because it is designed for automation and can emit JSONL events. Veritas launches it inside the task worktree, streams progress into attempt logs, parses usage events, and completes the task from the final Codex result.

Recommended default shape:

codex exec --cwd <task-worktree> --sandbox workspace-write --json <prompt>

When a Codex agent profile or workflow agent has sandboxPresetId, Veritas dry-runs the sandbox policy before launching the CLI process. The resulting filesystem mode, network posture, and environment passthrough are applied where the provider supports them. Required unsupported controls fail closed before execution and write a redacted sandbox-policy governance trace.

Codex SDK Provider

The SDK path supports long-lived local Codex threads, resumable session IDs, and richer follow-up workflows. Veritas starts @openai/codex-sdk threads in the task worktree, streams SDK events into attempt logs, emits token telemetry, and persists the SDK threadId on the active/completed attempt.

Recommended default shape:

const thread = codex.startThread({
  workingDirectory: '<task-worktree>',
  sandboxMode: 'workspace-write',
  approvalPolicy: 'never',
  networkAccessEnabled: true,
});

The SDK provider also honors sandbox policy presets. This is the preferred path for deny-by-default network policies because the SDK capability check supports network disablement, whereas the CLI path is limited to the controls exposed by codex exec.

Codex Cloud Delegation

Cloud delegation starts through GitHub-native workflows: Veritas can create or comment on GitHub issues/PRs with scoped @codex prompts, then sync links and outcomes back into the task. If official cloud APIs become available, they can be added behind the same provider boundary.

API shape:

POST /api/github/codex/delegate

{
  "taskId": "task_...",
  "target": "issue",
  "model": "gpt-5.5"
}

Architecture Direction

Executable task providers resolve through the dedicated AgentProviderAdapterRegistry. The registry owns exact provider selection, task-envelope rendering, runtime probing, run-event mapping, start dispatch, and stop semantics. ClawdbotAgentService supplies shared admission, supervision, journaling, budget, and completion effects without selecting an implicit fallback adapter.

codex agents resolve to the local Codex CLI runner, codex-sdk agents resolve to the SDK session runner, and codex-cloud uses GitHub-native delegation. OpenClaw task dispatch uses the gateway sessions_spawn path and persists the returned session identity on the active attempt.

Expected long-term provider capabilities:

• start
• stop
• status
• stream logs
• complete/fail
• optional resume
• optional review
• optional cloudDelegate

The provider adapter interface supports:

• OpenClaw compatibility through an OpenClaw provider adapter.
• Codex CLI through a local process provider.
• Codex SDK through the implemented thread/session provider.
• Codex Cloud through GitHub issue/PR delegation.
• Future providers without route-level branching.

Telemetry And Logs

Codex JSONL should be normalized into Veritas concepts:

• agent messages
• reasoning and progress updates
• command executions
• file changes
• MCP tool calls
• web searches
• final summaries
• token usage from completed turns when available

Attempt logs should remain readable markdown, while raw JSONL can be retained where it helps debugging.

Workflow Engine

Workflow agent steps execute through provider-aware step handling. Codex-backed steps support:

• fresh sessions
• resumable sessions when using SDK mode
• step output files
• retry and failure handling through the workflow runner
• tool-policy hints in prompt/config where direct enforcement is unavailable
• per-agent sandboxPresetId launch guardrails

Workflow agents can opt into Codex with provider metadata:

agents:
  - id: codex
    name: Codex
    role: implementer
    provider: codex-sdk
    model: gpt-5.5
    description: Codex workflow implementer

Workflow definitions should normally omit command for Codex agents. Command overrides are rejected unless they are codex, match VERITAS_CODEX_EXECUTABLE or CODEX_PATH, or the server is intentionally started with VERITAS_ALLOW_UNSAFE_CODEX_COMMAND_OVERRIDES=1.

Review Actions

Codex review actions run against the task worktree diff in read-only SDK mode and map structured findings into Veritas review comments:

POST /api/diff/<taskId>/codex-review

{
  "model": "gpt-5.5",
  "instructions": "Focus on regressions and missing tests.",
  "save": true
}

Settings Health

Settings exposes Codex readiness through a dedicated health check:

GET /api/settings/codex/health

The response reports Codex CLI install/version/auth state, the installed Codex SDK version and import availability, Codex agent profile readiness, enabled Codex profiles, and recommendations. Veritas Kanban currently validates its stream adapter against @openai/codex-sdk 0.144.1 event contracts.

MCP And Project Instructions

v4.3 makes Veritas MCP setup easy for Codex:

codex mcp add veritas-kanban --env VK_API_URL=http://localhost:3001 -- node /absolute/path/to/veritas-kanban/mcp/dist/index.js

The docs should also provide an AGENTS.md pattern that teaches Codex the Veritas task lifecycle: begin work, update task state, log findings, report deliverables, run checks, summarize completion, and keep the board as source of truth.

v4.3 Issue Track

• #298 - v4.3 Epic: Build first-class OpenAI Codex support
• #299 - Add agent provider abstraction for OpenClaw, Codex CLI, Codex SDK, and future agents
• #300 - Implement local Codex CLI adapter using codex exec JSONL events
• #301 - Add Codex SDK provider for long-lived local threads and richer session control
• #302 - Support Codex Cloud delegation through GitHub issue/PR workflows
• #303 - Build Codex settings UX for profiles, auth checks, sandbox mode, model, and provider mode
• #304 - Map Codex logs, JSONL events, token usage, and artifacts into Veritas telemetry
• #305 - Make Veritas MCP and AGENTS.md setup first-class for Codex
• #306 - Execute workflow engine agent steps through provider adapters including Codex
• #307 - Add Codex review and PR automation workflows
• #308 - Write v4.3 Codex documentation, examples, and release notes
• #309 - Create Codex test harness, mocked runners, E2E coverage, and v4.3 release QA checklist

Documentation Pass

The v4.3 docs should land with the implementation, not after it. Required documentation updates:

• Codex integration roadmap: architecture and release scope.
• Codex SOP: operational playbook for CLI, SDK, Cloud, MCP, telemetry, reviews, and workflow execution.
• Codex examples: copy/pasteable task, review, SDK, Cloud, MCP, and workflow recipes.
• README documentation map.
• FEATURES entry for Codex provider support.
• MCP guide with Codex setup.
• API reference for provider fields and Codex-specific routes.
• CLI guide if a setup/check helper is added.
• AGENTS.md template with Codex-specific lifecycle instructions and MCP commands.
• Release notes with known limitations and QA evidence.

Release Acceptance

v4.3 is done when:

• Codex can complete a Veritas code task from the UI or API through the local CLI provider.
• Codex can run as a workflow-engine agent step.
• Codex logs, final output, and token usage appear in Veritas attempt and telemetry surfaces.
• Codex setup has first-class Settings UX and docs.
• Veritas MCP setup for Codex is documented and smoke-tested.
• CI includes mocked Codex coverage.
• Manual release QA includes one real local Codex task, one Codex review, and one Codex workflow step.