Skip to content

paradigmxyz/centaur / .agents/skills/harness-development

harness-development

Verified

Add, 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.

FileKindSize
SKILL.mdskill md6.6 KB
agents/openai.yamlconfig228 B
---
name: harness-development
description: "Add, 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 optional `model`, `provider`,
  `reasoning`, and trace context), `attachment.chunk`, and `interrupt`. See
  `parse_blocks_line_with_state` in `src/server.rs`. `--mode jsonrpc` accepts
  Codex App Server requests instead, including `turn/steer`. It is used for
  protocol testing.
- **Output:** stdout carries only Codex App Server V2 notifications
  (`thread/started`, `item/*`, `turn/completed`, `error`), typed in
  `src/protocol.rs`. `crates/harness-server-conformance` (its own workspace,
  so the Codex crates stay out of other lockfiles) round-trips them through
  the upstream `codex-app-server-protocol` types at a pinned revision. Harness
  stderr may be logged, but nothing else may reach stdout.

Backends:

- `codex.rs`: runs `codex app-server` and passes its native protocol through.
- `claude.rs`, `amp.rs`, `pi.rs`: implement `HarnessServer` (`src/traits.rs`)
  on the shared runner in `server.rs`. Each one builds the process command and
  stdin lines, parses stdout lines into typed events, and normalizes them into
  `NormalizedEvent`. `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 feed `CodexTurnNormalizer`.

## Adding or changing a backend

1. **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.
2. **Implement `HarnessServer`** in one module, `src/<harness>.rs`. Use typed
   `serde` event enums. Use `serde_json::Value` only 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`, and `stdin_for_reasoning_effort`.
3. **Wire it up.** Add the subcommand in `src/main.rs`, the `HarnessKind`
   variant, and dispatch in `src/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 as `CENTAUR_<HARNESS>_*`.
4. **For a new harness, update the rest of the path.** `src/pi.rs` and commit
   `8814c7f8` are 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/Dockerfile` and
     `entrypoint.sh`.
   - Add the selector in the ingresses (`services/slackbotv2/src/overrides.ts`
     and `response-context.ts`) and in the Console harness list.
   - Add a page under `docs/pages/extend/` and update
     `docs/pages/reference/configuration.mdx`.

## 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 `userMessage` item started and completed events and ends
  with exactly one `turn/completed` that includes all of the turn's items.
- Complete a turn only at the harness's real terminal boundary: Claude Code's
  `result`, Pi's `agent_settled`, or Amp's terminal assistant stop, since Amp may
  not emit `result` while stdin is open. Use `terminal_assistant_stop_settle`
  rather than ad hoc timers.
- Interrupt is cancellation, and it is distinct from steering. Codex sends
  `turn/interrupt` to 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:

```bash
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 real `harness-server` binary against a scripted fake harness that
  replays recorded native output from `tests/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:

```bash
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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall