agent-tempo 1.0.1

package/dist/adapters/claude-code-headless/pre-flight.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeClaudeBinary = probeClaudeBinary;
+exports.probeClaudeAuth = probeClaudeAuth;
+exports.parseAuthStatusOutput = parseAuthStatusOutput;
+/**
+ * Pre-flight probes for the claude-code-headless adapter.
+ *
+ * Two checks, both invoked from `src/tools/recruit.ts` before submitting the
+ * spawn outbox entry; both also re-used by the daemon boot probe (PR-2) so
+ * cross-host recruit can fail fast against an unconfigured host.
+ *
+ *   1. **Binary probe** — `claude --version` exits 0 within 3s. Catches the
+ *      "Claude Code not installed" case with an actionable error, distinct
+ *      from "logged out" (#2 below).
+ *   2. **Auth probe** — `claude auth status` exits 0 within 5s and emits a
+ *      JSON envelope with `loggedIn: true`. Confirms the host's Claude Code
+ *      CLI has a usable OAuth session — which is the whole point of this
+ *      adapter (subscription extra-usage credits, design §1).
+ *
+ * Both probes are pure observers — they make NO billed API call and NO
+ * subprocess that registers as an ensemble player. The auth probe is an
+ * official `claude auth` subcommand; the version probe is a one-line
+ * `--version` invocation.
+ *
+ * Spike findings (issue #520 §11.3, captured 2026-05-02): `claude auth
+ * status` outputs JSON in all logged-in states; exit code is 0 even when
+ * logged out, so the boolean `loggedIn` field is the source of truth.
+ *
+ * Design reference: `docs/design/520-claude-code-headless-adapter.md`
+ *   §3.4 (recruit pre-flight contract)
+ *   §11.3 (auth-status parser fixtures)
+ */
+const child_process_1 = require("child_process");
+const VERSION_PROBE_TIMEOUT_MS = 3_000;
+const AUTH_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Probe whether `claude --version` is callable on the host PATH and returns
+ * a parseable version string. Bounded by {@link VERSION_PROBE_TIMEOUT_MS} so
+ * a hung binary can't stall the recruit pre-flight.
+ *
+ * Returns `{ ok: false, error }` for missing binary, hung process, or
+ * non-zero exit. The error string is operator-actionable (mentions both
+ * "install" and "PATH" so the user knows where to start).
+ */
+function probeClaudeBinary(claudeBin = 'claude') {
+    let result;
+    try {
+        result = (0, child_process_1.spawnSync)(claudeBin, ['--version'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: VERSION_PROBE_TIMEOUT_MS,
+            // shell: false on Windows — npm-installed `claude` is a `.cmd` shim;
+            // spawnSync's `shell: false` path won't find it. Workaround: call via
+            // `cmd.exe /c` on Windows so the shim resolves.
+            shell: false,
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `\`${claudeBin} --version\` failed to spawn: ${err?.message ?? err}. Install Claude Code (https://claude.com/download) and ensure \`${claudeBin}\` is on PATH.`,
+        };
+    }
+    if (result.error && result.error.code === 'ENOENT') {
+        // Try Windows `.cmd` fallback — npm-installed CLI binaries land as `.cmd`
+        // shims that bare spawnSync without shell can't resolve.
+        if (process.platform === 'win32' && claudeBin === 'claude') {
+            const winResult = (0, child_process_1.spawnSync)('cmd.exe', ['/c', 'claude', '--version'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                timeout: VERSION_PROBE_TIMEOUT_MS,
+            });
+            if (winResult.status === 0) {
+                const version = (winResult.stdout?.toString('utf8') ?? '').trim();
+                return { ok: true, version: parseVersion(version) };
+            }
+        }
+        return {
+            ok: false,
+            error: `\`${claudeBin}\` not found on PATH. Install Claude Code (https://claude.com/download) and verify \`which ${claudeBin}\` resolves.`,
+        };
+    }
+    // spawnSync sets `signal: 'SIGTERM'` on timeout; status is null in that case.
+    if (result.signal === 'SIGTERM' || (result.status === null && result.signal !== null)) {
+        return {
+            ok: false,
+            error: `\`${claudeBin} --version\` timed out after ${VERSION_PROBE_TIMEOUT_MS}ms. The binary may be hung or stuck on a first-run prompt; try \`${claudeBin} --version\` interactively first.`,
+        };
+    }
+    if (result.status !== 0) {
+        const stderr = (result.stderr?.toString('utf8') ?? '').trim().slice(0, 200);
+        return {
+            ok: false,
+            error: `\`${claudeBin} --version\` exited ${result.status}${stderr ? `: ${stderr}` : ''}.`,
+        };
+    }
+    const version = parseVersion((result.stdout?.toString('utf8') ?? '').trim());
+    return { ok: true, version };
+}
+/**
+ * Probe whether the host's Claude Code CLI is logged in to an Anthropic
+ * account. Calls `claude auth status` — an official supported subcommand
+ * that does NOT make a billed API call.
+ *
+ * Per spike findings (#520 §11.3), exit code is 0 in all cases — the
+ * boolean `loggedIn` field in the JSON envelope is the source of truth.
+ *
+ * Returns `{ loggedIn: false, error }` for: not-logged-in, malformed JSON,
+ * timeout, or spawn failure. Caller surfaces `error` actionably.
+ */
+function probeClaudeAuth(claudeBin = 'claude') {
+    let result;
+    try {
+        result = (0, child_process_1.spawnSync)(claudeBin, ['auth', 'status'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: AUTH_PROBE_TIMEOUT_MS,
+            shell: false,
+        });
+    }
+    catch (err) {
+        return {
+            loggedIn: false,
+            error: `\`${claudeBin} auth status\` failed to spawn: ${err?.message ?? err}.`,
+        };
+    }
+    // Windows .cmd shim fallback (mirrors probeClaudeBinary). Per QA Nit 2 from
+    // PR-1's review: explicitly check whether the cmd.exe fallback also failed,
+    // so the error copy stays "not found on PATH" instead of degrading to the
+    // generic "produced no output" the parser would otherwise emit on empty stdout.
+    if (result.error && result.error.code === 'ENOENT') {
+        if (process.platform === 'win32' && claudeBin === 'claude') {
+            result = (0, child_process_1.spawnSync)('cmd.exe', ['/c', 'claude', 'auth', 'status'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                timeout: AUTH_PROBE_TIMEOUT_MS,
+            });
+            if (result.status !== 0 && (!result.stdout || result.stdout.length === 0)) {
+                const stderr = (result.stderr?.toString('utf8') ?? '').trim().slice(0, 200);
+                return {
+                    loggedIn: false,
+                    error: `\`${claudeBin}\` not found on PATH (cmd.exe shim also failed: ${stderr || `exit ${result.status}`}).`,
+                };
+            }
+        }
+        else {
+            return { loggedIn: false, error: `\`${claudeBin}\` not found on PATH.` };
+        }
+    }
+    if (result.signal === 'SIGTERM' || (result.status === null && result.signal !== null)) {
+        return {
+            loggedIn: false,
+            error: `\`${claudeBin} auth status\` timed out after ${AUTH_PROBE_TIMEOUT_MS}ms.`,
+        };
+    }
+    const stdout = (result.stdout?.toString('utf8') ?? '').trim();
+    return parseAuthStatusOutput(stdout, result.status, claudeBin);
+}
+/**
+ * Parse a `claude auth status` stdout envelope. Exported for unit tests
+ * that load fixtures from `tests/adapters/fixtures/claude-code-headless/`.
+ *
+ * Per spike findings, the schema is JSON `{loggedIn, authMethod?, apiProvider?, ...}`.
+ * Logged-out variant is `{loggedIn: false}`. We tolerate trailing whitespace
+ * and missing optional fields.
+ */
+function parseAuthStatusOutput(stdout, exitStatus, claudeBin = 'claude') {
+    if (!stdout) {
+        return {
+            loggedIn: false,
+            error: `\`${claudeBin} auth status\` produced no output (exit=${exitStatus}).`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (err) {
+        return {
+            loggedIn: false,
+            error: `Failed to parse \`${claudeBin} auth status\` JSON output: ${err?.message ?? err}. First 200 bytes: ${stdout.slice(0, 200)}`,
+        };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            loggedIn: false,
+            error: `\`${claudeBin} auth status\` returned non-object JSON: ${stdout.slice(0, 200)}`,
+        };
+    }
+    const obj = parsed;
+    const loggedIn = obj.loggedIn === true;
+    const authMethod = typeof obj.authMethod === 'string' ? obj.authMethod : undefined;
+    const apiProvider = typeof obj.apiProvider === 'string' ? obj.apiProvider : undefined;
+    if (!loggedIn) {
+        return {
+            loggedIn: false,
+            error: `\`${claudeBin}\` is installed but not logged in. Run \`${claudeBin} auth login\` (subscription) or \`${claudeBin} auth setup-token\` (CI/long-lived OAuth), or recruit with \`agent: 'claude-api'\` to use a Console API key instead.`,
+        };
+    }
+    return { loggedIn: true, authMethod, apiProvider };
+}
+/**
+ * Parse the version string from `claude --version` stdout. The CLI prints
+ * `"2.1.126 (Claude Code)"` — we keep just the dotted-number prefix so
+ * downstream comparators work cleanly.
+ */
+function parseVersion(raw) {
+    const m = raw.match(/^(\d+\.\d+\.\d+(?:[-+][0-9a-zA-Z.]+)?)/);
+    return m ? m[1] : raw || undefined;
+}

package/dist/adapters/claude-code-headless/prompt.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure prompt-building helpers for the claude-code-headless adapter.
+ *
+ * Issue #536 root cause: `invokeSdkWithBatch` in `adapter.ts` was
+ * inlining both the per-message attribution prompt AND the per-turn
+ * argv composition, with no `--append-system-prompt` and no
+ * MAESTRO_ACK augmentation. The model received only
+ * `[from X]: <text>` framing, no MCP-tool guidance, and replied with
+ * stdout prose that the adapter captured but had nowhere to deliver
+ * — so cues from the dashboard saw zero cue-back replies.
+ *
+ * This module factors the two prompt-build steps out of the adapter
+ * for two reasons:
+ *
+ *   1. **Testability.** Both helpers are pure — no Temporal client,
+ *      no subprocess, no filesystem. The test in
+ *      `tests/adapters/claude-code-headless/prompt.test.ts` exercises
+ *      every `--append-system-prompt` invariant + every MAESTRO_ACK
+ *      conditional shape directly, instead of having to stub a
+ *      whole subprocess + spawn pipeline.
+ *
+ *   2. **Read-locality.** The `invokeSdkWithBatch` body in
+ *      `adapter.ts` was already 80+ lines of mixed concerns
+ *      (subprocess spawn, env hygiene, stream-json read loop,
+ *      cleanup). Extracting the string composition keeps the per-
+ *      turn driver focused on the I/O side.
+ */
+import type { Message } from '../../types';
+import { buildSdkSystemPrompt } from '../sdk/system-prompt';
+import type { ClaudeCodeHeadlessPermissionMode } from './types';
+/**
+ * Compose the per-turn prompt text from the workflow's queued
+ * messages. Mirrors copilot's poll-loop pattern at
+ * `src/adapters/copilot/adapter.ts:639-645` — same conditional
+ * MAESTRO_ACK augmentation per `m.isMaestro`, same `\n\n` join.
+ *
+ * The attribution prefix is `[from X]:` (matches the pre-#536
+ * shape in `invokeSdkWithBatch`); copilot's `[Message from X]:` is
+ * stylistic drift from a different vintage but is left unchanged
+ * here since #536 is scoped to the cue-back framing fix, not a
+ * cross-adapter prompt-styling unification.
+ *
+ * @returns Empty string when `messages` is empty (no `\n\n` floor).
+ */
+export declare function buildPromptText(messages: Message[]): string;
+export interface BuildClaudeArgsOpts {
+    /** Deterministic session UUID — pinned via `--session-id` on first
+     * turn, found via `--resume` on subsequent turns. */
+    sessionId: string;
+    /** True when the per-cwd JSONL session file already exists.
+     * Toggles `--resume <id>` vs `--session-id <id>` (mutually
+     * exclusive in `claude -p` v2.1.126+). */
+    isResume: boolean;
+    /** Already-stringified inline `--mcp-config` JSON. The adapter
+     * computes this from `getConfig()` at call time; the helper just
+     * threads the bytes. */
+    mcpConfig: string;
+    /** Resolved permission mode (default `'acceptEdits'`). Ignored
+     * when `dangerouslySkipPermissions` is true — they're mutually
+     * exclusive per #520 and rejected at recruit-tool layer. */
+    permissionMode: ClaudeCodeHeadlessPermissionMode;
+    /** When true, emit `--dangerously-skip-permissions` and skip
+     * `--permission-mode`. */
+    dangerouslySkipPermissions: boolean;
+    /** Per-turn system-prompt content. Pass the result of
+     * `buildSdkSystemPrompt({ ensemble })` for the canonical #536
+     * framing. */
+    systemPrompt: string;
+    /** Final positional argument — the prompt text the model receives
+     * for this turn. Pass the result of `buildPromptText(messages)`. */
+    promptText: string;
+}
+/**
+ * Compose the `claude -p` argv for a single turn. Pure function so
+ * tests can pin every flag invariant without mocking `spawn`.
+ *
+ * #536 change: emits `--append-system-prompt <systemPrompt>` to
+ * inject the canonical "use your MCP tools to reply" framing into
+ * the model's per-request system prompt. The flag is in the request
+ * itself, so it dodges the MCP-startup race the priming-turn pattern
+ * would otherwise mitigate (per the issue body's "MCP startup race —
+ * secondary" footnote).
+ *
+ * Invariant ordering (kept stable so transcripts and CI snapshots
+ * compare cleanly across releases):
+ *   `-p` → `--output-format` → `--verbose` → `--strict-mcp-config`
+ *   → `--mcp-config` → `--append-system-prompt`
+ *   → (`--resume` | `--session-id`)
+ *   → (`--dangerously-skip-permissions` | `--permission-mode`)
+ *   → `<promptText>`
+ */
+export declare function buildClaudeArgs(opts: BuildClaudeArgsOpts): string[];
+export { buildSdkSystemPrompt };

package/dist/adapters/claude-code-headless/prompt.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSdkSystemPrompt = void 0;
+exports.buildPromptText = buildPromptText;
+exports.buildClaudeArgs = buildClaudeArgs;
+const system_prompt_1 = require("../sdk/system-prompt");
+Object.defineProperty(exports, "buildSdkSystemPrompt", { enumerable: true, get: function () { return system_prompt_1.buildSdkSystemPrompt; } });
+/**
+ * Compose the per-turn prompt text from the workflow's queued
+ * messages. Mirrors copilot's poll-loop pattern at
+ * `src/adapters/copilot/adapter.ts:639-645` — same conditional
+ * MAESTRO_ACK augmentation per `m.isMaestro`, same `\n\n` join.
+ *
+ * The attribution prefix is `[from X]:` (matches the pre-#536
+ * shape in `invokeSdkWithBatch`); copilot's `[Message from X]:` is
+ * stylistic drift from a different vintage but is left unchanged
+ * here since #536 is scoped to the cue-back framing fix, not a
+ * cross-adapter prompt-styling unification.
+ *
+ * @returns Empty string when `messages` is empty (no `\n\n` floor).
+ */
+function buildPromptText(messages) {
+    return messages
+        .map((m) => {
+        const line = `[from ${m.from}]: ${m.text}`;
+        return m.isMaestro ? line + system_prompt_1.MAESTRO_ACK : line;
+    })
+        .join('\n\n');
+}
+/**
+ * Compose the `claude -p` argv for a single turn. Pure function so
+ * tests can pin every flag invariant without mocking `spawn`.
+ *
+ * #536 change: emits `--append-system-prompt <systemPrompt>` to
+ * inject the canonical "use your MCP tools to reply" framing into
+ * the model's per-request system prompt. The flag is in the request
+ * itself, so it dodges the MCP-startup race the priming-turn pattern
+ * would otherwise mitigate (per the issue body's "MCP startup race —
+ * secondary" footnote).
+ *
+ * Invariant ordering (kept stable so transcripts and CI snapshots
+ * compare cleanly across releases):
+ *   `-p` → `--output-format` → `--verbose` → `--strict-mcp-config`
+ *   → `--mcp-config` → `--append-system-prompt`
+ *   → (`--resume` | `--session-id`)
+ *   → (`--dangerously-skip-permissions` | `--permission-mode`)
+ *   → `<promptText>`
+ */
+function buildClaudeArgs(opts) {
+    return [
+        '-p',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--strict-mcp-config',
+        '--mcp-config', opts.mcpConfig,
+        // #536 — per-turn system-prompt injection. Without this, the
+        // model received only `[from X]: <text>` framing and had no
+        // reason to call the `cue` MCP tool to reply.
+        '--append-system-prompt', opts.systemPrompt,
+        // Mutually exclusive — `claude -p` v2.1.126 rejects the combo
+        // `--session-id X --resume X` with: *"--session-id can only be
+        // used with --continue or --resume if --fork-session is also
+        // specified."* Spike-confirmed during PR-4 §8.4 manual smoke;
+        // see #520 design doc §16.9. First turn uses `--session-id`
+        // to PIN the deterministic UUID; subsequent turns use `--resume`
+        // alone (the resume target IS the same UUID — the JSONL
+        // filename embeds it, so claude finds the right session).
+        ...(opts.isResume
+            ? ['--resume', opts.sessionId]
+            : ['--session-id', opts.sessionId]),
+        ...(opts.dangerouslySkipPermissions
+            ? ['--dangerously-skip-permissions']
+            : ['--permission-mode', opts.permissionMode]),
+        // Trailing positional argument — the prompt text. The CLI accepts
+        // up to ARG_MAX bytes here (Windows: 32KB). Per #520 §11.5 spike
+        // check, typical multi-cue batches stay well under the limit.
+        opts.promptText,
+    ];
+}

package/dist/adapters/claude-code-headless/stream-json.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Stream-JSON frame parser for `claude -p --output-format stream-json`.
+ *
+ * Issue #520 PR-3. Parses the newline-delimited JSON envelope the Claude
+ * Code CLI emits during a per-turn invocation, accumulating the bits the
+ * adapter needs (assembled assistant text, stop reason, usage, cost, plus
+ * the fatal-/transient-classifier inputs).
+ *
+ * **Schema is grounded in the §11.1 spike fixtures** captured against
+ * `claude --version` 2.1.126 — see `tests/adapters/fixtures/claude-code-headless/`.
+ * Three deltas vs design §5.3 (documented in §16 spike-findings appendix):
+ *
+ *   1. **`result` frame has a `subtype: 'success' | 'error'`** — design listed
+ *      `result` as a top-level type. Reality: `subtype` distinguishes success
+ *      vs error envelopes. Bonus: `is_error: boolean` + `api_error_status:
+ *      number | null` are clean classifier inputs (see {@link ResultFrame}).
+ *   2. **`system/hook_started` + `system/hook_response` + `system/status`** —
+ *      not in design. Emitted whenever the host has Claude Code hooks
+ *      configured (most operators do — SessionStart hooks for project
+ *      context). The `output`/`stdout` fields can carry arbitrary user
+ *      content, so we IGNORE them outright (the fixture corpus shows a
+ *      107KB SessionStart hook body in real captures).
+ *   3. **`rate_limit_event` is a top-level type** — design assumed it was
+ *      a `system/api_retry` subtype. Reality: it's its own frame. AND it
+ *      carries TWO signal modes (informational vs action-required) on the
+ *      same wire shape, distinguished by `rate_limit_info.status`. See
+ *      {@link RateLimitEvent}.
+ *
+ * Pure code; no I/O; trivially unit-testable with synthesized + captured
+ * fixtures. The error classifier (`./error-mapper.ts`) consumes the
+ * accumulator state to emit a single `ApiErrorCategory` per turn.
+ */
+/**
+ * Permissive frame shape — `claude -p` may add fields between minor versions.
+ * Every concrete frame type is a discriminated subset.
+ */
+export interface BaseFrame {
+    type: string;
+    subtype?: string;
+    uuid?: string;
+    session_id?: string;
+}
+/** First frame of every turn. Used for telemetry — not classifier input. */
+export interface SystemInitFrame extends BaseFrame {
+    type: 'system';
+    subtype: 'init';
+    /** `'none'` when running on OAuth (subscription billing — the v0.28 default). */
+    apiKeySource?: string;
+    cwd?: string;
+    model?: string;
+    permissionMode?: string;
+    claude_code_version?: string;
+    tools?: string[];
+    mcp_servers?: unknown[];
+    /** Non-empty array indicates a config error — log loudly. */
+    plugin_errors?: unknown[];
+}
+/** Hook lifecycle frames. Adapter IGNORES these — see Delta #2 above. */
+export interface SystemHookFrame extends BaseFrame {
+    type: 'system';
+    subtype: 'hook_started' | 'hook_response';
+    hook_name?: string;
+    hook_event?: string;
+    /** May contain arbitrary user content (operator's hook output). Ignored. */
+    output?: string;
+    stdout?: string;
+    stderr?: string;
+    exit_code?: number;
+    outcome?: string;
+}
+/** Bare status heartbeat. Ignored. */
+export interface SystemStatusFrame extends BaseFrame {
+    type: 'system';
+    subtype: 'status';
+    status?: string;
+}
+/** Documented retry signal. May or may not actually fire on v2.x — see Delta #3. */
+export interface SystemApiRetryFrame extends BaseFrame {
+    type: 'system';
+    subtype: 'api_retry';
+    attempt?: number;
+    max_retries?: number;
+    retry_delay_ms?: number;
+    error_status?: number;
+    /** Documented enum: `authentication_failed` | `oauth_org_not_allowed` | `billing_error` | `rate_limit` | `invalid_request` | `server_error` | `unknown` | `max_output_tokens`. */
+    error?: string;
+}
+/** Top-level rate-limit informational AND action-required signal — Delta #3. */
+export interface RateLimitEvent extends BaseFrame {
+    type: 'rate_limit_event';
+    rate_limit_info?: {
+        /** `'allowed'` (informational, every turn) | `'blocked'` (action-required). */
+        status?: string;
+        rateLimitType?: string;
+        resetsAt?: number;
+        /** `'allowed'` | `'blocked'`. When BOTH this AND `status` are blocked → fatal (subscription + extra-usage exhausted). */
+        overageStatus?: string;
+        overageResetsAt?: number;
+        isUsingOverage?: boolean;
+    };
+}
+/** Mid-turn assistant message. Content array may include text / thinking / tool_use blocks. */
+export interface AssistantFrame extends BaseFrame {
+    type: 'assistant';
+    message?: {
+        role?: 'assistant';
+        content?: Array<{
+            type?: 'text' | 'thinking' | 'tool_use' | string;
+            text?: string;
+            id?: string;
+            name?: string;
+            input?: unknown;
+        }>;
+        stop_reason?: string | null;
+        usage?: Record<string, unknown>;
+    };
+    parent_tool_use_id?: string | null;
+}
+/** Tool result wrapped as user turn — telemetry only. */
+export interface UserFrame extends BaseFrame {
+    type: 'user';
+    message?: {
+        role?: 'user';
+        content?: Array<{
+            type?: 'tool_result' | string;
+            tool_use_id?: string;
+            content?: unknown;
+        }>;
+    };
+    tool_use_result?: unknown;
+}
+/** Token-delta frame. Only emitted with `--include-partial-messages`. v1 ignores. */
+export interface StreamEventFrame extends BaseFrame {
+    type: 'stream_event';
+    event?: unknown;
+    ttft_ms?: number;
+}
+/** Closing frame of every turn. Authoritative source for assembled text + usage + cost. */
+export interface ResultFrame extends BaseFrame {
+    type: 'result';
+    /** `'success'` | `'error'` (and possibly more). Discriminates envelope shape. */
+    subtype?: string;
+    /** Clean fatal-vs-success boolean — primary classifier input per architect. */
+    is_error?: boolean;
+    /** HTTP status code on API errors. Reuse claude-api's HTTP-code classifier. */
+    api_error_status?: number | null;
+    /** Assembled assistant text — the canonical reply the adapter returns. */
+    result?: string;
+    /** `'end_turn'` | `'max_tokens'` | `'stop_sequence'` | … */
+    stop_reason?: string;
+    duration_ms?: number;
+    duration_api_ms?: number;
+    num_turns?: number;
+    /** Equivalent API cost (NOT real subscription burn). */
+    total_cost_usd?: number;
+    usage?: Record<string, unknown>;
+    modelUsage?: Record<string, unknown>;
+    permission_denials?: unknown[];
+    /** `'completed'` | `'aborted'` | … */
+    terminal_reason?: string;
+}
+/**
+ * Discriminated union of everything we recognize. The parser tolerates
+ * unknown `type` strings by passing them through as `BaseFrame`.
+ */
+export type StreamJsonFrame = SystemInitFrame | SystemHookFrame | SystemStatusFrame | SystemApiRetryFrame | RateLimitEvent | AssistantFrame | UserFrame | StreamEventFrame | ResultFrame | BaseFrame;
+/**
+ * Per-turn accumulator. The parser folds each frame into this state; the
+ * adapter reads it after the subprocess exits to assemble the SDK return
+ * value AND to feed the error classifier.
+ */
+export interface TurnAccumulator {
+    /** Canonical assembled assistant text — set from `result.result` (preferred) or assistant-frame text fallback. */
+    assembledText: string;
+    /** `result.stop_reason`. */
+    stopReason: string | null;
+    /** `result.usage` — opaque token accounting. */
+    usage: Record<string, unknown> | null;
+    /** `result.total_cost_usd` — equivalent API cost (NOT real subscription burn). */
+    totalCostUsd: number | null;
+    /** `result.is_error` — primary classifier input. */
+    resultIsError: boolean | null;
+    /** `result.api_error_status` — HTTP code when is_error=true. */
+    resultApiErrorStatus: number | null;
+    /** `result.subtype` — `'success'` | `'error'` | … */
+    resultSubtype: string | null;
+    /** Did we see a `result` frame at all? `false` means subprocess exited before completing the turn. */
+    resultFrameSeen: boolean;
+    /** `system/api_retry` events observed on stdout — fed into the classifier. */
+    apiRetryEvents: SystemApiRetryFrame[];
+    /** `rate_limit_event` frames observed — separated by status for the classifier. */
+    rateLimitEvents: RateLimitEvent[];
+    /** Plugin-config errors from `system/init` — non-empty means config bug. */
+    pluginErrors: unknown[];
+    /** Model id from `system/init`, e.g. `'claude-opus-4-7[1m]'`. Telemetry only. */
+    initModel: string | null;
+    /** `apiKeySource` from `system/init` — `'none'` confirms OAuth subscription billing. */
+    initApiKeySource: string | null;
+}
+/** Build a fresh accumulator. */
+export declare function newTurnAccumulator(): TurnAccumulator;
+/**
+ * Fold one stream-json frame into the accumulator. Pure mutation — return
+ * the same instance for chaining.
+ *
+ * Unknown frame types are silently passed through (the parser is tolerant
+ * by design — Claude Code may add new frame types between minor versions
+ * and we don't want to crash on them; the adapter only ever acts on the
+ * categories we recognize).
+ *
+ * The hook + status frames are explicitly enumerated as IGNORED rather
+ * than falling through `default`, so future readers don't think the
+ * pass-through is accidental.
+ */
+export declare function applyFrame(state: TurnAccumulator, frame: StreamJsonFrame): TurnAccumulator;
+/**
+ * Stateful line-buffered stream-json reader. Feed it raw stdout chunks;
+ * call `flush()` after subprocess exit to emit any trailing partial line.
+ *
+ * Exposed as a class so the adapter can wire it to the `claude -p`
+ * subprocess's `stdout.on('data', ...)` event without needing a
+ * Transform stream subclass — keeps the dep surface minimal.
+ *
+ * Malformed JSON lines are skipped with a logged warning (defensive —
+ * shouldn't happen in practice but a single bad line shouldn't crash
+ * the turn).
+ */
+export declare class StreamJsonReader {
+    private buffer;
+    private state;
+    private readonly onParseError?;
+    constructor(opts?: {
+        onParseError?: (line: string, err: Error) => void;
+    });
+    /** Feed a chunk of stdout. Triggers `applyFrame` for every complete line. */
+    feed(chunk: Buffer | string): void;
+    /** Process any trailing line that didn't end with a newline. Idempotent. */
+    flush(): void;
+    /** Snapshot of the current accumulator. Caller may freely mutate. */
+    snapshot(): TurnAccumulator;
+    private parseLine;
+}