Files
ai-engineering/docs/cli-adapters.md
T
Nilton Constantino bd2c9133da feat: add agent coordination and automatic work completion
Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation.

Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence.

Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
2026-11-14 01:12:21 +00:00

5.7 KiB
Raw Blame History

Local CLI adapter contract

PLN-0003 implements the transport/capability choices recorded in WRK-0001/SVY-0001: Codex and Claude local CLIs, for Discussion and synthesis returning proposals. DEC-0002 supplies the accepted routing/portable-context direction. Source repository editing, command execution, direct provider APIs and arbitrary CLI arguments are outside this slice. The AIE binary itself still requires neither JVM nor Node. Using an optional adapter requires that provider's CLI and its own authentication.

Invocation boundary

Adapters launch a fixed argument vector with ProcessBuilder, never a shell. Each invocation has a private temporary working directory containing only schema/output files; task and immutable portable context arrive through stdin. AIE does not give the provider an engineering root, source repository working directory or mutation service. Claude built-in tools are disabled. Codex command/agent/app/hook features are disabled and it runs in read-only sandbox mode with approval escalation off. No bypass-permissions flag is used. Provider/OS policies remain authoritative; these controls are not a claim that AIE is an OS sandbox.

Codex uses exec, ephemeral mode, ignored user config, disabled shell/agent/hooks/apps features, JSON Schema and a bounded final-message file. Claude uses print mode, structured JSON, no tools, restricted/safe mode, empty settings/MCP sources, no session persistence and no permission prompts. Authentication remains in the provider's private environment/store; credentials/config files are not copied into canonical AIE files. Only essential process/auth/proxy environment values are passed, and none are persisted. Raw provider stderr is not printed or recorded as evidence.

Each executor retains adapter/profile/model plus an optional timeout (default 120s, bounded 1–600s). Missing settings in old records preserve old behavior. default model omits the native model flag. Profile is an AIE role instruction, carried in the prompt; vendor configuration profiles are not loaded in this proposal-only slice. This keeps project profiles portable and prevents profiles from widening tools or permissions. Configured model/profile are distinct from an unreported actual model.

Stdout, stderr, final output and stdin have explicit byte limits. Streams drain concurrently; timeout/overflow interrupts the process and descendants, and temporary files are cleaned. Missing executables, unsupported flags, auth/exit failure, timeout, invalid UTF-8/JSON/schema, wrong identities and invalid references produce diagnostics. Transport failures happen before canonical publication and leave the Work unchanged. There is no silent retry or switch to another executor after a failure.

Structured data and provenance

Wire records are versioned JSON with explicit schemas. AIE, not the model, assigns adapter identity and fixture=false. Classification returns an activity from the configured/common set; clarify directs general to produce a survey when ambiguous. An explicit --activity skips the classification call. All state/conformance/EPIC checks continue in framework code. No provider response can approve a DEC, answer a human survey, complete a Work, create a Plan or execute repository commands.

Proposals use the existing typed topic/survey/entry/disposition/draft-DEC bundle and undergo complete preflight before domain services apply them. Input context is data, including any quoted instructions/evidence. References retain their Work ownership. Summaries retain source IDs and distinguish assumptions from recorded evidence.

Optional RUN provenance records classification/proposal transport, observed CLI version, configured model/profile, timeout, duration and output digest/size. It records no environment values, credentials or raw stderr. Old RUN files remain readable without rewriting. Pre-publication failures are diagnosed at the caller; they do not create a misleading successful RUN. Existing failed application markers remain valid.

CLI and acceptance

  • agent list exposes both real adapters and fixtures without contacting a model.
  • agent doctor [--adapter codex-cli|claude-cli] probes local version/help only.
  • agent configure --adapter codex-cli --profile general --model default --timeout 120
  • agent configure --activity analyze --adapter claude-cli --profile reviewer
  • agent run WRK --activity summarize --task TEXT uses the normal persisted contract.
  • init [DIRECTORY] --interactive [--input-file FILE] guides project/executor setup; noninteractive init remains usable with --name and optional --general-adapter.

Automated acceptance uses deterministic Java subprocess fixtures through the same process runner, with no provider installation, credentials, service or LLM needed. Cover argument isolation, wire parsing, classification, ownership, failure/timeout/ overflow cleanup, no mutation on invalid output, versioned persistence, guided setup, fresh processes, Modulith and standalone native execution. Actual provider trials are separate, bounded and reported as verified/failed/unavailable rather than faked.

Compatibility sources

Checked local help: codex-cli 0.169.0; Claude Code 2.1.311. Runtime doctor verifies the controls required by this implementation instead of assuming every version works.

Local CLI help is also authoritative for installed flags. Managed provider settings can be more restrictive. Explicit provider failure is preserved instead of silently weakening permission/configuration controls.