@theokit/sdk 4.53.1 → 4.55.0

package/dist/{run-C8FBAC8o.d.ts → run-BYSHf58D.d.ts}

@@ -143,20 +143,51 @@ interface UserMessageAppendedUpdate {
     type: "user-message-appended";
     userMessage: UserMessage;
 }
-/** @public */
+/**
+ * A conversation summary produced during a run, delivered through `SendOptions.onDelta`.
+ *
+ * Nothing in this package emits it. It is declared so an exhaustive `switch` over
+ * {@link InteractionUpdate} compiles, and so a runtime that does produce summaries has a typed
+ * channel — do not build a feature that waits on it against the local runtime.
+ *
+ * @public
+ */
 interface SummaryUpdate {
     type: "summary";
     summary: string;
 }
-/** @public */
+/**
+ * Opens the bracket around a {@link SummaryUpdate}, for a UI that wants to show a pending state
+ * before the summary text exists. Paired with {@link SummaryCompletedUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
 interface SummaryStartedUpdate {
     type: "summary-started";
 }
-/** @public */
+/**
+ * Closes the bracket opened by {@link SummaryStartedUpdate}. Carries no payload — the summary text
+ * itself arrives as {@link SummaryUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
 interface SummaryCompletedUpdate {
     type: "summary-completed";
 }
-/** @public */
+/**
+ * Incremental output from a shell command running inside a run.
+ *
+ * `event` is an untyped bag on purpose: this package neither produces nor narrows it, so a consumer
+ * that receives one should treat it as unvalidated input and check for the fields it needs rather
+ * than casting. As with the summary variants, nothing here emits this — it exists so the
+ * {@link InteractionUpdate} union covers a runtime that does.
+ *
+ * @public
+ */
 interface ShellOutputDeltaUpdate {
     type: "shell-output-delta";
     event: Record<string, unknown>;
@@ -219,6 +250,40 @@ declare function applyMode(verdict: PermissionAction, mode: PermissionMode, expl
  * a destructive shell call while leaving `ls` to fall through.
  */
 type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+/**
+ * One entry in a {@link PermissionEngine}'s ordered rule list.
+ *
+ * Order is the semantics. The engine walks the list and the first rule whose `tool` matches — and
+ * whose `args` matchers all pass, when it declares any — decides; nothing after it is consulted. Put
+ * the narrow rules first: a catch-all `tool` RegExp placed above a specific deny makes that deny
+ * unreachable, and nothing warns you.
+ *
+ * `args` is what lets one tool name resolve differently depending on what it is asked to do —
+ * `{ tool: "shell", args: { command: /rm\s+-rf/ }, action: "deny" }` blocks the destructive call and
+ * leaves `ls` to fall through to a later rule. Every declared matcher must pass.
+ *
+ * **A missing argument is NOT handled uniformly, and the difference bites in the unsafe direction.**
+ * For a string or RegExp matcher, an argument the call did not supply fails the matcher, so the rule
+ * does not match and evaluation continues. For a PREDICATE matcher the function is called anyway,
+ * with `undefined`:
+ *
+ * ```ts
+ * { tool: "shell", args: { command: (v) => v !== "prod" }, action: "allow" }
+ * // evaluate("shell", {}) → the predicate gets `undefined`, returns true, the rule MATCHES,
+ * // and a call that supplied no arguments at all is authorized.
+ *
+ * { tool: "shell", args: { command: (v) => v.includes("rm") }, action: "deny" }
+ * // evaluate("shell", {}) → TypeError thrown out of the permission gate.
+ * ```
+ *
+ * Until that is fixed (issue #367), guard the parameter in every predicate you write —
+ * `(v) => typeof v === "string" && v !== "prod"` — rather than relying on the matcher never being
+ * reached.
+ *
+ * A rule that matches yields an EXPLICIT verdict, and that is what makes it survive a permissive
+ * `PermissionMode`: `acceptEdits` auto-approves the unmatched default but still honours an explicit
+ * `ask` rule, and an explicit `deny` is immune to every mode, `bypass` included.
+ */
 interface PermissionRule {
     /** Tool name (exact string) or pattern (RegExp). */
     tool: string | RegExp;
@@ -241,6 +306,27 @@ interface PermissionEngineOptions {
      */
     readonly defaultAction?: PermissionAction;
 }
+/**
+ * Ordered first-match permission rules for tool invocations — the policy object you hand to
+ * `PermissionPlugin.create()` to have it enforced.
+ *
+ * On its own it enforces nothing. `evaluate(toolName, args, mode)` is a pure function returning
+ * `"allow" | "deny" | "ask"`, and no part of the SDK calls it until the engine is wrapped in a plugin
+ * and that plugin is registered on an agent. The plugin is where a verdict becomes behaviour: `deny`
+ * blocks the tool call, `allow` passes it through, and `ask` is routed to the host's `canUseTool`
+ * gate — with no gate configured, `ask` blocks. So constructing an engine and never registering it
+ * is a policy that does nothing, which is the mistake worth knowing about first.
+ *
+ * It is fail-closed by default: a call no rule matches resolves to `"ask"`, not `"allow"`, so a tool
+ * the rules never mention needs a human — or an explicit `{ defaultAction: "allow" }` — before it
+ * runs. Keep that default if you intend to use `PermissionMode: "plan"` for read-only behaviour,
+ * because `plan` gates on the RESOLVED verdict: an engine built with `defaultAction: "allow"` still
+ * allows every unmatched call under `plan`.
+ *
+ * The rules array is stored by reference and walked afresh on every `evaluate` call. Mutating the
+ * array you passed in therefore changes the policy of a live engine; build a new engine when you
+ * want a policy change to be a deliberate, visible event.
+ */
 declare class PermissionEngine {
     #private;
     private readonly rules;
@@ -274,7 +360,7 @@ declare class PermissionEngine {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent;
 /**
  * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
  * tools exist for this run.
@@ -294,6 +380,33 @@ interface RunMcpServerFailedEvent {
     /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
     readonly message: string;
 }
+/**
+ * usetheokit/theokit#426 — an MCP server came up, and these are the tools it delivered.
+ *
+ * The sibling of {@link RunMcpServerFailedEvent}, emitted from the same function, on the other
+ * branch. Without it a consumer could see what was CONFIGURED and what BROKE, and could not tell a
+ * server that came up with twelve tools from one that came up with none — which is exactly the case
+ * an operator opens a server-status panel to find. `tools: []` on a healthy server is a real and
+ * previously unreportable state.
+ *
+ * An EVENT rather than a getter, because the state is scoped to the run: with
+ * `mcpLifecycle: "run"` a server may not exist by the time anyone asks, so a getter would have to
+ * answer about something already gone. This says what was true when the run started.
+ *
+ * Emitted once per successfully-listed server per run.
+ */
+interface RunMcpServerReadyEvent {
+    readonly type: "mcp_server_ready";
+    /** The server as named in the MCP configuration — the key a consumer already lists it under. */
+    readonly serverName: string;
+    /**
+     * The tool names the server reported, as IT names them.
+     *
+     * Not the `mcp_<server>_<tool>` form the model sees: that spelling is sanitized for the provider,
+     * and a consumer matching it back to a server's own documentation would have to undo the mangling.
+     */
+    readonly tools: readonly string[];
+}
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
@@ -572,6 +685,20 @@ interface ModelSelection {
      * clamped — declaring 10M does not blow past the provider.
      */
     contextWindow?: number;
+    /**
+     * #332 — the endpoint THIS model should reach, for OpenAI-compatible and local servers.
+     *
+     * Without it the base URL came only from a process-wide env var (`OLLAMA_HOST`) or the provider
+     * profile's shipped default, so every `ollama/*` model in a process shared one host — an app
+     * could not run a small model on localhost and a large one on a GPU box.
+     *
+     * It outranks the env var deliberately: with the env var winning, whoever set it for one model
+     * would keep hijacking every other one, which is the same bug wearing a hat.
+     *
+     * Leaving it unset keeps the zero-config path exactly as it was — `ollama/qwen2.5:3b` still
+     * resolves to `http://localhost:11434` from the profile, with no key and no setup.
+     */
+    url?: string;
 }
 /**
  * SE12 — a read-only, text-only projection of one turn of the run's conversation,
@@ -679,11 +806,6 @@ interface ShellOutput {
     stderr: string;
     exitCode: number;
 }
-/**
- * Single step inside an agent turn.
- *
- * @public
- */
 /**
  * Result of a tool invocation. Pairs with the preceding `toolCall` step
  * by `callId`. `isError: true` when the tool returned a failure result.
@@ -699,6 +821,24 @@ interface ToolResult {
     result: string;
     isError: boolean;
 }
+/**
+ * A single step inside an agent turn, discriminated by `type`: an assistant message, a tool call, the
+ * tool result that pairs with it, or a thinking block.
+ *
+ * It reaches a caller by two routes that are NOT the same set. `Run.conversation()` returns the
+ * accumulated steps of a finished turn and includes `thinkingMessage`. `SendOptions.onStep` fires
+ * live while the turn runs and emits `assistantMessage`, `toolCall` and `toolResult` — but never
+ * `thinkingMessage`, which the loop builds only into the accumulated conversation. A UI that wants
+ * reasoning as it happens should read the `thinking-delta` / `thinking-completed` variants of
+ * `InteractionUpdate` through `onDelta` instead.
+ *
+ * `toolCall` and its `toolResult` arrive as an ordered pair matched by `callId`; a call whose result
+ * never came back has no `toolResult` step, so do not assume they alternate. Where a
+ * `thinkingMessage` exists it precedes the `assistantMessage` of the same turn — that is the order
+ * the provider requires of the message the block belongs to, not a presentation choice.
+ *
+ * @public
+ */
 type ConversationStep = {
     type: "assistantMessage";
     message: AssistantMessage;
@@ -1105,11 +1245,16 @@ interface RunGitInfo {
     }>;
 }
 /**
- * SE3 — provenance of the turn that produced a run: WHO triggered it. Stamped in
- * the multi-agent path (Squad / a2a / handoff / background-delegation) and
- * forwarded onto {@link RunResult.origin} — so consumers can attribute/route
- * turns by their trigger. Metadata-only; discriminate on `kind`. Mirrors the
- * Anthropic Agent SDK's `origin` shape.
+ * SE3 — provenance of the turn that produced a run: WHO triggered it. Metadata-only —
+ * it never changes routing or dispatch. Stamped in the multi-agent path (Squad / a2a /
+ * handoff / background-delegation) and forwarded onto {@link RunResult.origin}, so
+ * consumers can attribute/route turns by their trigger; discriminate on `kind`. Mirrors
+ * the Anthropic Agent SDK's `origin` shape.
+ *
+ * Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent delegation) and
+ * `auto-continuation` (the run-to-completion / stream-to-completion driver's continuation
+ * rounds) are stamped BY the SDK. `human` and `task-notification` are positive markers a
+ * HOST stamps (e.g. re-sending an agent after a background task completed).
  *
  * Encoding note (distinct from absence): an ABSENT origin (`undefined`) means the
  * provenance was NOT stamped — the default for a plain `agent.send()`. The explicit
@@ -1122,16 +1267,6 @@ interface RunGitInfo {
  *
  * @public
  */
-/**
- * SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).
- * Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent
- * delegation), `auto-continuation` (the run-to-completion / stream-to-completion
- * driver's continuation rounds) are stamped BY the SDK. `human` and
- * `task-notification` are positive markers a HOST stamps (e.g. re-sending an
- * agent after a background task completed). Absent origin ⇒ `undefined`.
- *
- * @public
- */
 type MessageOrigin = 
 /** Explicitly a human-triggered turn — a positive marker a host stamps (NOT the
  *  same as an absent/unstamped origin, which is `undefined`). */
@@ -1202,9 +1337,13 @@ interface RunResult {
     error?: RunErrorDetail;
     /**
      * Token usage observed for this run (ADR D376). Populated in every
-     * status where ≥1 LLM call completed — including partial-failure
-     * runs (EC-5). `undefined` only when zero LLM calls executed (e.g.,
-     * abort before send).
+     * status where ≥1 LLM call COMPLETED — including partial-failure
+     * runs (EC-5). `undefined` when zero LLM calls executed (e.g. an
+     * abort before send) and, for the same reason, when the only call was
+     * cut mid-stream: the counts arrive with the provider's terminating
+     * frame, which a severed connection never delivers. Such a run can
+     * therefore return partial text (#371) with no usage to bill it
+     * against — the tokens were generated and are not reported here.
      *
      * @public
      */
@@ -1576,11 +1715,6 @@ interface CompletionCheckResult {
     /** `true` when the judge output could not be parsed — fail-safe `complete: false`. */
     parseFailed: boolean;
 }
-/**
- * Handle to a single prompt submission.
- *
- * @public
- */
 /**
  * theokit#140 - one element of {@link Run.events}: either a structural SDK message or a live delta.
  *
@@ -1611,6 +1745,24 @@ type RunTimelineEvent = {
     kind: "delta";
     update: InteractionUpdate;
 };
+/**
+ * Handle to a single prompt submission, returned by `agent.send()` before the model has answered.
+ *
+ * It is a live handle rather than a result — `status` is `"running"` when you receive it — and how
+ * you consume the turn is the decision it asks of you. Call `wait()` when only the final answer
+ * matters. Call `events()` when you want the whole timeline: structural messages and token/tool
+ * deltas interleaved in true order, from one source. That is the one to reach for instead of fusing
+ * `stream()` with `SendOptions.onDelta` yourself, which is what produced the ordering and
+ * duplicate-text bugs it replaces. `stream()` remains the SDKMessage-only view, and
+ * `conversation()` returns the finished turn grouped per turn instead of as a stream.
+ *
+ * `cancel()` moves the run to `"cancelled"`, aborts the stream and stops in-flight tool calls.
+ *
+ * Not every method is available on every runtime — see {@link RunOperation}. Ask `supports(op)`
+ * before calling an optional one and surface `unsupportedReason(op)`, rather than calling it and
+ * catching. The optional fields (`result`, `model`, `durationMs`, `git`, `createdAt`) fill in as the
+ * run progresses, so treat their absence as "not yet", not as an error.
+ */
 interface Run {
     readonly id: string;
     readonly agentId: string;

package/dist/{run-to-completion-JDPIUKSH.js → run-to-completion-DRO77625.js}

@@ -1,3 +1,3 @@
-export { DEFAULT_CONTINUATION_PROMPT, DEFAULT_MAX_ROUNDS, addUsage, buildResult, classifyRound, continuationTail, isEmptyRound, promptForRound, resolveContinuation, runToCompletionImpl } from './chunk-UCFONJBG.js';
-//# sourceMappingURL=run-to-completion-JDPIUKSH.js.map
-//# sourceMappingURL=run-to-completion-JDPIUKSH.js.map
+export { DEFAULT_CONTINUATION_PROMPT, DEFAULT_MAX_ROUNDS, addUsage, buildResult, classifyRound, continuationTail, isEmptyRound, promptForRound, resolveContinuation, runToCompletionImpl } from './chunk-EPSICJLZ.js';
+//# sourceMappingURL=run-to-completion-DRO77625.js.map
+//# sourceMappingURL=run-to-completion-DRO77625.js.map

package/dist/{run-to-completion-JDPIUKSH.js.map → run-to-completion-DRO77625.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"run-to-completion-JDPIUKSH.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"run-to-completion-DRO77625.js"}

package/dist/{run-to-completion-J73I6IY4.cjs → run-to-completion-X4OWM673.cjs}

@@ -1,48 +1,48 @@
 'use strict';
 
-var chunkVK7MAV65_cjs = require('./chunk-VK7MAV65.cjs');
+var chunkQKLOP4VC_cjs = require('./chunk-QKLOP4VC.cjs');
 
 
 
 Object.defineProperty(exports, "DEFAULT_CONTINUATION_PROMPT", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.DEFAULT_CONTINUATION_PROMPT; }
+  get: function () { return chunkQKLOP4VC_cjs.DEFAULT_CONTINUATION_PROMPT; }
 });
 Object.defineProperty(exports, "DEFAULT_MAX_ROUNDS", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.DEFAULT_MAX_ROUNDS; }
+  get: function () { return chunkQKLOP4VC_cjs.DEFAULT_MAX_ROUNDS; }
 });
 Object.defineProperty(exports, "addUsage", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.addUsage; }
+  get: function () { return chunkQKLOP4VC_cjs.addUsage; }
 });
 Object.defineProperty(exports, "buildResult", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.buildResult; }
+  get: function () { return chunkQKLOP4VC_cjs.buildResult; }
 });
 Object.defineProperty(exports, "classifyRound", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.classifyRound; }
+  get: function () { return chunkQKLOP4VC_cjs.classifyRound; }
 });
 Object.defineProperty(exports, "continuationTail", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.continuationTail; }
+  get: function () { return chunkQKLOP4VC_cjs.continuationTail; }
 });
 Object.defineProperty(exports, "isEmptyRound", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.isEmptyRound; }
+  get: function () { return chunkQKLOP4VC_cjs.isEmptyRound; }
 });
 Object.defineProperty(exports, "promptForRound", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.promptForRound; }
+  get: function () { return chunkQKLOP4VC_cjs.promptForRound; }
 });
 Object.defineProperty(exports, "resolveContinuation", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.resolveContinuation; }
+  get: function () { return chunkQKLOP4VC_cjs.resolveContinuation; }
 });
 Object.defineProperty(exports, "runToCompletionImpl", {
   enumerable: true,
-  get: function () { return chunkVK7MAV65_cjs.runToCompletionImpl; }
+  get: function () { return chunkQKLOP4VC_cjs.runToCompletionImpl; }
 });
-//# sourceMappingURL=run-to-completion-J73I6IY4.cjs.map
-//# sourceMappingURL=run-to-completion-J73I6IY4.cjs.map
+//# sourceMappingURL=run-to-completion-X4OWM673.cjs.map
+//# sourceMappingURL=run-to-completion-X4OWM673.cjs.map

package/dist/{run-to-completion-J73I6IY4.cjs.map → run-to-completion-X4OWM673.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"run-to-completion-J73I6IY4.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"run-to-completion-X4OWM673.cjs"}

package/dist/sandbox/bwrap.d.cts

@@ -1,16 +1,3 @@
-/**
- * M53 — bubblewrap argv + honest detection.
- *
- * HONEST SCOPE: filesystem confinement + network isolation via bwrap, PLUS the second stage —
- * a cBPF seccomp syscall filter (`agents/sandbox/seccomp.ts`), wired in `agents/sandbox/backend.ts`
- * via `restrictedSeccompPath()`. Ported in M63; this block claimed the opposite until M67 and
- * UNDER-DECLARED the real security posture. The honest limit that remains: the filter is **x86_64**
- * (an architecture guard refuses to install it on any other arch, with a WARN, and bwrap's FS/network
- * confinement still applies) **and** it is only installed when the network is restricted
- * (`backend.ts:87`, faithful to `landlock.rs:96-117`): with the network on there is no syscall
- * filter, only bwrap's FS confinement. `danger-full-access` skips bwrap entirely, mirroring
- * `bwrap.rs:245-252`. Deltas versus Codex remain documented in docs/CODEX-PARITY.md.
- */
 /**
  * Codex's three canonical modes. Defined HERE because they are sandbox vocabulary, not consumer
  * configuration: `danger-full-access` means "do not wrap", and that is a decision belonging to the
@@ -31,6 +18,15 @@ export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access"
  * the two cannot disagree.
  */
 export declare function writableRootsFor(mode: SandboxMode, cwd: string): readonly string[] | null;
+/**
+ * Everything {@link buildBwrapArgv} needs besides the {@link SandboxMode}.
+ *
+ * Only `cwd` is required, and it is resolved to an absolute path before any bind
+ * is emitted. The defaults are the restrictive ones in one direction and the
+ * permissive one in the other: omitting `network` emits `--unshare-net` (no
+ * network), while omitting `env` means the child INHERITS the parent
+ * environment — bwrap only clears it when an allowlist is supplied.
+ */
 export interface BwrapArgvOptions {
     /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
     cwd: string;
@@ -59,6 +55,24 @@ export interface BwrapProbes {
     /** Active user-namespace probe with timeout (sandboxing/src/bwrap.rs:74-136). */
     userns: (bin: string) => boolean;
 }
+/**
+ * Result of {@link detectBwrap} / {@link detectBwrapMemoized}, discriminated on
+ * `ok`: `{ ok: true, bin }` carries the absolute path of the validated `bwrap`,
+ * `{ ok: false, reason }` a human-readable cause — "bwrap not found in PATH",
+ * "bwrap at <bin> lacks --perms support (too old)",
+ * "user namespaces unavailable (container/kernel restriction)",
+ * "bwrap probe failed: <err>", or (memoized only)
+ * "bwrap disappeared from <bin> after detection".
+ *
+ * `reason` is prose for a warning line. It is not a stable code — do not branch
+ * on it.
+ *
+ * `ok: false` is an ordinary outcome rather than an error: bubblewrap is
+ * Linux-only, so failing detection on macOS, on Windows, or inside a container
+ * without user namespaces is expected. Detection NEVER throws, so wrapping it in
+ * `try`/`catch` catches nothing; callers warn and fall back to an unconfined
+ * `LocalSandbox`.
+ */
 export type BwrapDetection = {
     ok: true;
     bin: string;

package/dist/sandbox/bwrap.d.ts

@@ -1,16 +1,3 @@
-/**
- * M53 — bubblewrap argv + honest detection.
- *
- * HONEST SCOPE: filesystem confinement + network isolation via bwrap, PLUS the second stage —
- * a cBPF seccomp syscall filter (`agents/sandbox/seccomp.ts`), wired in `agents/sandbox/backend.ts`
- * via `restrictedSeccompPath()`. Ported in M63; this block claimed the opposite until M67 and
- * UNDER-DECLARED the real security posture. The honest limit that remains: the filter is **x86_64**
- * (an architecture guard refuses to install it on any other arch, with a WARN, and bwrap's FS/network
- * confinement still applies) **and** it is only installed when the network is restricted
- * (`backend.ts:87`, faithful to `landlock.rs:96-117`): with the network on there is no syscall
- * filter, only bwrap's FS confinement. `danger-full-access` skips bwrap entirely, mirroring
- * `bwrap.rs:245-252`. Deltas versus Codex remain documented in docs/CODEX-PARITY.md.
- */
 /**
  * Codex's three canonical modes. Defined HERE because they are sandbox vocabulary, not consumer
  * configuration: `danger-full-access` means "do not wrap", and that is a decision belonging to the
@@ -31,6 +18,15 @@ export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access"
  * the two cannot disagree.
  */
 export declare function writableRootsFor(mode: SandboxMode, cwd: string): readonly string[] | null;
+/**
+ * Everything {@link buildBwrapArgv} needs besides the {@link SandboxMode}.
+ *
+ * Only `cwd` is required, and it is resolved to an absolute path before any bind
+ * is emitted. The defaults are the restrictive ones in one direction and the
+ * permissive one in the other: omitting `network` emits `--unshare-net` (no
+ * network), while omitting `env` means the child INHERITS the parent
+ * environment — bwrap only clears it when an allowlist is supplied.
+ */
 export interface BwrapArgvOptions {
     /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
     cwd: string;
@@ -59,6 +55,24 @@ export interface BwrapProbes {
     /** Active user-namespace probe with timeout (sandboxing/src/bwrap.rs:74-136). */
     userns: (bin: string) => boolean;
 }
+/**
+ * Result of {@link detectBwrap} / {@link detectBwrapMemoized}, discriminated on
+ * `ok`: `{ ok: true, bin }` carries the absolute path of the validated `bwrap`,
+ * `{ ok: false, reason }` a human-readable cause — "bwrap not found in PATH",
+ * "bwrap at <bin> lacks --perms support (too old)",
+ * "user namespaces unavailable (container/kernel restriction)",
+ * "bwrap probe failed: <err>", or (memoized only)
+ * "bwrap disappeared from <bin> after detection".
+ *
+ * `reason` is prose for a warning line. It is not a stable code — do not branch
+ * on it.
+ *
+ * `ok: false` is an ordinary outcome rather than an error: bubblewrap is
+ * Linux-only, so failing detection on macOS, on Windows, or inside a container
+ * without user namespaces is expected. Detection NEVER throws, so wrapping it in
+ * `try`/`catch` catches nothing; callers warn and fall back to an unconfined
+ * `LocalSandbox`.
+ */
 export type BwrapDetection = {
     ok: true;
     bin: string;

package/dist/sandbox/index.cjs

@@ -1,9 +1,10 @@
 'use strict';
 
-var chunkQ4RESANI_cjs = require('../chunk-Q4RESANI.cjs');
+var chunkJ24VJOH3_cjs = require('../chunk-J24VJOH3.cjs');
 require('../chunk-2ZPEDVLM.cjs');
-var chunkLPVIRJVF_cjs = require('../chunk-LPVIRJVF.cjs');
-var chunkBM6N4KHO_cjs = require('../chunk-BM6N4KHO.cjs');
+var chunkK3FW2XZD_cjs = require('../chunk-K3FW2XZD.cjs');
+var chunkJTB5Q42C_cjs = require('../chunk-JTB5Q42C.cjs');
+require('../chunk-NUKRL3I6.cjs');
 var child_process = require('child_process');
 var fs = require('fs');
 var path = require('path');
@@ -239,7 +240,7 @@ function allowlistedEnv(source = process.env) {
   }
   return out;
 }
-var LinuxSandbox = class extends chunkQ4RESANI_cjs.LocalSandbox {
+var LinuxSandbox = class extends chunkJ24VJOH3_cjs.LocalSandbox {
   mode;
   network;
   cwd;
@@ -333,7 +334,7 @@ function seccompPathForArch(arch, warn) {
 var seccompFilterPath;
 function restrictedSeccompPath() {
   if (seccompFilterPath !== void 0) return seccompFilterPath ?? void 0;
-  const path2 = seccompPathForArch(process.arch, (m) => console.warn(chunkBM6N4KHO_cjs.redactSecrets(m)));
+  const path2 = seccompPathForArch(process.arch, (m) => console.warn(chunkJTB5Q42C_cjs.redactSecrets(m)));
   seccompFilterPath = path2 ?? null;
   return path2;
 }
@@ -353,17 +354,17 @@ function resolveSandboxPosture(opts) {
 }
 function createSandboxBackend(opts) {
   const config = { workDir: opts.workDir, timeoutMs: opts.timeoutMs };
-  if (opts.mode === "danger-full-access") return new chunkQ4RESANI_cjs.LocalSandbox(config);
+  if (opts.mode === "danger-full-access") return new chunkJ24VJOH3_cjs.LocalSandbox(config);
   const detection = (opts.detect ?? detectBwrapMemoized)();
   if (!detection.ok) {
     if (!warnedUnavailable) {
       warnedUnavailable = true;
-      const warn = opts.warn ?? ((m) => console.warn(chunkBM6N4KHO_cjs.redactSecrets(m)));
+      const warn = opts.warn ?? ((m) => console.warn(chunkJTB5Q42C_cjs.redactSecrets(m)));
       warn(
         `[sandbox] OS-level enforcement unavailable (${detection.reason}) \u2014 falling back to tool-level gating only (sandbox_mode=${opts.mode}).`
       );
     }
-    return new chunkQ4RESANI_cjs.LocalSandbox(config);
+    return new chunkJ24VJOH3_cjs.LocalSandbox(config);
   }
   return new LinuxSandbox(config, { mode: opts.mode, network: opts.network, bin: detection.bin });
 }
@@ -380,7 +381,7 @@ function decideConfinement(opts) {
   if (detection.ok) return detection.bin;
   if (!interactiveWarned) {
     interactiveWarned = true;
-    const warn = opts.warn ?? ((m) => console.warn(chunkBM6N4KHO_cjs.redactSecrets(m)));
+    const warn = opts.warn ?? ((m) => console.warn(chunkJTB5Q42C_cjs.redactSecrets(m)));
     warn(
       `[sandbox] OS-level enforcement unavailable (${detection.reason}) \u2014 interactive session runs WITHOUT kernel confinement (sandbox_mode=${opts.mode}).`
     );
@@ -406,7 +407,7 @@ function interactiveWrapCommand(opts) {
 }
 
 // src/sandbox/provision.ts
-var RepoProvisionError = class extends chunkLPVIRJVF_cjs.TheokitAgentError {
+var RepoProvisionError = class extends chunkK3FW2XZD_cjs.TheokitAgentError {
   constructor(instanceId, message, options = {}) {
     super(`[${instanceId}] ${message}`, {
       code: "repo_provision_failed",
@@ -420,7 +421,7 @@ var RepoProvisionError = class extends chunkLPVIRJVF_cjs.TheokitAgentError {
 };
 var SAFE_INSTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 async function provisionRepo(sandboxOrOpts, maybeOpts) {
-  const sandbox = maybeOpts !== void 0 ? sandboxOrOpts : new chunkQ4RESANI_cjs.LocalSandbox();
+  const sandbox = maybeOpts !== void 0 ? sandboxOrOpts : new chunkJ24VJOH3_cjs.LocalSandbox();
   const opts = maybeOpts ?? sandboxOrOpts;
   const { repoUrl, ref, instanceId } = opts;
   if (!SAFE_INSTANCE_ID.test(instanceId)) {
@@ -433,20 +434,20 @@ async function provisionRepo(sandboxOrOpts, maybeOpts) {
     throw new RepoProvisionError(instanceId, `invalid ref: must not begin with '-' (got ${ref})`);
   }
   const clone = await sandbox.execute(
-    `git -c protocol.ext.allow=never clone --quiet -- ${chunkQ4RESANI_cjs.shellEscapePosix(repoUrl)} ${chunkQ4RESANI_cjs.shellEscapePosix(instanceId)}`
+    `git -c protocol.ext.allow=never clone --quiet -- ${chunkJ24VJOH3_cjs.shellEscapePosix(repoUrl)} ${chunkJ24VJOH3_cjs.shellEscapePosix(instanceId)}`
   );
   if (clone.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `clone failed: ${clone.stderr.trim()}`);
   }
   const top = await sandbox.execute(
-    `git -C ${chunkQ4RESANI_cjs.shellEscapePosix(instanceId)} rev-parse --show-toplevel`
+    `git -C ${chunkJ24VJOH3_cjs.shellEscapePosix(instanceId)} rev-parse --show-toplevel`
   );
   if (top.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `resolve repoDir failed: ${top.stderr.trim()}`);
   }
   const repoDir = top.stdout.trim();
   const checkout = await sandbox.execute(
-    `git -C ${chunkQ4RESANI_cjs.shellEscapePosix(repoDir)} checkout --quiet ${chunkQ4RESANI_cjs.shellEscapePosix(ref)}`
+    `git -C ${chunkJ24VJOH3_cjs.shellEscapePosix(repoDir)} checkout --quiet ${chunkJ24VJOH3_cjs.shellEscapePosix(ref)}`
   );
   if (checkout.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `checkout ${ref} failed: ${checkout.stderr.trim()}`);
@@ -456,23 +457,23 @@ async function provisionRepo(sandboxOrOpts, maybeOpts) {
 
 Object.defineProperty(exports, "LocalSandbox", {
   enumerable: true,
-  get: function () { return chunkQ4RESANI_cjs.LocalSandbox; }
+  get: function () { return chunkJ24VJOH3_cjs.LocalSandbox; }
 });
 Object.defineProperty(exports, "SandboxBackend", {
   enumerable: true,
-  get: function () { return chunkQ4RESANI_cjs.SandboxBackend; }
+  get: function () { return chunkJ24VJOH3_cjs.SandboxBackend; }
 });
 Object.defineProperty(exports, "SandboxNotAvailableError", {
   enumerable: true,
-  get: function () { return chunkQ4RESANI_cjs.SandboxNotAvailableError; }
+  get: function () { return chunkJ24VJOH3_cjs.SandboxNotAvailableError; }
 });
 Object.defineProperty(exports, "SandboxSecurityError", {
   enumerable: true,
-  get: function () { return chunkQ4RESANI_cjs.SandboxSecurityError; }
+  get: function () { return chunkJ24VJOH3_cjs.SandboxSecurityError; }
 });
 Object.defineProperty(exports, "resolveSandbox", {
   enumerable: true,
-  get: function () { return chunkQ4RESANI_cjs.resolveSandbox; }
+  get: function () { return chunkJ24VJOH3_cjs.resolveSandbox; }
 });
 exports.LinuxSandbox = LinuxSandbox;
 exports.RepoProvisionError = RepoProvisionError;