pi-workflow-engine 0.9.0 → 0.10.1

package/.pi/extensions/pi-workflow-engine/src/diff-capture.ts

@@ -1,6 +1,5 @@
-import { spawn } from "node:child_process";
-import { performance } from "node:perf_hooks";
 import type { PerfSink } from "./perf.ts";
+import { runBoundedProcess } from "./process-runner.ts";
 
 export interface AllowedDiffCommand {
   readonly file: "git" | "gh";
@@ -75,76 +74,23 @@ export async function captureDiff(command: string, options: DiffCaptureOptions):
     return { ok: false, stdout: "", durationMs: 0, bytes: 0, error: parsed.error };
   }
 
-  const start = performance.now();
-  let stdout = "";
-  let stderr = "";
-  let bytes = 0;
-  let error: string | undefined;
-  const child = spawn(parsed.file, [...parsed.args], {
+  const result = await runBoundedProcess({
+    file: parsed.file,
+    args: parsed.args,
     cwd: options.cwd,
     env: diffCaptureEnv(options.env),
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  return await new Promise<DiffCaptureResult>((resolve) => {
-    let settled = false;
-    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
-    const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
-    const finish = (ok: boolean, finishError?: string) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      const durationMs = performance.now() - start;
-      options.perf?.observe("diff.capture_ms", durationMs);
-      options.perf?.observe("diff.bytes", bytes);
-      resolve({ ok, stdout, durationMs, bytes, error: finishError });
-    };
-    const kill = (message: string) => {
-      error = error ?? message;
-      child.kill("SIGTERM");
-      forceKillTimer ??= setTimeout(() => {
-        child.kill("SIGKILL");
-        finish(false, error);
-      }, killGraceMs);
-    };
-    const onAbort = () => kill("diff capture aborted");
-    const timeout = setTimeout(() => kill(`diff capture timed out after ${options.timeoutMs}ms`), options.timeoutMs);
-    const cleanup = () => {
-      clearTimeout(timeout);
-      if (forceKillTimer) clearTimeout(forceKillTimer);
-      options.signal?.removeEventListener("abort", onAbort);
-    };
-
-    if (options.signal?.aborted) {
-      kill("diff capture aborted");
-    } else {
-      options.signal?.addEventListener("abort", onAbort, { once: true });
-    }
-
-    child.stdout?.on("data", (chunk: Buffer) => {
-      bytes += chunk.length;
-      if (bytes > options.maxBufferBytes) {
-        kill(`diff capture exceeded ${options.maxBufferBytes} bytes`);
-        return;
-      }
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf8");
-    });
-    child.on("error", (spawnError) => finish(false, spawnError.message));
-    child.on("close", (code, signal) => {
-      if (error) {
-        finish(false, error);
-        return;
-      }
-      if (code === 0) {
-        finish(true);
-        return;
-      }
-      finish(false, stderr.trim() || `diff command exited with code ${code ?? `signal ${signal ?? "unknown"}`}`);
-    });
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxBufferBytes: options.maxBufferBytes,
+    killGraceMs: options.killGraceMs,
+    abortError: "diff capture aborted",
+    timeoutError: `diff capture timed out after ${options.timeoutMs}ms`,
+    maxBufferError: `diff capture exceeded ${options.maxBufferBytes} bytes`,
+    exitError: (stderr, code, signal) => stderr.trim() || `diff command exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
   });
+  options.perf?.observe("diff.capture_ms", result.durationMs);
+  options.perf?.observe("diff.bytes", result.bytes);
+  return result;
 }
 
 function diffCaptureEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { parallel, pipeline, Semaphore } from "./concurrency.ts";
+import { bindPipeline, parallel, Semaphore } from "./concurrency.ts";
 import { linkAbortSignal } from "./cancellation.ts";
+import { createBudget } from "./budget.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
@@ -8,6 +9,8 @@ import { createWorkflowUsageRecorder } from "./usage.ts";
 import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
 import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
+import { WorktreeRegistry } from "./worktree.ts";
 
 /** Default global cap on concurrent agents per run. */
 const DEFAULT_CONCURRENCY = defaultConcurrency();
@@ -60,6 +63,14 @@ export async function runWorkflow(
 
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
   const usage = createWorkflowUsageRecorder();
+  const budget = createBudget(resolvedOptions.budget ?? null, usage);
+  const runId = resolvedOptions.runId ?? createWorkflowRunId();
+  const journalPath = workflowJournalPath(ctx.cwd, runId);
+  const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
+  const journal = await createWorkflowJournal({ resumePath, writePath: journalPath });
+  const worktrees = new WorktreeRegistry(ctx.cwd);
+  resolvedOptions.onRunMetadata?.({ runId, resumedFromRunId: resolvedOptions.resumeFromRunId, journalPath });
+  progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
@@ -72,6 +83,9 @@ export async function runWorkflow(
     signal: runAbortController.signal,
     perf,
     usage,
+    budget,
+    journal,
+    worktrees,
   };
 
   try {
@@ -99,6 +113,13 @@ export async function runWorkflow(
       resolvedOptions.onProgressSource?.(undefined);
       unlinkContextAbortSignal();
       unlinkOptionAbortSignal();
+      const cleanupResults = await worktrees.removeAll();
+      for (const result of cleanupResults) {
+        if (!result.ok) {
+          progress.log(`failed to remove isolated worktree ${result.path} (${result.error ?? (result.stderr.trim() || "unknown error")})`);
+        }
+      }
+      await pruneWorkflowJournals(ctx.cwd);
     }
   }
 }
@@ -156,12 +177,13 @@ export async function runWorkflowWithContext(
         abortController: opts.abortController,
         limit: opts.submissionLimit,
       }),
-    pipeline,
+    pipeline: bindPipeline({ signal: rc.signal, abortController: opts.abortController }),
     phase: scope.phase,
     log: scope.log,
     progress: scope.event,
     args,
     cwd: rc.cwd,
+    budget: rc.budget,
     signal: rc.signal,
   };
 

package/.pi/extensions/pi-workflow-engine/src/journal.ts

@@ -0,0 +1,200 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { AgentOptions } from "./types.ts";
+
+export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
+export const WORKFLOW_JOURNAL_KEEP = 50;
+
+export interface JournalEntry {
+  readonly key: string;
+  readonly value: unknown;
+}
+
+export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false };
+export type JournalRecordResult = { readonly ok: true } | { readonly ok: false; readonly error: string };
+
+export interface WorkflowJournal {
+  lookup(key: string): JournalLookup;
+  record(key: string, value: unknown): Promise<JournalRecordResult>;
+}
+
+export class WorkflowJournalLoadError extends Error {
+  override readonly name = "WorkflowJournalLoadError";
+}
+
+export function createWorkflowRunId(): string {
+  return randomUUID();
+}
+
+export function workflowJournalPath(cwd: string, runId: string): string {
+  return join(cwd, WORKFLOW_RUNS_DIR, `${validateRunId(runId)}.jsonl`);
+}
+
+export function agentJournalKey(prompt: string, opts: AgentOptions = {}): string {
+  const behaviorHash = hashAgentCall(prompt, opts);
+  const cacheKey = opts.cacheKey?.trim();
+  if (!cacheKey) return `agent:${behaviorHash}`;
+  const cacheKeyHash = createHash("sha256").update(cacheKey).digest("hex");
+  return `agent:${cacheKeyHash}:${behaviorHash}`;
+}
+
+export function hashAgentCall(prompt: string, opts: AgentOptions = {}): string {
+  const behavior = {
+    prompt,
+    opts: {
+      model: opts.model,
+      thinkingLevel: opts.thinkingLevel,
+      tools: sortedArray(opts.tools),
+      toolHints: sortedArray(opts.toolHints),
+      skills: sortedArray(opts.skills),
+      schema: opts.schema,
+      isolation: opts.isolation,
+    },
+  };
+  return createHash("sha256").update(stableStringify(behavior)).digest("hex");
+}
+
+export async function loadJournalEntries(path: string, options: { readonly required?: boolean } = {}): Promise<JournalEntry[]> {
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (options.required) {
+      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${formatError(error)}`);
+    }
+    return [];
+  }
+
+  const entries: JournalEntry[] = [];
+  let lineNumber = 0;
+  for (const line of content.split(/\r?\n/)) {
+    lineNumber += 1;
+    if (line.trim() === "") continue;
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (isJournalEntry(parsed)) {
+        entries.push(parsed);
+        continue;
+      }
+      if (options.required) {
+        throw new WorkflowJournalLoadError(`Workflow resume journal at ${path}:${lineNumber} has an incompatible entry format.`);
+      }
+    } catch (error) {
+      if (options.required) {
+        if (error instanceof WorkflowJournalLoadError) throw error;
+        throw new WorkflowJournalLoadError(`Workflow resume journal at ${path}:${lineNumber} is not valid JSON.`);
+      }
+    }
+  }
+  return entries;
+}
+
+export async function createWorkflowJournal(options: {
+  readonly resumePath?: string;
+  readonly writePath: string;
+}): Promise<WorkflowJournal> {
+  const priorEntries = options.resumePath ? await loadJournalEntries(options.resumePath, { required: true }) : [];
+  return createMemoryBackedJournal(priorEntries, options.writePath);
+}
+
+export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[] = [], writePath?: string): WorkflowJournal {
+  const priorByKey = new Map<string, JournalEntry | "ambiguous">();
+  for (const entry of priorEntries) {
+    priorByKey.set(entry.key, priorByKey.has(entry.key) ? "ambiguous" : entry);
+  }
+
+  return {
+    lookup(key) {
+      const entry = priorByKey.get(key);
+      if (!entry || entry === "ambiguous") return { hit: false };
+      return { hit: true, value: entry.value };
+    },
+    async record(key, value) {
+      const entry = { key, value };
+      if (writePath) {
+        try {
+          await mkdir(dirname(writePath), { recursive: true });
+          await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
+        } catch (error) {
+          return { ok: false, error: formatError(error) };
+        }
+      }
+      return { ok: true };
+    },
+  };
+}
+
+export async function pruneWorkflowJournals(cwd: string, keep = WORKFLOW_JOURNAL_KEEP): Promise<void> {
+  const dir = join(cwd, WORKFLOW_RUNS_DIR);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return;
+  }
+
+  const candidates = await Promise.all(
+    files
+      .filter((file) => file.endsWith(".jsonl"))
+      .map(async (file) => {
+        const path = join(dir, file);
+        try {
+          const info = await stat(path);
+          return { path, mtimeMs: info.mtimeMs };
+        } catch {
+          return undefined;
+        }
+      }),
+  );
+
+  const stale = candidates
+    .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(Math.max(0, keep));
+
+  await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
+}
+
+function validateRunId(runId: string): string {
+  const trimmed = runId.trim();
+  if (!/^[A-Za-z0-9_.-]+$/.test(trimmed)) {
+    throw new Error("Workflow run id must contain only letters, numbers, dots, underscores, or hyphens.");
+  }
+  return trimmed;
+}
+
+function sortedArray(values: readonly string[] | undefined): readonly string[] | undefined {
+  return values ? [...values].sort() : undefined;
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(normalizeStable(value));
+}
+
+function normalizeStable(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map(normalizeStable);
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(record).sort()) {
+      const normalized = normalizeStable(record[key]);
+      if (normalized !== undefined) out[key] = normalized;
+    }
+    return out;
+  }
+  return String(value);
+}
+
+function isJournalEntry(value: unknown): value is JournalEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as { readonly key?: unknown; readonly value?: unknown };
+  return typeof entry.key === "string" && "value" in entry;
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/.pi/extensions/pi-workflow-engine/src/options.ts

@@ -1,10 +1,14 @@
 import { cpus } from "node:os";
 import type { WorkflowRunOptions } from "./types.ts";
 
+export const WORKFLOW_BUDGET_MIN = 1;
+export const WORKFLOW_BUDGET_MAX = 1_000_000_000;
+
 export interface ResolvedWorkflowRunOptions extends WorkflowRunOptions {
   readonly perf: boolean;
   readonly concurrency: number;
   readonly parallelSubmissionLimit?: number;
+  readonly budget?: number;
 }
 
 export function defaultConcurrency(cpuCount = cpus().length): number {
@@ -21,16 +25,18 @@ export function resolveWorkflowRunOptions(
     1,
     10_000,
   );
+  const budget = resolveBudget(input.budget, env.PI_WORKFLOW_BUDGET);
   return {
     ...input,
     perf: input.perf ?? env.PI_WORKFLOW_PERF === "1",
     concurrency,
     parallelSubmissionLimit,
+    budget,
   };
 }
 
 function optionalClampedInteger(value: number | undefined, min: number, max: number): number | undefined {
-  if (value === undefined) return undefined;
+  if (value === undefined || !Number.isFinite(value)) return undefined;
   return clampInteger(value, min, max, value);
 }
 
@@ -44,3 +50,23 @@ function parseInteger(value: string | undefined): number | undefined {
   const parsed = Number(value);
   return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
 }
+
+function resolveBudget(inputBudget: number | undefined, envBudget: string | undefined): number | undefined {
+  if (inputBudget !== undefined) return normalizeExplicitBudget(inputBudget);
+  return envBudget === undefined ? undefined : parseWorkflowBudgetString(envBudget);
+}
+
+function normalizeExplicitBudget(value: number): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < WORKFLOW_BUDGET_MIN || value > WORKFLOW_BUDGET_MAX) {
+    throw new RangeError(`Workflow budget must be an integer between ${WORKFLOW_BUDGET_MIN} and ${WORKFLOW_BUDGET_MAX}.`);
+  }
+  return value;
+}
+
+export function parseWorkflowBudgetString(value: string): number | undefined {
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed) || parsed < WORKFLOW_BUDGET_MIN || parsed > WORKFLOW_BUDGET_MAX) return undefined;
+  return parsed;
+}

package/.pi/extensions/pi-workflow-engine/src/process-runner.ts

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+
+export interface BoundedProcessOptions {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+  readonly killGraceMs?: number;
+  readonly abortError: string;
+  readonly timeoutError: string;
+  readonly maxBufferError?: string;
+  readonly exitError: (stderr: string, code: number | null, signal: NodeJS.Signals | null) => string;
+}
+
+export interface BoundedProcessResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+  readonly bytes: number;
+  readonly error?: string;
+}
+
+export async function runBoundedProcess(options: BoundedProcessOptions): Promise<BoundedProcessResult> {
+  const start = performance.now();
+  let stdout = "";
+  let stderr = "";
+  let bytes = 0;
+  let error: string | undefined;
+  const child = spawn(options.file, [...options.args], {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  return await new Promise<BoundedProcessResult>((resolve) => {
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
+    const finish = (ok: boolean, finishError?: string) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({ ok, stdout, stderr, durationMs: performance.now() - start, bytes, error: finishError });
+    };
+    const kill = (message: string) => {
+      error = error ?? message;
+      child.kill("SIGTERM");
+      forceKillTimer ??= setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(false, error);
+      }, killGraceMs);
+    };
+    const onAbort = () => kill(options.abortError);
+    const timeout = setTimeout(() => kill(options.timeoutError), options.timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+
+    if (options.signal?.aborted) {
+      kill(options.abortError);
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
+        kill(options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`);
+        return;
+      }
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (spawnError) => finish(false, spawnError.message));
+    child.on("close", (code, signal) => {
+      if (error) {
+        finish(false, error);
+        return;
+      }
+      if (code === 0) {
+        finish(true);
+        return;
+      }
+      finish(false, options.exitError(stderr, code, signal));
+    });
+  });
+}

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -1,5 +1,6 @@
 import type { Static, TSchema } from "typebox";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { WorkflowBudget } from "./budget.ts";
 import type { Pipeline } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress.ts";
@@ -23,11 +24,23 @@ export interface WorkflowRunStats {
   [key: string]: string | number;
 }
 
+export interface WorkflowRunMetadata {
+  readonly runId: string;
+  readonly resumedFromRunId?: string;
+  readonly journalPath: string;
+}
+
 export interface WorkflowRunOptions {
   inspect?: boolean;
   perf?: boolean;
   concurrency?: number;
   parallelSubmissionLimit?: number;
+  /** Output-token ceiling for the whole run. Omit for no limit (budget.total === null). */
+  budget?: number;
+  /** Internal/test override for the generated run id. Omit to generate a new id. */
+  runId?: string;
+  /** Replay completed agent results from this prior run id when prompt/options hashes still match. */
+  resumeFromRunId?: string;
   resultViewer?: "open" | "skip";
   /** Additional abort signal to compose with the host context signal. */
   signal?: AbortSignal;
@@ -39,6 +52,8 @@ export interface WorkflowRunOptions {
   onPerfSnapshot?: (snapshot: PerfSnapshot) => void;
   /** Called with the final workflow subagent usage snapshot. */
   onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void;
+  /** Called once run identity and journal paths are known. */
+  onRunMetadata?: (metadata: WorkflowRunMetadata) => void;
   /** Called with the live progress source while a workflow is running, then undefined when it ends. */
   onProgressSource?: (source: WorkflowProgressSource | undefined) => void;
   /** Called with the final completed progress snapshot after live workflow UI teardown. */
@@ -52,6 +67,14 @@ export interface WorkflowProgressSource {
 /** Options for a single `agent()` call. */
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
+export type AgentToolHint = "search";
+
+export interface IsolatedAgentResult<T> {
+  readonly result: T;
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
 export type WorkflowProgressEvent =
   | { type: "counter"; key: string; label: string; value: number }
   | { type: "counter_delta"; key: string; label: string; delta: number }
@@ -77,8 +100,21 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   model?: string;
   /** Reasoning effort for this agent. */
   thinkingLevel?: ThinkingLevel;
-  /** Allowlist of built-in tool names the agent may use (e.g. ["read", "bash"]). */
+  /**
+   * Stable identity hint for resume replay. Use this for repeated logical calls
+   * with identical prompts/options, e.g. `${stage}:${item.id}`.
+   */
+  cacheKey?: string;
+  /** Run this agent in a disposable git worktree and return its patch with the result. */
+  isolation?: "worktree";
+  /** Allowlist of concrete tool names the agent may use (e.g. ["read", "bash"]). */
   tools?: string[];
+  /**
+   * Dynamically include installed tools matching semantic categories. Currently
+   * "search" matches grep/find/code-search style tools such as ast-grep,
+   * mgrep, ffgrep, fffind, ripgrep wrappers, and pi's built-in grep/find/ls.
+   */
+  toolHints?: readonly AgentToolHint[];
   /**
    * Skill names to expose to this subagent. Subagents receive no skills by default.
    * When omitted, clear prompt text such as `/skill:name`, `include skill name`, or
@@ -95,6 +131,13 @@ export interface AgentOptions<S extends TSchema = TSchema> {
  * exports `meta` plus a default `async (api: WorkflowApi) => result`.
  */
 export interface WorkflowApi {
+  /** Run a schema subagent in a disposable worktree and return its structured result plus patch. */
+  agent<S extends TSchema>(
+    prompt: string,
+    opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
+  ): Promise<IsolatedAgentResult<Static<S> | null>>;
+  /** Run a text subagent in a disposable worktree and return its final text plus patch. */
+  agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
   /** Run a subagent and return its validated structured output (null if it never produced one). */
   agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
   /** Run a subagent and return its final assistant text. */
@@ -106,9 +149,15 @@ export interface WorkflowApi {
    * a missing sub-workflow gracefully.
    */
   workflow(ref: WorkflowRef, args?: string): Promise<unknown>;
-  /** Run every thunk concurrently and wait for all (a barrier). */
-  parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
-  /** Run each item through all stages independently — no barrier between stages. */
+  /**
+   * Run every thunk concurrently and wait for all (a barrier). Recoverable thunk
+   * failures become null slots; filter nulls before consuming survivors.
+   */
+  parallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  /**
+   * Run each item through all stages independently — no barrier between stages.
+   * A recoverable stage failure drops that item to null and skips its later stages.
+   */
   pipeline: Pipeline;
   /** Start a new phase; subsequent agents group under it in the progress tree. */
   phase(title: string): void;
@@ -120,6 +169,12 @@ export interface WorkflowApi {
   args: string;
   /** Working directory of the host session (typically the repo root). */
   cwd: string;
+  /**
+   * Token budget for the run. `budget.total` is the output-token ceiling (null when unset),
+   * `spent()`/`remaining()` are live. Guard loops with `while (budget.total && budget.remaining() > N)`;
+   * `agent()` throws `WorkflowBudgetExceededError` once the ceiling is reached.
+   */
+  budget: WorkflowBudget;
   /** Abort signal for the run, propagated from the host. */
   signal: AbortSignal | undefined;
 }