paradigmxyz/centaur / .agents/skills/harness-development
harness-development
VerifiedAdd, modify, or debug Centaur harness-server backends in crates/harness-server. Use when adding a new harness CLI, changing how Codex, Claude Code, Amp, Pi, Nanocodex, or Hermes output is normalized, or investigating harness streaming, interrupt, resume, model, or reasoning-effort behavior.
Harness Development
Shape of the crate
crates/harness-server is the only layer that translates harness output. It is
built into the sandbox image and is the sandbox's PID 1: api-rs launches
harness-server <subcommand> (harness_server_subcommand in
crates/centaur-session-runtime/src/lib.rs). Don't add harness
output parsing in Python, TypeScript, api-rs, or the ingresses.
- Input: By default (
--mode blocks) stdin carries Centaur blocks NDJSON:user(text or content blocks, with optionalmodel,provider,reasoning, and trace context),attachment.chunk, andinterrupt. Seeparse_blocks_line_with_stateinsrc/server.rs.--mode jsonrpcaccepts Codex App Server requests instead, includingturn/steer. It is used for protocol testing. - Output: stdout carries only Codex App Server V2 notifications
(
thread/started,item/*,turn/completed,error), typed insrc/protocol.rs.crates/harness-server-conformance(its own workspace, so the Codex crates stay out of other lockfiles) round-trips them through the upstreamcodex-app-server-protocoltypes at a pinned revision. Harness stderr may be logged, but nothing else may reach stdout.
Backends:
codex.rs: runscodex app-serverand passes its native protocol through.claude.rs,amp.rs,pi.rs: implementHarnessServer(src/traits.rs) on the shared runner inserver.rs. Each one builds the process command and stdin lines, parses stdout lines into typed events, and normalizes them intoNormalizedEvent.CodexTurnNormalizer(turn.rs) turns those into App Server items.nanocodex.rs,hermes.rs: their own blocks servers (an in-process library and a long-lived JSON-RPC gateway). They also feedCodexTurnNormalizer.
Adding or changing a backend
- Observe the native CLI first. Start from the args in the backend's
command_for_turn(or the vendor docs for a new harness). Feed it hand-written stdin, and save every stdin, stdout, and stderr line to a temp directory. Establish the real contract: startup args, input shape, event types, terminal event, session id and resume, tool-call and tool-result shape, interrupt, model switching, and reasoning controls. - Implement
HarnessServerin one module,src/<harness>.rs. Use typedserdeevent enums. Useserde_json::Valueonly at the parser boundary. Override the trait hooks only when the harness needs them:terminal_assistant_stop_settle,turn_hold,restart_on_model_change,validate_model,reasoning_effort, andstdin_for_reasoning_effort. - Wire it up. Add the subcommand in
src/main.rs, theHarnessKindvariant, and dispatch insrc/server.rs. The binary path should be overridable through an env var (CLAUDE_BIN,AMP_BIN,CENTAUR_PI_BIN) so tests can substitute a fake. Namespace new settings asCENTAUR_<HARNESS>_*. - For a new harness, update the rest of the path.
src/pi.rsand commit8814c7f8are the reference:- api-rs
HarnessType(centaur-session-core), the subcommand mapping, and auth mode / proxy wiring (centaur-api-server/src/args.rs). - Install the CLI and persist its state in
services/sandbox/Dockerfileandentrypoint.sh. - Add the selector in the ingresses (
services/slackbotv2/src/overrides.tsandresponse-context.ts) and in the Console harness list. - Add a page under
docs/pages/extend/and updatedocs/pages/reference/configuration.mdx.
- api-rs
Invariants
- Keep one harness process per thread across turns, and resume it with the
native session id (
--resume,threads continue,--session-id). Never silently start a fresh conversation when the caller expects continuity. - Every turn emits the
userMessageitem started and completed events and ends with exactly oneturn/completedthat includes all of the turn's items. - Complete a turn only at the harness's real terminal boundary: Claude Code's
result, Pi'sagent_settled, or Amp's terminal assistant stop, since Amp may not emitresultwhile stdin is open. Useterminal_assistant_stop_settlerather than ad hoc timers. - Interrupt is cancellation, and it is distinct from steering. Codex sends
turn/interruptto the app server. The shared runner kills the harness process and finishes the turn as interrupted, and the next turn respawns the process and resumes the session. - Reject an unsupported model with a turn error worded "unsupported model". Slack keys on that wording to clear the thread's sticky model.
- Never log or emit credentials. Sandboxes see iron-proxy placeholders. Don't inject real keys in harness-server.
Tests
From the repository root:
cargo fmt -p harness-server --check
cargo clippy --locked -p harness-server --all-targets -- -D warnings
cargo test --locked -p harness-server
- Unit tests in each module: stdin generation, stdout parsing, and event normalization for representative recorded lines.
- Stdio integration tests (
tests/app_server_stdio.rs,tests/pi_stdio.rs): run the realharness-serverbinary against a scripted fake harness that replays recorded native output fromtests/fixtures/<harness>/*.jsonl. Record fixtures from the real CLI and note the CLI version in the test. Assert on the emitted App Server stream: item order, phases,turn/completed, interrupt, resume args, and model switches. - Real-binary tests are
#[ignore]tests that spawn installed harnesses and make network calls. Run them when native behavior is the question:
cargo test -p harness-server \
real_harnesses_basic_steer_and_resume -- --ignored --nocapture
Other real tests in tests/app_server_stdio.rs include
real_claude_code_long_streaming_is_anchored_to_native_cli,
real_amp_long_streaming_is_anchored_to_native_cli, and
real_codex_long_streaming_uses_native_app_server_chunks. Read the
--nocapture output, not just the summary. Look for non-JSON stdout, missing
item/completed, duplicate or stale assistant text, wrong thread or turn ids,
and lost session continuity.
For changes that affect the deployed path, also build the sandbox image and run
a real turn through the local stack. e2e/stack.sh test covers the Slack path
with scripted model providers.
Record any native quirk in the backend module or its tests, not only in the PR description.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |