scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-10-08 12:47:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
veritas-kanban/docs/CODEX-INTEGRATION.md

6.6 KiB
Raw Permalink Blame History

OpenAI Codex Integration

Veritas Kanban includes local codex exec execution, SDK-backed local Codex sessions, a supervised Codex app-server adapter, GitHub-native Codex Cloud delegation, Codex-backed workflow-engine steps, review actions, Settings health checks, provider adapters, event mapping, and mocked runner coverage.

Companion docs:

Product Scope

Veritas Kanban is a 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

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.

Provider capabilities include:

  • 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.
  • Additional providers can be added without route-level branching.

Telemetry And Logs

Codex JSONL is 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 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.149.0 event contracts.

MCP And Project Instructions

Configure Veritas MCP for Codex with:

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

Use the AGENTS.md Template to teach 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.