pi-workflow-engine 0.8.0 → 0.10.0

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

@@ -5,22 +5,39 @@ import type { AgentOptions } from "./types.ts";
 import type { Semaphore } from "./concurrency.ts";
 import type { PerfSink } from "./perf.ts";
 import type { WorkflowUsageSink } from "./usage.ts";
+import { WorkflowBudgetExceededError, type WorkflowBudget } from "./budget.ts";
 import { throwIfAborted } from "./cancellation.ts";
+import { appendSkillReminder, createAgentSkillResourceLoader, extractSkillSelectorsFromText } from "./agent-skills.ts";
+import { agentJournalKey, type WorkflowJournal } from "./journal.ts";
+import type { WorktreeRegistry } from "./worktree.ts";
 
 /** Name of the synthetic terminating tool that carries structured output. */
 const FINAL_TOOL = "final_answer";
+const SCHEMA_REPROMPT_ATTEMPTS = 1;
+const SCHEMA_REPROMPT =
+  `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
+  `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
+const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+const DEFAULT_SEARCH_BASE_TOOLS = ["read", "bash", "grep", "find", "ls"];
 
 export interface AgentRunnerEvent {
   readonly type: string;
   readonly toolName?: string;
 }
 
+export interface AgentRunnerToolInfo {
+  readonly name: string;
+  readonly description?: string;
+}
+
 export interface AgentRunnerSession {
   readonly state: { readonly messages: readonly unknown[] };
   prompt(text: string): Promise<void>;
   subscribe(listener: (event: AgentRunnerEvent) => void): () => void;
   dispose(): void;
   abort(): Promise<void>;
+  getAllTools?(): readonly AgentRunnerToolInfo[];
+  setActiveToolsByName?(toolNames: readonly string[]): void;
 }
 
 export type CreateAgentSession = (options: CreateAgentSessionOptions) => Promise<{ session: AgentRunnerSession }>;
@@ -44,6 +61,9 @@ export interface RunContext {
   signal: AbortSignal | undefined;
   perf: PerfSink;
   usage: WorkflowUsageSink;
+  budget: WorkflowBudget;
+  journal: WorkflowJournal;
+  worktrees: WorktreeRegistry;
   createSession?: CreateAgentSession;
 }
 
@@ -156,6 +176,173 @@ function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerS
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "excludeTools">;
+
+interface ToolSelection {
+  readonly sessionOptions: ToolSessionOptions;
+  readonly fallbackSessionOptions: ToolSessionOptions;
+  readonly activeTools?: readonly string[];
+  readonly toolHints: NonNullable<AgentOptions["toolHints"]>;
+}
+
+interface DynamicToolSession extends AgentRunnerSession {
+  getAllTools(): readonly AgentRunnerToolInfo[];
+  setActiveToolsByName(toolNames: readonly string[]): void;
+}
+
+function buildToolList(opts: AgentOptions, skillsEnabled: boolean, fallback?: readonly string[]): string[] | undefined {
+  const allow = opts.tools ? [...opts.tools] : fallback ? [...fallback] : undefined;
+  if (!allow) return undefined;
+  if (skillsEnabled && !allow.includes("read")) allow.push("read");
+  if (opts.schema && !allow.includes(FINAL_TOOL)) allow.push(FINAL_TOOL);
+  return allow;
+}
+
+function buildToolSelection(opts: AgentOptions, skillsEnabled: boolean): ToolSelection {
+  const toolHints = opts.toolHints ?? [];
+  const fallback = toolHints.includes("search") ? DEFAULT_SEARCH_BASE_TOOLS : undefined;
+  const activeTools = buildToolList(opts, skillsEnabled, fallback);
+  const strictSessionOptions = { tools: activeTools ? [...activeTools] : undefined };
+
+  if (toolHints.length === 0) {
+    return { sessionOptions: strictSessionOptions, fallbackSessionOptions: strictSessionOptions, activeTools, toolHints };
+  }
+
+  const explicitlyActive = new Set(activeTools ?? []);
+  return {
+    sessionOptions: { excludeTools: BUILTIN_TOOL_NAMES.filter((name) => !explicitlyActive.has(name)) },
+    // If dynamic tool APIs are unavailable, fail closed to the concrete tools we
+    // already know instead of keeping every extension/custom tool active.
+    fallbackSessionOptions: { tools: activeTools ? [...activeTools] : [] },
+    activeTools,
+    toolHints,
+  };
+}
+
+function hasDynamicToolApis(session: AgentRunnerSession): session is DynamicToolSession {
+  return typeof session.getAllTools === "function" && typeof session.setActiveToolsByName === "function";
+}
+
+function applyDynamicToolHints(session: AgentRunnerSession, selection: ToolSelection): boolean {
+  if (selection.toolHints.length === 0) return true;
+  if (!hasDynamicToolApis(session)) return false;
+
+  const active = new Set(selection.activeTools ?? []);
+  for (const tool of session.getAllTools()) {
+    if (matchesToolHints(tool, selection.toolHints)) active.add(tool.name);
+  }
+  session.setActiveToolsByName([...active]);
+  return true;
+}
+
+function matchesToolHints(tool: AgentRunnerToolInfo, toolHints: readonly string[]): boolean {
+  return toolHints.some((hint) => hint === "search" && isSearchLikeTool(tool));
+}
+
+function isSearchLikeTool(tool: AgentRunnerToolInfo): boolean {
+  if (isClearlyMutatingToolName(tool.name)) return false;
+  const name = tool.name.toLowerCase();
+  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
+  const description = tool.description?.toLowerCase() ?? "";
+  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(description);
+}
+
+function isClearlyMutatingToolName(name: string): boolean {
+  return /(?:^|[-_])(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)(?:$|[-_])/.test(name.toLowerCase());
+}
+
+function shouldCreateSkillResourceLoader(rc: RunContext, prompt: string, opts: AgentOptions): boolean {
+  if (!rc.createSession) return true;
+  if (opts.skills !== undefined) return true;
+  return extractSkillSelectorsFromText(prompt).length > 0;
+}
+
+/**
+ * Refuse to start a new subagent once the run is over budget. Called before queueing and
+ * again after a queued agent acquires a concurrency slot, so an exhausted run stops spending
+ * immediately rather than starting stale queued work.
+ *
+ * Policy: accept overshoot (matches the built-in Workflow tool). `budget.spent()` counts
+ * only COMPLETED agents (usage is recorded on session dispose), so agents admitted together
+ * can each pass this check and then collectively overshoot `budget.total` — we tolerate that
+ * rather than reserving per-agent estimates. An uncapped run (`budget.total === null`,
+ * `remaining()` is Infinity) never throws.
+ *
+ * Heads-up: a throw here is a recoverable branch failure inside `parallel`/`pipeline`, so the
+ * over-budget slot becomes null while already-started siblings can finish. The intended primary
+ * usage is the loop guard `while (budget.total && budget.remaining() > N) { await agent(...) }`,
+ * where this throw is only a backstop.
+ */
+function ensureWithinBudget(budget: WorkflowBudget): void {
+  if (budget.total !== null && budget.remaining() <= 0) {
+    throw new WorkflowBudgetExceededError(budget.total, budget.spent());
+  }
+}
+
+interface AgentWorkspace {
+  readonly cwd: string;
+  wrapResult(result: unknown): Promise<unknown>;
+  dispose(): Promise<void>;
+}
+
+async function createAgentWorkspace(rc: RunContext, opts: AgentOptions, label: string): Promise<AgentWorkspace> {
+  if (opts.isolation !== "worktree") {
+    return {
+      cwd: rc.cwd,
+      async wrapResult(result) {
+        return result;
+      },
+      async dispose() {},
+    };
+  }
+
+  const probe = await rc.worktrees.probe(rc.signal);
+  if (!probe.ok) {
+    throw new Error(`Failed to check git worktree availability for isolated agent: ${probe.error ?? "unknown git error"}`);
+  }
+  if (!probe.inside) {
+    throw new Error("Agent requested worktree isolation, but the workflow cwd is not inside a git work tree.");
+  }
+
+  const added = await rc.worktrees.add(rc.signal);
+  if ("error" in added) throw new Error(`Failed to create isolated worktree: ${added.error}`);
+  const worktreePath = added.path;
+  rc.progress.log(`${label}: using isolated worktree ${worktreePath}`);
+
+  return {
+    cwd: worktreePath,
+    async wrapResult(result) {
+      return await isolatedResult(rc, worktreePath, result);
+    },
+    async dispose() {
+      const removed = await rc.worktrees.remove(worktreePath);
+      if (!removed.ok) {
+        rc.progress.log(`${label}: failed to remove isolated worktree (${removed.error ?? (removed.stderr.trim() || "unknown error")})`);
+      }
+    },
+  };
+}
+
+async function disposeAgentWorkspace(rc: RunContext, label: string, workspace: AgentWorkspace | undefined): Promise<void> {
+  if (!workspace) return;
+  try {
+    await workspace.dispose();
+  } catch (error) {
+    rc.progress.log(`${label}: failed to dispose isolated workspace (${errorMessage(error)})`);
+  }
+}
+
+async function recordJournalResult(rc: RunContext, label: string, key: string, value: unknown): Promise<void> {
+  try {
+    const recorded = await rc.journal.record(key, value);
+    if (!recorded.ok) {
+      rc.progress.log(`${label}: workflow journal write failed (${recorded.error}); future resume may be incomplete`);
+    }
+  } catch (error) {
+    rc.progress.log(`${label}: workflow journal write failed (${errorMessage(error)}); future resume may be incomplete`);
+  }
+}
+
 /**
  * Run one subagent to completion in an isolated in-memory session.
  *
@@ -173,6 +360,16 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
 
   return await rc.perf.time("agent.total_ms", async () => {
     throwIfAborted(rc.signal);
+    const journalKey = agentJournalKey(prompt, opts);
+    const cached = rc.journal.lookup(journalKey);
+    if (cached.hit) {
+      rc.progress.log(`${label}: using cached result from workflow journal`);
+      rc.perf.counter("agent.cache_hit", 1, tags);
+      await recordJournalResult(rc, label, journalKey, cached.value);
+      return cached.value;
+    }
+    // Stop spending the moment the run is over budget — before queueing.
+    ensureWithinBudget(rc.budget);
     // Track queued agents before acquiring a global concurrency slot.
     const rowId = rc.progress.agentQueued(opts.phase, label);
     let failureHandled = false;
@@ -180,6 +377,8 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
       return await rc.semaphore.run(
         async () => {
         throwIfAborted(rc.signal);
+        // Re-check after waiting for a slot; earlier agents may have exhausted the budget.
+        ensureWithinBudget(rc.budget);
         rc.progress.agentStart(opts.phase, label, rowId);
 
         let captured: unknown = null;
@@ -187,6 +386,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
         let session: AgentRunnerSession | undefined;
         let usageRecorded = false;
         let unsubscribe: (() => void) | undefined;
+        let workspace: AgentWorkspace | undefined;
         const recordUsage = (activeSession: AgentRunnerSession): void => {
           if (usageRecorded) return;
           usageRecorded = true;
@@ -209,33 +409,62 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
           : [];
 
         try {
-          // When the workflow restricts built-in tools, keep the terminating tool visible.
-          const allow = opts.tools
-            ? opts.schema
-              ? [...opts.tools, FINAL_TOOL]
-              : opts.tools
-            : undefined;
+          workspace = await createAgentWorkspace(rc, opts, label);
+          const agentCwd = workspace.cwd;
 
           const { model } = resolveAgentModel(opts.model, rc.modelRegistry, rc.hostModel);
+          const skillSetup = shouldCreateSkillResourceLoader(rc, prompt, opts)
+            ? await rc.perf.time(
+                "agent.skills_ms",
+                () =>
+                  createAgentSkillResourceLoader({
+                    cwd: agentCwd,
+                    prompt,
+                    skills: opts.skills,
+                    log: (message) => rc.progress.log(`${label}: ${message}`),
+                  }),
+                tags,
+              )
+            : undefined;
+          const selectedSkills = skillSetup?.selectedSkills ?? [];
+          // When the workflow restricts tools, keep the terminating tool visible.
+          // Skill opt-ins also need read so the subagent can load SKILL.md on demand.
+          const toolSelection = buildToolSelection(opts, selectedSkills.length > 0);
+
           const createSessionForRun = rc.createSession ?? defaultCreateSession;
+          const createSubagentSession = (sessionOptions: ToolSessionOptions) =>
+            rc.perf.time(
+              "agent.create_session_ms",
+              () =>
+                createSessionForRun({
+                  cwd: agentCwd,
+                  model,
+                  modelRegistry: rc.modelRegistry as ModelRegistry,
+                  thinkingLevel: opts.thinkingLevel,
+                  tools: sessionOptions.tools,
+                  excludeTools: sessionOptions.excludeTools,
+                  customTools,
+                  resourceLoader: skillSetup?.resourceLoader,
+                  sessionManager: SessionManager.inMemory(agentCwd),
+                }),
+              tags,
+            );
 
           throwIfAborted(rc.signal);
-          const created = await rc.perf.time(
-            "agent.create_session_ms",
-            () =>
-              createSessionForRun({
-                cwd: rc.cwd,
-                model,
-                modelRegistry: rc.modelRegistry as ModelRegistry,
-                thinkingLevel: opts.thinkingLevel,
-                tools: allow,
-                customTools,
-                sessionManager: SessionManager.inMemory(rc.cwd),
-              }),
-            tags,
-          );
+          let created = await createSubagentSession(toolSelection.sessionOptions);
           session = created.session;
-          const activeSession = session;
+          let activeSession = session;
+          if (!applyDynamicToolHints(activeSession, toolSelection)) {
+            rc.progress.log(`${label}: dynamic tool hints unavailable; falling back to concrete tools only`);
+            rc.perf.counter("agent.tool_hint_fallback", 1, tags);
+            const dynamicSession = activeSession;
+            session = undefined;
+            rc.perf.timeSync("agent.dispose_ms", () => dynamicSession.dispose(), tags);
+            throwIfAborted(rc.signal);
+            created = await createSubagentSession(toolSelection.fallbackSessionOptions);
+            session = created.session;
+            activeSession = session;
+          }
           throwIfAborted(rc.signal);
 
           unsubscribe = activeSession.subscribe((event) => {
@@ -244,20 +473,29 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
             }
           });
 
+          const promptedWithSkills = appendSkillReminder(prompt, selectedSkills);
           const finalPrompt = opts.schema
-            ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
-            : prompt;
+            ? `${promptedWithSkills}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+            : promptedWithSkills;
           throwIfAborted(rc.signal);
           const unlinkPromptAbort = linkSessionAbort(rc.signal, activeSession);
           try {
             await rc.perf.time("agent.prompt_ms", () => activeSession.prompt(finalPrompt), tags);
+            if (opts.schema) {
+              for (let attempt = 0; captured === null && attempt < SCHEMA_REPROMPT_ATTEMPTS; attempt++) {
+                throwIfAborted(rc.signal);
+                rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${SCHEMA_REPROMPT_ATTEMPTS})`);
+                rc.perf.counter("agent.structured_reprompt", 1, tags);
+                await rc.perf.time("agent.prompt_ms", () => activeSession.prompt(SCHEMA_REPROMPT), tags);
+              }
+            }
           } finally {
             unlinkPromptAbort();
           }
           recordUsage(activeSession);
           throwIfAborted(rc.signal);
 
-          return rc.perf.timeSync(
+          const rawResult = rc.perf.timeSync(
             "agent.extract_result_ms",
             () => {
               if (opts.schema) {
@@ -271,6 +509,9 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
             },
             tags,
           );
+          const result = await workspace.wrapResult(rawResult);
+          await recordJournalResult(rc, label, journalKey, result);
+          return result;
         } catch (error) {
           failed = true;
           failureHandled = true;
@@ -290,6 +531,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
               tags,
             );
           }
+          await disposeAgentWorkspace(rc, label, workspace);
           if (!failed) rc.progress.agentDone(label, rowId);
         }
         },
@@ -304,3 +546,13 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
     }
   }, tags);
 }
+
+async function isolatedResult(rc: RunContext, worktreePath: string, result: unknown): Promise<{ readonly result: unknown; readonly patch: string; readonly changed: boolean }> {
+  const patch = await rc.worktrees.capturePatch(worktreePath, rc.signal);
+  if ("error" in patch) throw new Error(`Failed to capture isolated worktree patch: ${patch.error}`);
+  return { result, patch: patch.patch, changed: patch.changed };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,222 @@
+import { DefaultResourceLoader, getAgentDir, type ResourceDiagnostic, type Skill } from "@earendil-works/pi-coding-agent";
+
+export type AgentSkillOption = readonly string[] | undefined;
+export type AgentSkillRequestSource = "explicit" | "prompt";
+
+export interface AgentSkillRequest {
+  readonly selectors: readonly string[];
+  readonly source: AgentSkillRequestSource;
+  readonly strict: boolean;
+}
+
+export interface AgentSkillResolution {
+  readonly selected: readonly Skill[];
+  readonly unmatched: readonly string[];
+}
+
+export interface AgentSkillResourceSetup {
+  readonly resourceLoader: DefaultResourceLoader;
+  readonly selectedSkills: readonly Skill[];
+  readonly unmatchedSelectors: readonly string[];
+  readonly diagnostics: readonly ResourceDiagnostic[];
+}
+
+const SLASH_SKILL_PATTERN = /\/skill:([a-z0-9][a-z0-9-]{0,63})/gi;
+const SKILLS_FIELD_PATTERN = /(?<!\/)\bskills?\s*[:=]\s*([^\n.;]+)/gi;
+const VERB_SKILL_LIST_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?skills?\s+([^\n.;]+)/gi;
+const VERB_NAMED_SKILL_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?(["'`]?)([a-z0-9][a-z0-9 _-]{0,80}?)\1\s+skills?\b/gi;
+const PURPOSE_BOUNDARY_PATTERN = /\s+\b(?:for|to|when|while|so|because|in\s+order\s+to)\b.*$/i;
+
+/**
+ * Resolve which subagent skills were requested.
+ *
+ * Subagents are skillless by default. Explicit `opts.skills` wins and suppresses prompt inference;
+ * when it is omitted we only infer from clear natural-language opt-ins such as `/skill:name`,
+ * `include skill diagnose`, `include this Skill diagnose`, or `use the diagnose skill`.
+ */
+export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown): AgentSkillRequest {
+  if (explicitSkills !== undefined) {
+    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), source: "explicit", strict: true };
+  }
+  return { selectors: extractSkillSelectorsFromText(prompt), source: "prompt", strict: false };
+}
+
+export function extractSkillSelectorsFromText(text: string): string[] {
+  const selectors: string[] = [];
+  collectPatternMatches(text, SLASH_SKILL_PATTERN, selectors, 1);
+  collectListPatternMatches(text, SKILLS_FIELD_PATTERN, selectors);
+  collectListPatternMatches(text, VERB_SKILL_LIST_PATTERN, selectors);
+  collectPatternMatches(text, VERB_NAMED_SKILL_PATTERN, selectors, 2);
+  return uniqueSelectors(selectors);
+}
+
+export function normalizeSkillSelector(value: string): string {
+  return value
+    .trim()
+    .replace(/^\/skill:/i, "")
+    .replace(/^skills?\s*[:=]?\s*/i, "")
+    .replace(/^(?:named|called)\s+/i, "")
+    .replace(/^(?:the|this|these)\s+/i, "")
+    .replace(/\s+skills?$/i, "")
+    .replace(/^[`"']+|[`"']+$/g, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function selectAgentSkills(skills: readonly Skill[], selectors: readonly string[]): AgentSkillResolution {
+  const selected = new Map<string, Skill>();
+  const unmatched: string[] = [];
+
+  for (const selector of selectors) {
+    const match = matchSkillSelector(skills, selector);
+    if (!match) {
+      unmatched.push(selector);
+      continue;
+    }
+    selected.set(match.name, makeSkillModelInvocable(match));
+  }
+
+  return { selected: [...selected.values()], unmatched };
+}
+
+export async function createAgentSkillResourceLoader(options: {
+  readonly cwd: string;
+  readonly prompt: string;
+  readonly skills: unknown;
+  readonly log?: (message: string) => void;
+}): Promise<AgentSkillResourceSetup> {
+  const request = resolveAgentSkillRequest(options.prompt, options.skills);
+  let resolution: AgentSkillResolution = { selected: [], unmatched: [] };
+  let availableSkillNames: readonly string[] = [];
+
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir: getAgentDir(),
+    noSkills: request.selectors.length === 0,
+    skillsOverride:
+      request.selectors.length === 0
+        ? undefined
+        : (current) => {
+            availableSkillNames = current.skills.map((skill) => skill.name).sort();
+            resolution = selectAgentSkills(current.skills, request.selectors);
+            return { skills: [...resolution.selected], diagnostics: current.diagnostics };
+          },
+  });
+  await loader.reload();
+  const { diagnostics } = loader.getSkills();
+  logSkillDiagnostics(options.log, diagnostics, request.selectors.length > 0);
+
+  if (request.strict && resolution.unmatched.length > 0) {
+    throw new Error(
+      `Unknown subagent skill${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}. Available: ${
+        availableSkillNames.join(", ") || "(none)"
+      }.`,
+    );
+  }
+
+  if (!request.strict && resolution.unmatched.length > 0) {
+    options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
+  }
+
+  return { resourceLoader: loader, selectedSkills: resolution.selected, unmatchedSelectors: resolution.unmatched, diagnostics };
+}
+
+export function appendSkillReminder(prompt: string, skills: readonly Pick<Skill, "name" | "filePath">[]): string {
+  if (skills.length === 0) return prompt;
+  const skillList = skills.map((skill) => `${skill.name} (${skill.filePath})`).join(", ");
+  return `${prompt}\n\nWorkflow subagent skills enabled: ${skillList}. If you rely on an enabled skill, first read its SKILL.md with the read tool and follow its instructions. No other skills are available in this subagent.`;
+}
+
+function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[captureIndex];
+    if (value !== undefined) selectors.push(value);
+  }
+}
+
+function collectListPatternMatches(text: string, pattern: RegExp, selectors: string[]): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[1];
+    if (value === undefined) continue;
+    selectors.push(...parseSkillList(value));
+  }
+}
+
+function parseSkillList(fragment: string): string[] {
+  const scoped = fragment.replace(PURPOSE_BOUNDARY_PATTERN, "");
+  return scoped
+    .split(/\s*(?:,|\s+\band\b\s+|&|\+)\s*/i)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function normalizeExplicitSkillSelectors(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid subagent skills option: expected an array of skill names.");
+  }
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") {
+      throw new Error("Invalid subagent skills option: every skill name must be a string.");
+    }
+    const normalized = normalizeSkillSelector(item);
+    if (!normalized || isGenericSkillWord(normalized)) {
+      throw new Error(`Invalid subagent skills option: \"${item}\" is not a valid skill name.`);
+    }
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function logSkillDiagnostics(log: ((message: string) => void) | undefined, diagnostics: readonly ResourceDiagnostic[], requested: boolean): void {
+  if (!requested || !log) return;
+  for (const diagnostic of diagnostics) {
+    const where = diagnostic.path ? ` (${diagnostic.path})` : "";
+    log(`skill ${diagnostic.type}: ${diagnostic.message}${where}`);
+  }
+}
+
+function uniqueSelectors(values: Iterable<string>): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = normalizeSkillSelector(value);
+    if (!normalized || isGenericSkillWord(normalized) || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function isGenericSkillWord(value: string): boolean {
+  return value === "skill" || value === "skills" || value === "the" || value === "this" || value === "these" || value === "that";
+}
+
+function matchSkillSelector(skills: readonly Skill[], selector: string): Skill | undefined {
+  const normalized = normalizeSkillSelector(selector);
+  if (!normalized) return undefined;
+
+  const exact = skills.find((skill) => skill.name.toLowerCase() === normalized);
+  if (exact) return exact;
+
+  const selectorWords = normalized.replace(/-/g, " ");
+  const fuzzy = skills.filter((skill) => {
+    const name = skill.name.toLowerCase();
+    const words = name.replace(/-/g, " ");
+    return name.includes(normalized) || words.includes(selectorWords);
+  });
+  return fuzzy.length === 1 ? fuzzy[0] : undefined;
+}
+
+function makeSkillModelInvocable(skill: Skill): Skill {
+  return skill.disableModelInvocation ? { ...skill, disableModelInvocation: false } : skill;
+}

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

@@ -0,0 +1,46 @@
+import type { WorkflowUsageSink } from "./usage.ts";
+
+/**
+ * Thrown by `agent()` when a run has consumed its token budget. Carries the
+ * configured ceiling and the output tokens spent so callers can report both.
+ */
+export class WorkflowBudgetExceededError extends Error {
+  constructor(
+    readonly total: number,
+    readonly spent: number,
+  ) {
+    super(`Workflow token budget exhausted: spent ${spent} output tokens of ${total}.`);
+    this.name = "WorkflowBudgetExceededError";
+  }
+}
+
+/**
+ * The budget handle exposed on `WorkflowApi`. Mirrors the built-in Workflow tool:
+ * `total` is the output-token ceiling (or `null` when unset), `spent()` is the
+ * output tokens consumed by completed agents this run, and `remaining()` is the
+ * headroom left (`Infinity` when there is no ceiling).
+ *
+ * `spent()`/`remaining()` are LIVE — they re-read usage on every call so that
+ * `while (budget.total && budget.remaining() > N) { await agent(...) }` loops and
+ * `Math.floor(budget.total / N)` fleet-scaling see up-to-date numbers.
+ */
+export interface WorkflowBudget {
+  readonly total: number | null;
+  /** Output tokens consumed by completed agents this run (sub-workflows included). */
+  spent(): number;
+  /** `total - spent()` clamped at 0, or `Infinity` when `total` is null. */
+  remaining(): number;
+}
+
+/**
+ * Build a budget backed by the run's usage sink. `spent()` reads
+ * `usage.snapshot().totals.output` — the same output-token sum surfaced in the
+ * usage line — so no separate token accounting is needed.
+ */
+export function createBudget(total: number | null, usage: WorkflowUsageSink): WorkflowBudget {
+  return {
+    total,
+    spent: () => usage.snapshot().totals.output,
+    remaining: () => (total === null ? Infinity : Math.max(0, total - usage.snapshot().totals.output)),
+  };
+}

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

@@ -16,6 +16,13 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
   if (signal?.aborted) throw abortReason(signal);
 }
 
+export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  if (error instanceof WorkflowAbortError) return true;
+  if (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError") return true;
+  return false;
+}
+
 export function linkAbortSignal(parent: AbortSignal | undefined, controller: AbortController): () => void {
   if (!parent) return () => {};
   if (parent.aborted) {