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.
93 lines
5.7 KiB
Markdown
93 lines
5.7 KiB
Markdown
# 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.
|
||
|
||
- [Codex noninteractive output](https://developers.openai.com/codex/noninteractive)
|
||
- [Codex configuration controls](https://developers.openai.com/codex/config-reference)
|
||
- [Claude programmatic use](https://code.claude.com/docs/en/headless)
|
||
- [Claude CLI flags](https://code.claude.com/docs/en/cli-reference)
|
||
|
||
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.
|