# kcode-k1-codex-shim
This crate provides the per-conversation K1 bridge over `kcode-k1-codex-runtime` 0.1.0. Runtime facade types are reexported, so callers can use `Adapter`, `Error`, `ErrorKind`, `Event`, `ToolCall`, `ToolResult`, and the other runtime API without dependency-internal paths.
## Shim API
- `ASYNC_TOOL_ACKNOWLEDGEMENT` is the exact successful native result sent after K1 accepts a launch.
- `ToolLaunchFuture<'a>` is the boxed asynchronous launch result.
- `ToolCallLauncher<B>::launch` accepts, starts, or queues one canonical call box and returns promptly without waiting for tool completion.
- `BoxCodec` converts a runtime `ToolCall` exactly once and renders externally recorded boxes for native history.
- `ShimItem<B>` is ordered coalesced text or one call box.
- `ShimOutput<B>` is the atomic terminal output of one native turn.
- `Shim<C>` owns one conversation key, codec, launcher, and pending external-box queue.
`Shim::new` preserves the established facade-compatible constructor. `record_box`, `record_boxes`, and `pending_box_count` manage external canonical history. `infer` starts one fresh native turn and consumes it continuously through `Event::Done`. `close_conversation` is additive: while the shim is ready, it closes only the shim's own runtime conversation key; pending external boxes remain queued for a later fresh thread.
Pending external boxes prefix ordinary input in insertion order and are removed only after `Adapter::start_turn` accepts the turn. Generated call boxes are terminal output only and are never queued automatically.
For every runtime `Event::ToolCall`, `infer` converts the call once, awaits the injected launcher, sends the exact successful asynchronous acknowledgement to that call ID, and continues the same turn. Calls and call waves are handled sequentially in provider order with no timer, batch boundary, configured count limit, hidden turn, or current-turn real result.
Text/call interleaving is preserved, adjacent text deltas coalesce, and output is returned only after `Done`. A launcher rejection returns `ErrorKind::LaunchRejected` with runtime diagnostics. Any failure or cancellation after start acceptance makes the shim unusable; a definite start rejection restores readiness. Accepted launches are never retried or rolled back.
Use one shim sequentially for one conversation. Distinct shims may share cloned runtime adapters. Tool execution, scheduling, persistence, retry, and result replay remain outside this crate.