# kcode-k1-codex-adapter
Version 0.5.0 is a compatibility facade over `kcode-k1-codex-runtime` 0.3.0 and `kcode-k1-codex-shim` 0.3.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 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.
`Adapter::steer` submits input to an active native turn using that turn's existing profile binding; it does not change the model, effort, instructions, working directory, or tools. It rejects keys without an active turn locally and serializes same-key steering with completion and close.
`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, including any active-turn steering required by K1 work, before acknowledgements are sent. Available results or messages may be supplied separately at a later inference boundary in the continuing turn; they are not limited to a subsequent turn. 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, poisons the Shim, and does not certify whether the accepted wave is replayable.
## 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.