Codex runner adapter (preview)
What you'll find here
The Codex preview adapter — how to set it up, fixture behavior, smoke
testing, and current limitations. The adapter implements Craik's
shared RunnerAdapter protocol for Codex-compatible workflows and is
intentionally conservative in v0.1.0.
Preview, not live execution.
The adapter turns a compiled prompt into a normalized runner request and returns deterministic fixture results. Live external execution is not part of v0.1.0.
Local setup
Build the prompt first:
craik prompt compile <task-id> --runner codex
Python callers can then create a request and run the adapter:
from craik.runtime.codex_adapter import CodexRunnerAdapter, request_from_compiled_prompt
adapter = CodexRunnerAdapter()
request = request_from_compiled_prompt(compiled_prompt, adapter=adapter)
result = adapter.run(request)
CodexRunnerAdapter.metadata preserves runner identity, adapter
version, mode, fixture status, and live availability inside
craik.runner_metadata.metadata. Those fields are adapter details
and do not expand the core contract surface.
Fixture behavior
Fixture mode is the default preview path. It produces a
craik.runner_adapter_result with:
status
completed · blocked · failed · partial.
outputs.prompt_handoff
The compiled prompt for Codex-compatible execution.
outputs.handoff_input
Normalized fields suitable for a later handoff.
outputs.receipt_inputs
Normalized receipt drafts for granted capabilities.
outputs.runner_metadata
The adapter metadata used for the run.
diagnostics
Live-execution limitations and caller-supplied diagnostics.
Tests can force a deterministic outcome through request context:
request = request_from_compiled_prompt(
compiled_prompt,
context={"fixture_status": "blocked", "blocked_reason": "approval missing"},
)
Smoke test
Use the workflow in
Runner preview workflows to
run completed, blocked, and failed fixture paths. Check
outputs.runner_metadata, outputs.receipt_inputs, and
outputs.handoff_input before promoting any adapter output into
receipts or handoffs.
Limitations
No external Codex invocation.
The preview adapter returns prompt handoff and fixture outputs so Craik can validate policy, metadata, receipts, and handoff wiring before live execution is enabled.
Live execution will need explicit invocation policy, process isolation, receipt finalization, and artifact capture before it should be used for side-effecting work.