@theokit/sdk 4.40.0 → 4.41.1

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

@@ -274,7 +274,26 @@ declare class PermissionEngine {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent;
+/**
+ * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
+ * tools exist for this run.
+ *
+ * The failure was always caught (`safeListTools` returns `[]` so one broken server cannot take the
+ * turn down) and always DIAGNOSED — to `diag()`, i.e. the SDK's stderr. Nothing reached the
+ * consumer, so a UI listing configured servers could show one as present while every tool it
+ * provides had silently vanished. Degrading gracefully is right; degrading INVISIBLY is not.
+ *
+ * Emitted once per failing server per run, on the same catch path that already had both the name
+ * and the reason.
+ */
+interface RunMcpServerFailedEvent {
+    readonly type: "mcp_server_failed";
+    /** The server as named in the MCP configuration, so the consumer can match it to what it lists. */
+    readonly serverName: string;
+    /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
+    readonly message: string;
+}
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
@@ -1024,7 +1043,7 @@ type CostStatus = "actual" | "estimated" | "included" | "unknown";
 type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "subscription_included" | "unknown";
 /**
  * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
- * `amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
+ * `amountUsd` is `undefined` — DO NOT default to 0 (a lie). The UI shows
  * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
  */
 interface CostBreakdown {

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

@@ -274,7 +274,26 @@ declare class PermissionEngine {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent;
+/**
+ * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
+ * tools exist for this run.
+ *
+ * The failure was always caught (`safeListTools` returns `[]` so one broken server cannot take the
+ * turn down) and always DIAGNOSED — to `diag()`, i.e. the SDK's stderr. Nothing reached the
+ * consumer, so a UI listing configured servers could show one as present while every tool it
+ * provides had silently vanished. Degrading gracefully is right; degrading INVISIBLY is not.
+ *
+ * Emitted once per failing server per run, on the same catch path that already had both the name
+ * and the reason.
+ */
+interface RunMcpServerFailedEvent {
+    readonly type: "mcp_server_failed";
+    /** The server as named in the MCP configuration, so the consumer can match it to what it lists. */
+    readonly serverName: string;
+    /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
+    readonly message: string;
+}
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
@@ -1024,7 +1043,7 @@ type CostStatus = "actual" | "estimated" | "included" | "unknown";
 type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "subscription_included" | "unknown";
 /**
  * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
- * `amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
+ * `amountUsd` is `undefined` — DO NOT default to 0 (a lie). The UI shows
  * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
  */
 interface CostBreakdown {

package/dist/{run-until-BK56WG4P.js → run-until-HEQOUVU6.js}

@@ -174,5 +174,5 @@ ${lastResponse.slice(-1e3)}`
 }
 
 export { composeContinuation, runUntilImpl };
-//# sourceMappingURL=run-until-BK56WG4P.js.map
-//# sourceMappingURL=run-until-BK56WG4P.js.map
+//# sourceMappingURL=run-until-HEQOUVU6.js.map
+//# sourceMappingURL=run-until-HEQOUVU6.js.map

package/dist/run-until-HEQOUVU6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/run-until.ts"],"names":[],"mappings":"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","file":"run-until-HEQOUVU6.js","sourcesContent":["/**\n * Goal-driven Ralph loop (T3.2, ADRs D115-D121).\n *\n * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:\n * yields events as the loop progresses, returns the final result when\n * the goal completes, fails, or is paused. The auxiliary judge model is\n * injected via `deps.judge` so the generator stays free of the `Agent`\n * façade import.\n *\n * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.\n * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).\n *\n * @internal\n */\n\nimport type { SDKAgent } from \"../../../types/agent.js\";\nimport type {\n  GoalEvent,\n  GoalOptions,\n  GoalResult,\n  JudgeResult,\n} from \"../../../types/goal-events.js\";\nimport type { JudgeContext, JudgeOptions } from \"../../judge/judge-call.js\";\nimport { GOAL_CONTINUATION_MARKER } from \"./goal-marker.js\";\n\n/** DI contract: the judge is the only external touchpoint. */\nexport interface RunUntilDeps {\n  judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the goal-loop interleaves turn-start, send, judge, continuation, abort-check, and failure-bail — extracting helpers harms the linear narrative.\nexport async function* runUntilImpl(\n  agent: SDKAgent,\n  goal: string,\n  options: GoalOptions | undefined,\n  deps: RunUntilDeps,\n): AsyncGenerator<GoalEvent, GoalResult, void> {\n  const maxTurns = options?.maxTurns ?? 20;\n  const maxFails = options?.maxConsecutiveJudgeFailures ?? 3;\n  const tokenBudget = options?.tokenBudget; // M55 — undefined ⇒ unlimited\n  const signal = options?.signal;\n  // Use a function (not direct property access) so TS does not narrow\n  // `signal.aborted` to `false | undefined` after the initial check.\n  // AbortSignal.aborted is a getter that can flip true between calls.\n  // biome-ignore lint/complexity/useOptionalChain: optional-chain would re-narrow signal?.aborted to `false | undefined` after the first check, defeating the purpose of this helper.\n  const isAborted = (): boolean => signal !== undefined && signal.aborted;\n  let turn = 0;\n  let consecutiveFailures = 0;\n  let tokensUsed = 0; // M55 — the observed sum (0 when usage is absent — fail-open)\n  let lastResponse = \"\";\n\n  // EC-C: signal already aborted BEFORE first event → emit only [paused].\n  if (isAborted()) {\n    yield {\n      type: \"status_change\",\n      status: \"paused\",\n      reason: \"aborted via AbortSignal before first turn\",\n    };\n    return { status: \"paused\", turnsUsed: 0, tokensUsed, finalResponse: undefined };\n  }\n\n  yield { type: \"status_change\", status: \"active\", reason: \"Goal started\" };\n\n  while (turn < maxTurns) {\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    turn += 1;\n    yield { type: \"turn_start\", turn, goal };\n\n    const continuationPrompt = turn === 1 ? goal : composeContinuation(goal, lastResponse);\n\n    const run = await agent.send(continuationPrompt);\n    // M55 review HIGH — thread the abort INTO the in-flight run: without this, Esc mid-turn is\n    // cosmetic (the turn keeps mutating the workspace until it finishes on its own). `run.cancel()`\n    // aborts the stream + in-flight tool calls (types/run.ts contract).\n    const cancelOnAbort = (): void => {\n      void (run as { cancel?: () => Promise<void> }).cancel?.();\n    };\n    if (signal !== undefined) {\n      if (signal.aborted) cancelOnAbort();\n      else signal.addEventListener(\"abort\", cancelOnAbort, { once: true });\n    }\n    const result = await run.wait();\n    if (signal !== undefined) signal.removeEventListener(\"abort\", cancelOnAbort);\n    lastResponse = result.result ?? \"\";\n    // M55 — token accounting fails open: it only sums when the run reports usage.\n    const turnTokens = (result as { usage?: { totalTokens?: number } }).usage?.totalTokens;\n    if (typeof turnTokens === \"number\") tokensUsed += turnTokens;\n    // Re-check aborted right after the turn lands: a cancelled turn must NOT spend a judge call.\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    yield { type: \"agent_response\", turn, content: lastResponse };\n\n    const judgeOpts: JudgeOptions = {};\n    if (options?.judgeModel !== undefined) judgeOpts.judgeModel = options.judgeModel;\n    if (options?.judgeApiKey !== undefined) judgeOpts.apiKey = options.judgeApiKey;\n    // M80 — forwards the driven agent's model so the judge can derive when `judgeModel` is omitted.\n    if (options?.agentModel !== undefined) judgeOpts.agentModel = options.agentModel;\n    const judgeCtx: JudgeContext = { goal, lastResponse };\n    if (options?.subgoals !== undefined) judgeCtx.subgoals = options.subgoals;\n    const judgment = await deps.judge(judgeCtx, judgeOpts);\n    yield {\n      type: \"judge_verdict\",\n      turn,\n      verdict: judgment.verdict,\n      reason: judgment.reason,\n      parseFailed: judgment.parseFailed,\n    };\n\n    if (judgment.parseFailed) {\n      consecutiveFailures += 1;\n      if (consecutiveFailures >= maxFails) {\n        yield {\n          type: \"status_change\",\n          status: \"failed\",\n          reason: `judge model too unreliable (${consecutiveFailures} parse failures in a row)`,\n        };\n        return {\n          status: \"failed\",\n          turnsUsed: turn,\n          tokensUsed,\n          finalResponse: lastResponse || undefined,\n        };\n      }\n    } else {\n      consecutiveFailures = 0;\n    }\n\n    if (judgment.verdict === \"done\") {\n      yield { type: \"status_change\", status: \"completed\", reason: judgment.reason };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    // M80 — the missing arm. Without it, a judge recognizing impossibility could only say\n    // \"continue\", and the loop repeated the same turn until it blew the budget — reporting `failed` on\n    // a limit rather than `blocked` on impossibility. Two distinct causes with the same\n    // visible outcome, and the consumer had to reconcile after the loop to tell them apart.\n    if (judgment.verdict === \"blocked\") {\n      yield { type: \"status_change\", status: \"blocked\", reason: judgment.reason };\n      return {\n        status: \"blocked\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    if (judgment.verdict === \"skipped\") {\n      yield {\n        type: \"status_change\",\n        status: \"completed\",\n        reason: `skipped: ${judgment.reason}`,\n      };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    // M55 — token-budget check AFTER the turn (Codex: gentle wind-down, stops the loop).\n    if (tokenBudget !== undefined && tokensUsed >= tokenBudget) {\n      yield {\n        type: \"status_change\",\n        status: \"budget_limited\",\n        reason: `token budget (${tokenBudget}) reached: ${tokensUsed} used`,\n      };\n      return {\n        status: \"budget_limited\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    yield { type: \"continuation\", turn, prompt: continuationPrompt };\n  }\n\n  yield {\n    type: \"status_change\",\n    status: \"failed\",\n    reason: `max turns (${maxTurns}) exhausted`,\n  };\n  return {\n    status: \"failed\",\n    turnsUsed: turn,\n    tokensUsed,\n    finalResponse: lastResponse || undefined,\n  };\n}\n\n/**\n * Build the continuation user message for turns 2+. Keeps last response\n * preview short so we don't bloat the prompt cache.\n *\n * @internal\n */\n\nexport function composeContinuation(goal: string, lastResponse: string): string {\n  // M55 — Codex-faithful continuation (ext/goal templates/goals/continuation.md): keep the FULL\n  // objective intact, work from current-state evidence, and audit completion requirement-by-requirement\n  // before declaring done. Improves the quality of what the judge then evaluates.\n  return [\n    GOAL_CONTINUATION_MARKER,\n    \"Continue working toward the active goal.\",\n    \"\",\n    `<objective>\\n${goal}\\n</objective>`,\n    \"\",\n    \"Continuation behavior:\",\n    \"- This goal persists across turns. Keep the full objective intact; if it cannot be finished now,\",\n    \"  make concrete progress toward the real requested end state and do not redefine success around a\",\n    \"  smaller or easier task.\",\n    \"\",\n    \"Work from evidence:\",\n    \"- Use the current worktree and external state as authoritative. Inspect the current state before\",\n    \"  relying on it. Improve, replace, or remove existing work as needed to satisfy the actual objective.\",\n    \"\",\n    \"Completion audit:\",\n    \"- Before deciding the goal is achieved, treat completion as unproven and verify it against the actual\",\n    \"  current state, requirement by requirement. Treat uncertain or indirect evidence as not achieved.\",\n    \"\",\n    `Your last response was:\\n${lastResponse.slice(-1000)}`,\n  ].join(\"\\n\");\n}\n"]}

package/dist/{run-until-L5KQD3PV.cjs → run-until-U2B5FJJI.cjs}

@@ -177,5 +177,5 @@ ${lastResponse.slice(-1e3)}`
 
 exports.composeContinuation = composeContinuation;
 exports.runUntilImpl = runUntilImpl;
-//# sourceMappingURL=run-until-L5KQD3PV.cjs.map
-//# sourceMappingURL=run-until-L5KQD3PV.cjs.map
+//# sourceMappingURL=run-until-U2B5FJJI.cjs.map
+//# sourceMappingURL=run-until-U2B5FJJI.cjs.map

package/dist/run-until-U2B5FJJI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/run-until.ts"],"names":["GOAL_CONTINUATION_MARKER"],"mappings":"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","file":"run-until-U2B5FJJI.cjs","sourcesContent":["/**\n * Goal-driven Ralph loop (T3.2, ADRs D115-D121).\n *\n * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:\n * yields events as the loop progresses, returns the final result when\n * the goal completes, fails, or is paused. The auxiliary judge model is\n * injected via `deps.judge` so the generator stays free of the `Agent`\n * façade import.\n *\n * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.\n * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).\n *\n * @internal\n */\n\nimport type { SDKAgent } from \"../../../types/agent.js\";\nimport type {\n  GoalEvent,\n  GoalOptions,\n  GoalResult,\n  JudgeResult,\n} from \"../../../types/goal-events.js\";\nimport type { JudgeContext, JudgeOptions } from \"../../judge/judge-call.js\";\nimport { GOAL_CONTINUATION_MARKER } from \"./goal-marker.js\";\n\n/** DI contract: the judge is the only external touchpoint. */\nexport interface RunUntilDeps {\n  judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the goal-loop interleaves turn-start, send, judge, continuation, abort-check, and failure-bail — extracting helpers harms the linear narrative.\nexport async function* runUntilImpl(\n  agent: SDKAgent,\n  goal: string,\n  options: GoalOptions | undefined,\n  deps: RunUntilDeps,\n): AsyncGenerator<GoalEvent, GoalResult, void> {\n  const maxTurns = options?.maxTurns ?? 20;\n  const maxFails = options?.maxConsecutiveJudgeFailures ?? 3;\n  const tokenBudget = options?.tokenBudget; // M55 — undefined ⇒ unlimited\n  const signal = options?.signal;\n  // Use a function (not direct property access) so TS does not narrow\n  // `signal.aborted` to `false | undefined` after the initial check.\n  // AbortSignal.aborted is a getter that can flip true between calls.\n  // biome-ignore lint/complexity/useOptionalChain: optional-chain would re-narrow signal?.aborted to `false | undefined` after the first check, defeating the purpose of this helper.\n  const isAborted = (): boolean => signal !== undefined && signal.aborted;\n  let turn = 0;\n  let consecutiveFailures = 0;\n  let tokensUsed = 0; // M55 — the observed sum (0 when usage is absent — fail-open)\n  let lastResponse = \"\";\n\n  // EC-C: signal already aborted BEFORE first event → emit only [paused].\n  if (isAborted()) {\n    yield {\n      type: \"status_change\",\n      status: \"paused\",\n      reason: \"aborted via AbortSignal before first turn\",\n    };\n    return { status: \"paused\", turnsUsed: 0, tokensUsed, finalResponse: undefined };\n  }\n\n  yield { type: \"status_change\", status: \"active\", reason: \"Goal started\" };\n\n  while (turn < maxTurns) {\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    turn += 1;\n    yield { type: \"turn_start\", turn, goal };\n\n    const continuationPrompt = turn === 1 ? goal : composeContinuation(goal, lastResponse);\n\n    const run = await agent.send(continuationPrompt);\n    // M55 review HIGH — thread the abort INTO the in-flight run: without this, Esc mid-turn is\n    // cosmetic (the turn keeps mutating the workspace until it finishes on its own). `run.cancel()`\n    // aborts the stream + in-flight tool calls (types/run.ts contract).\n    const cancelOnAbort = (): void => {\n      void (run as { cancel?: () => Promise<void> }).cancel?.();\n    };\n    if (signal !== undefined) {\n      if (signal.aborted) cancelOnAbort();\n      else signal.addEventListener(\"abort\", cancelOnAbort, { once: true });\n    }\n    const result = await run.wait();\n    if (signal !== undefined) signal.removeEventListener(\"abort\", cancelOnAbort);\n    lastResponse = result.result ?? \"\";\n    // M55 — token accounting fails open: it only sums when the run reports usage.\n    const turnTokens = (result as { usage?: { totalTokens?: number } }).usage?.totalTokens;\n    if (typeof turnTokens === \"number\") tokensUsed += turnTokens;\n    // Re-check aborted right after the turn lands: a cancelled turn must NOT spend a judge call.\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    yield { type: \"agent_response\", turn, content: lastResponse };\n\n    const judgeOpts: JudgeOptions = {};\n    if (options?.judgeModel !== undefined) judgeOpts.judgeModel = options.judgeModel;\n    if (options?.judgeApiKey !== undefined) judgeOpts.apiKey = options.judgeApiKey;\n    // M80 — forwards the driven agent's model so the judge can derive when `judgeModel` is omitted.\n    if (options?.agentModel !== undefined) judgeOpts.agentModel = options.agentModel;\n    const judgeCtx: JudgeContext = { goal, lastResponse };\n    if (options?.subgoals !== undefined) judgeCtx.subgoals = options.subgoals;\n    const judgment = await deps.judge(judgeCtx, judgeOpts);\n    yield {\n      type: \"judge_verdict\",\n      turn,\n      verdict: judgment.verdict,\n      reason: judgment.reason,\n      parseFailed: judgment.parseFailed,\n    };\n\n    if (judgment.parseFailed) {\n      consecutiveFailures += 1;\n      if (consecutiveFailures >= maxFails) {\n        yield {\n          type: \"status_change\",\n          status: \"failed\",\n          reason: `judge model too unreliable (${consecutiveFailures} parse failures in a row)`,\n        };\n        return {\n          status: \"failed\",\n          turnsUsed: turn,\n          tokensUsed,\n          finalResponse: lastResponse || undefined,\n        };\n      }\n    } else {\n      consecutiveFailures = 0;\n    }\n\n    if (judgment.verdict === \"done\") {\n      yield { type: \"status_change\", status: \"completed\", reason: judgment.reason };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    // M80 — the missing arm. Without it, a judge recognizing impossibility could only say\n    // \"continue\", and the loop repeated the same turn until it blew the budget — reporting `failed` on\n    // a limit rather than `blocked` on impossibility. Two distinct causes with the same\n    // visible outcome, and the consumer had to reconcile after the loop to tell them apart.\n    if (judgment.verdict === \"blocked\") {\n      yield { type: \"status_change\", status: \"blocked\", reason: judgment.reason };\n      return {\n        status: \"blocked\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    if (judgment.verdict === \"skipped\") {\n      yield {\n        type: \"status_change\",\n        status: \"completed\",\n        reason: `skipped: ${judgment.reason}`,\n      };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    // M55 — token-budget check AFTER the turn (Codex: gentle wind-down, stops the loop).\n    if (tokenBudget !== undefined && tokensUsed >= tokenBudget) {\n      yield {\n        type: \"status_change\",\n        status: \"budget_limited\",\n        reason: `token budget (${tokenBudget}) reached: ${tokensUsed} used`,\n      };\n      return {\n        status: \"budget_limited\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    yield { type: \"continuation\", turn, prompt: continuationPrompt };\n  }\n\n  yield {\n    type: \"status_change\",\n    status: \"failed\",\n    reason: `max turns (${maxTurns}) exhausted`,\n  };\n  return {\n    status: \"failed\",\n    turnsUsed: turn,\n    tokensUsed,\n    finalResponse: lastResponse || undefined,\n  };\n}\n\n/**\n * Build the continuation user message for turns 2+. Keeps last response\n * preview short so we don't bloat the prompt cache.\n *\n * @internal\n */\n\nexport function composeContinuation(goal: string, lastResponse: string): string {\n  // M55 — Codex-faithful continuation (ext/goal templates/goals/continuation.md): keep the FULL\n  // objective intact, work from current-state evidence, and audit completion requirement-by-requirement\n  // before declaring done. Improves the quality of what the judge then evaluates.\n  return [\n    GOAL_CONTINUATION_MARKER,\n    \"Continue working toward the active goal.\",\n    \"\",\n    `<objective>\\n${goal}\\n</objective>`,\n    \"\",\n    \"Continuation behavior:\",\n    \"- This goal persists across turns. Keep the full objective intact; if it cannot be finished now,\",\n    \"  make concrete progress toward the real requested end state and do not redefine success around a\",\n    \"  smaller or easier task.\",\n    \"\",\n    \"Work from evidence:\",\n    \"- Use the current worktree and external state as authoritative. Inspect the current state before\",\n    \"  relying on it. Improve, replace, or remove existing work as needed to satisfy the actual objective.\",\n    \"\",\n    \"Completion audit:\",\n    \"- Before deciding the goal is achieved, treat completion as unproven and verify it against the actual\",\n    \"  current state, requirement by requirement. Treat uncertain or indirect evidence as not achieved.\",\n    \"\",\n    `Your last response was:\\n${lastResponse.slice(-1000)}`,\n  ].join(\"\\n\");\n}\n"]}

package/dist/sandbox/bwrap.d.cts

@@ -18,6 +18,20 @@
  * confinement subsystem.
  */
 export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/**
+ * U-6 — the roots a mode may write to, answerable WITHOUT spawning anything.
+ *
+ * `[]` means nothing is writable; `null` means unrestricted — which is not the same as `["/"]`,
+ * because unrestricted is the absence of a root rather than a root that happens to be `/`.
+ *
+ * The SDK already knew this: `buildBwrapArgv` binds these exact paths. It only knew it while
+ * BUILDING an argv, and a consumer needs the answer earlier — tools are scoped at agent
+ * construction, before any process exists, and a file-write tool has to be told its root then. With
+ * nothing to ask, consumers keep a second encoding of this three-mode vocabulary and it drifts from
+ * the argv builder with nothing to catch it. This reads from the same helper the builder uses, so
+ * the two cannot disagree.
+ */
+export declare function writableRootsFor(mode: SandboxMode, cwd: string): readonly string[] | null;
 export interface BwrapArgvOptions {
     /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
     cwd: string;
@@ -71,5 +85,5 @@ export declare const realProbes: BwrapProbes;
  * promoted to a positive, which would require the expensive probe back.
  */
 export declare function detectBwrapMemoized(probes?: BwrapProbes): BwrapDetection;
-/** TEST seam — clears the memo. Production never calls it (see m71-custo-por-turn#ADR-1). */
+/** TEST seam — clears the memo. Production never calls it (see m71-cost-per-turn#ADR-1). */
 export declare function resetBwrapMemo(): void;

package/dist/sandbox/bwrap.d.ts

@@ -18,6 +18,20 @@
  * confinement subsystem.
  */
 export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/**
+ * U-6 — the roots a mode may write to, answerable WITHOUT spawning anything.
+ *
+ * `[]` means nothing is writable; `null` means unrestricted — which is not the same as `["/"]`,
+ * because unrestricted is the absence of a root rather than a root that happens to be `/`.
+ *
+ * The SDK already knew this: `buildBwrapArgv` binds these exact paths. It only knew it while
+ * BUILDING an argv, and a consumer needs the answer earlier — tools are scoped at agent
+ * construction, before any process exists, and a file-write tool has to be told its root then. With
+ * nothing to ask, consumers keep a second encoding of this three-mode vocabulary and it drifts from
+ * the argv builder with nothing to catch it. This reads from the same helper the builder uses, so
+ * the two cannot disagree.
+ */
+export declare function writableRootsFor(mode: SandboxMode, cwd: string): readonly string[] | null;
 export interface BwrapArgvOptions {
     /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
     cwd: string;
@@ -71,5 +85,5 @@ export declare const realProbes: BwrapProbes;
  * promoted to a positive, which would require the expensive probe back.
  */
 export declare function detectBwrapMemoized(probes?: BwrapProbes): BwrapDetection;
-/** TEST seam — clears the memo. Production never calls it (see m71-custo-por-turn#ADR-1). */
+/** TEST seam — clears the memo. Production never calls it (see m71-cost-per-turn#ADR-1). */
 export declare function resetBwrapMemo(): void;

package/dist/sandbox/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkS7OEXQMI_cjs = require('../chunk-S7OEXQMI.cjs');
-require('../chunk-WPZTYOUX.cjs');
-var chunkE7WWIX34_cjs = require('../chunk-E7WWIX34.cjs');
-var chunkA76OFN2B_cjs = require('../chunk-A76OFN2B.cjs');
+var chunkR3CKCRK3_cjs = require('../chunk-R3CKCRK3.cjs');
+require('../chunk-BBZYXVLZ.cjs');
+var chunkYULF6FPB_cjs = require('../chunk-YULF6FPB.cjs');
+var chunkZHPET3LZ_cjs = require('../chunk-ZHPET3LZ.cjs');
 var child_process = require('child_process');
 var fs = require('fs');
 var path = require('path');
@@ -13,6 +13,23 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var path__default = /*#__PURE__*/_interopDefault(path);
 
+function pushWorkspaceBinds(argv, cwd, hasGit, gitDir) {
+  for (const root of workspaceWriteRoots(cwd)) argv.push("--bind", root, root);
+  if (hasGit) argv.push("--ro-bind", gitDir, gitDir);
+}
+function workspaceWriteRoots(cwd) {
+  return [cwd, "/tmp"];
+}
+function writableRootsFor(mode, cwd) {
+  switch (mode) {
+    case "read-only":
+      return [];
+    case "workspace-write":
+      return workspaceWriteRoots(cwd);
+    case "danger-full-access":
+      return null;
+  }
+}
 function buildBwrapArgv(mode, opts) {
   if (mode === "danger-full-access") return null;
   const cwd = path__default.default.resolve(opts.cwd);
@@ -41,10 +58,7 @@ function buildBwrapArgv(mode, opts) {
     ...opts.network ? {} : { CODEX_SANDBOX_NETWORK_DISABLED: "1" }
   };
   for (const [k, v] of Object.entries(setenv)) argv.push("--setenv", k, v);
-  if (mode === "workspace-write") {
-    argv.push("--bind", cwd, cwd, "--bind", "/tmp", "/tmp");
-    if (hasGit) argv.push("--ro-bind", gitDir, gitDir);
-  }
+  if (mode === "workspace-write") pushWorkspaceBinds(argv, cwd, hasGit, gitDir);
   argv.push("--chdir", cwd, "--");
   return argv;
 }
@@ -225,7 +239,7 @@ function allowlistedEnv(source = process.env) {
   }
   return out;
 }
-var LinuxSandbox = class extends chunkS7OEXQMI_cjs.LocalSandbox {
+var LinuxSandbox = class extends chunkR3CKCRK3_cjs.LocalSandbox {
   mode;
   network;
   cwd;
@@ -319,7 +333,7 @@ function seccompPathForArch(arch, warn) {
 var seccompFilterPath;
 function restrictedSeccompPath() {
   if (seccompFilterPath !== void 0) return seccompFilterPath ?? void 0;
-  const path2 = seccompPathForArch(process.arch, (m) => console.warn(chunkA76OFN2B_cjs.redactSecrets(m)));
+  const path2 = seccompPathForArch(process.arch, (m) => console.warn(chunkZHPET3LZ_cjs.redactSecrets(m)));
   seccompFilterPath = path2 ?? null;
   return path2;
 }
@@ -339,17 +353,17 @@ function resolveSandboxPosture(opts) {
 }
 function createSandboxBackend(opts) {
   const config = { workDir: opts.workDir, timeoutMs: opts.timeoutMs };
-  if (opts.mode === "danger-full-access") return new chunkS7OEXQMI_cjs.LocalSandbox(config);
+  if (opts.mode === "danger-full-access") return new chunkR3CKCRK3_cjs.LocalSandbox(config);
   const detection = (opts.detect ?? detectBwrapMemoized)();
   if (!detection.ok) {
     if (!warnedUnavailable) {
       warnedUnavailable = true;
-      const warn = opts.warn ?? ((m) => console.warn(chunkA76OFN2B_cjs.redactSecrets(m)));
+      const warn = opts.warn ?? ((m) => console.warn(chunkZHPET3LZ_cjs.redactSecrets(m)));
       warn(
         `[sandbox] OS-level enforcement unavailable (${detection.reason}) \u2014 falling back to tool-level gating only (sandbox_mode=${opts.mode}).`
       );
     }
-    return new chunkS7OEXQMI_cjs.LocalSandbox(config);
+    return new chunkR3CKCRK3_cjs.LocalSandbox(config);
   }
   return new LinuxSandbox(config, { mode: opts.mode, network: opts.network, bin: detection.bin });
 }
@@ -366,7 +380,7 @@ function decideConfinement(opts) {
   if (detection.ok) return detection.bin;
   if (!interactiveWarned) {
     interactiveWarned = true;
-    const warn = opts.warn ?? ((m) => console.warn(chunkA76OFN2B_cjs.redactSecrets(m)));
+    const warn = opts.warn ?? ((m) => console.warn(chunkZHPET3LZ_cjs.redactSecrets(m)));
     warn(
       `[sandbox] OS-level enforcement unavailable (${detection.reason}) \u2014 interactive session runs WITHOUT kernel confinement (sandbox_mode=${opts.mode}).`
     );
@@ -392,7 +406,7 @@ function interactiveWrapCommand(opts) {
 }
 
 // src/sandbox/provision.ts
-var RepoProvisionError = class extends chunkE7WWIX34_cjs.TheokitAgentError {
+var RepoProvisionError = class extends chunkYULF6FPB_cjs.TheokitAgentError {
   constructor(instanceId, message, options = {}) {
     super(`[${instanceId}] ${message}`, {
       code: "repo_provision_failed",
@@ -406,7 +420,7 @@ var RepoProvisionError = class extends chunkE7WWIX34_cjs.TheokitAgentError {
 };
 var SAFE_INSTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 async function provisionRepo(sandboxOrOpts, maybeOpts) {
-  const sandbox = maybeOpts !== void 0 ? sandboxOrOpts : new chunkS7OEXQMI_cjs.LocalSandbox();
+  const sandbox = maybeOpts !== void 0 ? sandboxOrOpts : new chunkR3CKCRK3_cjs.LocalSandbox();
   const opts = maybeOpts ?? sandboxOrOpts;
   const { repoUrl, ref, instanceId } = opts;
   if (!SAFE_INSTANCE_ID.test(instanceId)) {
@@ -419,20 +433,20 @@ async function provisionRepo(sandboxOrOpts, maybeOpts) {
     throw new RepoProvisionError(instanceId, `invalid ref: must not begin with '-' (got ${ref})`);
   }
   const clone = await sandbox.execute(
-    `git -c protocol.ext.allow=never clone --quiet -- ${chunkS7OEXQMI_cjs.shellEscapePosix(repoUrl)} ${chunkS7OEXQMI_cjs.shellEscapePosix(instanceId)}`
+    `git -c protocol.ext.allow=never clone --quiet -- ${chunkR3CKCRK3_cjs.shellEscapePosix(repoUrl)} ${chunkR3CKCRK3_cjs.shellEscapePosix(instanceId)}`
   );
   if (clone.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `clone failed: ${clone.stderr.trim()}`);
   }
   const top = await sandbox.execute(
-    `git -C ${chunkS7OEXQMI_cjs.shellEscapePosix(instanceId)} rev-parse --show-toplevel`
+    `git -C ${chunkR3CKCRK3_cjs.shellEscapePosix(instanceId)} rev-parse --show-toplevel`
   );
   if (top.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `resolve repoDir failed: ${top.stderr.trim()}`);
   }
   const repoDir = top.stdout.trim();
   const checkout = await sandbox.execute(
-    `git -C ${chunkS7OEXQMI_cjs.shellEscapePosix(repoDir)} checkout --quiet ${chunkS7OEXQMI_cjs.shellEscapePosix(ref)}`
+    `git -C ${chunkR3CKCRK3_cjs.shellEscapePosix(repoDir)} checkout --quiet ${chunkR3CKCRK3_cjs.shellEscapePosix(ref)}`
   );
   if (checkout.exitCode !== 0) {
     throw new RepoProvisionError(instanceId, `checkout ${ref} failed: ${checkout.stderr.trim()}`);
@@ -442,23 +456,23 @@ async function provisionRepo(sandboxOrOpts, maybeOpts) {
 
 Object.defineProperty(exports, "LocalSandbox", {
   enumerable: true,
-  get: function () { return chunkS7OEXQMI_cjs.LocalSandbox; }
+  get: function () { return chunkR3CKCRK3_cjs.LocalSandbox; }
 });
 Object.defineProperty(exports, "SandboxBackend", {
   enumerable: true,
-  get: function () { return chunkS7OEXQMI_cjs.SandboxBackend; }
+  get: function () { return chunkR3CKCRK3_cjs.SandboxBackend; }
 });
 Object.defineProperty(exports, "SandboxNotAvailableError", {
   enumerable: true,
-  get: function () { return chunkS7OEXQMI_cjs.SandboxNotAvailableError; }
+  get: function () { return chunkR3CKCRK3_cjs.SandboxNotAvailableError; }
 });
 Object.defineProperty(exports, "SandboxSecurityError", {
   enumerable: true,
-  get: function () { return chunkS7OEXQMI_cjs.SandboxSecurityError; }
+  get: function () { return chunkR3CKCRK3_cjs.SandboxSecurityError; }
 });
 Object.defineProperty(exports, "resolveSandbox", {
   enumerable: true,
-  get: function () { return chunkS7OEXQMI_cjs.resolveSandbox; }
+  get: function () { return chunkR3CKCRK3_cjs.resolveSandbox; }
 });
 exports.LinuxSandbox = LinuxSandbox;
 exports.RepoProvisionError = RepoProvisionError;
@@ -479,5 +493,6 @@ exports.resolveSandboxPosture = resolveSandboxPosture;
 exports.restrictedSeccompPath = restrictedSeccompPath;
 exports.seccompPathForArch = seccompPathForArch;
 exports.wrapCommandForSandbox = wrapCommandForSandbox;
+exports.writableRootsFor = writableRootsFor;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map