pi-long-task 0.6.0 → 0.7.0

package/src/session_guard.ts

@@ -15,13 +15,28 @@ export interface GuardedSessionPromptOptions {
   gracefulShutdownPrompt?: string;
   diagnostics?: string[];
   onEvent?: (event: unknown) => void;
+  /** Bounded elapsed-time checkpoints while the primary deadline is active. */
+  progressCheckpointsMs?: readonly number[];
+  onProgressCheckpoint?: (elapsedMs: number) => void;
+  /** Called exactly when a positive grace period begins. */
+  onGracePeriodStart?: (gracePeriodMs: number) => void;
   dispose?: boolean;
 }
 
 export interface GuardedSessionPromptResult {
   assistantText: string;
+  /** True when the primary prompt deadline elapsed, even if the prompt safely completed during grace. */
   timedOut: boolean;
+  /** True only when a timed-out prompt settled during the configured grace period. */
+  completedDuringGrace: boolean;
+  /** True when non-whitespace assistant output was observed before prompt termination. */
+  outputObserved: boolean;
+  /** True when the session had to be stopped because its grace period expired. */
+  graceExpired: boolean;
+  /** True when the session was stopped for any reason, including hard timeout. */
   aborted: boolean;
+  /** True only when the caller's AbortSignal cancelled the prompt. */
+  cancelled: boolean;
   error?: string;
   /** Untouched prompt failure for coordinator-level provider/transport classification. */
   failure?: unknown;
@@ -39,14 +54,19 @@ export async function runGuardedSessionPrompt(
   const events: unknown[] = [];
   const timers = new Set<ReturnType<typeof setTimeout>>();
   let assistantText = "";
+  let currentAssistantText = "";
+  let outputObserved = false;
   let timedOut = false;
+  let graceExpired = false;
   let aborted = false;
+  let cancelled = false;
   let error: string | undefined;
   let failure: unknown;
   let promptSettled = false;
   let finished = false;
   let unsubscribe: (() => void) | undefined;
   let complete: (() => void) | undefined;
+  const assistantTextAtStart = latestAssistantText(session, [], "");
 
   const completed = new Promise<void>((resolve) => {
     complete = resolve;
@@ -90,6 +110,14 @@ export async function runGuardedSessionPrompt(
     }
   };
 
+  const notifyTiming = (callback: (() => void) | undefined, label: string) => {
+    try {
+      callback?.();
+    } catch (exc) {
+      diagnostics.push(`${label} listener failed: ${errorMessage(exc)}`);
+    }
+  };
+
   const requestGracefulShutdown = () => {
     const message = options.gracefulShutdownPrompt?.trim();
     if (!message || finished || promptSettled || aborted) {
@@ -130,13 +158,18 @@ export async function runGuardedSessionPrompt(
     }
     timedOut = true;
     diagnostics.push(`session prompt timed out after ${formatMilliseconds(timeoutMs(options.timeoutMs))}`);
-    requestGracefulShutdown();
 
     const graceMs = nonNegativeMilliseconds(options.gracefulShutdownMs);
+    if (graceMs > 0) {
+      notifyTiming(() => options.onGracePeriodStart?.(graceMs), "grace-period progress");
+    }
+    requestGracefulShutdown();
+
     const hardAbort = () => {
       if (finished || promptSettled) {
         return;
       }
+      graceExpired = true;
       abortSession(`session prompt exceeded ${formatMilliseconds(timeoutMs(options.timeoutMs))} timeout`);
       resolveCompleted();
     };
@@ -152,20 +185,34 @@ export async function runGuardedSessionPrompt(
     if (finished || promptSettled) {
       return;
     }
-    abortSession(abortReason(options.abortSignal, "session prompt aborted by outer signal"));
+    cancelled = true;
+    abortSession(abortReason(options.abortSignal, "session prompt cancelled by outer signal"));
     resolveCompleted();
   };
 
   try {
     if (options.abortSignal?.aborted) {
       aborted = true;
-      error = abortReason(options.abortSignal, "session prompt aborted before start");
+      cancelled = true;
+      error = abortReason(options.abortSignal, "session prompt cancelled before start");
     } else {
       unsubscribe = session.subscribe((event: unknown) => {
         events.push(event);
-        const text = assistantTextFromEvent(event);
-        if (text) {
-          assistantText = text;
+        if (isAssistantMessageStart(event)) {
+          currentAssistantText = "";
+        }
+        const delta = assistantTextDeltaFromEvent(event);
+        if (delta !== undefined) {
+          currentAssistantText += delta;
+          assistantText = currentAssistantText || assistantText;
+          outputObserved ||= delta.trim().length > 0;
+        } else {
+          const text = assistantTextFromEvent(event);
+          if (text) {
+            currentAssistantText = text;
+            assistantText = text;
+            outputObserved ||= text.trim().length > 0;
+          }
         }
         try {
           options.onEvent?.(event);
@@ -192,6 +239,13 @@ export async function runGuardedSessionPrompt(
 
       const limitMs = timeoutMs(options.timeoutMs);
       if (limitMs > 0) {
+        for (const checkpoint of normalizedProgressCheckpoints(options.progressCheckpointsMs, limitMs)) {
+          schedule(() => {
+            if (!finished && !promptSettled && !timedOut && !aborted) {
+              notifyTiming(() => options.onProgressCheckpoint?.(checkpoint), "timing progress");
+            }
+          }, checkpoint);
+        }
         schedule(triggerTimeout, limitMs);
       }
 
@@ -206,6 +260,7 @@ export async function runGuardedSessionPrompt(
     options.abortSignal?.removeEventListener("abort", abortListener);
     unsubscribe?.();
     assistantText = latestAssistantText(session, events, assistantText);
+    outputObserved ||= assistantText.trim().length > 0 && assistantText !== assistantTextAtStart;
     if (options.dispose !== false) {
       try {
         const disposeResult = (session.dispose as (() => unknown) | undefined)?.();
@@ -220,7 +275,20 @@ export async function runGuardedSessionPrompt(
     }
   }
 
-  return buildResult(session, events, assistantText, timedOut, aborted, error, failure, diagnostics);
+  return buildResult(
+    session,
+    events,
+    assistantText,
+    timedOut,
+    timedOut && promptSettled && !graceExpired && !aborted && failure === undefined,
+    outputObserved,
+    graceExpired,
+    aborted,
+    cancelled,
+    error,
+    failure,
+    diagnostics,
+  );
 }
 
 function buildResult(
@@ -228,7 +296,11 @@ function buildResult(
   events: unknown[],
   assistantText: string,
   timedOut: boolean,
+  completedDuringGrace: boolean,
+  outputObserved: boolean,
+  graceExpired: boolean,
   aborted: boolean,
+  cancelled: boolean,
   error: string | undefined,
   failure: unknown,
   diagnostics: string[],
@@ -236,7 +308,11 @@ function buildResult(
   return {
     assistantText: latestAssistantText(session, events, assistantText),
     timedOut,
+    completedDuringGrace,
+    outputObserved,
+    graceExpired,
     aborted,
+    cancelled,
     error,
     ...(failure === undefined ? {} : { failure }),
     diagnostics: [...diagnostics],
@@ -266,6 +342,16 @@ function timeoutMs(value: number | undefined): number {
   return Math.max(0, value);
 }
 
+function normalizedProgressCheckpoints(values: readonly number[] | undefined, limitMs: number): number[] {
+  if (!values) {
+    return [];
+  }
+  return [...new Set(values)]
+    .filter((value) => Number.isFinite(value) && value > 0 && value < limitMs)
+    .map((value) => Math.floor(value))
+    .sort((left, right) => left - right);
+}
+
 function nonNegativeMilliseconds(value: number | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     return 0;
@@ -277,6 +363,26 @@ function formatMilliseconds(ms: number): string {
   return `${(ms / 1000).toFixed(3)}s`;
 }
 
+function isAssistantMessageStart(event: unknown): boolean {
+  return (
+    isRecord(event) && event.type === "message_start" && isRecord(event.message) && event.message.role === "assistant"
+  );
+}
+
+function assistantTextDeltaFromEvent(event: unknown): string | undefined {
+  if (!isRecord(event) || event.type !== "message_update" || !isRecord(event.assistantMessageEvent)) {
+    return undefined;
+  }
+  const assistantEvent = event.assistantMessageEvent;
+  return assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string"
+    ? assistantEvent.delta
+    : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 function abortReason(signal: AbortSignal | undefined, fallback: string): string {
   const reason = signal?.reason;
   if (reason === undefined) {

package/src/todo_generator.ts

@@ -133,7 +133,7 @@ export function applyGoalInstructionsToTodoMarkdown(markdown: string, goal?: str
     return markdown;
   }
 
-  let next = insertGlobalGoalInstructions(markdown, trimmedGoal);
+  let next = insertGlobalInstructions(markdown, goalInstructionLines(trimmedGoal));
   const coverageGoal = parseCoverageGoal(trimmedGoal);
   if (coverageGoal) {
     next = appendCoverageVerificationToTasks(next, coverageGoalVerifyBullet(coverageGoal));
@@ -142,14 +142,33 @@ export function applyGoalInstructionsToTodoMarkdown(markdown: string, goal?: str
   return next;
 }
 
-function insertGlobalGoalInstructions(markdown: string, goal: string): string {
+export function applyWorkerCapabilityConstraintsToTodoMarkdown(
+  markdown: string,
+  constraints: readonly string[],
+): string {
+  const additions = constraints
+    .map(oneLine)
+    .filter(Boolean)
+    .map((item) => `- ${item}`);
+  if (additions.length === 0) {
+    return markdown;
+  }
+  const next = insertGlobalInstructions(markdown, additions);
+  validateTodoMarkdown(next);
+  return next;
+}
+
+function goalInstructionLines(goal: string): string[] {
   const coverageGoal = parseCoverageGoal(goal);
   const additions = [`- Long task goal: ${goal}`];
   if (coverageGoal) {
     additions.push(`- Coverage goal: ${coverageGoalAction(coverageGoal)}`);
     additions.push(`- Coverage verification: ${coverageGoalVerification(coverageGoal)}`);
   }
+  return additions;
+}
 
+function insertGlobalInstructions(markdown: string, additions: readonly string[]): string {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
   const progressIndex = lines.findIndex((line) => /^##\s+Progress\s*$/i.test(line.trim()));
   if (progressIndex < 0) {
@@ -229,9 +248,43 @@ function oneLine(value: string): string {
   return value.replace(/\s+/g, " ").trim();
 }
 
-export function buildTodoCreationPrompt(rawInput: string, goal?: string): string {
+export function todoPlanningOnlyPromptBlock(capabilityConstraints: readonly string[] = []): string {
+  const capabilityBlock = capabilityConstraints.length
+    ? `\n\nWorker capability constraints (preserve these above ## Progress and in affected tasks):\n${capabilityConstraints
+        .map((constraint) => `- ${oneLine(constraint)}`)
+        .join("\n")}`
+    : "";
+  return `Planning-only boundary:
+- Produce only a concise executable plan for future workers.
+- Do not perform requested end work: do not implement or write code, execute research or report findings, create requested creative output (prose, stories, copy, designs, or assets), or produce any other final deliverable.
+- Use future-worker action language; do not claim work is complete or invent results.
+- Keep repeated task sections compact: use a one-sentence Goal and Done when, plus only the necessary Status and Verify bullets. Omit rationale, lengthy analysis, summaries, duplicated context, unrequested examples, and boilerplate.
+- Preserve every instruction, constraint, required deliverable, and acceptance condition from the source request and supplied planning context. Put shared constraints above ## Progress and task-specific requirements in the relevant task.${capabilityBlock}`;
+}
+
+export function buildTodoCreationPrompt(
+  rawInput: string,
+  goal?: string,
+  capabilityConstraints: readonly string[] = [],
+): string {
   const goalBlock = todoGoalPromptBlock(goal);
-  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.\n\nRequirements:\n- Output only markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n${goalBlock}\nRaw input:\n\n${rawInput.trim()}\n`;
+  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.
+
+${todoPlanningOnlyPromptBlock(capabilityConstraints)}
+
+Required format:
+- Output only markdown, with no commentary and no code fence.
+- Start with exactly: # Pi Long Task TODO
+- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title
+- Include a --- separator before task sections.
+- Create sequential sections named ## TODO N — Title.
+- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.
+- Keep tasks focused and independently assignable to worker sessions.
+${goalBlock}
+Raw input:
+
+${rawInput.trim()}
+`;
 }
 
 export function buildTodoRepairPrompt(
@@ -239,9 +292,33 @@ export function buildTodoRepairPrompt(
   invalidOutput: string,
   validationError: string,
   goal?: string,
+  capabilityConstraints: readonly string[] = [],
 ): string {
   const goalBlock = todoGoalPromptBlock(goal);
-  return `Your previous response was not valid Pi Long Task TODO markdown. Correct it now.\n\nValidation/extraction error:\n${validationError.trim() || "Unknown validation error."}\n\nRequirements:\n- Output only corrected markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n${goalBlock}\nOriginal raw input:\n\n${rawInput.trim()}\n\nPrevious invalid output:\n\n${invalidOutput.trim()}\n`;
+  return `Repair the previous response into valid Pi Long Task TODO markdown. Correct its plan and format only; do not continue or perform any attempted end work.
+
+${todoPlanningOnlyPromptBlock(capabilityConstraints)}
+
+Validation/extraction error:
+${validationError.trim() || "Unknown validation error."}
+
+Required format:
+- Output only corrected markdown, with no commentary and no code fence.
+- Start with exactly: # Pi Long Task TODO
+- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title
+- Include a --- separator before task sections.
+- Create sequential sections named ## TODO N — Title.
+- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.
+- Keep tasks focused and independently assignable to worker sessions.
+${goalBlock}
+Original raw input:
+
+${rawInput.trim()}
+
+Previous invalid output (repair its planning content; do not extend its end work):
+
+${invalidOutput.trim()}
+`;
 }
 
 function todoGoalPromptBlock(goal: string | undefined): string {

package/src/types.ts

@@ -1,7 +1,9 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
 
+import { MAX_PLANNER_DURATION_MS, type PlannerBudget } from "./planner_config.ts";
 import type { TaskProgressModel } from "./task_progress.ts";
+import type { WorkerCapabilityWarning } from "./worker_capabilities.ts";
 import type { SessionOutcome } from "./worker_session.ts";
 
 const NetworkRecoveryParams = Type.Object(
@@ -51,6 +53,22 @@ export const PiLongTaskParams = Type.Object(
         description: "Optional high-level goal or desired outcome for the long-task run.",
       }),
     ),
+    todoTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Explicit TODO-planner timeout in milliseconds. When omitted, the 5-minute default adapts deterministically for explicit item counts, enumerated deliverables, and separately planned tasks, up to 15 minutes.",
+      }),
+    ),
+    todoGracefulShutdownMs: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Grace period in milliseconds after the TODO-planner timeout. Defaults to 15000 (15 seconds); use 0 to disable the grace period.",
+      }),
+    ),
     networkRecovery: Type.Optional(NetworkRecoveryParams),
   },
   { additionalProperties: false },
@@ -113,6 +131,22 @@ export const PiGoalTaskParams = Type.Object(
         description: "Maximum bash command timeout in milliseconds allowed in worker sessions.",
       }),
     ),
+    todoTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Explicit TODO-planner timeout in milliseconds for child long-task planning and plan revisions. When omitted, the 5-minute default adapts deterministically for explicit item counts, enumerated deliverables, and separately planned tasks, up to 15 minutes.",
+      }),
+    ),
+    todoGracefulShutdownMs: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Grace period in milliseconds after a child TODO-planner timeout. Defaults to 15000 (15 seconds); use 0 to disable the grace period.",
+      }),
+    ),
     networkRecovery: Type.Optional(NetworkRecoveryParams),
   },
   { additionalProperties: false },
@@ -165,6 +199,8 @@ export interface PiLongTaskResult {
   }>;
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
+  plannerBudget?: Readonly<PlannerBudget>;
+  capabilityWarnings?: readonly WorkerCapabilityWarning[];
   commit: boolean;
   goal?: string;
   error?: string;

package/src/worker_capabilities.ts

@@ -0,0 +1,103 @@
+export interface IsolatedWorkerCapabilities {
+  /** Tool names exposed directly to the worker session. */
+  tools: readonly string[];
+  /** Pi Long Task isolated sessions deliberately disable extension runtimes. */
+  extensionsEnabled: boolean;
+}
+
+export type WorkerCapabilityWarningCode = "unavailable_browser_capability";
+
+export interface WorkerCapabilityWarning {
+  code: WorkerCapabilityWarningCode;
+  requestedCapabilities: readonly string[];
+  availableTools: readonly string[];
+  message: string;
+  planningConstraint: string;
+}
+
+const BROWSER_EXTENSION_REQUIREMENT_RE =
+  /\b(?:must(?:\s+use)?|need(?:s|ed)?(?:\s+to\s+use)?|require(?:s|d)?|rely(?:ing)?\s+on|use|using|via|through|with)\s+(?:the\s+|an?\s+)?(?:google\s+)?(?:chrome|chromium|firefox|edge|browser)(?:\s+(?:browser|devtools?))?\s+(?:extension|mcp|connector)\b/i;
+const REQUIRED_NAMED_BROWSER_EXTENSION_RE =
+  /\b(?:chrome\s+devtools\s+(?:mcp|extension|tool)|(?:chrome|browser)\s+(?:mcp|extension(?:\s+tool)?|tool\s+extension))\s+(?:is\s+(?:required|needed)|must\s+be\s+used)\b/i;
+const IMPERATIVE_CHROME_RE =
+  /\b(?:open|launch|control|drive|browse\s+with|inspect\s+(?:with|using)|scrape\s+(?:with|using)|fetch\s+(?:with|using)|test\s+(?:with|using))\s+(?:google\s+)?chrome\b/i;
+const EXPLICIT_BROWSER_TOOL_RE =
+  /\b(?:must(?:\s+use)?|need(?:s|ed)?(?:\s+to\s+use)?|require(?:s|d)?|use|using|via|through|with)\s+(?:the\s+)?(browser|chrome|web[_-]?fetch|playwright|puppeteer)\s+tool\b/i;
+const EXPLICIT_CHROME_RUNTIME_RE =
+  /(?:\b(?:must\s+use|need(?:s|ed)?\s+to\s+use|use|using)\s+(?:google\s+)?chrome(?:\s+devtools?)?(?=\s+(?:to|for)\b|\s*[.,;:]|\s*$)|\b(?:via|through)\s+(?:google\s+)?chrome\b|\b(?:google\s+)?chrome(?:\s+devtools?)?\s+(?:is\s+required|must\s+be\s+used)\b)/i;
+const NEGATED_CAPABILITY_RE =
+  /\b(?:do\s+not|don't|dont|never|avoid|without)\s+(?:use|using|rely(?:ing)?\s+on|requiring?)?\s*(?:the\s+|an?\s+)?(?:google\s+)?(?:chrome(?:\s+(?:browser|devtools?))?|chromium|firefox|edge|browser|web[_-]?fetch|playwright|puppeteer)(?:\s+(?:extension|mcp|tool(?:ing)?|connector))?/gi;
+
+/**
+ * Detect only explicit requests to invoke a browser capability. Merely asking
+ * workers to build or support a browser extension is implementation work and
+ * does not imply that the extension must be loaded during the run.
+ */
+export function detectUnavailableWorkerCapabilities(
+  requestText: string,
+  capabilities: Readonly<IsolatedWorkerCapabilities>,
+): WorkerCapabilityWarning[] {
+  const text = requestText.replace(NEGATED_CAPABILITY_RE, " ");
+  const extensionRequested =
+    BROWSER_EXTENSION_REQUIREMENT_RE.test(text) ||
+    REQUIRED_NAMED_BROWSER_EXTENSION_RE.test(text) ||
+    IMPERATIVE_CHROME_RE.test(text);
+  const browserToolMatch = EXPLICIT_BROWSER_TOOL_RE.exec(text);
+  const requestedDirectTools = [
+    browserToolMatch?.[1],
+    EXPLICIT_CHROME_RUNTIME_RE.test(text) ? "chrome" : undefined,
+  ].filter((item, index, all): item is string => Boolean(item) && all.indexOf(item) === index);
+  const unavailableDirectTools = requestedDirectTools.filter(
+    (requested) =>
+      !capabilities.tools.some((available) => canonicalToolName(available) === canonicalToolName(requested)),
+  );
+
+  if ((!extensionRequested || capabilities.extensionsEnabled) && unavailableDirectTools.length === 0) {
+    return [];
+  }
+
+  const requestedCapabilities = [
+    extensionRequested && !capabilities.extensionsEnabled ? "Chrome/browser extension runtime" : undefined,
+    unavailableDirectTools.length > 0 ? `${unavailableDirectTools.join("/")} direct tool` : undefined,
+  ].filter((item): item is string => Boolean(item));
+  const availableTools = [...capabilities.tools];
+  const toolList = availableTools.length > 0 ? availableTools.join(", ") : "none";
+  const alternatives = availableWorkerAlternatives(capabilities);
+  const alternativeText = alternatives.join(", or ");
+
+  return [
+    {
+      code: "unavailable_browser_capability",
+      requestedCapabilities,
+      availableTools,
+      message:
+        `Worker capability warning: isolated Pi Long Task workers disable extensions and expose only these direct tools: ${toolList}. ` +
+        `They cannot silently use the requested ${requestedCapabilities.join(" or ")}. The run will continue, but it must use an available safe alternative when that satisfies the request: ${alternativeText}. ` +
+        "If the exact extension or browser tool is mandatory, the affected task must report blocked instead of claiming it used that capability.",
+      planningConstraint:
+        `Isolated-worker capability constraint: extensions are disabled and workers have only these direct tools: ${toolList}. ` +
+        `Do not create or execute tasks that assume the requested ${requestedCapabilities.join(" or ")} is available, and never claim it was used. ` +
+        `When equivalent, ${alternativeText}. If the exact unavailable capability is mandatory, make the affected task report blocked with the required user action.`,
+    },
+  ];
+}
+
+function canonicalToolName(tool: string): string {
+  return tool.toLowerCase().replace(/[-_]/g, "");
+}
+
+function availableWorkerAlternatives(capabilities: Readonly<IsolatedWorkerCapabilities>): string[] {
+  const alternatives: string[] = [];
+  if (capabilities.tools.includes("bash")) {
+    alternatives.push(
+      "fetch public content through a supported command-line mechanism via bash or run project-provided browser automation via bash when available",
+    );
+  }
+  if (capabilities.tools.includes("read")) {
+    alternatives.push("supply the page or source content to the run so workers can read it locally");
+  }
+  if (alternatives.length === 0) {
+    alternatives.push("supply the needed source content to the run");
+  }
+  return alternatives;
+}

package/src/worker_config.ts

@@ -3,11 +3,14 @@ import {
   resolveNetworkRecoveryConfig,
   type NetworkRecoveryConfigInput,
 } from "./network_recovery_config.ts";
+import { MAX_PLANNER_DURATION_MS, PlannerDurationConfigError } from "./planner_config.ts";
 
 export interface ParsedWorkerRuntimeConfig {
   modelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   maxBashTimeoutMs?: number;
   workerSessionReuseEnabled?: boolean;
   workerSessionReuseContextThresholdPercent?: number;
@@ -52,6 +55,8 @@ export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfi
     ...(modelName ? { modelName } : {}),
     ...(state.maxAttemptsPerTask !== undefined ? { maxAttemptsPerTask: state.maxAttemptsPerTask } : {}),
     ...(state.taskTimeoutMs !== undefined ? { taskTimeoutMs: state.taskTimeoutMs } : {}),
+    ...(state.todoTimeoutMs !== undefined ? { todoTimeoutMs: state.todoTimeoutMs } : {}),
+    ...(state.todoGracefulShutdownMs !== undefined ? { todoGracefulShutdownMs: state.todoGracefulShutdownMs } : {}),
     ...(state.maxBashTimeoutMs !== undefined ? { maxBashTimeoutMs: state.maxBashTimeoutMs } : {}),
     ...(state.workerSessionReuseEnabled !== undefined
       ? { workerSessionReuseEnabled: state.workerSessionReuseEnabled }
@@ -135,14 +140,36 @@ function parseNaturalLanguageDirectives(text: string, state: MutableWorkerRuntim
 
   captureDurations(
     text,
-    /\b(?<!bash\s)(?<!max\s)(?:worker\s+|task\s+)?timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    /\b(?:todo\s+)?(?:planner|planning)\s+timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    (value) => {
+      state.todoTimeoutMs = value;
+    },
+  );
+  captureDurations(
+    text,
+    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))\s+(?:todo\s+)?(?:planner|planning)\s+timeout\b/gi,
+    (value) => {
+      state.todoTimeoutMs = value;
+    },
+  );
+  captureDurations(
+    text,
+    /\b(?:todo\s+)?(?:planner|planning)\s+(?:grace(?:ful)?(?:\s+shutdown|\s+period)?|shutdown\s+grace(?:\s+period)?)\s*(?:duration\s*)?(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    (value) => {
+      state.todoGracefulShutdownMs = value;
+    },
+    { allowZero: true },
+  );
+  captureDurations(
+    text,
+    /\b(?<!bash\s)(?<!max\s)(?<!planner\s)(?<!planning\s)(?:worker\s+|task\s+)?timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
     (value) => {
       state.taskTimeoutMs = value;
     },
   );
   captureDurations(
     text,
-    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))\s+(?:worker\s+|task\s+)?timeout\b/gi,
+    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))[ \t]+(?:worker[ \t]+|task[ \t]+)?timeout\b/gi,
     (value) => {
       state.taskTimeoutMs = value;
     },
@@ -215,6 +242,16 @@ function applyDirective(key: string, value: string, state: MutableWorkerRuntimeC
     return;
   }
 
+  if (/\b(?:planner|planning)\b/.test(key) && /\b(?:grace|graceful|shutdown)\b/.test(key)) {
+    state.todoGracefulShutdownMs = requiredPlannerDuration("graceful-shutdown duration", value, true);
+    return;
+  }
+
+  if (/\b(?:planner|planning)\b/.test(key) && /\btimeout\b/.test(key)) {
+    state.todoTimeoutMs = requiredPlannerDuration("timeout", value, false);
+    return;
+  }
+
   if (/\bbash\b/.test(key) && /\btimeout\b/.test(key)) {
     const timeout = durationMsFromText(value, { allowBareSeconds: true });
     if (timeout !== undefined) {
@@ -268,6 +305,23 @@ function applyNetworkRecoveryDirective(key: string, value: string, state: Mutabl
   throw new NetworkRecoveryConfigError(`Unknown network recovery configuration directive: ${key}.`);
 }
 
+function requiredPlannerDuration(label: string, value: string, allowZero: boolean): number {
+  const trimmed = trimDirectiveValue(value)
+    .replace(/[.!]+$/g, "")
+    .trim();
+  const match = /^(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?$/i.exec(
+    trimmed,
+  );
+  const milliseconds = match ? durationMsFromText(trimmed, { allowBareSeconds: true, allowZero }) : undefined;
+  if (milliseconds === undefined || milliseconds > MAX_PLANNER_DURATION_MS) {
+    const minimum = allowZero ? "non-negative" : "positive";
+    throw new PlannerDurationConfigError(
+      `TODO planner ${label} must be a ${minimum} finite duration no greater than about 24.9 days (${MAX_PLANNER_DURATION_MS} milliseconds), for example 30s or 5m.`,
+    );
+  }
+  return milliseconds;
+}
+
 function requiredNetworkRecoveryDuration(label: string, value: string): number {
   const trimmed = trimDirectiveValue(value)
     .replace(/[.!]+$/g, "")
@@ -307,9 +361,17 @@ function captureNumbers(text: string, pattern: RegExp, apply: (value: number) =>
   }
 }
 
-function captureDurations(text: string, pattern: RegExp, apply: (value: number) => void): void {
+function captureDurations(
+  text: string,
+  pattern: RegExp,
+  apply: (value: number) => void,
+  options: { allowZero?: boolean } = {},
+): void {
   for (const match of text.matchAll(pattern)) {
-    const value = durationMsFromText(match[1] ?? "", { allowBareSeconds: true });
+    const value = durationMsFromText(match[1] ?? "", {
+      allowBareSeconds: true,
+      allowZero: options.allowZero,
+    });
     if (value !== undefined) {
       apply(value);
     }
@@ -373,7 +435,10 @@ function booleanSetting(value: string): boolean | undefined {
   return undefined;
 }
 
-function durationMsFromText(value: string, options: { allowBareSeconds: boolean }): number | undefined {
+function durationMsFromText(
+  value: string,
+  options: { allowBareSeconds: boolean; allowZero?: boolean },
+): number | undefined {
   const match = /(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?\b/i.exec(
     value,
   );
@@ -382,7 +447,7 @@ function durationMsFromText(value: string, options: { allowBareSeconds: boolean
   }
 
   const amount = Number.parseFloat(match[1] ?? "");
-  if (!Number.isFinite(amount) || amount <= 0) {
+  if (!Number.isFinite(amount) || amount < 0 || (!options.allowZero && amount === 0)) {
     return undefined;
   }
 
@@ -393,7 +458,9 @@ function durationMsFromText(value: string, options: { allowBareSeconds: boolean
 
   const multiplier = durationMultiplier(unit || "seconds");
   const milliseconds = Math.round(amount * multiplier);
-  return Number.isSafeInteger(milliseconds) && milliseconds > 0 ? milliseconds : undefined;
+  return Number.isSafeInteger(milliseconds) && (options.allowZero ? milliseconds >= 0 : milliseconds > 0)
+    ? milliseconds
+    : undefined;
 }
 
 function durationMultiplier(unit: string): number {