Adapters

An adapter is the contract between Codencer and a coding executor. The adapter knows how to dispatch a step's work to the executor, how to catch the executor's output, and how to surface artifacts back to the run record. Codencer ships several executor adapters in the v0.2.0-beta tag, with conformance tests verifying each one against a known fixture set.

The adapter contract

Every adapter must:

1. Accept a normalized step input. Goal, workspace path, validators, environment. The adapter does not see the full task spec — only the per-step slice.
2. Invoke the executor. Spawn the executor binary, attach stdio, pass the goal. Each adapter knows its own executor's invocation conventions.
3. Capture artifacts. Diff, test output, logs. The adapter copies them to the run's artifact directory.
4. Return a normalized status. Completed, failed, aborted. The state machine reads this; nothing else.
5. Pass conformance tests. Every adapter has a test suite that runs the same canonical step against a known fixture and verifies the artifacts and status match expectations.

The contract is narrow on purpose. Adapters cannot mutate the run record. Adapters cannot bypass validators. Adapters cannot run validations themselves — that is the validation runner's job.

Local adapter proof levels at v0.2.0-beta

| Surface | Current repo proof | Local beta truth | | --- | --- | --- | | Local daemon + CLI + simulation lifecycle | direct smoke + repo tests | canonical | | codex adapter | simulation smoke + conformance + fake-binary codex exec proof | primary intended local beta adapter; live authenticated Codex service calls remain operator-environment proof | | claude adapter | wrapper, prompt, normalize, and fake-binary tests | supported-beta target with narrow wrapper claims only | | qwen adapter | conformance / simulation only | secondary | | antigravity / antigravity-broker | mocked integration and environment-specific proof | secondary | | openclaw-acpx | unit and simulation-only proof | experimental / deferred | | ide-chat | code/manual handoff only | experimental / deferred |

Claude is executed in headless print mode as claude -p --output-format json. Codencer writes the built prompt to prompt.txt, sends it on stdin, and runs the process from the attempt workspace root.

Adapter conformance tests

Each adapter has a conformance test under internal/adapter/<name>/. The tests verify:

• The adapter accepts the canonical step input shape
• The adapter invokes the executor with the right arguments
• The adapter copies artifacts to the expected paths
• The adapter returns the expected status for known-good and known-bad fixtures
• The adapter does not bypass worktree isolation

Conformance tests run in CI on macOS, Windows (where supported), and WSL/Linux. A new adapter cannot land without passing them.

How to add a new adapter

If the executor you want isn't on the list, the path is:

1. Read internal/adapter/codex/ as the canonical reference. It is the most mature adapter and the cleanest example of the contract.
2. Copy the directory structure to internal/adapter/<your-executor>/.
3. Implement the four required interface methods: dispatch, capture, status, conformance.
4. Write the conformance test against your executor's known fixtures.
5. Register the adapter in cmd/orchestratord/main.go so the daemon dispatches to it when the task spec specifies its name.
6. Run make build and the conformance suite. Both green = adapter ships.

The adapter API is intentionally simple. Most contributors land their first adapter in a single PR.

What's deferred

NOTE — friction: Adapter-specific features — streaming chain-of-thought, tool-use trace, vendor-specific extensions — are exposed as artifacts where they exist, but Codencer does not normalize them across adapters. The state model captures what every adapter must capture; vendor-specific extras live in the artifact directory and are queryable but not promoted to first-class entities.

NOTE — experimental: The openclaw-acpx adapter ships at v0.2.0-beta as experimental support via the standardized ACP bridge. Use for evaluation; do not depend on it for production work.

For the deep adapter API reference, see the repo's docs/06_adapters_and_ide.md.