{
  "id": "page:docs-agent-mux-reference-14-harness-mock",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/reference/14-harness-mock.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/reference/14-harness-mock.md",
    "sourceKind": "repo-docs",
    "title": "Harness Mock",
    "displayName": "Harness Mock",
    "slug": "docs/agent-mux/reference/14-harness-mock",
    "articlePath": "wiki/docs/agent-mux/reference/14-harness-mock.md",
    "article": "\n# Harness Mock\n\nCanonical package documentation lives in `packages/agent-mux/harness-mock/README.md`.\nThis page is the repository reference mirror for `@a5c-ai/agent-mux-harness-mock`\nand should stay aligned with that README and the exported surface from\n`packages/agent-mux/harness-mock/src/index.ts`.\n\n## Package Location\n\n- Package path: `packages/agent-mux/harness-mock/`\n- NPM package: `@a5c-ai/agent-mux-harness-mock`\n- CLI binary: `mock-harness`\n\n## CLI\n\n```bash\nmock-harness --list\nmock-harness --agent claude --list\nmock-harness --scenario claude:stream-json\nmock-harness --agent cursor --scenario error\n```\n\n`--agent <name>` scopes `--list` to `<name>:*` scenarios and lets bare\n`--scenario` values resolve within that prefix. For example,\n`mock-harness --agent cursor --scenario error` resolves `cursor:error`.\n\n## What It Exports\n\nThe public entrypoint re-exports these surface areas:\n\n- subprocess simulation and registries from `mock-process`, `scenarios`, and `types`\n- workspace and probe helpers from `workspace` and `probe`\n- bindable transport mocks from `http-mock` and `websocket-mock`\n- SDK/remote mock factories and grouped registries from `mocks/index`\n\nThe current must-know exports are:\n\n- `MockProcess`, `WorkspaceSandbox`\n- `AGENT_SCENARIOS`, `SUBPROCESS_HARNESS_PROFILES`, `SUBPROCESS_SCENARIO_EXPECTATIONS`\n- `resolveScenario`, `listScenarioNames`\n- `HttpServerMock`, `WebSocketServerMock`\n- `createProgrammaticMockBuilder`, `createRemoteMockBuilder`, `createScriptableTransportBuilder`\n- `ClaudeAgentSdkMock`, `CodexSdkMock`, `PiSdkMock`\n- `OpenCodeHttpMock`, `CodexWebSocketMock`\n- `AdapterMockFactory`, `adapterMocks`, `mockScenarios`\n- `probeHarness`, `probeAllHarnesses`, `compareProfiles`, `PROBE_CONFIGS`\n\n## Supported Harnesses And Transports\n\n### Subprocess harness profiles\n\n`SUBPROCESS_HARNESS_PROFILES` currently covers:\n\n- `claude`\n- `codex`\n- `gemini`\n- `copilot`\n- `cursor`\n- `opencode`\n- `pi`\n- `omp`\n- `openclaw`\n- `hermes`\n- `amp`\n- `droid`\n- `qwen`\n\nEach profile maps to canonical scenario names and parser-backed expectations in\n`SUBPROCESS_SCENARIO_EXPECTATIONS`.\n\n### Non-subprocess adapters\n\nThe package also ships public fixtures for these adapter identities:\n\n- SDK/programmatic: `claude-agent-sdk`, `codex-sdk`, `pi-sdk`\n- HTTP transport: `opencode-http`\n- WebSocket transport: `codex-websocket`\n\nExecution shapes documented by the package are `subprocess`, `sdk`, `http`, and\n`websocket`.\n\n## Usage Patterns\n\n### Validate a subprocess parser path\n\n```ts\nimport {\n  AGENT_SCENARIOS,\n  MockProcess,\n  SUBPROCESS_SCENARIO_EXPECTATIONS,\n} from '@a5c-ai/agent-mux-harness-mock';\n\nconst scenario = AGENT_SCENARIOS['opencode:tool-call'];\nconst proc = new MockProcess(scenario);\n\nproc.start();\nconst result = await proc.waitForExit();\n\nconsole.log(result.exitCode);\nconsole.log(SUBPROCESS_SCENARIO_EXPECTATIONS['opencode:tool-call']);\n```\n\n### Build SDK or transport fixtures\n\n```ts\nimport {\n  ClaudeAgentSdkMock,\n  OpenCodeHttpMock,\n  adapterMocks,\n  createProgrammaticMockBuilder,\n  createRemoteMockBuilder,\n} from '@a5c-ai/agent-mux-harness-mock';\n\nconst presetSdk = ClaudeAgentSdkMock.basicSuccess();\nconst presetRemote = OpenCodeHttpMock.basicSuccess();\n\nconst customSdk = createProgrammaticMockBuilder()\n  .name('custom-sdk')\n  .addTextStream('hello')\n  .build();\n\nconst customRemote = createRemoteMockBuilder()\n  .name('custom-remote')\n  .addEvents([{ type: 'text_delta', data: { delta: 'hello' }, delayMs: 5 }])\n  .build();\n\nvoid presetSdk;\nvoid presetRemote;\nvoid customSdk;\nvoid customRemote;\nvoid adapterMocks;\n```\n\n### Bind a real local transport\n\nUse `HttpServerMock`, `WebSocketServerMock`, or the higher-level `MockServer`\nwhen a client under test needs to connect over the network rather than consume\nan in-process event emitter.\n\n## Limitations\n\n- `MockProcess` replays scripted output in-process. It does not execute a real harness binary.\n- `HttpServerMock`, `WebSocketServerMock`, and `MockServer` bind local ports and are heavier than pure fixture replay.\n- Probe helpers such as `probeHarness` and `probeAllHarnesses` execute real harness binaries and are intended for drift checks, not hermetic unit tests.\n- The package documents the current exported surface from `packages/agent-mux/harness-mock/`; older v1-era source-path references are obsolete.\n\n## Probe Coverage\n\nThe built-in `PROBE_CONFIGS` now cover the subprocess harness matrix:\n\n- `claude-code`\n- `codex`\n- `gemini`\n- `copilot`\n- `cursor`\n- `opencode`\n- `pi`\n- `omp`\n- `openclaw`\n- `hermes`\n- `amp`\n- `droid`\n- `qwen`\n\nThey also cover the SDK/programmatic targets as fixture-backed contract probes:\n\n- `claude-agent-sdk`\n- `codex-sdk`\n- `pi-sdk`\n\nThey also cover the transport-oriented targets:\n\n- `codex-websocket`\n- `opencode-http`\n\nEach `HarnessBehaviorProfile` now carries:\n\n- `executionType`\n- `outputFormat` and `outputFormatTraits`\n- `supportsStdin` and `stdinSignals`\n- per-scenario `exitCodes`\n- `environmentVariables`, `fileOperationPatterns`, and `cliPatterns`\n- `availability` and `probeNotes`\n\nChecked-in offline baseline contracts live at\n`packages/agent-mux/harness-mock/tests/fixtures/probes/baseline-profiles.json`.\n\nCI vs local/manual:\n\n- CI-safe: fixture coverage checks, contract-shape validation, the node-based\n  offline probe tests in `packages/agent-mux/harness-mock/tests/probe-offline.test.ts`,\n  and the offline-only SDK contract profiles for `claude-agent-sdk`,\n  `codex-sdk`, and `pi-sdk`\n- Local/manual: authenticated vendor CLI probes and transport startup probes for\n  binaries that are not expected to exist in CI\n- Offline-only: SDK entries materialize reviewed contract profiles without\n  executing a harness binary, so drift review happens through the checked-in\n  fixture rather than a live probe run\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-mux-reference",
      "to": "page:docs-agent-mux-reference-14-harness-mock",
      "kind": "contains_page"
    }
  ]
}