orizu 0.5.19 → 0.5.21

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"}

package/dist/hosted-headless.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Headless-run helpers (ALI-1037) for the in-sandbox loop.
+ *
+ *   - `withIdleWatchdog`: wraps a harness event stream and aborts a prompt that
+ *     makes NO progress (no harness event) for a bounded window, so a stalled
+ *     agent can never hang a hosted run forever. On idle it invokes `onTimeout`
+ *     (the loop aborts the harness) then throws `AgentStalledError`, which the
+ *     loop turns into a `failed` terminal — AFTER running the end-of-run harvest.
+ *
+ *   - `annotateHeadlessQuestions`: observability for the question-tool deny path.
+ *     The interactive `question` tool is DENIED via OpenCode's permission map
+ *     (see HEADLESS_DENIED_TOOLS in hosted-harness-opencode.ts), so a headless
+ *     run never blocks on it. When the agent nonetheless attempts a `question`
+ *     tool call, this wrapper emits a `question_auto_answered` event recording the
+ *     question and the option that WOULD be recommended, so the run timeline shows
+ *     the auto-handling. It touches only the normalized event stream — never the
+ *     fragile OpenCode SSE transform.
+ */
+import type { HarnessEvent } from './hosted-harness.js';
+/** Thrown by `withIdleWatchdog` when the stream is idle past its timeout. */
+export declare class AgentStalledError extends Error {
+    readonly idleMs: number;
+    constructor(idleMs: number);
+}
+/** Render the idle window for the error message. Minutes (the operator-facing
+ *  unit; default window is 25m), rounded to one decimal so sub-minute test
+ *  windows still read sensibly. */
+export declare function formatIdleWindow(ms: number): string;
+export interface IdleWatchdogOptions<T> {
+    /** No harness event within this many ms aborts the prompt. <= 0 disables. */
+    timeoutMs: number;
+    /** Invoked once on idle (the loop aborts the harness) before the throw. */
+    onTimeout: () => Promise<void> | void;
+    /**
+     * Whether a value counts as PROGRESS (resets the idle timer). Values passed
+     * through as non-progress are still yielded downstream but do NOT extend the
+     * idle deadline. Defaults to treating every value as progress. Used to exclude
+     * synthetic deny-path events (e.g. `question_auto_answered`) so a model stuck
+     * in a denied-question retry loop still trips `agent_stalled` (ALI-1069).
+     */
+    isProgress?: (value: T) => boolean;
+}
+/**
+ * Wrap `source` so that if no PROGRESS arrives within `timeoutMs`, `onTimeout`
+ * runs and `AgentStalledError` is thrown. The idle deadline advances only on
+ * values `opts.isProgress` accepts (default: all), so it measures gaps between
+ * real progress events, not total duration — a stream of non-progress values
+ * (e.g. `question_auto_answered` deny-path events) passes through WITHOUT
+ * resetting the timer, so a stuck loop still stalls. The still-pending `next()`
+ * is not left as an unhandled rejection, and the underlying iterator is
+ * returned/closed on any early exit.
+ */
+export declare function withIdleWatchdog<T>(source: AsyncIterable<T>, opts: IdleWatchdogOptions<T>): AsyncGenerator<T>;
+export interface ParsedHeadlessQuestion {
+    question: string;
+    chosenOption: string;
+}
+/**
+ * Parse the OpenCode `question` tool args into the question text and the option
+ * we would pick headless: the one labeled "(Recommended)" if present, else the
+ * first. Defensive against the tool's shape drifting (options as strings or
+ * objects; the question under any of several keys).
+ */
+export declare function parseHeadlessQuestion(args: unknown): ParsedHeadlessQuestion;
+/**
+ * Pass every harness event through unchanged; when a `question` tool call/result
+ * is seen, additionally emit a `question_auto_answered` event (deduped per
+ * callId+message) recording the auto-handling. The tool is denied at the
+ * permission layer, so this is a record — not an interactive reply.
+ */
+export declare function annotateHeadlessQuestions(source: AsyncIterable<HarnessEvent>): AsyncGenerator<HarnessEvent>;
+//# sourceMappingURL=hosted-headless.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-headless.d.ts","sourceRoot":"","sources":["../src/hosted-headless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,6EAA6E;AAC7E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBACX,MAAM,EAAE,MAAM;CAK3B;AAED;;mCAEmC;AACnC,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACrC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAA;CACnC;AAID;;;;;;;;;GASG;AACH,wBAAuB,gBAAgB,CAAC,CAAC,EACvC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CAyCnB;AAeD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,sBAAsB,CA0B3E;AAED;;;;;GAKG;AACH,wBAAuB,yBAAyB,CAC9C,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,cAAc,CAAC,YAAY,CAAC,CAuB9B"}