pi-extensible-workflows 3.2.0 → 3.4.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,26 +322,48 @@ class CliProgress {
   #lines = 0;
   #frame = 0;
   #run: PersistedRun | undefined;
+  #runId: string | undefined;
+  #runtimeStartedAt = 0;
+  #runtimeBaseMs = 0;
   #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.#runtimeStartedAt = Date.now();
+      this.#runtimeBaseMs = run.usage?.durationMs ?? 0;
+    } else if (this.#run && this.#run.state !== "running" && run.state === "running") {
+      this.#runtimeStartedAt = Date.now();
+      this.#runtimeBaseMs = run.usage?.durationMs ?? 0;
+    }
     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;
+    const run = this.#run.state !== "running" ? this.#run : { ...this.#run, usage: { ...(this.#run.usage ?? { tokens: 0, costUsd: 0, durationMs: 0, agentLaunches: 0 }), durationMs: Math.max(this.#run.usage?.durationMs ?? 0, this.#runtimeBaseMs + Date.now() - this.#runtimeStartedAt) } };
+    if (!this.#interactive) {
+      const stable = formatWorkflowProgress(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");
+    const text = truncateWorkflowProgress(formatWorkflowProgress(run, spinner, this.#styles), width).join("\n");
     this.stderr(`${this.#lines ? `\x1b[${String(this.#lines)}A` : ""}${this.#lines ? "" : "\x1b[?25l"}\x1b[0J${text}\n`);
     this.#lines = text.split("\n").length;
   }
@@ -334,16 +374,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 +430,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 +439,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 +475,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 +548,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 +564,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,12 +46,43 @@ 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 validateSessionReference(value: unknown, label: string): void {
+  if (!object(value) || typeof value.transport !== "string" || !value.transport || typeof value.sessionId !== "string" || !value.sessionId || (value.locator !== undefined && !jsonValue(value.locator))) throw new Error(`${label} is invalid`);
+}
+function validateAgentSetup(value: unknown, label: string): void {
+  if (!object(value)) throw new Error(`${label} is invalid`);
+  stringList(value.hookNames, `${label}.hookNames`);
+  model(value.model, `${label}.model`);
+  stringList(value.tools, `${label}.tools`);
+  if (typeof value.cwd !== "string" || !value.cwd) throw new Error(`${label}.cwd is invalid`);
+  resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`);
+}
+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.systemPrompt, `${label}.systemPrompt`); optionalString(value.prompt, `${label}.prompt`); 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.transport !== "string" || !attempt.transport || Object.hasOwn(attempt, "sessionId") || Object.hasOwn(attempt, "sessionFile")) throw new Error(`${at} is invalid`);
+      validateAgentSetup(attempt.setup, `${at}.setup`);
+      if (attempt.session !== undefined) { validateSessionReference(attempt.session, `${at}.session`); if ((attempt.session as Record<string, unknown>).transport !== attempt.transport) throw new Error(`${at}.session transport does not match attempt transport`); }
+      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 (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 [index, call] of value.toolCalls.entries()) if (!object(call) || typeof call.id !== "string" || !call.id || typeof call.name !== "string" || !call.name || !["running", "completed", "failed"].includes(call.state as string)) throw new Error(`${label}.toolCalls[${String(index)}] is invalid`); }
+  if (value.activity !== undefined) { if (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind as string) || typeof value.activity.text !== "string") throw new Error(`${label}.activity is invalid`); }
+  if (value.lastEventAt !== undefined) finiteNumber(value.lastEventAt, `${label}.lastEventAt`);
+}
 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 {
   const value = run as unknown;
-  if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !RUN_STATES.includes(value.state as RunState) || !Array.isArray(value.agents) || !Array.isArray(value.nativeSessions)) throw new Error("Persisted run state is invalid");
+  if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !RUN_STATES.includes(value.state as RunState) || !Array.isArray(value.agents) || !Array.isArray(value.agentSessions) || Object.hasOwn(value, "nativeSessions")) throw new Error("Persisted run state is invalid");
   const agents = value.agents as Record<string, unknown>[];
   agents.forEach((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); });
   const agentIds = new Set<string>();
@@ -72,8 +103,10 @@ function validateRunRecord(run: PersistedRun): void {
       parent = typeof parentAgent?.parentId === "string" ? parentAgent.parentId : undefined;
     }
   }
-  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`);
+  const sessions = value.agentSessions as unknown[];
+  for (const [index, session] of sessions.entries()) validateSessionReference(session, `agentSessions[${String(index)}]`);
   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;
@@ -145,6 +178,7 @@ async function validateRunArtifacts(store: RunStore, workflowScript: string, sta
     if (!object(record) || typeof record.id !== "string" || !record.id || ownershipIds.has(record.id) || typeof record.label !== "string" || !record.label || typeof record.state !== "string" || !SCHEDULER_STATES.has(record.state)) throw new Error(`${label} is invalid`);
     ownershipIds.add(record.id);
     optionalString(record.parentId, `${label}.parentId`);
+    optionalString(record.prompt, `${label}.prompt`);
     validateScheduledOptions(record.options, `${label}.options`);
   }
   for (const record of ownership) if (object(record) && record.parentId !== undefined && (typeof record.parentId !== "string" || !ownershipIds.has(record.parentId))) throw new Error("Persisted ownership parent is missing");

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { RunStore, structuralPath as operationPath } from "./persistence.js";
 import type { AgentAttempt } from "./agent-execution.js";
-import type { AgentIdentity, JsonValue, ShellIdentity, ShellOptions, ShellResult, WorkflowBridge, WorkflowErrorCode, WorkflowExecution } from "./types.js";
+import type { AgentIdentity, AgentAttemptSummary, JsonValue, ShellIdentity, ShellOptions, ShellResult, WorkflowAgentSessionReference, WorkflowBridge, WorkflowErrorCode, WorkflowExecution } from "./types.js";
 import { WorkflowError } from "./types.js";
 import { asWorkflowError, errorText, fail, isWorkflowAuthored, jsonValue, markWorkflowAuthored, object, positiveInteger } from "./utils.js";
 import { instrumentWorkflow, validateAgentOptions, validateShellCommand, validateShellOptions } from "./validation.js";
@@ -13,6 +13,7 @@ import { instrumentWorkflow, validateAgentOptions, validateShellCommand, validat
 export const RPC_LIMIT_BYTES = 10 * 1024 * 1024;
 type WorkerErrorShape = { code?: string; message: string; authored?: boolean; failedAt?: string };
 export const HEARTBEAT_TIMEOUT_MS = 5000;
+const HEARTBEAT_INTERVAL_MS = 1000;
 
 const OUTCOME_ERRORS = new Set<string>(["AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID"]);
 const WORK_RESULT_BRAND = "__workResult";
@@ -64,7 +65,7 @@ process.on("message", raw => {
   if (message.ok) request.resolve(message.value);
   else request.reject(workflowError(message.error));
 });
-const heartbeat = setInterval(() => send({ type: "heartbeat" }), 1000);
+const heartbeat = setInterval(() => send({ type: "heartbeat" }), ${HEARTBEAT_INTERVAL_MS});
 send({ type: "heartbeat" });
 const BRAND = "${WORK_RESULT_BRAND}";
 const workError = (code, message) => Object.assign(new Error(message), { code });
@@ -416,7 +417,16 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
   const controller = new AbortController();
   let settled = false;
   let rejectResult: (error: WorkflowError) => void = () => undefined;
-  let watchdog = setTimeout(() => { stop("WORKER_UNRESPONSIVE", "Workflow worker missed its five-second heartbeat"); }, HEARTBEAT_TIMEOUT_MS);
+  let lastHeartbeatAt = performance.now();
+  let lastWatchdogCheckAt = lastHeartbeatAt;
+  const watchdog = setInterval(() => {
+    const now = performance.now();
+    // A check delayed enough to bridge the normal heartbeat margin makes elapsed time unreliable.
+    const watchdogCheckWasDelayed = now - lastWatchdogCheckAt >= HEARTBEAT_TIMEOUT_MS - HEARTBEAT_INTERVAL_MS;
+    lastWatchdogCheckAt = now;
+    if (watchdogCheckWasDelayed) { lastHeartbeatAt = now; return; }
+    if (now - lastHeartbeatAt >= HEARTBEAT_TIMEOUT_MS) stop("WORKER_UNRESPONSIVE", "Workflow worker missed its five-second heartbeat");
+  }, HEARTBEAT_INTERVAL_MS);
   const result = new Promise<JsonValue>((resolve, reject) => {
     rejectResult = reject;
     child.on("message", (raw: unknown) => {
@@ -424,7 +434,7 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
         if (typeof raw !== "string" || Buffer.byteLength(raw) > RPC_LIMIT_BYTES) fail("RPC_LIMIT_EXCEEDED", "RPC value exceeds the 10 MB JSON boundary");
         const message = JSON.parse(raw) as { type?: string; id?: number; method?: string; args?: JsonValue[]; ok?: boolean; value?: JsonValue; error?: WorkerErrorShape };
         if (!jsonValue(message)) fail("RPC_LIMIT_EXCEEDED", "Worker RPC must contain JSON-compatible values");
-        if (message.type === "heartbeat") { clearTimeout(watchdog); watchdog = setTimeout(() => { stop("WORKER_UNRESPONSIVE", "Workflow worker missed its five-second heartbeat"); }, HEARTBEAT_TIMEOUT_MS); return; }
+        if (message.type === "heartbeat") { lastHeartbeatAt = performance.now(); return; }
         if (message.type === "result") { encoded(message.value); finish(); resolve(message.value ?? null); return; }
         if (message.type === "error") { finish(); reject(workflowErrorFromWorker(message.error ?? { code: "INTERNAL_ERROR", message: "Worker failed" })); return; }
         if (message.type === "rpc" && message.id !== undefined) void handleRpc(message.id, message.method ?? "", message.args ?? []);
@@ -439,7 +449,7 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
       setTimeout(() => { if (!child.killed) child.kill("SIGKILL"); }, 1000).unref();
     }
   }
-  function finish() { settled = true; clearTimeout(watchdog); signal?.removeEventListener("abort", cancel); killChild(); rmSync(childDir, { recursive: true, force: true }); }
+  function finish() { settled = true; clearInterval(watchdog); signal?.removeEventListener("abort", cancel); killChild(); rmSync(childDir, { recursive: true, force: true }); }
   function stop(code: WorkflowErrorCode, message: string) { if (settled) return; controller.abort(); finish(); rejectResult(new WorkflowError(code, message)); }
   function branded(result: Record<string, JsonValue>): JsonValue { return { ...result, [WORK_RESULT_BRAND]: true }; }
   async function handleRpc(id: number, method: string, values: JsonValue[]) {
@@ -520,18 +530,19 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
   if (signal?.aborted) cancel(); else signal?.addEventListener("abort", cancel, { once: true });
   return { result, cancel };
 }
-function nativeSessionReference(attempt: Pick<AgentAttempt, "sessionId" | "sessionFile">): { sessionId: string; sessionFile: string } {
-  return { sessionId: attempt.sessionId, sessionFile: attempt.sessionFile };
+function attemptSummary(attempt: AgentAttempt, accounting = attempt.accounting): AgentAttemptSummary {
+  return { attempt: attempt.attempt, transport: attempt.transport, ...(attempt.session ? { session: attempt.session } : {}), ...(attempt.error ? { error: attempt.error } : {}), accounting, setup: attempt.setup };
 }
-
-export async function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): Promise<void> {
+export async function persistActiveAgentAttempt(store: RunStore, id: string, active: AgentAttempt): Promise<void> {
   await store.updateState((run) => {
     const agent = run.agents.find((candidate) => candidate.id === id);
     if (!agent) throw new WorkflowError("INTERNAL_ERROR", `Missing production ownership record: ${id}`);
     const accounting = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
-    const details = [...(agent.attemptDetails ?? []).filter((candidate) => candidate.attempt !== active.attempt), { ...active, accounting }];
-    const nativeSessions = run.nativeSessions.some(({ sessionId }) => sessionId === active.sessionId) ? run.nativeSessions : [...run.nativeSessions, nativeSessionReference(active)];
-    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: Math.max(candidate.attempts, active.attempt), attemptDetails: details } : candidate), nativeSessions };
+    const detail = attemptSummary(active, accounting);
+    const details = [...(agent.attemptDetails ?? []).filter((candidate) => candidate.attempt !== active.attempt), detail];
+    const session = active.session;
+    const agentSessions = session && !run.agentSessions.some(({ transport, sessionId }) => transport === session.transport && sessionId === session.sessionId) ? [...run.agentSessions, session] : run.agentSessions;
+    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: Math.max(candidate.attempts, active.attempt), attemptDetails: details } : candidate), agentSessions };
   });
 }
 
@@ -540,9 +551,10 @@ export async function persistAgentAttempts(store: RunStore, id: string, attempts
     const agent = run.agents.find((candidate) => candidate.id === id);
     if (!agent) throw new WorkflowError("INTERNAL_ERROR", `Missing production ownership record: ${id}`);
     const total = attempts.reduce((sum, attempt) => ({ input: sum.input + attempt.accounting.input, output: sum.output + attempt.accounting.output, cacheRead: sum.cacheRead + attempt.accounting.cacheRead, cacheWrite: sum.cacheWrite + attempt.accounting.cacheWrite, cost: sum.cost + attempt.accounting.cost }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 });
-    const attemptDetails = attempts.map(({ attempt, sessionId, sessionFile, error, accounting, setup }) => ({ attempt, sessionId, sessionFile, ...(error ? { error } : {}), accounting, ...(setup ? { setup } : {}) }));
-    const sessionIds = new Set(attempts.map(({ sessionId }) => sessionId));
-    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: attempts.length, attemptDetails, accounting: total } : candidate), nativeSessions: [...run.nativeSessions.filter(({ sessionId }) => !sessionIds.has(sessionId)), ...attempts.map((attempt) => nativeSessionReference(attempt))] };
+    const attemptDetails = attempts.map((attempt) => attemptSummary(attempt));
+    const sessions = attempts.map((attempt) => attempt.session).filter((session): session is WorkflowAgentSessionReference => session !== undefined);
+    const sessionKeys = new Set(sessions.map(({ transport, sessionId }) => `${transport}:${sessionId}`));
+    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: attempts.length, attemptDetails, accounting: total } : candidate), agentSessions: [...run.agentSessions.filter(({ transport, sessionId }) => !sessionKeys.has(`${transport}:${sessionId}`)), ...sessions] };
   });
 }