# kcode-k1-codex-adapter
Version 0.4.1 is a compatibility facade over `kcode-k1-codex-runtime` 0.2.1 and `kcode-k1-codex-shim` 0.2.0. It contains no transport, conversation, shim, or test implementation of its own.
## Public facade
The runtime names `Adapter`, `Turn`, `Config`, `DynamicTool`, `Error`, `ErrorKind`, `Event`, `ToolCall`, and `ToolResult` are direct reexports from `kcode-k1-codex-runtime`.
The shim names `ASYNC_TOOL_ACKNOWLEDGEMENT`, `ToolLaunchFuture`, `ToolCallLauncher`, `BoxCodec`, `ShimItem`, `ShimOutput`, and `Shim` are direct reexports from `kcode-k1-codex-shim`.
Compatibility through this facade is subject to the intentional 0.2.0 Shim stage API: `ToolCallLauncher::launch_stage` receives accumulated assistant text and an ordered vector of call boxes.
## Runtime lifecycle
`Adapter::open` starts one shared long-lived Codex app-server. Cloned adapters multiplex opaque conversation keys over persistent native threads. One key is sequential; distinct keys may progress concurrently.
`Adapter::with_config` derives a handle with a distinct model, reasoning effort, base instructions, or dynamic-tool set while retaining the same app-server process. Derived profiles must preserve the opening adapter's executable and working directory. A conversation key binds to one complete configuration value until its native thread is successfully closed, preventing profile and tool leakage across consumers.
`Turn::try_next_event` returns only an already-buffered event without waiting. `Adapter::close_conversation` is idle-only and idempotent. Dropping a live `Turn` rejects pending calls and interrupts that turn; dropping all adapter handles closes and reaps the process.
## Shim lifecycle
A `Shim` is a sequential per-conversation owner. Externally recorded boxes prefix the next fresh turn and clear only after start acceptance.
On a tool call, the Shim nonblockingly groups only already-buffered consecutive calls, without a timer. One `launch_stage` callback receives text accumulated since the previous wave plus the ordered call boxes. The callback must succeed before any call is acknowledged. Calls arriving only after an acknowledgement form later waves.
Terminal `ShimOutput` contains only assistant text accumulated after the final wave. A callback rejection sends no acknowledgements. Failure after an accepted stage makes the Shim unusable and does not license replay.
## Diagnostics and evidence
`Adapter::diagnostics` returns captured child stderr bytes; errors carry the same channel separately from display text. Transport, runtime, shim, publication, consumer selection, deployment, and live-provider behavior remain distinct lifecycle states.