orizu 0.5.19 → 0.5.21

package/dist/hosted-bootstrap.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Host-driven hosted-sandbox bootstrap (ALI-925 / P3.3, per ADR-005 §8).
+ *
+ * Given a live `SandboxSession` (from the Orizu `SandboxProvider` seam — works
+ * with BOTH the Daytona adapter and local-sim), an Orizu API base URL, a bearer,
+ * and the workspace/session/run ids + session branch, `bootstrapHostedSandbox`
+ * performs the in-sandbox boot flow forked in DESIGN from OpenInspect's
+ * `entrypoint.py` supervisor:
+ *
+ *   1. inject boot context (env/config) as run-scoped files — the bearer only in
+ *      a 0600 file reaped at teardown, never in git config or the clone URL (G3);
+ *   2. install the git credential helper (self-contained script asset) and scope
+ *      it to the repo dir ONLY (never --global);
+ *   3. clone the session branch via the helper (no token in URL / .git/config);
+ *   4. install the Orizu CLI (non-fatal, recorded);
+ *   5. run the customer `.orizu/setup.sh` hook if present (fresh-boot, non-fatal);
+ *   6. record lifecycle events to the RunAPI with client-assigned sequences
+ *      (generic event types only — never the reserved run_* lifecycle types);
+ *   7. on failure, record `bootstrap_failed`, tear down, and sweep for residue.
+ *
+ * P3.4/P3.5 (OpenCode driver, event bridge, `orizu session start --hosted`)
+ * build ON TOP of this — `bootstrapHostedSandbox` is the single writer for the
+ * run at this stage and returns the run cursor so a follow-on can continue it.
+ */
+import type { SandboxSession } from './sandbox-provider.js';
+import { type HygieneFinding } from './sandbox-hygiene.js';
+export type HostedFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export interface AppendedRunEvent {
+    eventId: string;
+    sequence: number;
+    eventType: string;
+    /** Already redacted — safe to inspect / serialize in tests. */
+    payload: Record<string, unknown>;
+}
+/**
+ * The bootstrap orchestrator is the single writer for the run at this stage, so
+ * it owns a local monotonic sequence (per §4b). Every payload is redacted with
+ * the bearer before it leaves the process — a run-event body must never carry
+ * the bearer or a minted token. Lifecycle run_* types are rejected server-side;
+ * the orchestrator only emits generic types.
+ */
+export interface BootstrapRunEventSink {
+    append(eventType: string, payload?: Record<string, unknown>): Promise<AppendedRunEvent>;
+    readonly recorded: readonly AppendedRunEvent[];
+}
+export interface CreateRunEventSinkOptions {
+    apiBaseUrl: string;
+    runId: string;
+    bearer: string;
+    fetchImpl?: HostedFetch;
+    /** Extra verbatim secrets to redact from payloads (e.g. minted tokens). */
+    redactSecretsList?: readonly string[];
+    now?: () => number;
+    /** Sequence to start at (defaults to 1). */
+    startSequence?: number;
+}
+export declare function createBootstrapRunEventSink(options: CreateRunEventSinkOptions): BootstrapRunEventSink;
+export interface HostedBootstrapOptions {
+    session: SandboxSession;
+    apiBaseUrl: string;
+    /** Opaque bearer — a PAT in rehearsal, a G2 session token in production. */
+    bearer: string;
+    workspaceId: string;
+    sessionId: string;
+    runId: string;
+    sessionBranch: string;
+    repoFullName: string;
+    /** Map the broker repo full-name → a clone URL the provider understands.
+     *  Live: `https://github.com/<repo>.git`. Local-sim: the bare repo path. */
+    resolveCloneUrl: (repo: string) => string;
+    /** Directory (relative to the sandbox root) the session branch clones into. */
+    workspaceDir?: string;
+    /** VCS host the credential helper serves (default github.com). */
+    host?: string;
+    /**
+     * Broker purpose vocabulary the helper mints with. When omitted, the default
+     * is chosen from `bearerKind` (below): a human bearer mints `write`/`read`, an
+     * agent bearer mints `session_write`/`session_read`. Injectable so a caller can
+     * override without editing the credential-helper script.
+     */
+    tokenPurposes?: {
+        primary: string;
+        fallback: string;
+    };
+    /**
+     * Kind of bearer in the 0600 file — the orchestrator KNOWS what it minted, so
+     * the default broker purposes are chosen from this EXPLICIT signal, never by
+     * sniffing the token. 'agent' → session_write/session_read; 'human' (default)
+     * → write/read. Ignored when `tokenPurposes` is passed explicitly.
+     */
+    bearerKind?: 'agent' | 'human';
+    /**
+     * Hosts the credential helper may serve over plain HTTP (loopback rehearsal
+     * only). Production omits this → the helper stays https-only.
+     */
+    insecureHttpHosts?: readonly string[];
+    /** Helper cache refresh buffer (ms) — overridable so tests can force refresh. */
+    cacheBufferMs?: number;
+    /**
+     * Defer the customer `.orizu/setup.sh` hook to the in-sandbox loop (P3-a). When
+     * true, bootstrap does NOT run the hook; it records `setup_hook_deferred` and
+     * the loop runs it AFTER its egress canary passes. The host sets this for
+     * enforced-egress providers so the hook's network access cannot precede the
+     * canary's detection of a silent firewall failure. Default false (run inline).
+     */
+    deferSetupHook?: boolean;
+    /** Published CLI version to install in-sandbox (default 'latest'). */
+    cliVersion?: string;
+    /** Override the CLI-install shell command (tests inject a deterministic one). */
+    cliInstallCommand?: string;
+    /**
+     * Pre-baked runtime (ALI-1017): the image already ships the Orizu CLI on PATH,
+     * so the CLI-install step is SKIPPED (it would fail under G5 default-deny egress
+     * anyway) and a `cli_prebaked` event is recorded instead of `cli_installed`.
+     * The host sets this together with the sandbox `image` so the two never
+     * disagree. When unset, bootstrap ALSO belt-checks the `/opt/orizu/prebaked.json`
+     * marker on the sandbox filesystem; either signal skips the install.
+     */
+    prebaked?: boolean;
+    /** Inject a RunAPI sink (tests/production); default builds one over apiBaseUrl. */
+    sink?: BootstrapRunEventSink;
+    fetchImpl?: HostedFetch;
+    now?: () => number;
+}
+export interface HostedBootstrapStep {
+    key: string;
+    ok: boolean;
+    detail: string;
+}
+export interface HostedBootstrapResult {
+    ok: boolean;
+    steps: HostedBootstrapStep[];
+    events: readonly AppendedRunEvent[];
+    paths: HostedRuntimePaths;
+    /** Set on the failure path: the residue sweep result after teardown. */
+    sweep: {
+        clean: boolean;
+        findings: HygieneFinding[];
+    } | null;
+    failure: {
+        step: string;
+        error: string;
+    } | null;
+}
+export interface HostedRuntimePaths {
+    root: string;
+    runDirRel: string;
+    runDirAbs: string;
+    repoDirRel: string;
+    helperScriptAbs: string;
+    bootContextAbs: string;
+    bearerFileAbs: string;
+    cacheFileAbs: string;
+}
+export declare function computeRuntimePaths(root: string, runId: string, workspaceDir: string): HostedRuntimePaths;
+export declare function bootstrapHostedSandbox(opts: HostedBootstrapOptions): Promise<HostedBootstrapResult>;
+export interface TeardownOptions {
+    session: SandboxSession;
+    paths: HostedRuntimePaths;
+    bearer: string;
+    workspaceDir?: string;
+    /** Extra token values to sweep for (e.g. a minted repo token a test planted). */
+    extraTokens?: readonly string[];
+}
+/**
+ * Tear the run-scoped credential material down and PROVE no token residue
+ * remains (G3, extends ALI-973's `sweepForTokenResidue`). Removes the run dir
+ * (bearer + boot context + minted-token cache), unsets the repo-local credential
+ * helper, then sweeps .git/config, the git credential cache, env, argv, and
+ * ~/.git-credentials for the bearer, any extra tokens, and the token markers.
+ */
+export declare function teardownHostedSandbox(opts: TeardownOptions): Promise<{
+    clean: boolean;
+    findings: HygieneFinding[];
+}>;
+export interface HostedSweepOptions {
+    bearer: string;
+    paths: HostedRuntimePaths;
+    workspaceDir: string;
+    extraTokens?: readonly string[];
+}
+/**
+ * Extend the ALI-973 sweep with hosted-specific probes: the run dir (bearer +
+ * cache) must be gone, and the standard leak surfaces (.git/config, ~/.git-
+ * credentials, credential cache, env, argv) must be free of the bearer.
+ */
+export declare function sweepHostedResidue(session: SandboxSession, opts: HostedSweepOptions): Promise<HygieneFinding[]>;
+//# sourceMappingURL=hosted-bootstrap.d.ts.map

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

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

package/dist/hosted-broker-server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Standalone fake Orizu control-plane broker for the ALI-925 rehearsal + tests.
+ *
+ * This runs as its OWN process (spawned via `bun <this file>`), NOT in-process,
+ * for a specific reason: the local-sim `SandboxSession.exec` uses a blocking
+ * `spawnSync`, and the in-sandbox credential helper it runs makes a real HTTP
+ * call back to this broker. An in-process server can't answer that call while
+ * the test thread is blocked in `spawnSync` — so the broker must be a separate
+ * process with its own event loop.
+ *
+ * It implements exactly the two contracts the bootstrap depends on:
+ *   - POST /api/cli/workspaces/:id/repo-token → {token, expiresAt, repo, mintId}
+ *   - POST /api/cli/workbench-runs/:id/events → 201 (rejects reserved run_* 400)
+ * and it journals every accepted event / issued token to newline-delimited JSON
+ * files so the parent test can read them back. Config comes from env (below).
+ *
+ * Not shipped to end users — a test/rehearsal fixture only.
+ */
+export interface BrokerConfig {
+    bearer: string;
+    repo: string;
+    /** Test-only exact Artifacts remote returned by the repo-token endpoint. */
+    artifactsRemote?: string;
+    /** Test-only expiry override for fail-closed helper rehearsals. */
+    artifactsExpiresAt?: string;
+    eventsFile?: string;
+    tokensFile?: string;
+    repoTokenStatus?: number;
+    eventsStatus?: number;
+    denyWrite?: boolean;
+    port?: number;
+    /**
+     * E2E mode: accept ANY non-empty Bearer (the full hosted flow uses a human
+     * bearer for session/agent-token mints and a DISTINCT agent bearer for
+     * run/events), and serve the full RunAPI + session + agent-token surface so
+     * `startHostedSession` can be driven end to end. Off by default so the
+     * bootstrap/credential-helper tests keep their strict single-bearer contract.
+     */
+    fullRunApi?: boolean;
+    /** E2E: the session id + branch the /sessions endpoint returns (so it matches
+     *  a pre-seeded session branch on the local bare repo). */
+    sessionId?: string;
+    sessionBranch?: string;
+}
+export declare function readBrokerConfigFromEnv(env: NodeJS.ProcessEnv): BrokerConfig;
+export declare function startBrokerServer(config: BrokerConfig): {
+    port: number;
+    stop: (force?: boolean) => void;
+};
+//# sourceMappingURL=hosted-broker-server.d.ts.map

package/dist/hosted-broker-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-broker-server.d.ts","sourceRoot":"","sources":["../src/hosted-broker-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA8BH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;+DAC2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,YAAY,CAgB5E;AASD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,CA6LzG"}

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

@@ -0,0 +1,36 @@
+/**
+ * Standalone authenticated smart-HTTP git server for the ALI-925 rehearsal.
+ *
+ * Runs as its OWN process (spawned via `bun <this file>`), for the same reason
+ * the fake broker does: the local-sim `SandboxSession.exec` blocks on a
+ * `spawnSync` git clone, and the in-sandbox credential helper that clone drives
+ * makes real HTTP calls out. A server sharing the test's event loop could not
+ * answer while that loop is blocked — so the git server must be its own process.
+ *
+ * It proves the integrated credential path end-to-end: it (a) requires HTTP Basic
+ * auth and rejects unauthenticated requests with 401 + `WWW-Authenticate`, forcing
+ * git to invoke the credential helper, and (b) on authenticated requests serves a
+ * real bare repo by shelling to `git http-backend` as CGI. Every Basic-auth
+ * password it receives is journaled to a file so the rehearsal can assert the
+ * password git presented equals the token the broker minted (git → helper →
+ * broker → token → authenticated clone).
+ *
+ * Not shipped to end users — a test/rehearsal fixture only.
+ */
+export interface GitHttpConfig {
+    /** Absolute path to the bare repo (e.g. `<root>/workbench.git`). */
+    repoDir: string;
+    /** File the server appends every received `{ user, pass }` to (NDJSON). */
+    authLogFile?: string;
+    port?: number;
+}
+export declare function readGitHttpConfigFromEnv(env: NodeJS.ProcessEnv): GitHttpConfig;
+/** The env keys the server reads (kept here so callers do not hand-roll them). */
+export declare function gitHttpEnv(config: GitHttpConfig): Record<string, string>;
+/** The clone path segment a client uses (the bare repo's basename). */
+export declare function gitHttpRepoSegment(config: GitHttpConfig): string;
+export declare function startGitHttpServer(config: GitHttpConfig): {
+    port: number;
+    stop: (force?: boolean) => void;
+};
+//# sourceMappingURL=hosted-git-http-server.d.ts.map

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH,OAAO,KAAK,EACV,YAAY,EAKb,MAAM,qBAAqB,CAAA;AAW5B;6EAC6E;AAC7E,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAA;IAEZ,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,UAAU,mBAAmB;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,eAAe,EAAE,GAAG,MAAM,CAAA;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED;8EAC8E;AAC9E,UAAU,iBAAiB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACxC,aAAa,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjC,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1B;AAED,+EAA+E;AAC/E,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,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,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;0FAEsF;IACtF,+BAA+B,CAAC,EAAE,OAAO,CAAA;IACzC,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IAC/C;;qFAEiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACzC;AAED,oFAAoF;AACpF,UAAU,cAAe,SAAQ,aAAa,CAAC,UAAU,CAAC;IACxD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,eAAe,CAAA;KAAE,KAAK,cAAc,CAAA;CAC9E;AAwBD,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAChD;6DACyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AA2DD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAoTd"}