pi-workflow-engine 1.1.0 → 1.2.0

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

@@ -17,8 +17,10 @@ import {
   isPersistedWorkflowBackground,
   type PersistedWorkflowBackground,
 } from "./workflow-run-background.ts";
+import { isWorkflowRunScriptSeal } from "./workflow-run-seal.ts";
 
 export const WORKFLOW_RUN_RECORD_VERSION = 1;
+export const WORKFLOW_RUN_SCRIPT_SUFFIX = ".script.js";
 
 const MAX_RESULT_BYTES = 1 << 20;
 const MAX_RESULT_DEPTH = 64;
@@ -97,6 +99,14 @@ interface WorkflowRunRecordBase {
   readonly runId: string;
   readonly workflow: PersistedWorkflowIdentity;
   readonly journalFile: string;
+  /** An inline run's script, persisted beside the record; prompts in it never enter the record itself. */
+  readonly scriptFile?: string;
+  /**
+   * This install's HMAC over the run id and source fingerprint, proving the engine recorded the script
+   * rather than a repository shipping it. A run of an inline or saved script relaunches from
+   * `/workflow:runs` only with one.
+   */
+  readonly scriptSeal?: string;
   readonly options: PersistedWorkflowRunOptions;
   readonly createdAt: number;
   readonly updatedAt: number;
@@ -125,6 +135,10 @@ export function createWorkflowRunRecord(input: {
   readonly options: ResolvedWorkflowRunOptions;
   readonly progress: WorkflowProgressSnapshot;
   readonly argumentsPresent?: boolean;
+  /** Whether the run's inline script was persisted beside the record. */
+  readonly scriptPersisted?: boolean;
+  /** The run's script seal; see {@link WorkflowRunRecordBase.scriptSeal}. */
+  readonly scriptSeal?: string;
 }): WorkflowRunRecord {
   const runId = validateWorkflowRunId(input.runId);
   assertMatchingRun(runId, input.progress.runId);
@@ -134,6 +148,8 @@ export function createWorkflowRunRecord(input: {
     state: "queued",
     workflow: persistedWorkflowIdentity(input.workflow),
     journalFile: `${runId}.jsonl`,
+    scriptFile: input.scriptPersisted ? workflowRunScriptFile(runId) : undefined,
+    scriptSeal: input.scriptSeal,
     options: persistedWorkflowRunOptions(input.options, input.argumentsPresent ?? false),
     createdAt: input.progress.startedAt,
     updatedAt: input.progress.startedAt,
@@ -142,6 +158,11 @@ export function createWorkflowRunRecord(input: {
   };
 }
 
+/** The persisted script's file name in the runs directory. */
+export function workflowRunScriptFile(runId: string): string {
+  return `${runId}${WORKFLOW_RUN_SCRIPT_SUFFIX}`;
+}
+
 export function updateWorkflowRunProgress(
   record: WorkflowRunRecord,
   progress: WorkflowProgressSnapshot,
@@ -169,6 +190,8 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
     runId: record.runId,
     workflow: record.workflow,
     journalFile: record.journalFile,
+    scriptFile: record.scriptFile,
+    scriptSeal: record.scriptSeal,
     options: record.options,
     createdAt: record.createdAt,
     updatedAt: at,
@@ -475,6 +498,9 @@ export function isWorkflowRunRecord(value: unknown): value is WorkflowRunRecord
   if (!isValidRunId(value.runId) || !isWorkflowRunState(value.state)) return false;
   if (!isPersistedWorkflowIdentity(value.workflow) || !isPersistedWorkflowRunOptions(value.options)) return false;
   if (value.journalFile !== `${value.runId}.jsonl`) return false;
+  if (value.scriptFile !== undefined && value.scriptFile !== workflowRunScriptFile(value.runId)) return false;
+  // A seal covers an inline run's persisted script or a saved script, which resolves again by name.
+  if (value.scriptSeal !== undefined && (!isWorkflowRunScriptSeal(value.scriptSeal) || (value.scriptFile === undefined && value.workflow.sourceKind !== "file"))) return false;
   if (!isFiniteNumber(value.createdAt) || !isFiniteNumber(value.updatedAt)) return false;
   if (value.startedAt !== undefined && !isFiniteNumber(value.startedAt)) return false;
   if (value.endedAt !== undefined && !isFiniteNumber(value.endedAt)) return false;
@@ -568,7 +594,7 @@ function isPhaseSnapshot(value: unknown): boolean {
 
 function isAgentSnapshot(value: unknown): boolean {
   if (!isRecord(value) || !isFiniteNumber(value.id) || typeof value.label !== "string") return false;
-  if (value.status !== "queued" && value.status !== "running" && value.status !== "done" && value.status !== "failed") return false;
+  if (value.status !== "queued" && value.status !== "running" && value.status !== "done" && value.status !== "failed" && value.status !== "skipped") return false;
   if (!isFiniteNumber(value.toolUses)) return false;
   if (value.startedAt !== undefined && !isFiniteNumber(value.startedAt)) return false;
   if (value.doneAt !== undefined && !isFiniteNumber(value.doneAt)) return false;

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

@@ -0,0 +1,83 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isExistingPathError, isMissingPathError } from "./filesystem-error.ts";
+
+/**
+ * The per-install key that seals inline run scripts, in pi's agent directory. It lives outside every
+ * project, so a repository can ship run records and scripts but never a seal this install accepts.
+ */
+export const WORKFLOW_RUN_SEAL_KEY_FILE = "workflow-run-seal.key";
+
+const KEY_BYTES = 32;
+const HEX_256 = /^[0-9a-f]{64}$/;
+
+/** Whether `value` has a seal's shape; only {@link verifyWorkflowRunScriptSeal} says whether it is genuine. */
+export function isWorkflowRunScriptSeal(value: unknown): value is string {
+  return typeof value === "string" && HEX_256.test(value);
+}
+
+/** The seal a run record carries for its persisted inline script, creating this install's key on first use. */
+export async function sealWorkflowRunScript(
+  runId: string,
+  sourceFingerprint: string,
+  agentDir: string = getAgentDir(),
+): Promise<string> {
+  const path = join(agentDir, WORKFLOW_RUN_SEAL_KEY_FILE);
+  return runSeal((await readSealKey(path)) ?? (await createSealKey(agentDir, path)), runId, sourceFingerprint);
+}
+
+/** Whether this install sealed `sourceFingerprint` for `runId`. Never creates a key: without one, nothing was sealed here. */
+export async function verifyWorkflowRunScriptSeal(
+  runId: string,
+  sourceFingerprint: string,
+  seal: string,
+  agentDir: string = getAgentDir(),
+): Promise<boolean> {
+  if (!isWorkflowRunScriptSeal(seal)) return false;
+  const key = await readSealKey(join(agentDir, WORKFLOW_RUN_SEAL_KEY_FILE));
+  if (key === undefined) return false;
+  return timingSafeEqual(Buffer.from(runSeal(key, runId, sourceFingerprint), "hex"), Buffer.from(seal, "hex"));
+}
+
+function runSeal(key: Buffer, runId: string, sourceFingerprint: string): string {
+  return createHmac("sha256", key).update(`${runId}\0${sourceFingerprint}`).digest("hex");
+}
+
+async function readSealKey(path: string): Promise<Buffer | undefined> {
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw error;
+  }
+  const hex = content.trim();
+  if (!HEX_256.test(hex)) {
+    throw new Error(`workflow run seal key ${path} is malformed; delete it to create a new one, which retires every existing seal`);
+  }
+  return Buffer.from(hex, "hex");
+}
+
+/**
+ * Publish a new key with an exclusive hard link from a complete temporary file, so a concurrent reader
+ * never sees a partial key. When another process published one first, its key wins and is read back.
+ */
+async function createSealKey(agentDir: string, path: string): Promise<Buffer> {
+  await mkdir(agentDir, { recursive: true });
+  const key = randomBytes(KEY_BYTES);
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${key.toString("hex")}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await link(temporaryPath, path);
+    return key;
+  } catch (error) {
+    if (!isExistingPathError(error)) throw error;
+    const existing = await readSealKey(path);
+    if (existing === undefined) throw error;
+    return existing;
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}

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

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
+import { ensureWorkflowRunsDir, validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
 import {
   isWorkflowRunRecord,
   transitionWorkflowRun,
   updateWorkflowRunProgress,
+  WORKFLOW_RUN_SCRIPT_SUFFIX,
+  workflowRunScriptFile,
   type WorkflowRunRecord,
   type WorkflowRunState,
   type WorkflowRunTransition,
@@ -34,7 +36,7 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
     if (Buffer.byteLength(content) > MAX_RECORD_BYTES) {
       throw new Error(`Workflow run record exceeded ${MAX_RECORD_BYTES} bytes.`);
     }
-    await mkdir(dirname(path), { recursive: true });
+    await ensureWorkflowRunsDir(dirname(path));
     try {
       await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
       await rename(temporaryPath, path);
@@ -70,7 +72,12 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
       .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
       .sort((left, right) => right.mtimeMs - left.mtimeMs)
       .slice(Math.max(0, keep));
-    await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
+    // A pruned record takes its persisted script with it: scripts are only ever reached through their record.
+    const paths = stale.flatMap((entry) => [
+      entry.path,
+      `${entry.path.slice(0, -WORKFLOW_RUN_RECORD_SUFFIX.length)}${WORKFLOW_RUN_SCRIPT_SUFFIX}`,
+    ]);
+    await Promise.all(paths.map((path) => rm(path, { force: true }).catch(() => undefined)));
   }
 
   /** Record file paths in the runs directory; empty when the directory cannot be read. */
@@ -153,6 +160,25 @@ export function workflowRunRecordPath(cwd: string, runId: string): string {
   return join(cwd, WORKFLOW_RUNS_DIR, `${validateWorkflowRunId(runId)}${WORKFLOW_RUN_RECORD_SUFFIX}`);
 }
 
+export function workflowRunScriptPath(cwd: string, runId: string): string {
+  return join(cwd, WORKFLOW_RUNS_DIR, workflowRunScriptFile(validateWorkflowRunId(runId)));
+}
+
+/**
+ * Persist an inline run's script beside its record, which redacts prompts and so cannot hold it. This
+ * adds no new exposure: pi's session transcript already holds the script as the tool call's arguments.
+ */
+export async function persistWorkflowRunScript(cwd: string, runId: string, source: string): Promise<string> {
+  const path = workflowRunScriptPath(cwd, runId);
+  await ensureWorkflowRunsDir(dirname(path));
+  await writeFile(path, source, { encoding: "utf8", mode: 0o600 });
+  return path;
+}
+
+export async function readWorkflowRunScript(cwd: string, runId: string): Promise<string> {
+  return await readFile(workflowRunScriptPath(cwd, runId), "utf8");
+}
+
 async function loadWorkflowRunRecord(path: string): Promise<WorkflowRunRecord | undefined> {
   try {
     const content = await readFile(path, "utf8");

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

@@ -0,0 +1,50 @@
+import type { Stats } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { compileInlineWorkflow } from "./inline-workflow.ts";
+import type { LoadedWorkflow } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** The largest script file a `scriptPath` may name; real workflow scripts are a few kilobytes. */
+export const MAX_WORKFLOW_SCRIPT_FILE_BYTES = 1 << 20;
+
+/** A `scriptPath` that cannot be read. */
+export class WorkflowScriptPathError extends Error {
+  override readonly name = "WorkflowScriptPathError";
+}
+
+/**
+ * Read an inline-format script named relative to `cwd`. No containment: the script runs with the
+ * extension's access either way, as an inline `script` does.
+ */
+export async function readWorkflowScriptFile(cwd: string, scriptPath: string): Promise<string> {
+  return await readBoundedScriptFile(resolve(cwd, scriptPath), `scriptPath ${scriptPath}`);
+}
+
+/**
+ * Read a workflow script only if it is a regular file within the size limit: a FIFO or device would
+ * block the read or never end. `label` names the file in errors.
+ */
+export async function readBoundedScriptFile(file: string, label: string): Promise<string> {
+  const unreadable = (error: unknown) => new WorkflowScriptPathError(`${label} could not be read: ${unknownErrorMessage(error)}`);
+  let info: Stats;
+  try {
+    info = await stat(file);
+  } catch (error) {
+    throw unreadable(error);
+  }
+  if (!info.isFile()) throw new WorkflowScriptPathError(`${label} is not a regular file`);
+  if (info.size > MAX_WORKFLOW_SCRIPT_FILE_BYTES) {
+    throw new WorkflowScriptPathError(`${label} is ${info.size} bytes, over the ${MAX_WORKFLOW_SCRIPT_FILE_BYTES}-byte limit`);
+  }
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    throw unreadable(error);
+  }
+}
+
+/** Compile a script file exactly like an inline `script`: same contract, injected `Type`, content fingerprint. */
+export async function compileWorkflowScriptFile(cwd: string, scriptPath: string): Promise<LoadedWorkflow> {
+  return compileInlineWorkflow(await readWorkflowScriptFile(cwd, scriptPath));
+}

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

@@ -0,0 +1,147 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
+import { configFilePaths, readJsonConfigFile, writeJsonConfigFile, type ConfigFilePaths } from "./config-file.ts";
+import { isRecord } from "./guards.ts";
+import { DEFAULT_WORKFLOW_MAX_AGENTS } from "./options.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/**
+ * How large the host should make each workflow it authors. A prompt guideline only: the run's
+ * `maxAgents` limit stays the separate hard cap.
+ */
+export const WORKFLOW_SIZE_GUIDELINES = ["small", "medium", "large", "off"] as const;
+export type WorkflowSizeGuideline = (typeof WORKFLOW_SIZE_GUIDELINES)[number];
+export const DEFAULT_WORKFLOW_SIZE_GUIDELINE: WorkflowSizeGuideline = "medium";
+
+const SIZE_AGENT_LIMITS: Readonly<Record<Exclude<WorkflowSizeGuideline, "off">, number>> = { small: 5, medium: 10, large: 25 };
+const SETTINGS_FILE_NAME = "workflow-settings.json";
+const SETTINGS_LABEL = "workflow settings";
+
+export interface WorkflowSettingsFile {
+  readonly size?: WorkflowSizeGuideline;
+}
+
+export type ResolvedWorkflowSize =
+  | { readonly size: WorkflowSizeGuideline; readonly source: "default" }
+  | { readonly size: WorkflowSizeGuideline; readonly source: "user" | "project"; readonly configPath: string };
+
+export function workflowSettingsPaths(cwd: string, agentDir?: string): ConfigFilePaths {
+  return configFilePaths(SETTINGS_FILE_NAME, cwd, agentDir);
+}
+
+export function isWorkflowSizeGuideline(value: string): value is WorkflowSizeGuideline {
+  return WORKFLOW_SIZE_GUIDELINES.includes(value as WorkflowSizeGuideline);
+}
+
+export function readWorkflowSettingsFile(configPath: string): WorkflowSettingsFile {
+  const parsed = readJsonConfigFile(configPath, SETTINGS_LABEL);
+  if (parsed === undefined) return {};
+  if (!isRecord(parsed)) throw invalidSettings(configPath, "the root must be an object");
+  const unexpected = Object.keys(parsed).find((key) => key !== "size");
+  if (unexpected) throw invalidSettings(configPath, `unexpected key "${unexpected}"`);
+  const { size } = parsed;
+  if (size === undefined) return {};
+  if (typeof size !== "string" || !isWorkflowSizeGuideline(size)) {
+    throw invalidSettings(configPath, '"size" must be small, medium, large, or off');
+  }
+  return { size };
+}
+
+/** The project file wins over the user file, which wins over the default. */
+export function resolveWorkflowSize(paths: ConfigFilePaths): ResolvedWorkflowSize {
+  for (const source of ["project", "user"] as const) {
+    const { size } = readWorkflowSettingsFile(paths[source]);
+    if (size !== undefined) return { size, source, configPath: paths[source] };
+  }
+  return { size: DEFAULT_WORKFLOW_SIZE_GUIDELINE, source: "default" };
+}
+
+export function setWorkflowSize(configPath: string, size: WorkflowSizeGuideline): void {
+  const current = readWorkflowSettingsFile(configPath);
+  writeJsonConfigFile(configPath, { ...current, size }, SETTINGS_LABEL);
+}
+
+/** The catalog line for a size, or undefined when the guideline is off. */
+export function workflowSizeGuidelineLine(size: WorkflowSizeGuideline): string | undefined {
+  if (size === "off") return undefined;
+  return `Workflow size guideline: ${size} — keep each workflow under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; the user changes this with /workflow:size.`;
+}
+
+type WorkflowSizeCommand =
+  | { readonly kind: "status" }
+  | { readonly kind: "set"; readonly size: WorkflowSizeGuideline; readonly scope: keyof ConfigFilePaths }
+  | { readonly kind: "error"; readonly message: string };
+
+const USAGE = "Usage: /workflow:size [small|medium|large|off] [--user|--project]";
+const SIZE_COMPLETIONS = WORKFLOW_SIZE_GUIDELINES.map((value) => ({
+  value,
+  description: value === "off" ? "No size guideline in the prompt" : `Keep each workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
+}));
+const SCOPE_COMPLETIONS = [
+  { value: "--user", description: "Write the user-level workflow settings" },
+  { value: "--project", description: "Write the project-level workflow settings" },
+] as const;
+
+export function parseWorkflowSizeCommand(args: string): WorkflowSizeCommand {
+  const tokens = args.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  const userScope = tokens.includes("--user");
+  const projectScope = tokens.includes("--project");
+  if (userScope && projectScope) return { kind: "error", message: "Choose either --user or --project, not both." };
+  const positional = tokens.filter((token) => token !== "--user" && token !== "--project");
+  if (positional.length === 0) {
+    return userScope || projectScope ? { kind: "error", message: "Name a size to write." } : { kind: "status" };
+  }
+  const [size, ...extra] = positional;
+  if (extra.length > 0 || !size || !isWorkflowSizeGuideline(size)) {
+    return { kind: "error", message: "Size must be small, medium, large, or off." };
+  }
+  return { kind: "set", size, scope: projectScope ? "project" : "user" };
+}
+
+export function workflowSizeArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+  const { completed } = splitArgumentPrefix(argumentPrefix);
+  if (completed.length === 0) return completeCurrentArgument(argumentPrefix, SIZE_COMPLETIONS);
+  if (completed.length === 1 && isWorkflowSizeGuideline(completed[0] ?? "")) return completeCurrentArgument(argumentPrefix, SCOPE_COMPLETIONS);
+  return null;
+}
+
+export function formatWorkflowSize(resolved: ResolvedWorkflowSize): string {
+  const source = resolved.source === "default" ? "default" : `${resolved.source} config ${resolved.configPath}`;
+  const rule = resolved.size === "off"
+    ? "no size guideline is added to the prompt"
+    : `keep each workflow under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more`;
+  return [
+    `Workflow size guideline: ${resolved.size} (${source}) — ${rule}.`,
+    `The maxAgents run limit (default ${DEFAULT_WORKFLOW_MAX_AGENTS}) stays the hard cap on live agents per run.`,
+  ].join("\n");
+}
+
+/** Register `/workflow:size`; `onChange` lets the session's prompt pick the new guideline up. */
+export function registerWorkflowSizeCommand(pi: Pick<ExtensionAPI, "registerCommand">, onChange: (ctx: ExtensionCommandContext) => void): void {
+  pi.registerCommand("workflow:size", {
+    description: "Show or set the workflow size guideline: /workflow:size [small|medium|large|off] [--user|--project]",
+    getArgumentCompletions: workflowSizeArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const command = parseWorkflowSizeCommand(args);
+      if (command.kind === "error") {
+        ctx.ui.notify(`${command.message}\n${USAGE}`, "warning");
+        return;
+      }
+      try {
+        const paths = workflowSettingsPaths(ctx.cwd);
+        if (command.kind === "set") {
+          setWorkflowSize(paths[command.scope], command.size);
+          onChange(ctx);
+        }
+        ctx.ui.notify(formatWorkflowSize(resolveWorkflowSize(paths)), "info");
+      } catch (error) {
+        ctx.ui.notify(unknownErrorMessage(error), "error");
+      }
+    },
+  });
+}
+
+function invalidSettings(configPath: string, reason: string): Error {
+  return new Error(`Invalid workflow settings at ${configPath}: ${reason}. Fix or remove the file.`);
+}

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

@@ -0,0 +1,61 @@
+export interface WorkflowToolRequestParams {
+  readonly name?: string;
+  readonly script?: string;
+  readonly scriptPath?: string;
+  readonly resumeFromRunId?: string;
+  readonly background?: boolean;
+}
+
+export type WorkflowToolRequest =
+  | { readonly kind: "named"; readonly name: string }
+  | { readonly kind: "inline"; readonly script: string }
+  | { readonly kind: "script-path"; readonly scriptPath: string }
+  | { readonly kind: "error"; readonly error: "invalid_workflow_invocation"; readonly message: string };
+
+export const INVALID_WORKFLOW_INVOCATION_MESSAGE = "Provide exactly one of a workflow name, an inline workflow script, or a scriptPath.";
+
+export function normalizeWorkflowToolRequest(params: WorkflowToolRequestParams): WorkflowToolRequest {
+  const name = params.name?.trim() ?? "";
+  const script = params.script?.trim() ?? "";
+  const scriptPath = params.scriptPath?.trim() ?? "";
+  const provided = [name, script, scriptPath].filter((value) => value.length > 0).length;
+  if (provided !== 1) return { kind: "error", error: "invalid_workflow_invocation", message: INVALID_WORKFLOW_INVOCATION_MESSAGE };
+  if (name) return { kind: "named", name };
+  return script ? { kind: "inline", script } : { kind: "script-path", scriptPath };
+}
+
+/** pi names MCP tools `mcp__<server>__<tool>`; such a word contains its server's `mcp__<server>` namespace. */
+const MCP_TOOL_REFERENCE = /mcp__[A-Za-z0-9_-]+/g;
+/** `api.workflow(...)` or a destructured `workflow(...)`; prose that happens to match only costs one wait. */
+const SUB_WORKFLOW_CALL = /\bworkflow\s*\(/;
+
+/**
+ * Which tools a `workflow` tool call may reach, for pi's `reachesTools`, read from the same request the
+ * call executes. Before the call runs, pi's MCP extension waits for every server whose namespace a
+ * returned word contains, or for all of them on `"all"`. Without that wait a synchronous run early in a
+ * session can start before MCP tools register, and agents that name them then fail at the host-tools bridge.
+ *
+ * - A background run never gets the bridge, so it reaches nothing.
+ * - A named workflow is opaque, so it reaches `"all"`. Each server's readiness settles once, so this
+ *   costs at most one wait at session start.
+ * - An inline script reaches the MCP tools it names, or `"all"` when it asks for `external-search`
+ *   tools or composes a sub-workflow, which is as opaque as a named one.
+ * - A script file reaches `"all"` unread. pi asks synchronously on its main thread, where reading a FIFO,
+ *   a terminal or a device named as `scriptPath` would block or never end.
+ * - An invalid call fails before running anything, so it reaches nothing.
+ */
+export function workflowToolReach(input: Record<string, unknown>): "all" | readonly string[] {
+  if (input.background === true) return [];
+  const request = normalizeWorkflowToolRequest({ name: text(input.name), script: text(input.script), scriptPath: text(input.scriptPath) });
+  if (request.kind === "inline") return scriptReach(request.script);
+  return request.kind === "error" ? [] : "all";
+}
+
+function scriptReach(script: string): "all" | readonly string[] {
+  if (script.includes("external-search") || SUB_WORKFLOW_CALL.test(script)) return "all";
+  return [...new Set(script.match(MCP_TOOL_REFERENCE) ?? [])];
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -23,6 +23,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "code-review",
   description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
+  whenToUse: "Use to review a PR, branch diff, ref range, or focused target for correctness bugs and cleanups, with every finding independently verified; args are the target or review instructions, blank auto-detects the diff.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -16,6 +16,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "diagnose",
   description: "Advisory-only bug diagnosis: scope symptoms → competing hypotheses → independent verify → synthesize likely root causes.",
+  whenToUse: "Use when a bug, failing command, flaky test, or regression has an unclear cause and competing hypotheses should be checked independently before anyone edits code; args describe the symptom.",
   phases: [{ title: "Scope" }, { title: "Hypothesize" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -17,6 +17,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "perf-review",
   description: "Advisory-only performance review: scope slow path → per-lens bottleneck hypotheses → verify evidence → synthesize measurements and safe optimizations.",
+  whenToUse: "Use for a slow path, startup cost, or performance concern where measured bottlenecks and safe optimizations matter more than guesses; args name the path, workload, or command.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -18,6 +18,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "refactor-scout",
   description: "Advisory-only refactor scout: scope → per-lens find → independent verify → synthesize safe refactor opportunities.",
+  whenToUse: "Use to find small, behaviour-preserving refactors (duplication, complexity, type safety, boundaries, dead code) in a path or module without changing it; args name the target.",
   phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 

package/.pi/extensions/pi-workflow-engine/workflows/research.ts

@@ -1,5 +1,6 @@
 import {
   MAX_RESEARCH_LANES,
+  MAX_VERIFICATION_CLAIMS,
   ResearchLaneResultSchema,
   ResearchPlanSchema,
   ResearchReportSchema,
@@ -23,6 +24,7 @@ import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 export const meta: WorkflowMeta = {
   name: "research",
   description: "Source-grounded external research: decompose → gather direct-page evidence → independently verify claims → cited synthesis.",
+  whenToUse: "Use for questions that need current external sources and cited, independently verified claims; needs an installed web search or browsing tool; args are the question and any scope constraints.",
   phases: [{ title: "Plan" }, { title: "Gather" }, { title: "Verify" }, { title: "Synthesize" }],
 };
 
@@ -105,10 +107,11 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   const gathered = gatherResults.flatMap((result) => (result.ok ? [result.value] : []));
   const failedLanes = lanes.filter((_, index) => !gatherResults[index]!.ok);
 
-  const candidates = buildClaimCandidates(gathered);
+  const { candidates, overCap } = buildClaimCandidates(gathered);
   if (candidates.length === 0) return unavailableResearchReport(failedLanes.length > 0 ? "lanes-failed" : "no-evidence");
   progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
   log(`${candidates.length} bounded claim(s) selected for independent verification`);
+  if (overCap > 0) log(`Dropped ${overCap} lower-priority claim(s) over the verification cap of ${MAX_VERIFICATION_CLAIMS}`);
 
   phase("Verify");
   const verificationResults = await parallel(
@@ -162,9 +165,14 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   }
 
   const report = sanitizeResearchReport(synthesis, synthesisInputs);
-  if (failedLanes.length === 0) return report;
-  const laneGap = `${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`;
-  return { ...report, limitations: [...report.limitations, laneGap] };
+  const gaps: string[] = [];
+  if (failedLanes.length > 0) {
+    gaps.push(`${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`);
+  }
+  if (overCap > 0) {
+    gaps.push(`${overCap} lower-priority claim(s) were not independently verified; verification is capped at ${MAX_VERIFICATION_CLAIMS} claims.`);
+  }
+  return gaps.length === 0 ? report : { ...report, limitations: [...report.limitations, ...gaps] };
 }
 
 function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {

package/README.md

@@ -72,15 +72,21 @@ dynamax investigate this flaky test using separate timing, fixture, diff, and ex
 dynamax argue both implementation options, then have another agent challenge the recommendation
 ```
 
-The token enables Dynamax for one turn. Sticky mode remains active for the pi
-session:
+The token enables Dynamax for that one request. Sticky mode instead makes
+workflow orchestration the default for every substantive task in the pi session;
+`/workflow:dynamax` with no argument toggles it:
 
 ```text
+/workflow:dynamax
 /workflow:dynamax on
 /workflow:dynamax off
 /workflow:dynamax status
 ```
 
+`/workflow:size small|medium|large|off` sets how many agents pi aims to keep
+each authored workflow under (5, 10 by default, or 25); see the
+[size guideline](USAGE.md#workflow-size-guideline).
+
 In the TUI, a standalone `dynamax` token receives a short moving-shine sweep and
 then stays highlighted. Use `PI_DYNAMAX_EFFECT=static` or
 `PI_DYNAMAX_EFFECT=off` to reduce or disable the cue; the
@@ -108,7 +114,9 @@ covers review actions and recent run history.
 ## Create your own workflows
 
 Saved workflows are TypeScript modules for repeatable orchestration; inline
-workflows are useful for one-off Dynamax tasks. The
+workflows are useful for one-off Dynamax tasks. An inline script that proves
+useful can be saved as a `.js` file in a project's `.pi/workflows/` or in
+`~/.pi/agent/workflows/` and run by name. The
 [workflow authoring guide](USAGE.md#author-a-saved-workflow) covers the API,
 typed handoffs, model profiles, tool access, composition, and registration.