pi-extensible-workflows 3.1.0 → 3.3.0

package/src/cli.ts

@@ -8,12 +8,13 @@ import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionF
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport, type DoctorOptions } from "./doctor.js";
 import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport, type DoctorCleanupOptions } from "./doctor-cleanup.js";
-import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath, type JsonSchema, type JsonValue, type WorkflowProgressStyles } from "./index.js";
-import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
+import workflowExtension, { formatWorkflowProgress, loadAgentDefinitions, registeredWorkflowFunctions, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath, type JsonSchema, type JsonValue, type WorkflowProgressStyles } from "./index.js";
+import { portableEngineVersion, portablePiVersion, writePortableWorkflowBundle } from "./bundles.js";
+import { runSessionInspector, transcriptFileLines, type InspectMode } from "./session-inspector.js";
 import type { PersistedRun } from "./persistence.js";
 import type { WorkflowCatalogFunction } from "./index.js";
 
-export interface CliOptions extends DoctorOptions { inspect?: (sessionId?: string) => Promise<void>; transcript?: (sessionFile: string) => Promise<void>; stderr?: (text: string) => void; signal?: AbortSignal; trustOverride?: boolean; isTTY?: boolean }
+export interface CliOptions extends DoctorOptions { inspect?: (sessionId?: string, mode?: InspectMode, failedOnly?: boolean) => Promise<void>; transcript?: (sessionFile: string) => Promise<void>; stderr?: (text: string) => void; signal?: AbortSignal; trustOverride?: boolean; isTTY?: boolean; skillPaths?: readonly string[] }
 
 type CliScalar = "string" | "integer" | "number" | "boolean";
 type CliField = { name: string; option: string; schema: Record<string, unknown>; type: CliScalar | "array"; itemType?: CliScalar; required: boolean };
@@ -158,7 +159,24 @@ function launcherHelpLines(): string[] {
   ];
 }
 function workflowUsage(): string { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
-function exportUsage(): string { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function exportUsage(): string { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function bundleUsage(): string { return [`Usage: pi-extensible-workflows bundle <workflow-name> [--name <command>] [--output <directory>] [--force]`, "", "The bundle contains a launcher, manifest, workflow payload, and external-runtime setup instructions.", "Repeat --role, --alias, --tool, --command, or --environment to declare recipient requirements.", "Use --extension, --skill, --resource, and --dependency to copy selected payload resources."].join("\n") + "\n"; }
+function parseInspectArgs(rawArgs: readonly string[]): { sessionId?: string; mode: InspectMode; failedOnly: boolean } {
+  let sessionId: string | undefined;
+  let mode: InspectMode = "tui";
+  let failedOnly = false;
+  for (const arg of rawArgs) {
+    if (arg === "--json" || arg === "--summary") {
+      const next: InspectMode = arg === "--json" ? "json" : "summary";
+      if (mode !== "tui" && mode !== next) throw new Error("inspect accepts only one output mode");
+      mode = next;
+    } else if (arg === "--failed") failedOnly = true;
+    else if (arg.startsWith("--")) throw new Error(`Unknown inspect option: ${arg}`);
+    else if (sessionId !== undefined) throw new Error(`Unexpected argument: ${arg}`);
+    else sessionId = arg;
+  }
+  return { ...(sessionId ? { sessionId } : {}), mode: failedOnly && mode === "tui" ? "summary" : mode, failedOnly };
+}
 export function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">> {
   let olderThanDays = 90;
   let yes = false;
@@ -193,7 +211,7 @@ function stripTrustOptions(rawArgs: readonly string[]): { args: string[]; trustO
   }
   return { args, ...(trustOverride !== undefined ? { trustOverride } : {}) };
 }
-type WorkflowIo = { write: (text: string) => void; stderr: (text: string) => void; cwd?: string; agentDir?: string; trustOverride?: boolean; isTTY?: boolean; signal?: AbortSignal };
+type WorkflowIo = { write: (text: string) => void; stderr: (text: string) => void; cwd?: string; agentDir?: string; trustOverride?: boolean; isTTY?: boolean; signal?: AbortSignal; skillPaths?: readonly string[] };
 
 type HeadlessWorkflowTool = { execute: (toolCallId: string, params: Record<string, JsonValue>, signal: AbortSignal | undefined, onUpdate: ((update: unknown) => void) | undefined, context: unknown) => Promise<{ content: Array<{ type: string; text: string }>; details?: unknown }> };
 type ShutdownHandler = (event: unknown, context: unknown) => Promise<void> | void;
@@ -235,7 +253,7 @@ async function createWorkflowRuntime(options: WorkflowIo, shutdownHandlers: Shut
     cwd,
     agentDir,
     settingsManager,
-    resourceLoaderOptions: {},
+    resourceLoaderOptions: { ...(options.skillPaths?.length ? { additionalSkillPaths: [...options.skillPaths] } : {}) },
     resourceLoaderReloadOptions: { resolveProjectTrust },
   });
   const extensions = services.resourceLoader.getExtensions();
@@ -251,7 +269,7 @@ async function createWorkflowRuntime(options: WorkflowIo, shutdownHandlers: Shut
     sendMessage() {},
     events: { emit() {} },
   };
-  workflowExtension(headlessPi as never, homedir(), undefined, undefined, agentDir);
+  workflowExtension(headlessPi as never, homedir(), undefined, undefined, agentDir, options.skillPaths);
   const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow") as HeadlessWorkflowTool | undefined;
   if (!workflowTool) throw new Error("The workflow runtime could not be initialized");
   return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
@@ -304,23 +322,34 @@ class CliProgress {
   #lines = 0;
   #frame = 0;
   #run: PersistedRun | undefined;
+  #runId: string | undefined;
   #timer: ReturnType<typeof setInterval> | undefined;
   #interactive: boolean;
   #styles: WorkflowProgressStyles;
-  constructor(private readonly stderr: (text: string) => void, tty: boolean) {
+  constructor(private readonly stderr: (text: string) => void, tty: boolean, private readonly onRunId: (runId: string) => void) {
     this.#interactive = tty && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
     this.#styles = terminalProgressStyles(this.#interactive);
   }
   update(run: PersistedRun): void {
-    const stable = formatWorkflowProgress(run, "◇", this.#styles);
-    if (!this.#interactive) { if (stable !== this.#lastStable) { this.#lastStable = stable; this.stderr(`${stable}\n`); } return; }
+    if (this.#runId !== run.id) { this.#runId = run.id; this.onRunId(run.id); }
     this.#run = run;
+    if (!this.#interactive) {
+      this.#timer ??= setInterval(() => { this.render(); }, 1000);
+      this.#timer.unref();
+      this.render();
+      return;
+    }
     this.#timer ??= setInterval(() => { this.render(); }, 80);
     this.#timer.unref();
     this.render();
   }
   render(): void {
     if (!this.#run) return;
+    if (!this.#interactive) {
+      const stable = formatWorkflowProgress(this.#run, "◇", this.#styles);
+      if (stable !== this.#lastStable) { this.#lastStable = stable; this.stderr(`${stable}\n`); }
+      return;
+    }
     const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][this.#frame++ % 10] ?? "◇";
     const width = process.stderr.columns || 80;
     const text = truncateWorkflowProgress(formatWorkflowProgress(this.#run, spinner, this.#styles), width).join("\n");
@@ -334,16 +363,21 @@ class CliProgress {
   }
 }
 
-async function invokeWorkflow(fn: WorkflowCatalogFunction, args: Record<string, JsonValue>, runtime: WorkflowRuntime, options: WorkflowIo, context: unknown): Promise<JsonValue> {
+type CliWorkflowResult = { value: JsonValue; runId?: string };
+async function invokeWorkflow(fn: WorkflowCatalogFunction, args: Record<string, JsonValue>, runtime: WorkflowRuntime, options: WorkflowIo, context: unknown): Promise<CliWorkflowResult> {
   if (!Value.Check(fn.input, args)) throw new Error(`Invalid input for ${fn.name}`);
-  const progress = new CliProgress(options.stderr, options.isTTY ?? process.stderr.isTTY);
+  let announcedRunId: string | undefined;
+  const announceRunId = (runId: string) => { if (announcedRunId === runId) return; announcedRunId = runId; options.stderr(`Run ID: ${runId}\n`); };
+  const progress = new CliProgress(options.stderr, options.isTTY ?? process.stderr.isTTY, announceRunId);
   try {
     const result = await runtime.workflowTool.execute(randomUUID(), { workflow: fn.name, args, foreground: true }, options.signal, (update: unknown) => { if (object(update) && object(update.details) && object(update.details.run)) progress.update(update.details.run as unknown as PersistedRun); }, context);
     const details = object(result.details) ? result.details : {};
-    if (has(details, "value")) return details.value as JsonValue;
+    const runId = typeof details.runId === "string" ? details.runId : undefined;
+    if (runId) announceRunId(runId);
+    if (has(details, "value")) return { value: details.value as JsonValue, ...(runId ? { runId } : {}) };
     const first = result.content[0];
     if (!first || first.type !== "text") throw new Error("Workflow returned no result");
-    try { return parseJsonInput(first.text); } catch { throw new Error("Workflow returned invalid JSON"); }
+    try { return { value: parseJsonInput(first.text), ...(runId ? { runId } : {}) }; } catch { throw new Error("Workflow returned invalid JSON"); }
   } finally {
     progress.finish();
   }
@@ -385,8 +419,8 @@ async function runWorkflowCli(rawArgs: readonly string[], options: WorkflowIo):
     if (!fn) throw new Error(`Unknown workflow function: ${name}`);
     if (help) { options.write(formatWorkflowCliHelp(fn)); return 0; }
     const input = parseWorkflowCliArgs(fn.input, args.slice(1));
-    const value = await invokeWorkflow(fn, input, runtime, options, context);
-    options.write(`${JSON.stringify(value)}\n`);
+    const result = await invokeWorkflow(fn, input, runtime, options, context);
+    options.write(`${JSON.stringify(result.value)}\n`);
     return 0;
   });
 }
@@ -394,6 +428,7 @@ async function runWorkflowCli(rawArgs: readonly string[], options: WorkflowIo):
 async function exportWorkflowCli(rawArgs: readonly string[], options: WorkflowIo): Promise<number> {
   const parsed = stripTrustOptions(rawArgs);
   const args = parsed.args;
+  if (args.includes("--bundle")) return bundleWorkflowCli(args.filter((arg) => arg !== "--bundle"), options);
   if (!args.length || args[0] === "--help" || args[0] === "-h") { options.write(exportUsage()); return args.length ? 0 : 1; }
   const workflowName = args[0] as string;
   return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
@@ -429,6 +464,62 @@ async function exportWorkflowCli(rawArgs: readonly string[], options: WorkflowIo
   });
 }
 
+async function bundleWorkflowCli(rawArgs: readonly string[], options: WorkflowIo): Promise<number> {
+  const parsed = stripTrustOptions(rawArgs);
+  const args = parsed.args;
+  if (!args.length || args[0] === "--help" || args[0] === "-h") { options.write(bundleUsage()); return args.length ? 0 : 1; }
+  const workflowName = args[0] as string;
+  return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
+    let name: string | undefined;
+    let output: string | undefined;
+    let force = false;
+    const requirements = { roles: [] as string[], aliases: [] as string[], tools: [] as string[], commands: [] as string[], environment: [] as string[] };
+    const resources = { extensions: [] as string[], skills: [] as string[], static: [] as string[], dependencies: [] as string[] };
+    for (let index = 1; index < args.length; index += 1) {
+      const arg = args[index] as string;
+      if (arg === "--force") { force = true; continue; }
+      const equals = arg.indexOf("=");
+      const option = equals >= 0 ? arg.slice(0, equals) : arg;
+      const requirementOptions = { "--role": "roles", "--alias": "aliases", "--tool": "tools", "--command": "commands", "--environment": "environment" } as const;
+      const resourceOptions = { "--extension": "extensions", "--skill": "skills", "--resource": "static", "--dependency": "dependencies" } as const;
+      if (option === "--name" || option === "--output" || Object.prototype.hasOwnProperty.call(requirementOptions, option) || Object.prototype.hasOwnProperty.call(resourceOptions, option)) {
+        const value = equals >= 0 ? arg.slice(equals + 1) : args[++index];
+        if (!value) throw new Error(`Missing value for ${option}`);
+        if (option === "--name") name = value;
+        else if (option === "--output") output = value;
+        else if (Object.prototype.hasOwnProperty.call(requirementOptions, option)) requirements[requirementOptions[option as keyof typeof requirementOptions]].push(value);
+        else resources[resourceOptions[option as keyof typeof resourceOptions]].push(value);
+        continue;
+      }
+      if (arg === "--help" || arg === "-h") { options.write(bundleUsage()); return 0; }
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    const fn = runtime.catalog.functions.find((candidate) => candidate.name === workflowName);
+    if (!fn) throw new Error(`Unknown workflow function: ${workflowName}`);
+    const registered = registeredWorkflowFunctions()[workflowName];
+    if (!registered) throw new Error(`Workflow ${workflowName} is not exportable because its registered implementation is unavailable`);
+    const definitions = requirements.roles.length ? loadAgentDefinitions(options.cwd ?? process.cwd(), options.agentDir ?? getAgentDir(), runtime.services.settingsManager.isProjectTrusted()) : {};
+    const roles = Object.fromEntries(requirements.roles.map((role) => {
+      if (!role || role === "." || role === ".." || role.includes("/") || role.includes("\\")) throw new Error(`Invalid role name for bundle: ${role}`);
+      const definition = definitions[role];
+      if (!definition) throw new Error(`Unknown role for bundle: ${role}`);
+      return [role, definition];
+    }));
+    const command = commandName(name ?? kebabCase(workflowName));
+    if (!command) throw new Error("Command name must be a non-empty name without path separators");
+    const destination = output ?? join(homedir(), ".local", "share", "pi-extensible-workflows", "bundles", command);
+    const aliasTargets = Object.fromEntries(requirements.aliases.flatMap((name) => {
+      const target = runtime.catalog.modelAliases?.[name];
+      return typeof target === "string" ? [[name, target]] : [];
+    }));
+    const selectedResources = Object.values(resources).some((entries) => entries.length) ? resources : undefined;
+    writePortableWorkflowBundle({ destination, command, workflow: fn, functionSource: registered.run.toString(), requirements, aliasTargets, roles, ...(selectedResources ? { resources: selectedResources } : {}), piVersion: portablePiVersion(), engineVersion: portableEngineVersion(), force });
+    options.write(`Bundled ${workflowName} at ${destination}\n`);
+    options.write(`Run ${join(destination, command)} setup before launching the workflow.\n`);
+    return 0;
+  });
+}
+
 export async function runCli(args: readonly string[], options: CliOptions = {}, write: (text: string) => void = (text) => { process.stdout.write(text); }): Promise<number> {
   const stderr = options.stderr ?? ((text: string) => { process.stderr.write(text); });
   if (args[0] === "doctor" && args.length === 1) {
@@ -446,8 +537,13 @@ export async function runCli(args: readonly string[], options: CliOptions = {},
       return doctorCleanupExitCode(report);
     } catch (error) { stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
   }
-  if (args[0] === "inspect" && args.length <= 2) {
-    try { await (options.inspect ?? runSessionInspector)(args[1]); return 0; }
+  if (args[0] === "inspect") {
+    try {
+      const parsed = parseInspectArgs(args.slice(1));
+      if (options.inspect) await options.inspect(parsed.sessionId, parsed.mode, parsed.failedOnly);
+      else await runSessionInspector(parsed.sessionId, parsed.mode, options.cwd ?? process.cwd(), undefined, write, parsed.failedOnly);
+      return 0;
+    }
     catch (error) { write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
   }
   if (args[0] === "transcript" && args.length === 2) {
@@ -457,13 +553,14 @@ export async function runCli(args: readonly string[], options: CliOptions = {},
       return 0;
     } catch (error) { write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
   }
-  if (args[0] === "run" || args[0] === "export") {
+  if (args[0] === "bundle" || args[0] === "run" || args[0] === "export") {
     try {
-      const workflowOptions: WorkflowIo = { write, stderr, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}), ...(options.agentDir !== undefined ? { agentDir: options.agentDir } : {}), ...(options.signal ? { signal: options.signal } : {}), ...(options.trustOverride !== undefined ? { trustOverride: options.trustOverride } : {}), ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}) };
+      const workflowOptions: WorkflowIo = { write, stderr, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}), ...(options.agentDir !== undefined ? { agentDir: options.agentDir } : {}), ...(options.signal ? { signal: options.signal } : {}), ...(options.trustOverride !== undefined ? { trustOverride: options.trustOverride } : {}), ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}), ...(options.skillPaths?.length ? { skillPaths: [...options.skillPaths] } : {}) };
+      if (args[0] === "bundle") return await bundleWorkflowCli(args.slice(1), workflowOptions);
       return args[0] === "run" ? await runWorkflowCli(args.slice(1), workflowOptions) : await exportWorkflowCli(args.slice(1), workflowOptions);
     } catch (error) { stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
   }
-  write("Usage: pi-extensible-workflows doctor | inspect [session-id] | transcript <session-file> | run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]\n");
+  write("Usage: pi-extensible-workflows doctor | inspect [session-id] [--json|--summary] [--failed] | transcript <session-file> | bundle <workflow-name> [--name <command>] [--output <path>] [--force] | run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]\n");
   return 1;
 }
 

package/src/doctor-cleanup.ts

@@ -11,7 +11,7 @@ import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, Run
 const TERMINAL_STATES = new Set<RunState>(["completed", "failed", "stopped"]);
 const DAY_MS = 24 * 60 * 60 * 1000;
 const REQUIRED_RUN_FILES = ["workflow.js", "state.json", "snapshot.json", "journal.json", "ownership.json", "worktrees.json", "borrowed-worktrees.json", "system-prompts.json"] as const;
-const OPTIONAL_RUN_FILES = new Set(["result.json"]);
+const OPTIONAL_RUN_FILES = new Set(["result.json", "summary.json"]);
 const RUN_DIRECTORIES = new Set(["worktrees"]);
 const RUN_FILES = new Set<string>([...REQUIRED_RUN_FILES, ...OPTIONAL_RUN_FILES]);
 const AGENT_STATES = new Set(["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"]);
@@ -46,7 +46,7 @@ function accounting(value: unknown, label: string): void { if (!object(value)) t
 function resourceExclusions(value: unknown, label: string): void { if (value === undefined) return; if (!object(value)) throw new Error(`${label} is invalid`); if (value.skills !== undefined) stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined) stringList(value.extensions, `${label}.extensions`); }
 function agentDefinition(value: unknown, label: string): void { if (!object(value)) throw new Error(`${label} is invalid`); optionalString(value.prompt, `${label}.prompt`); optionalString(value.description, `${label}.description`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking as string)) throw new Error(`${label}.thinking is invalid`); if (value.tools !== undefined) stringList(value.tools, `${label}.tools`); resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`); }
 function validateScheduledOptions(value: unknown, label: string): void { if (!object(value) || typeof value.label !== "string" || !value.label || typeof value.cwd !== "string" || !value.cwd) throw new Error(`${label} is invalid`); optionalString(value.requestedLabel, `${label}.requestedLabel`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); stringList(value.tools, `${label}.tools`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking as string)) throw new Error(`${label}.thinking is invalid`); optionalString(value.role, `${label}.role`); if (value.schema !== undefined) validateSchema(value.schema, `${label}.schema`); if (value.retries !== undefined) nonNegativeInteger(value.retries, `${label}.retries`); if (value.timeoutMs !== undefined && value.timeoutMs !== null) positiveInteger(value.timeoutMs, `${label}.timeoutMs`); if (value.agentOptions !== undefined && (!object(value.agentOptions) || !jsonValue(value.agentOptions))) throw new Error(`${label}.agentOptions is invalid`); if (value.agentIdentity !== undefined) { if (!object(value.agentIdentity) || !Array.isArray(value.agentIdentity.structuralPath) || value.agentIdentity.structuralPath.some((part) => typeof part !== "string") || typeof value.agentIdentity.callSite !== "string") throw new Error(`${label}.agentIdentity is invalid`); positiveInteger(value.agentIdentity.occurrence, `${label}.agentIdentity.occurrence`); optionalString(value.agentIdentity.parentBreadcrumb, `${label}.agentIdentity.parentBreadcrumb`); optionalString(value.agentIdentity.worktreeOwner, `${label}.agentIdentity.worktreeOwner`); } }
-function validateAgent(value: unknown, label: string): void { if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || typeof value.state !== "string" || !AGENT_STATES.has(value.state)) throw new Error(`${label} is invalid`); optionalString(value.label, `${label}.label`); optionalString(value.parentId, `${label}.parentId`); if (value.structuralPath !== undefined) stringList(value.structuralPath, `${label}.structuralPath`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.role, `${label}.role`); optionalString(value.requestedModel, `${label}.requestedModel`); model(value.model, `${label}.model`); stringList(value.tools, `${label}.tools`); nonNegativeInteger(value.attempts, `${label}.attempts`); if (value.attemptDetails !== undefined) { if (!Array.isArray(value.attemptDetails)) throw new Error(`${label}.attemptDetails is invalid`); for (const [index, attempt] of value.attemptDetails.entries()) { const at = `${label}.attemptDetails[${String(index)}]`; if (!object(attempt) || !Number.isSafeInteger(attempt.attempt) || Number(attempt.attempt) < 1 || typeof attempt.sessionId !== "string" || !attempt.sessionId || typeof attempt.sessionFile !== "string" || !attempt.sessionFile) throw new Error(`${at} is invalid`); accounting(attempt.accounting, `${at}.accounting`); if (attempt.error !== undefined && (!object(attempt.error) || typeof attempt.error.code !== "string" || typeof attempt.error.message !== "string")) throw new Error(`${at}.error is invalid`); if (attempt.setup !== undefined) { if (!object(attempt.setup) || !Array.isArray(attempt.setup.hookNames) || attempt.setup.hookNames.some((name) => typeof name !== "string") || typeof attempt.setup.cwd !== "string") throw new Error(`${at}.setup is invalid`); model(attempt.setup.model, `${at}.setup.model`); stringList(attempt.setup.tools, `${at}.setup.tools`); resourceExclusions(attempt.setup.disabledAgentResources, `${at}.setup.disabledAgentResources`); } } } if (value.accounting !== undefined) accounting(value.accounting, `${label}.accounting`); if (value.toolCalls !== undefined) { if (!Array.isArray(value.toolCalls)) throw new Error(`${label}.toolCalls is invalid`); for (const call of value.toolCalls) if (!object(call) || typeof call.id !== "string" || typeof call.name !== "string" || !["running", "completed", "failed"].includes(call.state as string)) throw new Error(`${label}.toolCalls is invalid`); } if (value.activity !== undefined && (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind as string) || typeof value.activity.text !== "string")) throw new Error(`${label}.activity is invalid`); }
+function validateAgent(value: unknown, label: string): void { if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || typeof value.state !== "string" || !AGENT_STATES.has(value.state)) throw new Error(`${label} is invalid`); optionalString(value.label, `${label}.label`); optionalString(value.parentId, `${label}.parentId`); if (value.structuralPath !== undefined) stringList(value.structuralPath, `${label}.structuralPath`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.role, `${label}.role`); optionalString(value.requestedModel, `${label}.requestedModel`); model(value.model, `${label}.model`); stringList(value.tools, `${label}.tools`); nonNegativeInteger(value.attempts, `${label}.attempts`); if (value.lastEventAt !== undefined) finiteNumber(value.lastEventAt, `${label}.lastEventAt`); if (value.attemptDetails !== undefined) { if (!Array.isArray(value.attemptDetails)) throw new Error(`${label}.attemptDetails is invalid`); for (const [index, attempt] of value.attemptDetails.entries()) { const at = `${label}.attemptDetails[${String(index)}]`; if (!object(attempt) || !Number.isSafeInteger(attempt.attempt) || Number(attempt.attempt) < 1 || typeof attempt.sessionId !== "string" || !attempt.sessionId || typeof attempt.sessionFile !== "string" || !attempt.sessionFile) throw new Error(`${at} is invalid`); accounting(attempt.accounting, `${at}.accounting`); if (attempt.error !== undefined && (!object(attempt.error) || typeof attempt.error.code !== "string" || typeof attempt.error.message !== "string")) throw new Error(`${at}.error is invalid`); if (attempt.setup !== undefined) { if (!object(attempt.setup) || !Array.isArray(attempt.setup.hookNames) || attempt.setup.hookNames.some((name) => typeof name !== "string") || typeof attempt.setup.cwd !== "string") throw new Error(`${at}.setup is invalid`); model(attempt.setup.model, `${at}.setup.model`); stringList(attempt.setup.tools, `${at}.setup.tools`); resourceExclusions(attempt.setup.disabledAgentResources, `${at}.setup.disabledAgentResources`); } } } if (value.accounting !== undefined) accounting(value.accounting, `${label}.accounting`); if (value.toolCalls !== undefined) { if (!Array.isArray(value.toolCalls)) throw new Error(`${label}.toolCalls is invalid`); for (const call of value.toolCalls) if (!object(call) || typeof call.id !== "string" || typeof call.name !== "string" || !["running", "completed", "failed"].includes(call.state as string)) throw new Error(`${label}.toolCalls is invalid`); } if (value.activity !== undefined && (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind as string) || typeof value.activity.text !== "string")) throw new Error(`${label}.activity is invalid`); }
 function validateUsage(value: unknown, label: string): void { if (!object(value)) throw new Error(`${label} is invalid`); for (const key of ["tokens", "costUsd", "durationMs", "agentLaunches"]) finiteNumber(value[key], `${label}.${key}`); }
 function validateBudgetEvents(value: unknown): void { if (value === undefined) return; if (!Array.isArray(value)) throw new Error("Persisted budget events are invalid"); for (const [index, event] of value.entries()) { const label = `budgetEvents[${String(index)}]`; if (!object(event) || typeof event.type !== "string" || !BUDGET_EVENT_TYPES.has(event.type) || !Number.isSafeInteger(event.budgetVersion) || Number(event.budgetVersion) < 1 || !Array.isArray(event.dimensions) || event.dimensions.some((dimension) => typeof dimension !== "string" || !BUDGET_DIMENSIONS.has(dimension)) || typeof event.at !== "number" || !Number.isFinite(event.at) || event.limits === undefined) throw new Error(`${label} is invalid`); validateUsage(event.usage, `${label}.usage`); validateBudget(event.limits); } }
 function validateRunRecord(run: PersistedRun): void {
@@ -74,6 +74,7 @@ function validateRunRecord(run: PersistedRun): void {
   }
   for (const [index, session] of (value.nativeSessions as unknown[]).entries()) if (!object(session) || typeof session.sessionId !== "string" || !session.sessionId || typeof session.sessionFile !== "string" || !session.sessionFile) throw new Error(`nativeSessions[${String(index)}] is invalid`);
   optionalString(value.parentRunId, "Persisted parent run");
+  optionalString(value.failedAt, "Persisted failed path");
   if (value.retry !== undefined) {
     if (!object(value.retry) || typeof value.retry.sourceRunId !== "string" || !value.retry.sourceRunId || typeof value.retry.lineageRootRunId !== "string" || !value.retry.lineageRootRunId) throw new Error("Persisted retry provenance is invalid");
     const sourceRunId = value.retry.sourceRunId;

package/src/eval-capture-extension.ts

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { validateWorkflowLaunch, WorkflowError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_LABEL, WORKFLOW_TOOL_PARAMETERS, WORKFLOW_TOOL_PROMPT_SNIPPET, type WorkflowValidationParameters } from "./index.js";
+import { validateWorkflowLaunch, WorkflowError, WORKFLOW_RETRY_PARAMETERS, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_LABEL, WORKFLOW_TOOL_PARAMETERS, WORKFLOW_TOOL_PROMPT_SNIPPET, type WorkflowValidationParameters } from "./index.js";
 
 export const CAPTURE_IDENTITY = "pi-extensible-workflows-eval-capture-v1";
 export const CAPTURE_ERROR_PREFIX = `${CAPTURE_IDENTITY}:`;
@@ -51,4 +51,18 @@ export default function evalCaptureExtension(pi: ExtensionAPI): void {
       }
     },
   } as never);
+  pi.registerTool({
+    name: "workflow_retry",
+    label: "Workflow Retry",
+    description: "Capture a recovery selection without executing it",
+    parameters: WORKFLOW_RETRY_PARAMETERS,
+    async execute(_id: string, params: { runId: string }) {
+      if (!params.runId.trim()) throw new WorkflowError("RESUME_INCOMPATIBLE", `${CAPTURE_ERROR_PREFIX}RESUME_INCOMPATIBLE: workflow_retry requires an explicit run ID`);
+      const selection = { tool: "workflow_retry", arguments: { runId: params.runId } };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ captured: true, ...selection }) }],
+        details: { captured: true, captureIdentity: CAPTURE_IDENTITY, realWorkflowAgentsLaunched: 0, selection },
+      };
+    },
+  } as never);
 }

package/src/execution.ts

@@ -1,5 +1,5 @@
 import { fork, spawn, type ChildProcess } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
@@ -78,6 +78,7 @@ const named = (value, kind) => { if (typeof value !== "string" || !value.trim())
 const path = (...names) => names.map(encodeURIComponent).join("/");
 const inheritedAgentPath = new AsyncLocalStorage();
 const agentOccurrences = new Map();
+const agentInflight = new Set();
 const shellOccurrences = new Map();
 const worktreeOwners = new AsyncLocalStorage();
 const rejectAgent = () => { throw workError("INVALID_METADATA", "Workflow agent calls must use a direct agent(...) call; aliases and indirect calls are unsupported"); };
@@ -98,14 +99,22 @@ const internalAgent = (...values) => {
   const callSite = values.pop();
   if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow agent call-site identity");
   const inherited = inheritedAgentPath.getStore() || [];
-  // ponytail: same-callsite races outside parallel/pipeline lack a stable structural scope and are unsupported.
   const occurrenceKey = JSON.stringify([inherited, callSite]);
+  if (agentInflight.has(occurrenceKey)) throw workError("INVALID_METADATA", "Concurrent agent calls from the same source call site are unsupported; use parallel(...) or pipeline(...)");
+  agentInflight.add(occurrenceKey);
   const occurrence = (agentOccurrences.get(occurrenceKey) || 0) + 1;
   agentOccurrences.set(occurrenceKey, occurrence);
   const options = values.length < 2 || values[1] === undefined ? {} : values[1];
   const worktreeOwner = worktreeOwners.getStore();
   const identity = { structuralPath: [...inherited], callSite, occurrence, ...(worktreeOwner ? { worktreeOwner } : {}) };
-  const result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  let result;
+  try {
+    result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  } catch (error) {
+    agentInflight.delete(occurrenceKey);
+    throw error;
+  }
+  void result.then(() => agentInflight.delete(occurrenceKey), () => agentInflight.delete(occurrenceKey));
   Object.defineProperties(result, {
     toJSON: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before serialization"); } },
     toString: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before interpolation"); } },
@@ -386,7 +395,7 @@ function workflowErrorFromWorker(error: WorkerErrorShape): WorkflowError {
 export function runWorkflow(script: string, args: JsonValue = null, bridge: WorkflowBridge = {}, signal?: AbortSignal): WorkflowExecution {
   encoded(args);
   const config = JSON.stringify({ script: instrumentWorkflow(script), args: structuredClone(args), functions: bridge.functions ?? {}, variables: bridge.variables ?? {} });
-  const childDir = mkdtempSync(join(tmpdir(), "pi-wf-"));
+  const childDir = realpathSync(mkdtempSync(join(tmpdir(), "pi-wf-")));
   const childFile = join(childDir, "child.cjs");
   writeFileSync(childFile, childSource);
   const child: ChildProcess = fork(childFile, [String(RPC_LIMIT_BYTES), config], {