orizu 0.5.20 → 0.5.21

package/dist/hosted-git-http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-git-http-server.d.ts","sourceRoot":"","sources":["../src/hosted-git-http-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmCH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,aAAa,CAM9E;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxE;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,CAyE3G"}

package/dist/hosted-harness-claude.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Claude-Agent-SDK driver for the AgentHarness seam (ALI-929 / P3.6, per ADR-005
+ * §4a — the swappability proof).
+ *
+ * This is the SECOND `AgentHarness` implementation behind the same seam as the
+ * OpenCode driver (`hosted-harness-opencode.ts`). It drives
+ * `@anthropic-ai/claude-agent-sdk`'s `query()` loop — an IN-PROCESS agent loop,
+ * with NO server process to spawn and no localhost SSE to parse — and normalizes
+ * the SDK's message/tool stream into the SAME `HarnessEvent` vocabulary the
+ * event bridge (`hosted-run-event-sink.ts`) already consumes. It carries ZERO
+ * Claude-Agent-SDK types across the seam: everything below stays behind
+ * `createClaudeAgentHarness`, exactly as the OpenCode SSE schema stays behind
+ * `createOpenCodeHarness`.
+ *
+ * The founder's locked escape-hatch ("OpenInspect, but we can move to our own
+ * harness whenever we want") is proven by this module existing and passing the
+ * SAME session-cell invariants through the SAME sink — see
+ * `test/cli/hosted-harness-swap.test.ts`.
+ *
+ * INJECTABLE LOADER: like the Daytona/Vercel SDK adapters, the SDK is imported
+ * LAZILY through a NON-LITERAL specifier so the CLI/app build resolve without the
+ * package, and a `loadModule` dep is injectable so tests exercise the
+ * normalization against a fake `query()` with no real SDK and no model calls.
+ *
+ * ── query() → runPrompt() mapping ────────────────────────────────────────────
+ * ONE `query()` call drives ONE `runPrompt()` to completion. The SDK's async
+ * iterable yields `SDKMessage`s; we translate them:
+ *   • system/init            → capture session_id; emit `ready` once.
+ *   • assistant.message      → text blocks → `token` (keyed by the SDK message id
+ *                              for coalescing); tool_use blocks → `tool_call`. The
+ *                              per-turn `message.usage` the SDK ALWAYS populates is
+ *                              deliberately NOT emitted as a `step_finish` (see
+ *                              leak #3): the driver coalesces to ONE terminal
+ *                              step_finish so both harnesses share one granularity.
+ *   • user.message           → tool_result blocks → `tool_result` (paired to the
+ *                              tool_use by callId, exactly once).
+ *   • stream_event (partial) → text deltas are accumulated into the running token
+ *                              snapshot for coalescing; consumed, not 1:1 mapped.
+ *   • result/success         → final `step_finish` with cost+tokens, then
+ *                              `execution_complete` (success, or aborted on stop).
+ *   • result/error_*         → `error` (critical terminal).
+ * The stream ALWAYS ends with exactly one terminal event.
+ *
+ * ── WHAT LEAKS THROUGH THE BOUNDARY (map-conservatively evidence) ─────────────
+ * These SDK signals have NO clean `HarnessEvent` kind and are DROPPED here (not a
+ * reason to widen the seam — this is the audit of the boundary's fit):
+ *   1. `thinking` / `redacted_thinking` content blocks — the harness vocabulary
+ *      has no reasoning kind (OpenCode's driver drops reasoning too), so extended
+ *      thinking is not forwarded. Cost of surfacing it: a new `thinking` kind on
+ *      the seam + a bridge mapping — a deliberate future decision, not done here.
+ *   2. `system/compact_boundary` — context-compaction markers are dropped (the
+ *      OpenCode driver handles `session.compacted` internally and forwards
+ *      nothing either; parity, not a leak).
+ *   3. Per-assistant-turn USAGE granularity — the real contract is that every
+ *      `SDKAssistantMessage.message` is a `BetaMessage` whose `usage: BetaUsage`
+ *      is ALWAYS populated (input/output token counts are non-optional), so the
+ *      SDK reports usage on EACH assistant turn, not only at the terminal. The
+ *      driver deliberately DOES NOT emit a `step_finish` per assistant turn: it
+ *      coalesces to exactly ONE terminal `step_finish` at the `result` message,
+ *      carrying `total_cost_usd` + aggregate `usage`. OpenCode emits one
+ *      `step_finish` per `step-finish` part; for a one-tool task that is also a
+ *      single terminal step, so the two streams are legitimately identical at the
+ *      seam. This coalescing is itself a swappability win — the seam absorbs the
+ *      raw per-turn/per-step granularity difference so downstream sees one
+ *      normalized `agent_step_finish` from either harness. (Cost is only known at
+ *      the terminal `result`; per-turn `usage` carries tokens but no cost, which
+ *      is why folding to the terminal loses nothing the seam surfaces.)
+ *   4. `result.num_turns` / `duration_ms` / `permission_denials` — folded into
+ *      the terminal transition's shape (success/aborted/error), not surfaced as
+ *      distinct events.
+ *   5. Git author identity is plumbed via `GIT_AUTHOR_*` / `GIT_COMMITTER_*`
+ *      ENV on the query options (the SDK has no first-class author param), where
+ *      OpenCode takes it structurally. Same effect, different plumbing point.
+ *      NOTE the `env` CONTRACT: the SDK's `env` REPLACES the subprocess
+ *      environment entirely (it is NOT merged with `process.env`), so we spread
+ *      `...process.env` FIRST — without it the `claude` subprocess would lose
+ *      `PATH`/`HOME`/`ANTHROPIC_API_KEY` and die. G3 credential model: like the
+ *      OpenCode path (which hands `opencode` the non-secret dummy key), the SDK
+ *      client is given the same `anthropicDummyKey` as `ANTHROPIC_API_KEY`; the
+ *      real key is injected by the sandbox firewall on egress to
+ *      api.anthropic.com, so NO raw key ever enters the in-process client. See
+ *      the G3/credentials axis in ali-929-harness-comparison.md.
+ *   6. The resumable agent session id is assigned LAZILY by the SDK at
+ *      `system/init` — it does not exist before the first `runPrompt`. So
+ *      `start()` returns the RESUME id if given, else `''`; the real id first
+ *      reaches the bridge via the `ready` event. OpenCode creates its session
+ *      eagerly in `start()`. This is the one place the seam's "start returns the
+ *      session id" shape fits OpenCode better than the SDK — the run still
+ *      completes identically (the sink records the id from `ready`); see the
+ *      comparison doc's swappability verdict.
+ *   7. Provider-qualified model strings (e.g. `anthropic/claude-opus-4-8`) are
+ *      reduced to the bare model id the SDK expects (leading `anthropic/` is
+ *      stripped; other providers pass through unchanged and would be the SDK's to
+ *      reject).
+ */
+import type { AgentHarness } from './hosted-harness.js';
+/** An Anthropic content block as it appears inside an SDK assistant/user message
+ *  (`message.content`). Kept structural — we read only the fields we map. */
+interface SdkContentBlock {
+    type: string;
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+interface SdkAnthropicMessage {
+    id?: string;
+    role?: string;
+    content?: SdkContentBlock[] | string;
+    usage?: Record<string, unknown>;
+}
+/** A raw Anthropic streaming event, forwarded by the SDK when partial messages
+ *  are enabled (`type: 'stream_event'`). We read only the text-delta path. */
+interface SdkStreamRawEvent {
+    type?: string;
+    index?: number;
+    delta?: {
+        type?: string;
+        text?: string;
+    };
+    content_block?: {
+        type?: string;
+    };
+    message?: {
+        id?: string;
+    };
+}
+/** The SDK message union. Discriminated on `type` (+ `subtype` for system). */
+interface SdkMessage {
+    type: string;
+    subtype?: string;
+    session_id?: string;
+    message?: SdkAnthropicMessage;
+    event?: SdkStreamRawEvent;
+    is_error?: boolean;
+    total_cost_usd?: number;
+    usage?: Record<string, unknown>;
+    result?: string;
+}
+interface SdkMcpServerConfig {
+    type: string;
+    command?: string;
+    args?: readonly string[];
+    url?: string;
+    env?: Record<string, string>;
+}
+interface SdkQueryOptions {
+    model?: string;
+    cwd?: string;
+    resume?: string;
+    abortController?: AbortController;
+    permissionMode?: string;
+    /** REQUIRED by the SDK whenever `permissionMode: 'bypassPermissions'` — a
+     *  safety measure to make the bypass intentional. Verified against
+     *  @anthropic-ai/claude-agent-sdk@0.3.201 Options.allowDangerouslySkipPermissions. */
+    allowDangerouslySkipPermissions?: boolean;
+    includePartialMessages?: boolean;
+    mcpServers?: Record<string, SdkMcpServerConfig>;
+    /** The SDK's `env` REPLACES the subprocess environment entirely (it is NOT
+     *  merged with `process.env`). Matches the real contract's
+     *  `{ [k: string]: string | undefined }` so `...process.env` spreads cleanly. */
+    env?: Record<string, string | undefined>;
+}
+/** The object `query()` returns: an async iterable of messages plus `interrupt`. */
+interface SdkQueryResult extends AsyncIterable<SdkMessage> {
+    interrupt?: () => Promise<void>;
+}
+export interface ClaudeAgentSdkModule {
+    query: (args: {
+        prompt: string;
+        options: SdkQueryOptions;
+    }) => SdkQueryResult;
+}
+export interface ClaudeAgentHarnessOptions {
+    /** Test seam: inject a fake SDK so normalization runs with no real query/model. */
+    loadModule?: () => Promise<ClaudeAgentSdkModule>;
+    /** Permission posture; default 'bypassPermissions' (the sandbox is the boundary,
+     *  mirroring the OpenCode driver's allow-all config). */
+    permissionMode?: string;
+    /**
+     * Non-secret placeholder key handed to the in-process SDK client as
+     * `ANTHROPIC_API_KEY` (G3). The sandbox firewall swaps in the real key on
+     * egress to api.anthropic.com, so no raw key enters the client — the SAME
+     * brokering the OpenCode path relies on. Threaded from the loop boot context;
+     * never a real key. When absent, `ANTHROPIC_API_KEY` is inherited from
+     * `process.env` as-is (still expected to be the dummy in the sandbox).
+     */
+    anthropicDummyKey?: string;
+}
+export declare function createClaudeAgentHarness(options?: ClaudeAgentHarnessOptions): AgentHarness;
+export {};
+//# sourceMappingURL=hosted-harness-claude.d.ts.map

package/dist/hosted-harness-claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-harness-claude.d.ts","sourceRoot":"","sources":["../src/hosted-harness-claude.ts"],"names":[],"mappings":"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"}

package/dist/hosted-harness-opencode.d.ts

@@ -0,0 +1,227 @@
+/**
+ * OpenCode driver for the AgentHarness seam (ALI-926 / P3.4, per ADR-005 §4a).
+ *
+ * The `opencode` implementation of `AgentHarness`. Drives a long-running
+ * `opencode serve` process over localhost HTTP/SSE, exactly as OpenInspect's
+ * `bridge.py` does — this module is a DESIGN port of `bridge.py`'s
+ * `_stream_opencode_response_sse` + `_transform_part_to_event` into idiomatic
+ * TypeScript. The WebSocket half of `bridge.py` is NOT ported: the transport is
+ * the RunAPI event bridge (`hosted-run-event-sink.ts`), not a Durable Object.
+ *
+ * DRIVING PROTOCOL (all localhost):
+ *   - POST /session                          → create an OpenCode session
+ *   - GET  /session/{id}                     → validate a resumed session
+ *   - GET  /event                            → SSE stream of message parts
+ *   - POST /session/{id}/prompt_async        → enqueue a prompt (non-blocking)
+ *   - GET  /session/{id}/message             → final-state reconciliation
+ *   - POST /session/{id}/abort               → stop the in-flight prompt
+ *
+ * The stream is opened BEFORE the prompt is POSTed (mirrors bridge.py) so no
+ * early parts are missed. Termination is driven by `session.idle` /
+ * `session.status{idle}` (→ `execution_complete`) or `session.error` (→
+ * `error`). Sub-task / child-session fan-out is intentionally NOT ported —
+ * ADR-005 keeps the RunAPI single-writer-per-run, so `spawn-task` is out of P3.
+ *
+ * TESTABILITY: the driver takes a `baseUrl` (localhost:port) and an injectable
+ * `fetchImpl`, so it runs against a fake in-process OpenCode SSE server with no
+ * real `opencode` binary. `spawnOpenCode` (below) is the P3.5 in-sandbox launch
+ * helper; the driver itself never spawns a process.
+ *
+ * ── Deliberate deltas from bridge.py (kept in ONE place) ─────────────────────
+ * This driver is a faithful port EXCEPT for these consciously-chosen
+ * differences — read them before diffing behavior against `bridge.py`:
+ *   • Sub-task / child-session fan-out is OUT OF SCOPE. bridge.py tracks
+ *     `tracked_child_session_ids`, authorizes child assistant messages, and
+ *     emits `isSubtask` events; ADR-005 keeps the RunAPI single-writer-per-run,
+ *     so `task`-tool child sessions are neither tracked nor forwarded here.
+ *   • Compaction IS NOW PORTED (P2-1). `session.compacted` sets a
+ *     `compactionOccurred` flag; thereafter assistant messages whose parentID
+ *     no longer matches the user message are accepted (except the compaction
+ *     summary itself), in both the live stream and `fetchFinalState` — mirrors
+ *     bridge.py lines ~1300-1307 / 1153-1160 / 1421-1425.
+ *   • Max prompt duration IS NOW PORTED (P3-1). `PROMPT_MAX_DURATION`
+ *     (default 5400s, injectable) runs ALONGSIDE the SSE inactivity deadline;
+ *     on breach the prompt is aborted and a terminal `error` is emitted.
+ *   • SSE framing assumes LF `\n\n` event separators and `data:` lines, exactly
+ *     as OpenCode 1.14.41 emits them (bridge.py `_parse_sse_stream` makes the
+ *     same assumption — it splits on `"\n\n"`, never CRLF). This is pinned to
+ *     `OPENCODE_PINNED_VERSION`; a bump that switches OpenCode to CRLF framing
+ *     would break both ports and must be re-verified.
+ */
+import type { AgentHarness } from './hosted-harness.js';
+export declare const OPENCODE_PINNED_VERSION = "1.14.41";
+export declare const DEFAULT_PROMPT_MAX_DURATION_MS = 5400000;
+export type HarnessFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export interface OpenCodeHarnessOptions {
+    /** Base URL of the local `opencode serve`, e.g. "http://localhost:4096". */
+    baseUrl: string;
+    fetchImpl?: HarnessFetch;
+    /** Inactivity ceiling on the SSE stream (ms); reset on every chunk. */
+    sseInactivityMs?: number;
+    /** Timeout for the discrete (non-streaming) OpenCode requests (ms). */
+    requestTimeoutMs?: number;
+    /** Wall-clock ceiling on a single prompt (ms); breach aborts + errors out. */
+    promptMaxDurationMs?: number;
+    now?: () => number;
+}
+/** Distinct terminal reason emitted when a prompt breaches PROMPT_MAX_DURATION,
+ *  so the bridge/tests can tell a duration abort from a model error. */
+export declare const PROMPT_MAX_DURATION_ERROR = "prompt exceeded max duration";
+/**
+ * Split a possibly provider-qualified model string into provider + model id.
+ * SINGLE-SLASH ids ("anthropic/claude-opus-4-8") are the assumed form; a bare
+ * id defaults to provider "anthropic". This is THE shared parse — consumed by
+ * BOTH the prompt path (`buildPromptRequestBody`) and the pre-prompt
+ * validation (`awaitOpenCodeModelResolvable`), so the two can never drift:
+ * parity is exactly what makes the validation meaningful (ALI-1086).
+ * KNOWN LIMIT: `split('/', 2)` drops everything after the second slash, so a
+ * 3-part id ("openrouter/anthropic/claude-x") misparses to provider
+ * "openrouter" + model "anthropic" — identically in both places (today's
+ * pre-existing prompt-path behavior, now shared rather than duplicated).
+ */
+export declare function qualifyHostedModel(model: string): {
+    providerId: string;
+    modelId: string;
+};
+export declare function buildPromptRequestBody(content: string, model: string | undefined, opencodeMessageId: string, reasoningEffort: string | undefined): Record<string, unknown>;
+export declare function createOpenCodeHarness(options: OpenCodeHarnessOptions): AgentHarness;
+/** provider id → model ids the RUNNING opencode instance can resolve. */
+export type OpenCodeModelCatalog = ReadonlyMap<string, readonly string[]>;
+/**
+ * Read the resolvable catalog from a running `opencode serve` via
+ * `GET /config/providers` (shape: `{ providers: [{ id, models: { <id>: … } }] }`,
+ * verified against opencode-ai@1.14.41). Returns null on ANY transport/shape
+ * failure — the caller treats that as "cannot validate", never as "invalid".
+ */
+export declare function fetchOpenCodeModelCatalog(baseUrl: string, fetchImpl?: HarnessFetch, timeoutMs?: number): Promise<OpenCodeModelCatalog | null>;
+/** Rank candidate model ids by similarity to the requested id (longest shared
+ *  prefix first, ties broken lexicographically DESCENDING so the newest of a
+ *  versioned family leads) and cap the list — the fail-fast error should lead
+ *  with the closest/newest substitutes, not a full catalog dump. */
+export declare function rankModelAlternatives(requested: string, candidates: readonly string[], limit?: number): string[];
+export type ModelValidationOutcome = {
+    kind: 'resolvable';
+    waitedMs: number;
+} | {
+    kind: 'unresolvable';
+    /** Provider-qualified requested model, e.g. "anthropic/claude-opus-4-8". */
+    requested: string;
+    /** Provider-qualified resolvable substitutes, closest first. */
+    alternatives: string[];
+    /** False when the PROVIDER itself is unknown to the runtime. */
+    providerKnown: boolean;
+    waitedMs: number;
+} | {
+    kind: 'skipped';
+    reason: string;
+};
+export interface AwaitModelResolvableOptions {
+    /** Base URL of the running `opencode serve`. */
+    baseUrl: string;
+    /** Requested model, provider-qualified or bare (bare → "anthropic"). */
+    model: string;
+    fetchImpl?: HarnessFetch;
+    /**
+     * Total budget to wait for the model to become resolvable. OpenCode's
+     * models.dev refresh runs in the BACKGROUND at boot, so the catalog can be
+     * bundled-only for the first seconds after the server answers HTTP; polling
+     * bridges that window instead of failing a run the refresh would have fixed.
+     */
+    timeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Decide whether the requested model is resolvable by the RUNNING opencode,
+ * polling briefly so the boot-time models.dev refresh has time to land.
+ * Fail-open on validator infrastructure, with a DELIBERATE asymmetry on null
+ * catalog reads:
+ *   - null BEFORE any successful read → `skipped` immediately (dead/absent
+ *     endpoint; opencode's own `session.error` remains the backstop, and the
+ *     early exit keeps absent-endpoint runs — and tests — cheap);
+ *   - null AFTER at least one successful read → a transient boot-window blip
+ *     (5xx/drop): sleep and keep polling within the budget; a budget that
+ *     ends in that state returns `skipped`, NEVER a false `unresolvable` off
+ *     a flaky read.
+ * Only a HEALTHY catalog that never lists the model within the budget yields
+ * `unresolvable`, with ranked, provider-qualified alternatives.
+ */
+export declare function awaitOpenCodeModelResolvable(opts: AwaitModelResolvableOptions): Promise<ModelValidationOutcome>;
+export interface OpenCodeConfigOptions {
+    /** Provider-qualified model string, e.g. "anthropic/claude-opus-4-8". */
+    model: string;
+    /** OpenCode permission map; defaults to allow-all EXCEPT the headless-denied
+     *  tools below (sandbox is the boundary for everything else). */
+    permission?: Record<string, unknown>;
+}
+/**
+ * Tools DENIED in a hosted headless run (ALI-1037). OpenCode exposes a `question`
+ * permission key (docs/permissions) that gates the interactive "ask the user a
+ * question" tool. In an unattended sandbox there is no human to answer it, and
+ * OpenCode's only external reply endpoint — `POST /session/{id}/permissions/{permID}`
+ * — takes a BOOLEAN allow/deny, so it cannot select one of the tool's multiple
+ * options anyway. Denying the tool makes the model's ask fail fast (surfaced back
+ * to it as a tool error) so it proceeds autonomously per the standing preamble
+ * (HOSTED_TASK_PREAMBLE), instead of blocking the run forever. This is the
+ * documented fallback path in ALI-1037 (answer-externally is not cleanly possible).
+ */
+export declare const HEADLESS_DENIED_TOOLS: readonly ["question"];
+/** The default headless permission map: allow everything, deny the interactive
+ *  question tool (see HEADLESS_DENIED_TOOLS). */
+export declare function defaultHeadlessPermission(): Record<string, unknown>;
+/**
+ * Build the `OPENCODE_CONFIG_CONTENT` payload OpenCode reads at boot (mirrors
+ * OpenInspect's `start_opencode`). Kept pure so the launch command and the
+ * config are independently testable.
+ */
+export declare function buildOpenCodeConfigContent(opts: OpenCodeConfigOptions): string;
+export interface SpawnOpenCodeOptions extends OpenCodeConfigOptions {
+    port?: number;
+    /** Directory OpenCode runs in (the cloned workspace). */
+    cwd?: string;
+    /** Extra env merged over the config-content injection. */
+    env?: Record<string, string>;
+    /** Injectable spawner (defaults to Bun.spawn) so this stays unit-testable. */
+    spawn?: (cmd: string[], opts: {
+        cwd?: string;
+        env: Record<string, string>;
+        logPath?: string;
+    }) => {
+        kill: () => void;
+    };
+    /** File the spawner should append opencode's stdout/stderr to. On readiness
+     *  timeout its tail is included in the thrown error — the bare "fetch failed"
+     *  this replaces was undiagnosable (ALI-1034). */
+    logPath?: string;
+    /** Overall readiness budget. OpenCode's FIRST boot runs a one-time sqlite
+     *  migration ("may take a few minutes") before it listens, so this must
+     *  comfortably cover a cold snapshot. */
+    readyTimeoutMs?: number;
+    /** Poll interval while waiting for the server to answer. */
+    readyPollMs?: number;
+    /** Abort (e.g. run cancelled) while still waiting for readiness. */
+    signal?: AbortSignal;
+    /** Injectable readiness probe (defaults to global fetch) for tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface SpawnedOpenCode {
+    baseUrl: string;
+    port: number;
+    stop: () => void;
+    /** How long the server took to answer its first request (set by the real
+     *  spawnOpenCode; injected test spawners may omit it). */
+    readyAfterMs?: number;
+}
+/**
+ * Launch `opencode serve` locally and WAIT until it answers HTTP. OpenCode's
+ * first boot performs a one-time sqlite migration before it listens; returning
+ * the baseUrl without waiting raced the harness's first `POST /session` into a
+ * connection-refused "fetch failed" (ALI-1034, found live in QA-3). Any HTTP
+ * status counts as ready — we only need the socket to be accepting. Process
+ * supervision is otherwise intentionally minimal for this slice; the pinned
+ * version (`OPENCODE_PINNED_VERSION`) is the one the sandbox image must install
+ * (see the SSE-fragility note on that constant).
+ */
+export declare function spawnOpenCode(opts: SpawnOpenCodeOptions): Promise<SpawnedOpenCode>;
+//# sourceMappingURL=hosted-harness-opencode.d.ts.map

package/dist/hosted-harness-opencode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-harness-opencode.d.ts","sourceRoot":"","sources":["../src/hosted-harness-opencode.ts"],"names":[],"mappings":"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"}

package/dist/hosted-harness.d.ts

@@ -0,0 +1,118 @@
+/**
+ * AgentHarness seam (ALI-926 / P3.4, interface 1 of ADR-005's swappability
+ * contract; sketch in audit §4a).
+ *
+ * `AgentHarness` abstracts "what starts and steps the agent" so the OpenCode
+ * driver (`hosted-harness-opencode.ts`) can be swapped for a Claude-Agent-SDK
+ * loop (ALI-929) WITHOUT touching the event bridge (`hosted-run-event-sink.ts`)
+ * or the RunAPI. The interface therefore carries ZERO OpenCode types: it speaks
+ * only in normalized `HarnessEvent`s whose `kind` is the audit §4b left column.
+ *
+ * Shape ported (in DESIGN, not code) from OpenInspect's `bridge.py`:
+ *   create session → send prompt → stream parts → detect idle → stop.
+ * The OpenCode-specific SSE part schema, message-id correlation, and localhost
+ * HTTP driving live entirely behind this seam.
+ *
+ * Terminal semantics: `execution_complete` and `error` are emitted as ordinary
+ * stream events with `critical: true`. The bridge (§4b) routes those to the
+ * RunAPI terminal PATCH — they are NEVER appended as raw run events. The harness
+ * does not know about run status; "Orizu records win" (the disagreement rule) is
+ * enforced by the sink, not here.
+ */
+/** Minimal MCP server descriptor. Kept structural so the seam does not depend on
+ *  any concrete MCP client type; the driver interprets it. */
+export interface McpServerConfig {
+    name: string;
+    /** Transport hint the driver understands (e.g. 'stdio' | 'http'). */
+    transport?: string;
+    command?: string;
+    args?: readonly string[];
+    url?: string;
+    env?: Record<string, string>;
+}
+export interface HarnessStartOptions {
+    /** Absolute or repo-relative working directory the agent operates in. */
+    workspaceDir: string;
+    /** Provider-qualified model, e.g. "anthropic/claude-opus-4-8". */
+    model: string;
+    reasoningEffort?: string;
+    mcpServers?: readonly McpServerConfig[];
+    /** OpenCode session id persisted across restarts (reconnect/resume). */
+    resumeAgentSessionId?: string;
+}
+export interface HarnessPrompt {
+    runId: string;
+    /** Idempotency / correlation key handed by the caller. */
+    messageId: string;
+    content: string;
+    /** Git identity used for commit attribution during the prompt. */
+    author: {
+        name: string;
+        email: string;
+    };
+}
+/**
+ * The normalized event vocabulary — the audit §4b left column. The bridge maps
+ * each kind onto a `workbench_run_events.event_type` (or drops it). Kept as a
+ * const map (no enums, per project guidelines).
+ *
+ * `push_complete` / `push_error` are deliberately OMITTED: they belong to the
+ * finish-branch / manifest push flow deferred to P3.5. `heartbeat` and
+ * `user_message` are not modeled at all — the harness never emits liveness or
+ * prompt-echo events (§4b drops both).
+ */
+export declare const HARNESS_EVENT_KINDS: {
+    readonly ready: "ready";
+    readonly token: "token";
+    readonly tool_call: "tool_call";
+    readonly tool_result: "tool_result";
+    readonly step_start: "step_start";
+    readonly step_finish: "step_finish";
+    readonly git_sync: "git_sync";
+    readonly artifact: "artifact";
+    readonly session_title: "session_title";
+    readonly egress_blocked: "egress_blocked";
+    readonly egress_allowed: "egress_allowed";
+    readonly work_persisted: "work_persisted";
+    readonly work_none: "work_none";
+    readonly work_persist_failed: "work_persist_failed";
+    readonly question_auto_answered: "question_auto_answered";
+    readonly error: "error";
+    readonly execution_complete: "execution_complete";
+};
+export type HarnessEventKind = keyof typeof HARNESS_EVENT_KINDS;
+/** The two kinds that must NEVER be appended as raw events — they drive the
+ *  terminal PATCH instead (§4b mapping rule). */
+export declare const HARNESS_TERMINAL_KINDS: {
+    readonly execution_complete: "execution_complete";
+    readonly error: "error";
+};
+export declare function isHarnessTerminalKind(kind: HarnessEventKind): boolean;
+export interface HarnessEvent {
+    kind: HarnessEventKind;
+    /** Correlation key for coalescing (token snapshots) and attribution. */
+    messageId?: string;
+    payload: Record<string, unknown>;
+    /** Requires guaranteed delivery (execution_complete / error / push_*). */
+    critical?: boolean;
+}
+export interface AgentHarness {
+    /** Stable driver name — "opencode" | "claude-agent-sdk". */
+    readonly name: string;
+    /** Boot the agent process/session; returns the resumable agent session id. */
+    start(opts: HarnessStartOptions): Promise<{
+        agentSessionId: string;
+    }>;
+    /**
+     * Drive one prompt to completion, yielding normalized events. Cancellable via
+     * `signal` (abort → the driver requests the agent to stop and ends the stream
+     * with a terminal event). The stream ALWAYS ends with exactly one terminal
+     * event (`execution_complete` or `error`).
+     */
+    runPrompt(prompt: HarnessPrompt, signal: AbortSignal): AsyncIterable<HarnessEvent>;
+    /** Abort the in-flight prompt (e.g. OpenCode POST /session/{id}/abort). */
+    stop(): Promise<void>;
+    /** Release all resources; the harness is unusable afterward. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=hosted-harness.d.ts.map

package/dist/hosted-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-harness.d.ts","sourceRoot":"","sources":["../src/hosted-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;8DAC8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IACvC,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CACxC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;CA4BtB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,mBAAmB,CAAA;AAE/D;iDACiD;AACjD,eAAO,MAAM,sBAAsB;;;CAGzB,CAAA;AAEV,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAA;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,KAAK,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACrE;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC,YAAY,CAAC,CAAA;IAClF,2EAA2E;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,gEAAgE;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B"}

package/dist/hosted-harvest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Auto-harvest (ALI-1036) — deterministic, loop-side durability.
+ *
+ * At the END of a hosted run (BOTH the success and failure paths — a failed
+ * run's partial work is still valuable), the in-sandbox loop calls
+ * `harvestWorkspace` to make sure nothing the agent produced is lost:
+ *
+ *   1. `git status --porcelain` (plumbing) decides if the clone is dirty. Ignored
+ *      files never appear in porcelain output, so a checkpoint is skipped when the
+ *      only changes are ignored files.
+ *   2. If dirty: `git add -A` then `git commit` attributed to the agent identity
+ *      (AGENT_GIT_IDENTITY) with message `checkpoint: run <runId> auto-harvest`.
+ *   3. If there is anything unpushed (a fresh checkpoint OR pre-existing local
+ *      commits the agent made but did not push), `git push` to the session branch
+ *      (the repo-local credential helper configured by bootstrap authorizes it).
+ *   4. Return a typed outcome the loop records as a run event: `work_persisted`
+ *      (sha + files), `work_none` (clean, nothing to push), or `work_persist_failed`
+ *      (error). Harvest NEVER throws — a harvest failure must not change the run's
+ *      terminal status; it is recorded and the run proceeds to terminal.
+ *
+ * The loop runs IN the sandbox, so git is driven with `child_process` (matching
+ * `defaultRunSetupHook` / `installOpenCodePinned` in `hosted-loop.ts`). `exec` is
+ * injectable so the whole thing is unit-testable with no real git.
+ */
+export interface HarvestExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** Injectable git runner. Defaults to a `spawnSync` git in the workspace dir. */
+export type HarvestExec = (args: readonly string[]) => HarvestExecResult;
+export interface HarvestOptions {
+    /** Directory of the cloned session-branch workspace (the loop's cwd for git). */
+    workspaceDir: string;
+    runId: string;
+    /** Commit attribution (AGENT_GIT_IDENTITY from hosted-runtime-assets). */
+    author: {
+        name: string;
+        email: string;
+    };
+    /** Injectable git runner (default: real `git` via child_process). */
+    exec?: HarvestExec;
+    /**
+     * Safety gate (review finding #1): the default exec runs REAL `git add/commit/
+     * push` in `workspaceDir`. Real harvest must be affirmatively enabled — the loop
+     * only enables it inside a genuine hosted sandbox (prebaked marker present). When
+     * false AND no `exec` is injected, harvest is a no-op (`work_none`) so an errant
+     * workspaceDir (a test, a dev run) can never commit/push a host repo. An injected
+     * `exec` always wins (tests that DO drive harvest).
+     */
+    enabled?: boolean;
+}
+export type HarvestOutcome = {
+    kind: 'work_persisted';
+    sha: string;
+    files: string[];
+} | {
+    kind: 'work_none';
+} | {
+    kind: 'work_persist_failed';
+    error: string;
+};
+/**
+ * Persist any uncommitted or unpushed work in the workspace. Deterministic and
+ * total: every path returns a `HarvestOutcome`, never throws.
+ */
+export declare function harvestWorkspace(opts: HarvestOptions): HarvestOutcome;
+//# sourceMappingURL=hosted-harvest.d.ts.map

package/dist/hosted-harvest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-harvest.d.ts","sourceRoot":"","sources":["../src/hosted-harvest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,iBAAiB,CAAA;AAExE,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,qEAAqE;IACrE,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAoClD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAiErE"}