@theokit/sdk 2.15.2 → 2.18.1

package/dist/job-queue.d.ts

@@ -1,8 +1,13 @@
 /**
- * `JobQueue` — background job queue with status tracking.
+ * `JobQueue` — background job queue with status tracking, cancellation, and an
+ * optional concurrency bound.
  *
- * EC-1: all enqueued functions are wrapped in Promise.resolve().then()
- * to ensure synchronous throws become rejections.
+ * EC-1: all enqueued functions are wrapped in Promise.resolve().then() so
+ * synchronous throws become rejections.
+ *
+ * #58: each job runs under an `AbortController` whose signal is passed to the
+ * job fn, so `cancel()` actually interrupts a running job (not just a status
+ * flip); an optional `maxConcurrency` bounds how many jobs run at once.
  */
 type JobStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
 interface Job<T> {
@@ -11,17 +16,34 @@ interface Job<T> {
     result?: T;
     error?: string;
 }
+/** #58 — construction options. */
+export interface JobQueueOptions {
+    /**
+     * Max jobs running concurrently. Omit for unbounded (previous behavior).
+     * Values < 1 are clamped to 1 (an invalid bound must not deadlock).
+     */
+    maxConcurrency?: number;
+}
 export declare class JobQueue {
+    #private;
     private jobs;
+    private controllers;
+    private readonly maxConcurrency;
+    private running;
+    private readonly waiting;
+    constructor(options?: JobQueueOptions);
     /**
-     * Enqueue a background function. Returns the job ID immediately.
-     * EC-1: wraps fn in Promise.resolve().then() so sync throws are caught.
+     * Enqueue a background function. Returns the job ID immediately. The function
+     * receives an `AbortSignal` that fires when the job is cancelled (#58) — a
+     * cooperative job should observe it to stop early. Existing `() => Promise<T>`
+     * callers are unaffected (the signal argument is simply ignored).
      */
-    enqueue<T>(fn: () => Promise<T>): string;
+    enqueue<T>(fn: (signal: AbortSignal) => Promise<T>): string;
     getJob(id: string): Job<unknown> | undefined;
     list(): Job<unknown>[];
     /**
-     * Cancel a pending or running job. Returns true if cancelled.
+     * Cancel a pending or running job. Returns true if cancelled. #58 — aborts the
+     * job's `AbortSignal` so a cooperative running job is actually interrupted.
      */
     cancel(id: string): boolean;
 }

package/dist/permission-engine.d.ts

@@ -1,29 +1,54 @@
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
- * Evaluates a tool name against an ordered list of rules. First matching rule
- * wins; when no rule matches the `defaultAction` is returned (M7-4 — default
- * `"allow"`, opt into default-deny via `{ defaultAction: "deny" }`).
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
  */
 export type PermissionAction = "allow" | "deny" | "ask";
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+export type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
 export interface PermissionRule {
     /** Tool name (exact string) or pattern (RegExp). */
     tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
     /** Action to take when rule matches. */
     action: PermissionAction;
 }
 /** Options for {@link PermissionEngine}. */
 export interface PermissionEngineOptions {
-    /** Action when no rule matches. Default `"allow"` (backward-compatible). M7-4. */
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
     readonly defaultAction?: PermissionAction;
 }
 export declare class PermissionEngine {
+    #private;
     private readonly rules;
     private readonly defaultAction;
     constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
     /**
-     * Evaluate a tool name against the rules. First match wins; falls back to the
-     * configured `defaultAction` (default `"allow"`) when no rule matches.
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
      */
-    evaluate(toolName: string): PermissionAction;
+    evaluate(toolName: string, args?: Record<string, unknown>): PermissionAction;
 }

package/dist/{run-DXy_MVwz.d.cts → run-pE-34AAo.d.cts}

@@ -1,3 +1,23 @@
+/**
+ * #57 — content-level defense for tool results before they reach the LLM.
+ *
+ * Two opt-in behaviors, applied at the `transform_tool_result` seam (#65):
+ *  - `delimit`: wrap untrusted tool output in explicit data boundaries
+ *    ("spotlighting") so the model treats it as DATA, not instructions — the
+ *    primary mitigation against tool-result prompt injection. Non-destructive:
+ *    the content is preserved, only framed. A boundary marker appearing inside
+ *    the content is neutralized so it cannot break out of the frame.
+ *  - `redactPii`: replace common PII patterns (email, phone) with `[REDACTED]`.
+ *
+ * @internal
+ */
+interface ToolResultGuardOptions {
+    /** Wrap tool-result content in explicit data boundaries (spotlighting). */
+    delimit?: boolean;
+    /** Redact common PII patterns (email, phone) in tool-result content. */
+    redactPii?: boolean;
+}
+
 /**
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
@@ -55,9 +75,13 @@ interface CustomTool {
      * Local handler invoked when the model emits `tool_use` for this tool.
      * Returns a string (becomes the `tool_result.content` surfaced back to the
      * model). Throws → SDK converts to `tool_result` with `isError: true` and
-     * the error `message` as content.
+     * the error `message` as content. #65 — an optional 2nd `ToolContext`
+     * argument carries the run's `AbortSignal`; single-argument handlers are
+     * unaffected.
      */
-    handler: (input: Record<string, unknown>) => string | Promise<string>;
+    handler: (input: Record<string, unknown>, ctx?: {
+        signal?: AbortSignal;
+    }) => string | Promise<string>;
 }
 
 /**
@@ -341,6 +365,20 @@ type McpStdioServerConfig = {
     env?: Record<string, string>;
     /** Local agents only. Cloud rejects this field. */
     cwd?: string;
+    /**
+     * #59 — per-request timeout in ms. A request that gets no reply within this
+     * window rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead
+     * of hanging the agent loop forever. Default 30_000.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * #54 — env inherit/scrub policy for the spawned MCP server process. Defaults
+     * to `"inherit-scrubbed"` (drop secret-like host vars: `*KEY*`/`*SECRET*`/
+     * `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`/…) so a third-party MCP server binary cannot
+     * exfiltrate host secrets via the environment. `env` above is merged AFTER the
+     * policy and always wins. Pass `"all"` to restore full inheritance.
+     */
+    envPolicy?: undefined;
 };
 /**
  * OAuth-style auth bundle for HTTP/SSE MCP servers.
@@ -386,6 +424,12 @@ type McpHttpServerConfig = {
     /** Passed through. `Authorization` works here. */
     headers?: Record<string, string>;
     auth?: McpAuthConfig;
+    /**
+     * #59 — per-request timeout in ms, enforced via `AbortSignal.timeout`. A
+     * fetch that does not respond within this window rejects with a typed
+     * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
+     */
+    requestTimeoutMs?: number;
 };
 /**
  * Union of MCP server configs. See `docs.md` for the full reference.
@@ -874,6 +918,23 @@ interface SendOptions {
      * @public
      */
     signal?: AbortSignal;
+    /**
+     * #58 — per-tool execution timeout in ms. Each tool call is bounded by this
+     * deadline (merged with `signal`); a hung tool yields a typed timeout result
+     * (exit 124) instead of wedging the run. Undefined = no per-tool timeout.
+     *
+     * @public
+     */
+    perToolTimeoutMs?: number;
+    /**
+     * #57 — opt-in tool-result content guard applied before tool output reaches
+     * the LLM. `{ delimit: true }` frames untrusted tool output as data
+     * (prompt-injection mitigation); `{ redactPii: true }` redacts email/phone.
+     * Undefined = no guard.
+     *
+     * @public
+     */
+    toolResultGuard?: ToolResultGuardOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —
@@ -937,4 +998,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolUseBlock as a7, TurnEndedUpdate as a8, UserMessage as a9, UserMessageAppendedUpdate as aa, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };
+export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolResultGuardOptions as a7, ToolUseBlock as a8, TurnEndedUpdate as a9, UserMessage as aa, UserMessageAppendedUpdate as ab, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };

package/dist/{run-DXy_MVwz.d.ts → run-pE-34AAo.d.ts}

@@ -1,3 +1,23 @@
+/**
+ * #57 — content-level defense for tool results before they reach the LLM.
+ *
+ * Two opt-in behaviors, applied at the `transform_tool_result` seam (#65):
+ *  - `delimit`: wrap untrusted tool output in explicit data boundaries
+ *    ("spotlighting") so the model treats it as DATA, not instructions — the
+ *    primary mitigation against tool-result prompt injection. Non-destructive:
+ *    the content is preserved, only framed. A boundary marker appearing inside
+ *    the content is neutralized so it cannot break out of the frame.
+ *  - `redactPii`: replace common PII patterns (email, phone) with `[REDACTED]`.
+ *
+ * @internal
+ */
+interface ToolResultGuardOptions {
+    /** Wrap tool-result content in explicit data boundaries (spotlighting). */
+    delimit?: boolean;
+    /** Redact common PII patterns (email, phone) in tool-result content. */
+    redactPii?: boolean;
+}
+
 /**
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
@@ -55,9 +75,13 @@ interface CustomTool {
      * Local handler invoked when the model emits `tool_use` for this tool.
      * Returns a string (becomes the `tool_result.content` surfaced back to the
      * model). Throws → SDK converts to `tool_result` with `isError: true` and
-     * the error `message` as content.
+     * the error `message` as content. #65 — an optional 2nd `ToolContext`
+     * argument carries the run's `AbortSignal`; single-argument handlers are
+     * unaffected.
      */
-    handler: (input: Record<string, unknown>) => string | Promise<string>;
+    handler: (input: Record<string, unknown>, ctx?: {
+        signal?: AbortSignal;
+    }) => string | Promise<string>;
 }
 
 /**
@@ -341,6 +365,20 @@ type McpStdioServerConfig = {
     env?: Record<string, string>;
     /** Local agents only. Cloud rejects this field. */
     cwd?: string;
+    /**
+     * #59 — per-request timeout in ms. A request that gets no reply within this
+     * window rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead
+     * of hanging the agent loop forever. Default 30_000.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * #54 — env inherit/scrub policy for the spawned MCP server process. Defaults
+     * to `"inherit-scrubbed"` (drop secret-like host vars: `*KEY*`/`*SECRET*`/
+     * `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`/…) so a third-party MCP server binary cannot
+     * exfiltrate host secrets via the environment. `env` above is merged AFTER the
+     * policy and always wins. Pass `"all"` to restore full inheritance.
+     */
+    envPolicy?: undefined;
 };
 /**
  * OAuth-style auth bundle for HTTP/SSE MCP servers.
@@ -386,6 +424,12 @@ type McpHttpServerConfig = {
     /** Passed through. `Authorization` works here. */
     headers?: Record<string, string>;
     auth?: McpAuthConfig;
+    /**
+     * #59 — per-request timeout in ms, enforced via `AbortSignal.timeout`. A
+     * fetch that does not respond within this window rejects with a typed
+     * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
+     */
+    requestTimeoutMs?: number;
 };
 /**
  * Union of MCP server configs. See `docs.md` for the full reference.
@@ -874,6 +918,23 @@ interface SendOptions {
      * @public
      */
     signal?: AbortSignal;
+    /**
+     * #58 — per-tool execution timeout in ms. Each tool call is bounded by this
+     * deadline (merged with `signal`); a hung tool yields a typed timeout result
+     * (exit 124) instead of wedging the run. Undefined = no per-tool timeout.
+     *
+     * @public
+     */
+    perToolTimeoutMs?: number;
+    /**
+     * #57 — opt-in tool-result content guard applied before tool output reaches
+     * the LLM. `{ delimit: true }` frames untrusted tool output as data
+     * (prompt-injection mitigation); `{ redactPii: true }` redacts email/phone.
+     * Undefined = no guard.
+     *
+     * @public
+     */
+    toolResultGuard?: ToolResultGuardOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —
@@ -937,4 +998,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolUseBlock as a7, TurnEndedUpdate as a8, UserMessage as a9, UserMessageAppendedUpdate as aa, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };
+export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolResultGuardOptions as a7, ToolUseBlock as a8, TurnEndedUpdate as a9, UserMessage as aa, UserMessageAppendedUpdate as ab, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };

package/dist/sandbox/index.cjs

@@ -6,6 +6,53 @@ var path = require('path');
 
 // src/sandbox/local-sandbox.ts
 
+// src/internal/runtime/lifecycle/env-policy.ts
+var SECRET_PATTERNS = [
+  /KEY/i,
+  /SECRET/i,
+  /TOKEN/i,
+  /PASSWORD/i,
+  /PASSWD/i,
+  /PASSPHRASE/i,
+  /[_-]PWD/i,
+  /CREDENTIAL/i,
+  /PRIVATE/i,
+  /_AUTH/i
+];
+var CORE_VARS = [
+  "PATH",
+  "HOME",
+  "SHELL",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "USER",
+  "LOGNAME"
+];
+function isSecretName(name) {
+  return SECRET_PATTERNS.some((re) => re.test(name));
+}
+function inheritsUnderPolicy(name, policy) {
+  if (policy === "all") return true;
+  if (policy === "core") return CORE_VARS.includes(name);
+  return !isSecretName(name);
+}
+function resolveChildEnv(options = {}) {
+  const parent = options.parent ?? process.env;
+  const policy = options.policy ?? "inherit-scrubbed";
+  const base = {};
+  for (const [name, value] of Object.entries(parent)) {
+    if (value !== void 0 && inheritsUnderPolicy(name, policy)) base[name] = value;
+  }
+  for (const [name, value] of Object.entries(options.overrides ?? {})) {
+    base[name] = value;
+  }
+  return base;
+}
+
 // src/sandbox/shell-escape.ts
 function shellEscapePosix(arg) {
   return `'${arg.replace(/'/g, "'\\''")}'`;
@@ -33,7 +80,9 @@ var SandboxBackend = class {
     this.config = {
       workDir: config.workDir ?? "/tmp",
       timeoutMs: config.timeoutMs ?? 3e4,
-      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024
+      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,
+      // #54 — preserve the env policy so backends can scrub secrets.
+      env: config.env ?? "inherit-scrubbed"
     };
   }
   async readFile(path) {
@@ -103,7 +152,9 @@ var LocalSandbox = class extends SandboxBackend {
           cwd: this.config.workDir,
           timeout,
           maxBuffer: max,
-          encoding: "utf-8"
+          encoding: "utf-8",
+          // #54 — scrub secret-like host env vars from the child by default.
+          env: resolveChildEnv({ policy: this.config.env })
         },
         (error, stdout, stderr) => {
           resolve(this.buildResult(error, stdout ?? "", stderr ?? ""));

package/dist/sandbox/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/sandbox/shell-escape.ts","../../src/sandbox/types.ts","../../src/sandbox/local-sandbox.ts","../../src/errors.ts","../../src/sandbox/provision.ts"],"names":["execFile","path","mkdir","dirname","fsWriteFile"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n}\n\nexport class SandboxSecurityError extends Error {\n  readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxSecurityError\";\n  }\n}\n\nexport class SandboxNotAvailableError extends Error {\n  readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxNotAvailableError\";\n  }\n}\n\nconst SHELL_METACHARACTERS = /[;&|`$(){}]/;\n\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  protected validateCommand(command: string): void {\n    if (SHELL_METACHARACTERS.test(command)) {\n      throw new SandboxSecurityError(\n        `Command contains shell metacharacters: ${command.slice(0, 80)}`,\n      );\n    }\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n","/**\n * LocalSandbox — subprocess-based execution with NO isolation.\n *\n * Uses `execFile` with split args (NOT `exec` with string) per EC-1.\n * This is NOT a security boundary — only DockerSandbox provides isolation.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    return {\n      stdout: this.truncateOutput(stdout),\n      stderr: this.truncateOutput(stderr),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n","import { defaultRetriableForCode } from \"./internal/default-retriable.js\";\nimport { redactSecrets } from \"./internal/security/redact.js\";\nimport type { RunOperation } from \"./types/run.js\";\n\n/**\n * Finite, machine-readable error codes for provider-originated errors\n * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively\n * — adding a new variant is an explicit decision + test coverage.\n *\n * @public\n */\nexport type ErrorCode =\n  | \"rate_limit\"\n  | \"auth_failed\"\n  | \"invalid_request\"\n  | \"timeout\"\n  | \"server_error\"\n  | \"context_too_long\"\n  | \"content_filtered\"\n  | \"model_unavailable\"\n  | \"network\"\n  | \"quota_exceeded\"\n  | \"unknown\";\n\n/**\n * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).\n *\n * Superset of {@link ErrorCode} extended with codes that do NOT originate\n * from a provider HTTP response:\n *\n * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)\n * - `tool_runtime_error` — custom tool handler threw inside dispatch\n * - `aborted` — caller's `AbortSignal` fired (Phase 4)\n * - `invalid_model` — model id rejected by provider (400 \"model not found\")\n * - `safety_blocked` — provider safety filter blocked req or resp\n * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary\n *\n * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while\n * accepting any string for forward compatibility with constructor calls\n * that pass arbitrary code values (legacy callers).\n *\n * @public\n */\n/**\n * T1.1 — closed literal union for `AgentRunError.code`. The previous\n * `(string & {})` escape hatch let arbitrary strings slip into the type\n * surface and defeated exhaustive `switch (code)` discrimination. This is\n * the canonical closed form. `AgentRunErrorCode` is re-aliased below for\n * source-level back-compat.\n *\n * Adding a new code: append the literal here AND audit every `switch (err.code)`\n * in callers. Type-checker enforces the audit via the `default: assertNever(code)`\n * convention.\n *\n * @public\n */\nexport type KnownAgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\";\n\n/**\n * Back-compat alias of {@link KnownAgentRunErrorCode}. Pre-T1.1 callers that\n * imported `AgentRunErrorCode` keep working; new code SHOULD prefer\n * `KnownAgentRunErrorCode` to make the closed-union intent explicit.\n *\n * @public\n */\nexport type AgentRunErrorCode = KnownAgentRunErrorCode;\n\n/** Snapshot of every known code at runtime — used by the boundary coercer. */\nconst KNOWN_AGENT_RUN_ERROR_CODES = new Set<string>([\n  \"rate_limit\",\n  \"auth_failed\",\n  \"invalid_request\",\n  \"timeout\",\n  \"server_error\",\n  \"context_too_long\",\n  \"content_filtered\",\n  \"model_unavailable\",\n  \"network\",\n  \"unknown\",\n  \"quota_exceeded\",\n  \"tool_runtime_error\",\n  \"aborted\",\n  \"invalid_model\",\n  \"safety_blocked\",\n  \"provider_unreachable\",\n]);\n\n/**\n * T1.1 boundary helper — coerce an arbitrary string (typically arriving from\n * a downstream `RunErrorDetail.code` or a deserialized cloud response) into a\n * `KnownAgentRunErrorCode`. Unknown strings collapse to `\"unknown\"` so the\n * closed type contract holds without forcing every caller to switch.\n *\n * @internal\n */\nexport function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode {\n  if (code !== undefined && KNOWN_AGENT_RUN_ERROR_CODES.has(code)) {\n    return code as KnownAgentRunErrorCode;\n  }\n  return \"unknown\";\n}\n\n/**\n * Structured context for errors that originated from a provider HTTP\n * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),\n * surface actionable diagnostics (`provider`, `endpoint`), and inspect the\n * raw response body when needed (`raw`, capped at ~2KB by the mapper).\n *\n * @public\n */\nexport interface ErrorMetadata {\n  /** Provider canonical name (e.g., `\"anthropic\"`, `\"openai\"`, `\"openrouter\"`, `\"gemini\"`). */\n  provider: string;\n  /** HTTP endpoint that failed (e.g., `\"/v1/messages\"`, `\"/v1/chat/completions\"`). */\n  endpoint: string;\n  /** Machine-readable error code (finite enum). */\n  code: ErrorCode;\n  /** HTTP status code if applicable. */\n  statusCode?: number;\n  /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */\n  retryAfter?: number;\n  /** Raw response body for debugging (truncated to ~2KB by the mapper). */\n  raw?: unknown;\n}\n\n/**\n * Base class for all errors thrown by `@theokit/sdk`.\n *\n * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`\n * are populated for server-originated errors when available. `metadata`\n * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when\n * the error originated from a provider HTTP call.\n *\n * @public\n */\nexport class TheokitAgentError extends Error {\n  override readonly name: string = \"TheokitAgentError\";\n  readonly isRetryable: boolean;\n  readonly code?: string;\n  readonly protoErrorCode?: string;\n  readonly metadata?: ErrorMetadata;\n\n  constructor(\n    message: string,\n    options: {\n      isRetryable?: boolean;\n      code?: string;\n      protoErrorCode?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    } = {},\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.isRetryable = options.isRetryable ?? false;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.protoErrorCode !== undefined) this.protoErrorCode = options.protoErrorCode;\n    if (options.metadata !== undefined) this.metadata = options.metadata;\n  }\n}\n\n/**\n * Invalid API key, not logged in, insufficient permissions.\n *\n * @public\n */\nexport class AuthenticationError extends TheokitAgentError {\n  override readonly name: string = \"AuthenticationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Too many requests or usage limits exceeded.\n *\n * @public\n */\nexport class RateLimitError extends TheokitAgentError {\n  override readonly name: string = \"RateLimitError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Invalid model, bad request parameters, malformed options.\n *\n * @public\n */\nexport class ConfigurationError extends TheokitAgentError {\n  override readonly name: string = \"ConfigurationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown when creating a cloud agent for a repo whose SCM provider is not\n * connected. Use `helpUrl` to point the user at the right reconnect flow.\n *\n * @public\n */\nexport class IntegrationNotConnectedError extends ConfigurationError {\n  override readonly name: string = \"IntegrationNotConnectedError\";\n  readonly provider: string;\n  readonly helpUrl: string;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      helpUrl: string;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, options);\n    this.provider = options.provider;\n    this.helpUrl = options.helpUrl;\n  }\n}\n\n/**\n * Service unavailable, timeout, transport-level failure.\n *\n * @public\n */\nexport class NetworkError extends TheokitAgentError {\n  override readonly name: string = \"NetworkError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Catch-all for unclassified server or runtime errors.\n *\n * @public\n */\nexport class UnknownAgentError extends TheokitAgentError {\n  override readonly name: string = \"UnknownAgentError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when\n * the option `{ throwOnError: true }` is set and the run terminates with\n * `status: 'error'`. Carries the structured `RunResult.error` fields so\n * callers can `catch` once and branch on `code` / `provider` instead of\n * unwrapping the run.\n *\n * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.\n *\n * @example\n *   try {\n *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });\n *   } catch (err) {\n *     if (err instanceof AgentRunError && err.code === 'auth_failed') {\n *       // bad key\n *     }\n *   }\n *\n * @public\n */\nexport class AgentRunError extends TheokitAgentError {\n  override readonly name: string = \"AgentRunError\";\n  readonly provider?: string;\n  readonly raw?: string;\n  /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */\n  readonly requestId?: string;\n  /** SDK conversation id this error was raised inside. */\n  readonly conversationId?: string;\n\n  constructor(\n    message: string,\n    options: {\n      code: AgentRunErrorCode;\n      provider?: string;\n      raw?: string;\n      requestId?: string;\n      conversationId?: string;\n      retriable?: boolean;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      code: options.code,\n      cause: options.cause,\n      metadata: options.metadata,\n      // D311: most AgentRunErrors are not retriable (auth, validation, abort).\n      // Provider mappers (D314) override per-status — explicit `retriable` wins\n      // over the implicit default when supplied.\n      isRetryable: options.retriable ?? defaultRetriableForCode(options.code),\n    });\n    if (options.provider !== undefined) this.provider = options.provider;\n    if (options.raw !== undefined) this.raw = options.raw;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n    if (options.conversationId !== undefined) this.conversationId = options.conversationId;\n  }\n\n  /**\n   * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as\n   * `retriable` to match the handoff contract. Future v2 will deprecate\n   * `isRetryable` in favor of this.\n   */\n  get retriable(): boolean {\n    return this.isRetryable;\n  }\n\n  /**\n   * D312: provider's `Retry-After` header in **milliseconds**. Mappers store\n   * the header value (seconds) in `metadata.retryAfter`; this getter\n   * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.\n   *\n   * Returns `undefined` when no hint was provided. `0` is a legitimate value\n   * — use `=== undefined` check rather than truthy check.\n   */\n  get retryAfterMs(): number | undefined {\n    if (this.metadata?.retryAfter === undefined) return undefined;\n    return this.metadata.retryAfter * 1000;\n  }\n\n  /**\n   * D313 + T1.5: alias for `metadata.raw`. Provider response body for\n   * debugging. T1.5 wraps the value in `redactSecrets` at the getter\n   * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are\n   * stripped before reaching the caller. Available but NEVER serialized\n   * into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    const raw = this.metadata?.raw;\n    if (raw === undefined) return undefined;\n    if (typeof raw === \"string\") return redactSecrets(raw);\n    // Non-string raw (object/buffer) — stringify then redact.\n    try {\n      return redactSecrets(JSON.stringify(raw));\n    } catch {\n      return redactSecrets(String(raw));\n    }\n  }\n\n  /**\n   * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt\n   * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw\n   * payload for diagnostics. Every other field stays accessible.\n   *\n   * The single env-var gate is read each call so operators can toggle at\n   * runtime without restarting the process.\n   */\n  toJSON(): Record<string, unknown> {\n    const json: Record<string, unknown> = {\n      name: this.name,\n      message: this.message,\n      isRetryable: this.isRetryable,\n    };\n    addOptionalFields(json, this);\n    const safeMeta = sanitizeMetadata(this.metadata);\n    if (safeMeta !== undefined) json.metadata = safeMeta;\n    return json;\n  }\n}\n\nfunction addOptionalFields(json: Record<string, unknown>, err: AgentRunError): void {\n  if (err.code !== undefined) json.code = err.code;\n  if (err.provider !== undefined) json.provider = err.provider;\n  if (err.requestId !== undefined) json.requestId = err.requestId;\n  if (err.conversationId !== undefined) json.conversationId = err.conversationId;\n  if (err.raw !== undefined) json.raw = redactSecrets(err.raw);\n}\n\nfunction sanitizeMetadata(meta: ErrorMetadata | undefined): ErrorMetadata | undefined {\n  if (meta === undefined) return undefined;\n  const { raw, ...rest } = meta;\n  const debugRaw = process.env.THEOKIT_DEBUG_RAW_ERRORS === \"1\";\n  if (debugRaw && raw !== undefined) {\n    const redactedRaw =\n      typeof raw === \"string\" ? redactSecrets(raw) : redactSecrets(safeStringify(raw));\n    return { ...rest, raw: redactedRaw } as ErrorMetadata;\n  }\n  return rest as ErrorMetadata;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * Is this error transient (worth retrying)?\n *\n * Returns the SDK's own retryability verdict: every {@link TheokitAgentError}\n * subclass computes `isRetryable` at construction (rate-limit / network /\n * credential-pool-exhausted are retryable; auth / configuration / unsupported\n * are not), so this predicate is a single source of truth rather than a\n * re-derivation. Non-SDK errors return `false` conservatively — wrap a foreign\n * error in the appropriate SDK error first if you want it considered transient.\n * It never inspects `err.message`.\n *\n * @example\n *   try {\n *     await agent.send(message, { throwOnError: true });\n *   } catch (err) {\n *     if (isTransientError(err)) return retryWithBackoff();\n *     throw err;\n *   }\n *\n * @public\n */\nexport function isTransientError(err: unknown): boolean {\n  return err instanceof TheokitAgentError && err.isRetryable === true;\n}\n\n/**\n * Thrown when a {@link Run} or agent operation is not available on the current\n * runtime. Check first with `run.supports(operation)`.\n *\n * Extends {@link TheokitAgentError} (so error-catching code that branches on\n * `instanceof TheokitAgentError` continues to work) but is never retryable —\n * an unsupported operation will not become supported on retry.\n *\n * @public\n */\nexport class UnsupportedRunOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedRunOperationError\";\n  readonly operation: RunOperation;\n\n  constructor(\n    message: string,\n    operation: RunOperation,\n    options: { code?: string; cause?: unknown } = {},\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: options.code ?? \"unsupported_run_operation\",\n    });\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown when every credential in a per-provider pool is in cooldown\n * and no healthy key is available (ADR D133). The caller's\n * {@link import(\"./internal/llm/fallback-client.js\").FallbackLlmClient}\n * catches this and tries the next provider in the fallback chain.\n *\n * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest\n * pool entry resumes — useful for manual retry scheduling.\n *\n * @public\n */\nexport class CredentialPoolExhaustedError extends TheokitAgentError {\n  override readonly name: string = \"CredentialPoolExhaustedError\";\n  readonly provider: string;\n  readonly nextRetryAt: number | undefined;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      nextRetryAt?: number;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: true,\n      code: options.code ?? \"credential_pool_exhausted\",\n    });\n    this.provider = options.provider;\n    this.nextRetryAt = options.nextRetryAt;\n  }\n}\n\n/**\n * Finite error codes specific to memory adapter operations (ADR D141).\n *\n * @public\n */\nexport type MemoryAdapterErrorCode =\n  | \"auth_failed\"\n  | \"rate_limited\"\n  | \"not_found\"\n  | \"network\"\n  | \"invalid_input\"\n  | \"unknown\";\n\n/**\n * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`\n * so callers can branch on which provider failed (ADR D141).\n *\n * @public\n */\nexport class MemoryAdapterError extends TheokitAgentError {\n  override readonly name: string = \"MemoryAdapterError\";\n  readonly adapterId: string;\n\n  constructor(\n    message: string,\n    options: {\n      adapterId: string;\n      code: MemoryAdapterErrorCode;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      isRetryable: options.code === \"rate_limited\" || options.code === \"network\",\n      code: options.code,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n      ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),\n    });\n    this.adapterId = options.adapterId;\n  }\n}\n\n/**\n * Thrown when a user-supplied task ID violates the grammar\n * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter\n * prefix (`wf-` / `b-` / `cron-`, EC-5).\n *\n * @public\n */\nexport class InvalidTaskIdError extends TheokitAgentError {\n  override readonly name: string = \"InvalidTaskIdError\";\n  readonly taskId: string;\n\n  constructor(message: string, taskId: string, options: { cause?: unknown } = {}) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: \"invalid_task_id\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `Task.subscribe(id)` is called for a task that has been\n * evicted, never submitted, or evicted after retention (D373).\n *\n * @public\n */\nexport class TaskNotFoundError extends TheokitAgentError {\n  override readonly name: string = \"TaskNotFoundError\";\n  readonly taskId: string;\n\n  constructor(taskId: string, options: { cause?: unknown } = {}) {\n    super(`Task not found: ${taskId}`, {\n      ...options,\n      isRetryable: false,\n      code: \"task_not_found\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud\n * task observability is deferred until Theo PaaS GA.\n *\n * @public\n */\nexport class UnsupportedTaskOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedTaskOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Task operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D370)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"task_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. Caller pega\n * tipado para retry-after-window-reset or surface to the user.\n *\n * @public\n */\nexport class BudgetExceededError extends TheokitAgentError {\n  override readonly name: string = \"BudgetExceededError\";\n  readonly budgetName: string;\n  readonly window: import(\"./types/budget.js\").BudgetWindow;\n  readonly spentUsd: number;\n  readonly limitUsd: number;\n  readonly mode: import(\"./types/budget.js\").BudgetMode;\n\n  constructor(args: {\n    budgetName: string;\n    window: import(\"./types/budget.js\").BudgetWindow;\n    spentUsd: number;\n    limitUsd: number;\n    mode: import(\"./types/budget.js\").BudgetMode;\n    cause?: unknown;\n  }) {\n    super(\n      `Budget \"${args.budgetName}\" exceeded for window ${args.window}: spent $${args.spentUsd.toFixed(4)} > limit $${args.limitUsd.toFixed(4)}`,\n      {\n        ...(args.cause !== undefined ? { cause: args.cause } : {}),\n        isRetryable: false,\n        code: \"budget_exceeded\",\n      },\n    );\n    this.budgetName = args.budgetName;\n    this.window = args.window;\n    this.spentUsd = args.spentUsd;\n    this.limitUsd = args.limitUsd;\n    this.mode = args.mode;\n  }\n}\n\n/**\n * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud\n * budget surface waits for Theo PaaS GA.\n *\n * @public\n */\n/**\n * T1.6 — Thrown when a consumer calls `agent.send()` or any method\n * on an agent that has already been `dispose()`d. Pre-T1.6 this was\n * a generic `new Error(\"Agent has been disposed\")` — consumers\n * couldn't catch it without string-matching the message.\n *\n * @public\n */\nexport class AgentDisposedError extends TheokitAgentError {\n  override readonly name: string = \"AgentDisposedError\";\n  readonly agentId: string;\n\n  constructor(agentId: string) {\n    super(`Agent \"${agentId}\" has been disposed. Create a new agent or use Agent.resume().`, {\n      isRetryable: false,\n      code: \"agent_disposed\",\n    });\n    this.agentId = agentId;\n  }\n}\n\nexport class UnsupportedBudgetOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedBudgetOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Budget operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D388)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"budget_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n","/**\n * M6-3 — portable repo provisioner for the eval harness.\n *\n * Clones a repository and checks out a ref into an isolated working dir, issuing\n * every git command through {@link SandboxBackend.execute} (ADR D2 — same code\n * runs on Local/Docker/E2B; never a direct `child_process` import). Promotes\n * theocode's `prepareRepo` (`swebench-provision.ts:37`) onto the SDK's sandbox\n * abstraction.\n *\n * referencia: knowledge-base/references/theocode-eval/lib/swebench-provision.ts:37\n * (clone+checkout), :13 (ProvisionError with instanceId).\n *\n * @public\n */\n\nimport { TheokitAgentError } from \"../errors.js\";\nimport { LocalSandbox } from \"./local-sandbox.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\nimport type { SandboxBackend } from \"./types.js\";\n\n/**\n * Raised when cloning or checking out a repo fails. Carries the `instanceId`\n * so a batch run can attribute the failure to the offending dataset row.\n */\nexport class RepoProvisionError extends TheokitAgentError {\n  override readonly name = \"RepoProvisionError\";\n\n  constructor(\n    readonly instanceId: string,\n    message: string,\n    options: { cause?: unknown } = {},\n  ) {\n    super(`[${instanceId}] ${message}`, {\n      code: \"repo_provision_failed\",\n      isRetryable: false,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n    });\n  }\n}\n\n/** Options for {@link provisionRepo}. */\nexport interface ProvisionRepoOptions {\n  /**\n   * Clonable repo URL or local path. SECURITY: when this comes from an\n   * untrusted dataset, the value is passed to `git clone` after a `--`\n   * end-of-options terminator (no flag injection) and with the `ext::`\n   * transport disabled (no arbitrary-command transport).\n   */\n  readonly repoUrl: string;\n  /** Branch, tag, or commit SHA to check out. Rejected if it begins with `-`. */\n  readonly ref: string;\n  /**\n   * Unique id for this row — names the target dir and any error. Validated to\n   * `[A-Za-z0-9._-]` (no path traversal) since it becomes a directory name.\n   */\n  readonly instanceId: string;\n}\n\n/**\n * Reject ids that would escape the workdir or be parsed as a git flag. Must\n * start with an alphanumeric (blocks `.`, `..`, `-foo`, leading-dot names) and\n * thereafter allow only `[A-Za-z0-9._-]`.\n */\nconst SAFE_INSTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\n\n/**\n * Clone `repoUrl` into `<sandbox workdir>/<instanceId>` and check out `ref`.\n * Returns the absolute `repoDir` (resolved via `git rev-parse --show-toplevel`,\n * which is portable across backends). Throws {@link RepoProvisionError} naming\n * the `instanceId` when clone or checkout exits non-zero.\n *\n * The `sandbox` is optional (V3-5): when omitted, a default {@link LocalSandbox}\n * is used (clones into the process cwd's `<instanceId>`) — pass an explicit\n * sandbox (e.g. `LocalSandbox({ workDir })` / Docker / E2B) to control the workdir.\n */\nexport function provisionRepo(opts: ProvisionRepoOptions): Promise<{ repoDir: string }>;\nexport function provisionRepo(\n  sandbox: SandboxBackend,\n  opts: ProvisionRepoOptions,\n): Promise<{ repoDir: string }>;\nexport async function provisionRepo(\n  sandboxOrOpts: SandboxBackend | ProvisionRepoOptions,\n  maybeOpts?: ProvisionRepoOptions,\n): Promise<{ repoDir: string }> {\n  const sandbox = maybeOpts !== undefined ? (sandboxOrOpts as SandboxBackend) : new LocalSandbox();\n  const opts = maybeOpts ?? (sandboxOrOpts as ProvisionRepoOptions);\n  const { repoUrl, ref, instanceId } = opts;\n\n  // Validate untrusted-derivable inputs before they reach git/the shell.\n  if (!SAFE_INSTANCE_ID.test(instanceId)) {\n    throw new RepoProvisionError(\n      instanceId,\n      \"invalid instanceId: must match [A-Za-z0-9._-] (no path traversal)\",\n    );\n  }\n  if (ref.startsWith(\"-\")) {\n    throw new RepoProvisionError(instanceId, `invalid ref: must not begin with '-' (got ${ref})`);\n  }\n\n  // `--` terminates options (no `--upload-pack=` flag injection); `protocol.ext.allow=never`\n  // blocks the `ext::` arbitrary-command transport. `file`/`https` stay allowed.\n  const clone = await sandbox.execute(\n    `git -c protocol.ext.allow=never clone --quiet -- ${shellEscapePosix(repoUrl)} ${shellEscapePosix(instanceId)}`,\n  );\n  if (clone.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `clone failed: ${clone.stderr.trim()}`);\n  }\n\n  const top = await sandbox.execute(\n    `git -C ${shellEscapePosix(instanceId)} rev-parse --show-toplevel`,\n  );\n  if (top.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `resolve repoDir failed: ${top.stderr.trim()}`);\n  }\n  const repoDir = top.stdout.trim();\n\n  // `ref` is validated above not to begin with `-`, so it cannot be parsed as a flag.\n  const checkout = await sandbox.execute(\n    `git -C ${shellEscapePosix(repoDir)} checkout --quiet ${shellEscapePosix(ref)}`,\n  );\n  if (checkout.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `checkout ${ref} failed: ${checkout.stderr.trim()}`);\n  }\n\n  return { repoDir };\n}\n"]}
+{"version":3,"sources":["../../src/internal/runtime/lifecycle/env-policy.ts","../../src/sandbox/shell-escape.ts","../../src/sandbox/types.ts","../../src/sandbox/local-sandbox.ts","../../src/errors.ts","../../src/sandbox/provision.ts"],"names":["execFile","path","mkdir","dirname","fsWriteFile"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Child-process environment policy (#54).\n *\n * Every subprocess the SDK spawns previously inherited the FULL `process.env`,\n * so API keys, tokens and passwords leaked into hook scripts and shell tools.\n * `resolveChildEnv` computes the env a child receives under an explicit policy,\n * modeled on codex's `ShellEnvironmentPolicy`\n * (referencia: codex/codex-rs/protocol/src/shell_environment.rs).\n *\n * Modes:\n *  - `inherit-scrubbed` (DEFAULT) — inherit all parent vars EXCEPT secret-like\n *    names (`*KEY*`, `*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Non-breaking:\n *    existing spawns keep every non-secret var; only secrets stop leaking.\n *  - `core` — inherit ONLY a safe base allowlist (PATH/HOME/…); strongest scrub.\n *  - `all` — explicit opt-out: inherit everything, secrets included.\n *\n * Explicit `overrides` ALWAYS win (merged last), so a tool can re-inject a var\n * it genuinely needs even under a scrubbing policy.\n *\n * @internal\n */\n\nexport type EnvPolicy = \"inherit-scrubbed\" | \"core\" | \"all\";\n\nexport interface ResolveChildEnvOptions {\n  /** Source env to derive from. Defaults to `process.env`. */\n  parent?: Record<string, string | undefined>;\n  /** Inherit/scrub policy. Defaults to `inherit-scrubbed`. */\n  policy?: EnvPolicy;\n  /** Explicit vars merged AFTER the policy — always win. */\n  overrides?: Record<string, string>;\n}\n\n/**\n * Secret-like variable-name patterns (case-insensitive). A parent var whose\n * name matches any of these is dropped under `inherit-scrubbed`. Conservative\n * by design — see the EC-4 false-positive test. `[_-]PWD` (not bare `PWD`)\n * catches `DB_PWD` without dropping the shell's working-directory `PWD`.\n * `CREDENTIAL` catches `GOOGLE_APPLICATION_CREDENTIALS`. NOTE: a denylist cannot\n * catch creds embedded in a value (e.g. `DATABASE_URL=postgres://u:pw@…`) — for\n * untrusted children use policy `\"core\"` (allowlist), the only fail-closed mode.\n */\nconst SECRET_PATTERNS: readonly RegExp[] = [\n  /KEY/i,\n  /SECRET/i,\n  /TOKEN/i,\n  /PASSWORD/i,\n  /PASSWD/i,\n  /PASSPHRASE/i,\n  /[_-]PWD/i,\n  /CREDENTIAL/i,\n  /PRIVATE/i,\n  /_AUTH/i,\n];\n\n/**\n * Safe base variables kept under the `core` policy. Process-hygiene vars a\n * child almost always needs; none are secret-bearing.\n */\nconst CORE_VARS: readonly string[] = [\n  \"PATH\",\n  \"HOME\",\n  \"SHELL\",\n  \"LANG\",\n  \"LC_ALL\",\n  \"LC_CTYPE\",\n  \"TMPDIR\",\n  \"TMP\",\n  \"TEMP\",\n  \"USER\",\n  \"LOGNAME\",\n];\n\nfunction isSecretName(name: string): boolean {\n  return SECRET_PATTERNS.some((re) => re.test(name));\n}\n\n/** Whether a parent var of the given name is inherited under `policy`. */\nfunction inheritsUnderPolicy(name: string, policy: EnvPolicy): boolean {\n  if (policy === \"all\") return true;\n  if (policy === \"core\") return CORE_VARS.includes(name);\n  return !isSecretName(name); // inherit-scrubbed\n}\n\nexport function resolveChildEnv(options: ResolveChildEnvOptions = {}): Record<string, string> {\n  const parent = options.parent ?? process.env;\n  const policy = options.policy ?? \"inherit-scrubbed\";\n\n  const base: Record<string, string> = {};\n  for (const [name, value] of Object.entries(parent)) {\n    if (value !== undefined && inheritsUnderPolicy(name, policy)) base[name] = value;\n  }\n\n  // Explicit overrides always win — even over a scrub.\n  for (const [name, value] of Object.entries(options.overrides ?? {})) {\n    base[name] = value;\n  }\n  return base;\n}\n","/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n  /**\n   * #54 — env inherit/scrub policy for the executed command's child process.\n   * Defaults to `\"inherit-scrubbed\"` (drop secret-like vars: `*KEY*`, `*SECRET*`,\n   * `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Pass `\"all\"` to restore full inheritance\n   * or `\"core\"` for a minimal safe allowlist.\n   */\n  env?: import(\"../internal/runtime/lifecycle/env-policy.js\").EnvPolicy;\n}\n\nexport class SandboxSecurityError extends Error {\n  readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxSecurityError\";\n  }\n}\n\nexport class SandboxNotAvailableError extends Error {\n  readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxNotAvailableError\";\n  }\n}\n\nconst SHELL_METACHARACTERS = /[;&|`$(){}]/;\n\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n      // #54 — preserve the env policy so backends can scrub secrets.\n      env: config.env ?? \"inherit-scrubbed\",\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  protected validateCommand(command: string): void {\n    if (SHELL_METACHARACTERS.test(command)) {\n      throw new SandboxSecurityError(\n        `Command contains shell metacharacters: ${command.slice(0, 80)}`,\n      );\n    }\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n","/**\n * LocalSandbox — subprocess-based execution. **This is NOT an isolation\n * boundary.** It runs the command via `/bin/sh -c` in the SAME OS as the host\n * with the host's filesystem and network fully reachable — it provides NO\n * process, filesystem, or network isolation. Its only safety affordances are:\n *   - a wall-clock timeout (kills a runaway command),\n *   - an output-size cap (bounds memory), and\n *   - env scrubbing (#54): secret-like parent env vars (`*KEY*`/`*SECRET*`/\n *     `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`) are dropped from the child by default\n *     (`SandboxConfig.env`), so a shell tool cannot exfiltrate host secrets via\n *     the environment.\n *\n * For real isolation (untrusted code), use a container/VM backend — NOT this.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { resolveChildEnv } from \"../internal/runtime/lifecycle/env-policy.js\";\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n          // #54 — scrub secret-like host env vars from the child by default.\n          env: resolveChildEnv({ policy: this.config.env }),\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    return {\n      stdout: this.truncateOutput(stdout),\n      stderr: this.truncateOutput(stderr),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n","import { defaultRetriableForCode } from \"./internal/default-retriable.js\";\nimport { redactSecrets } from \"./internal/security/redact.js\";\nimport type { RunOperation } from \"./types/run.js\";\n\n/**\n * Finite, machine-readable error codes for provider-originated errors\n * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively\n * — adding a new variant is an explicit decision + test coverage.\n *\n * @public\n */\nexport type ErrorCode =\n  | \"rate_limit\"\n  | \"auth_failed\"\n  | \"invalid_request\"\n  | \"timeout\"\n  | \"server_error\"\n  | \"context_too_long\"\n  | \"content_filtered\"\n  | \"model_unavailable\"\n  | \"network\"\n  | \"quota_exceeded\"\n  | \"unknown\";\n\n/**\n * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).\n *\n * Superset of {@link ErrorCode} extended with codes that do NOT originate\n * from a provider HTTP response:\n *\n * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)\n * - `tool_runtime_error` — custom tool handler threw inside dispatch\n * - `aborted` — caller's `AbortSignal` fired (Phase 4)\n * - `invalid_model` — model id rejected by provider (400 \"model not found\")\n * - `safety_blocked` — provider safety filter blocked req or resp\n * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary\n *\n * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while\n * accepting any string for forward compatibility with constructor calls\n * that pass arbitrary code values (legacy callers).\n *\n * @public\n */\n/**\n * T1.1 — closed literal union for `AgentRunError.code`. The previous\n * `(string & {})` escape hatch let arbitrary strings slip into the type\n * surface and defeated exhaustive `switch (code)` discrimination. This is\n * the canonical closed form. `AgentRunErrorCode` is re-aliased below for\n * source-level back-compat.\n *\n * Adding a new code: append the literal here AND audit every `switch (err.code)`\n * in callers. Type-checker enforces the audit via the `default: assertNever(code)`\n * convention.\n *\n * @public\n */\nexport type KnownAgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\";\n\n/**\n * Back-compat alias of {@link KnownAgentRunErrorCode}. Pre-T1.1 callers that\n * imported `AgentRunErrorCode` keep working; new code SHOULD prefer\n * `KnownAgentRunErrorCode` to make the closed-union intent explicit.\n *\n * @public\n */\nexport type AgentRunErrorCode = KnownAgentRunErrorCode;\n\n/** Snapshot of every known code at runtime — used by the boundary coercer. */\nconst KNOWN_AGENT_RUN_ERROR_CODES = new Set<string>([\n  \"rate_limit\",\n  \"auth_failed\",\n  \"invalid_request\",\n  \"timeout\",\n  \"server_error\",\n  \"context_too_long\",\n  \"content_filtered\",\n  \"model_unavailable\",\n  \"network\",\n  \"unknown\",\n  \"quota_exceeded\",\n  \"tool_runtime_error\",\n  \"aborted\",\n  \"invalid_model\",\n  \"safety_blocked\",\n  \"provider_unreachable\",\n]);\n\n/**\n * T1.1 boundary helper — coerce an arbitrary string (typically arriving from\n * a downstream `RunErrorDetail.code` or a deserialized cloud response) into a\n * `KnownAgentRunErrorCode`. Unknown strings collapse to `\"unknown\"` so the\n * closed type contract holds without forcing every caller to switch.\n *\n * @internal\n */\nexport function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode {\n  if (code !== undefined && KNOWN_AGENT_RUN_ERROR_CODES.has(code)) {\n    return code as KnownAgentRunErrorCode;\n  }\n  return \"unknown\";\n}\n\n/**\n * Structured context for errors that originated from a provider HTTP\n * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),\n * surface actionable diagnostics (`provider`, `endpoint`), and inspect the\n * raw response body when needed (`raw`, capped at ~2KB by the mapper).\n *\n * @public\n */\nexport interface ErrorMetadata {\n  /** Provider canonical name (e.g., `\"anthropic\"`, `\"openai\"`, `\"openrouter\"`, `\"gemini\"`). */\n  provider: string;\n  /** HTTP endpoint that failed (e.g., `\"/v1/messages\"`, `\"/v1/chat/completions\"`). */\n  endpoint: string;\n  /** Machine-readable error code (finite enum). */\n  code: ErrorCode;\n  /** HTTP status code if applicable. */\n  statusCode?: number;\n  /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */\n  retryAfter?: number;\n  /** Raw response body for debugging (truncated to ~2KB by the mapper). */\n  raw?: unknown;\n}\n\n/**\n * Base class for all errors thrown by `@theokit/sdk`.\n *\n * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`\n * are populated for server-originated errors when available. `metadata`\n * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when\n * the error originated from a provider HTTP call.\n *\n * @public\n */\nexport class TheokitAgentError extends Error {\n  override readonly name: string = \"TheokitAgentError\";\n  readonly isRetryable: boolean;\n  readonly code?: string;\n  readonly protoErrorCode?: string;\n  readonly metadata?: ErrorMetadata;\n\n  constructor(\n    message: string,\n    options: {\n      isRetryable?: boolean;\n      code?: string;\n      protoErrorCode?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    } = {},\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.isRetryable = options.isRetryable ?? false;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.protoErrorCode !== undefined) this.protoErrorCode = options.protoErrorCode;\n    if (options.metadata !== undefined) this.metadata = options.metadata;\n  }\n}\n\n/**\n * Invalid API key, not logged in, insufficient permissions.\n *\n * @public\n */\nexport class AuthenticationError extends TheokitAgentError {\n  override readonly name: string = \"AuthenticationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Too many requests or usage limits exceeded.\n *\n * @public\n */\nexport class RateLimitError extends TheokitAgentError {\n  override readonly name: string = \"RateLimitError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Invalid model, bad request parameters, malformed options.\n *\n * @public\n */\nexport class ConfigurationError extends TheokitAgentError {\n  override readonly name: string = \"ConfigurationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown when creating a cloud agent for a repo whose SCM provider is not\n * connected. Use `helpUrl` to point the user at the right reconnect flow.\n *\n * @public\n */\nexport class IntegrationNotConnectedError extends ConfigurationError {\n  override readonly name: string = \"IntegrationNotConnectedError\";\n  readonly provider: string;\n  readonly helpUrl: string;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      helpUrl: string;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, options);\n    this.provider = options.provider;\n    this.helpUrl = options.helpUrl;\n  }\n}\n\n/**\n * Service unavailable, timeout, transport-level failure.\n *\n * @public\n */\nexport class NetworkError extends TheokitAgentError {\n  override readonly name: string = \"NetworkError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Catch-all for unclassified server or runtime errors.\n *\n * @public\n */\nexport class UnknownAgentError extends TheokitAgentError {\n  override readonly name: string = \"UnknownAgentError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when\n * the option `{ throwOnError: true }` is set and the run terminates with\n * `status: 'error'`. Carries the structured `RunResult.error` fields so\n * callers can `catch` once and branch on `code` / `provider` instead of\n * unwrapping the run.\n *\n * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.\n *\n * @example\n *   try {\n *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });\n *   } catch (err) {\n *     if (err instanceof AgentRunError && err.code === 'auth_failed') {\n *       // bad key\n *     }\n *   }\n *\n * @public\n */\nexport class AgentRunError extends TheokitAgentError {\n  override readonly name: string = \"AgentRunError\";\n  readonly provider?: string;\n  readonly raw?: string;\n  /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */\n  readonly requestId?: string;\n  /** SDK conversation id this error was raised inside. */\n  readonly conversationId?: string;\n\n  constructor(\n    message: string,\n    options: {\n      code: AgentRunErrorCode;\n      provider?: string;\n      raw?: string;\n      requestId?: string;\n      conversationId?: string;\n      retriable?: boolean;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      code: options.code,\n      cause: options.cause,\n      metadata: options.metadata,\n      // D311: most AgentRunErrors are not retriable (auth, validation, abort).\n      // Provider mappers (D314) override per-status — explicit `retriable` wins\n      // over the implicit default when supplied.\n      isRetryable: options.retriable ?? defaultRetriableForCode(options.code),\n    });\n    if (options.provider !== undefined) this.provider = options.provider;\n    if (options.raw !== undefined) this.raw = options.raw;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n    if (options.conversationId !== undefined) this.conversationId = options.conversationId;\n  }\n\n  /**\n   * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as\n   * `retriable` to match the handoff contract. Future v2 will deprecate\n   * `isRetryable` in favor of this.\n   */\n  get retriable(): boolean {\n    return this.isRetryable;\n  }\n\n  /**\n   * D312: provider's `Retry-After` header in **milliseconds**. Mappers store\n   * the header value (seconds) in `metadata.retryAfter`; this getter\n   * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.\n   *\n   * Returns `undefined` when no hint was provided. `0` is a legitimate value\n   * — use `=== undefined` check rather than truthy check.\n   */\n  get retryAfterMs(): number | undefined {\n    if (this.metadata?.retryAfter === undefined) return undefined;\n    return this.metadata.retryAfter * 1000;\n  }\n\n  /**\n   * D313 + T1.5: alias for `metadata.raw`. Provider response body for\n   * debugging. T1.5 wraps the value in `redactSecrets` at the getter\n   * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are\n   * stripped before reaching the caller. Available but NEVER serialized\n   * into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    const raw = this.metadata?.raw;\n    if (raw === undefined) return undefined;\n    if (typeof raw === \"string\") return redactSecrets(raw);\n    // Non-string raw (object/buffer) — stringify then redact.\n    try {\n      return redactSecrets(JSON.stringify(raw));\n    } catch {\n      return redactSecrets(String(raw));\n    }\n  }\n\n  /**\n   * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt\n   * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw\n   * payload for diagnostics. Every other field stays accessible.\n   *\n   * The single env-var gate is read each call so operators can toggle at\n   * runtime without restarting the process.\n   */\n  toJSON(): Record<string, unknown> {\n    const json: Record<string, unknown> = {\n      name: this.name,\n      message: this.message,\n      isRetryable: this.isRetryable,\n    };\n    addOptionalFields(json, this);\n    const safeMeta = sanitizeMetadata(this.metadata);\n    if (safeMeta !== undefined) json.metadata = safeMeta;\n    return json;\n  }\n}\n\nfunction addOptionalFields(json: Record<string, unknown>, err: AgentRunError): void {\n  if (err.code !== undefined) json.code = err.code;\n  if (err.provider !== undefined) json.provider = err.provider;\n  if (err.requestId !== undefined) json.requestId = err.requestId;\n  if (err.conversationId !== undefined) json.conversationId = err.conversationId;\n  if (err.raw !== undefined) json.raw = redactSecrets(err.raw);\n}\n\nfunction sanitizeMetadata(meta: ErrorMetadata | undefined): ErrorMetadata | undefined {\n  if (meta === undefined) return undefined;\n  const { raw, ...rest } = meta;\n  const debugRaw = process.env.THEOKIT_DEBUG_RAW_ERRORS === \"1\";\n  if (debugRaw && raw !== undefined) {\n    const redactedRaw =\n      typeof raw === \"string\" ? redactSecrets(raw) : redactSecrets(safeStringify(raw));\n    return { ...rest, raw: redactedRaw } as ErrorMetadata;\n  }\n  return rest as ErrorMetadata;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * Is this error transient (worth retrying)?\n *\n * Returns the SDK's own retryability verdict: every {@link TheokitAgentError}\n * subclass computes `isRetryable` at construction (rate-limit / network /\n * credential-pool-exhausted are retryable; auth / configuration / unsupported\n * are not), so this predicate is a single source of truth rather than a\n * re-derivation. Non-SDK errors return `false` conservatively — wrap a foreign\n * error in the appropriate SDK error first if you want it considered transient.\n * It never inspects `err.message`.\n *\n * @example\n *   try {\n *     await agent.send(message, { throwOnError: true });\n *   } catch (err) {\n *     if (isTransientError(err)) return retryWithBackoff();\n *     throw err;\n *   }\n *\n * @public\n */\nexport function isTransientError(err: unknown): boolean {\n  return err instanceof TheokitAgentError && err.isRetryable === true;\n}\n\n/**\n * Thrown when a {@link Run} or agent operation is not available on the current\n * runtime. Check first with `run.supports(operation)`.\n *\n * Extends {@link TheokitAgentError} (so error-catching code that branches on\n * `instanceof TheokitAgentError` continues to work) but is never retryable —\n * an unsupported operation will not become supported on retry.\n *\n * @public\n */\nexport class UnsupportedRunOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedRunOperationError\";\n  readonly operation: RunOperation;\n\n  constructor(\n    message: string,\n    operation: RunOperation,\n    options: { code?: string; cause?: unknown } = {},\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: options.code ?? \"unsupported_run_operation\",\n    });\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown when every credential in a per-provider pool is in cooldown\n * and no healthy key is available (ADR D133). The caller's\n * {@link import(\"./internal/llm/fallback-client.js\").FallbackLlmClient}\n * catches this and tries the next provider in the fallback chain.\n *\n * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest\n * pool entry resumes — useful for manual retry scheduling.\n *\n * @public\n */\nexport class CredentialPoolExhaustedError extends TheokitAgentError {\n  override readonly name: string = \"CredentialPoolExhaustedError\";\n  readonly provider: string;\n  readonly nextRetryAt: number | undefined;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      nextRetryAt?: number;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: true,\n      code: options.code ?? \"credential_pool_exhausted\",\n    });\n    this.provider = options.provider;\n    this.nextRetryAt = options.nextRetryAt;\n  }\n}\n\n/**\n * Finite error codes specific to memory adapter operations (ADR D141).\n *\n * @public\n */\nexport type MemoryAdapterErrorCode =\n  | \"auth_failed\"\n  | \"rate_limited\"\n  | \"not_found\"\n  | \"network\"\n  | \"invalid_input\"\n  | \"unknown\";\n\n/**\n * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`\n * so callers can branch on which provider failed (ADR D141).\n *\n * @public\n */\nexport class MemoryAdapterError extends TheokitAgentError {\n  override readonly name: string = \"MemoryAdapterError\";\n  readonly adapterId: string;\n\n  constructor(\n    message: string,\n    options: {\n      adapterId: string;\n      code: MemoryAdapterErrorCode;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      isRetryable: options.code === \"rate_limited\" || options.code === \"network\",\n      code: options.code,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n      ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),\n    });\n    this.adapterId = options.adapterId;\n  }\n}\n\n/**\n * Thrown when a user-supplied task ID violates the grammar\n * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter\n * prefix (`wf-` / `b-` / `cron-`, EC-5).\n *\n * @public\n */\nexport class InvalidTaskIdError extends TheokitAgentError {\n  override readonly name: string = \"InvalidTaskIdError\";\n  readonly taskId: string;\n\n  constructor(message: string, taskId: string, options: { cause?: unknown } = {}) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: \"invalid_task_id\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `Task.subscribe(id)` is called for a task that has been\n * evicted, never submitted, or evicted after retention (D373).\n *\n * @public\n */\nexport class TaskNotFoundError extends TheokitAgentError {\n  override readonly name: string = \"TaskNotFoundError\";\n  readonly taskId: string;\n\n  constructor(taskId: string, options: { cause?: unknown } = {}) {\n    super(`Task not found: ${taskId}`, {\n      ...options,\n      isRetryable: false,\n      code: \"task_not_found\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud\n * task observability is deferred until Theo PaaS GA.\n *\n * @public\n */\nexport class UnsupportedTaskOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedTaskOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Task operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D370)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"task_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. Caller pega\n * tipado para retry-after-window-reset or surface to the user.\n *\n * @public\n */\nexport class BudgetExceededError extends TheokitAgentError {\n  override readonly name: string = \"BudgetExceededError\";\n  readonly budgetName: string;\n  readonly window: import(\"./types/budget.js\").BudgetWindow;\n  readonly spentUsd: number;\n  readonly limitUsd: number;\n  readonly mode: import(\"./types/budget.js\").BudgetMode;\n\n  constructor(args: {\n    budgetName: string;\n    window: import(\"./types/budget.js\").BudgetWindow;\n    spentUsd: number;\n    limitUsd: number;\n    mode: import(\"./types/budget.js\").BudgetMode;\n    cause?: unknown;\n  }) {\n    super(\n      `Budget \"${args.budgetName}\" exceeded for window ${args.window}: spent $${args.spentUsd.toFixed(4)} > limit $${args.limitUsd.toFixed(4)}`,\n      {\n        ...(args.cause !== undefined ? { cause: args.cause } : {}),\n        isRetryable: false,\n        code: \"budget_exceeded\",\n      },\n    );\n    this.budgetName = args.budgetName;\n    this.window = args.window;\n    this.spentUsd = args.spentUsd;\n    this.limitUsd = args.limitUsd;\n    this.mode = args.mode;\n  }\n}\n\n/**\n * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud\n * budget surface waits for Theo PaaS GA.\n *\n * @public\n */\n/**\n * T1.6 — Thrown when a consumer calls `agent.send()` or any method\n * on an agent that has already been `dispose()`d. Pre-T1.6 this was\n * a generic `new Error(\"Agent has been disposed\")` — consumers\n * couldn't catch it without string-matching the message.\n *\n * @public\n */\nexport class AgentDisposedError extends TheokitAgentError {\n  override readonly name: string = \"AgentDisposedError\";\n  readonly agentId: string;\n\n  constructor(agentId: string) {\n    super(`Agent \"${agentId}\" has been disposed. Create a new agent or use Agent.resume().`, {\n      isRetryable: false,\n      code: \"agent_disposed\",\n    });\n    this.agentId = agentId;\n  }\n}\n\nexport class UnsupportedBudgetOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedBudgetOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Budget operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D388)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"budget_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n","/**\n * M6-3 — portable repo provisioner for the eval harness.\n *\n * Clones a repository and checks out a ref into an isolated working dir, issuing\n * every git command through {@link SandboxBackend.execute} (ADR D2 — same code\n * runs on Local/Docker/E2B; never a direct `child_process` import). Promotes\n * theocode's `prepareRepo` (`swebench-provision.ts:37`) onto the SDK's sandbox\n * abstraction.\n *\n * referencia: knowledge-base/references/theocode-eval/lib/swebench-provision.ts:37\n * (clone+checkout), :13 (ProvisionError with instanceId).\n *\n * @public\n */\n\nimport { TheokitAgentError } from \"../errors.js\";\nimport { LocalSandbox } from \"./local-sandbox.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\nimport type { SandboxBackend } from \"./types.js\";\n\n/**\n * Raised when cloning or checking out a repo fails. Carries the `instanceId`\n * so a batch run can attribute the failure to the offending dataset row.\n */\nexport class RepoProvisionError extends TheokitAgentError {\n  override readonly name = \"RepoProvisionError\";\n\n  constructor(\n    readonly instanceId: string,\n    message: string,\n    options: { cause?: unknown } = {},\n  ) {\n    super(`[${instanceId}] ${message}`, {\n      code: \"repo_provision_failed\",\n      isRetryable: false,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n    });\n  }\n}\n\n/** Options for {@link provisionRepo}. */\nexport interface ProvisionRepoOptions {\n  /**\n   * Clonable repo URL or local path. SECURITY: when this comes from an\n   * untrusted dataset, the value is passed to `git clone` after a `--`\n   * end-of-options terminator (no flag injection) and with the `ext::`\n   * transport disabled (no arbitrary-command transport).\n   */\n  readonly repoUrl: string;\n  /** Branch, tag, or commit SHA to check out. Rejected if it begins with `-`. */\n  readonly ref: string;\n  /**\n   * Unique id for this row — names the target dir and any error. Validated to\n   * `[A-Za-z0-9._-]` (no path traversal) since it becomes a directory name.\n   */\n  readonly instanceId: string;\n}\n\n/**\n * Reject ids that would escape the workdir or be parsed as a git flag. Must\n * start with an alphanumeric (blocks `.`, `..`, `-foo`, leading-dot names) and\n * thereafter allow only `[A-Za-z0-9._-]`.\n */\nconst SAFE_INSTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\n\n/**\n * Clone `repoUrl` into `<sandbox workdir>/<instanceId>` and check out `ref`.\n * Returns the absolute `repoDir` (resolved via `git rev-parse --show-toplevel`,\n * which is portable across backends). Throws {@link RepoProvisionError} naming\n * the `instanceId` when clone or checkout exits non-zero.\n *\n * The `sandbox` is optional (V3-5): when omitted, a default {@link LocalSandbox}\n * is used (clones into the process cwd's `<instanceId>`) — pass an explicit\n * sandbox (e.g. `LocalSandbox({ workDir })` / Docker / E2B) to control the workdir.\n */\nexport function provisionRepo(opts: ProvisionRepoOptions): Promise<{ repoDir: string }>;\nexport function provisionRepo(\n  sandbox: SandboxBackend,\n  opts: ProvisionRepoOptions,\n): Promise<{ repoDir: string }>;\nexport async function provisionRepo(\n  sandboxOrOpts: SandboxBackend | ProvisionRepoOptions,\n  maybeOpts?: ProvisionRepoOptions,\n): Promise<{ repoDir: string }> {\n  const sandbox = maybeOpts !== undefined ? (sandboxOrOpts as SandboxBackend) : new LocalSandbox();\n  const opts = maybeOpts ?? (sandboxOrOpts as ProvisionRepoOptions);\n  const { repoUrl, ref, instanceId } = opts;\n\n  // Validate untrusted-derivable inputs before they reach git/the shell.\n  if (!SAFE_INSTANCE_ID.test(instanceId)) {\n    throw new RepoProvisionError(\n      instanceId,\n      \"invalid instanceId: must match [A-Za-z0-9._-] (no path traversal)\",\n    );\n  }\n  if (ref.startsWith(\"-\")) {\n    throw new RepoProvisionError(instanceId, `invalid ref: must not begin with '-' (got ${ref})`);\n  }\n\n  // `--` terminates options (no `--upload-pack=` flag injection); `protocol.ext.allow=never`\n  // blocks the `ext::` arbitrary-command transport. `file`/`https` stay allowed.\n  const clone = await sandbox.execute(\n    `git -c protocol.ext.allow=never clone --quiet -- ${shellEscapePosix(repoUrl)} ${shellEscapePosix(instanceId)}`,\n  );\n  if (clone.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `clone failed: ${clone.stderr.trim()}`);\n  }\n\n  const top = await sandbox.execute(\n    `git -C ${shellEscapePosix(instanceId)} rev-parse --show-toplevel`,\n  );\n  if (top.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `resolve repoDir failed: ${top.stderr.trim()}`);\n  }\n  const repoDir = top.stdout.trim();\n\n  // `ref` is validated above not to begin with `-`, so it cannot be parsed as a flag.\n  const checkout = await sandbox.execute(\n    `git -C ${shellEscapePosix(repoDir)} checkout --quiet ${shellEscapePosix(ref)}`,\n  );\n  if (checkout.exitCode !== 0) {\n    throw new RepoProvisionError(instanceId, `checkout ${ref} failed: ${checkout.stderr.trim()}`);\n  }\n\n  return { repoDir };\n}\n"]}