pi-extensible-workflows 3.2.0 → 3.4.0

package/dist/src/cli.js

@@ -8,7 +8,8 @@ import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionF
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
-import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "./index.js";
+import workflowExtension, { formatWorkflowProgress, loadAgentDefinitions, registeredWorkflowFunctions, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "./index.js";
+import { portableEngineVersion, portablePiVersion, writePortableWorkflowBundle } from "./bundles.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function has(value, key) { return Object.prototype.hasOwnProperty.call(value, key); }
@@ -193,7 +194,30 @@ function launcherHelpLines() {
     ];
 }
 function workflowUsage() { 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() { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function exportUsage() { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function bundleUsage() { 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) {
+    let sessionId;
+    let mode = "tui";
+    let failedOnly = false;
+    for (const arg of rawArgs) {
+        if (arg === "--json" || arg === "--summary") {
+            const next = 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) {
     let olderThanDays = 90;
     let yes = false;
@@ -286,7 +310,7 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
         cwd,
         agentDir,
         settingsManager,
-        resourceLoaderOptions: {},
+        resourceLoaderOptions: { ...(options.skillPaths?.length ? { additionalSkillPaths: [...options.skillPaths] } : {}) },
         resourceLoaderReloadOptions: { resolveProjectTrust },
     });
     const extensions = services.resourceLoader.getExtensions();
@@ -303,7 +327,7 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
         sendMessage() { },
         events: { emit() { } },
     };
-    workflowExtension(headlessPi, homedir(), undefined, undefined, agentDir);
+    workflowExtension(headlessPi, homedir(), undefined, undefined, agentDir, options.skillPaths);
     const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow");
     if (!workflowTool)
         throw new Error("The workflow runtime could not be initialized");
@@ -356,28 +380,41 @@ function terminalProgressStyles(enabled) {
 }
 class CliProgress {
     stderr;
+    onRunId;
     #lastStable = "";
     #lines = 0;
     #frame = 0;
     #run;
+    #runId;
+    #runtimeStartedAt = 0;
+    #runtimeBaseMs = 0;
     #timer;
     #interactive;
     #styles;
-    constructor(stderr, tty) {
+    constructor(stderr, tty, onRunId) {
         this.stderr = stderr;
+        this.onRunId = onRunId;
         this.#interactive = tty && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
         this.#styles = terminalProgressStyles(this.#interactive);
     }
     update(run) {
-        const stable = formatWorkflowProgress(run, "◇", this.#styles);
+        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) {
-            if (stable !== this.#lastStable) {
-                this.#lastStable = stable;
-                this.stderr(`${stable}\n`);
-            }
+            this.#timer ??= setInterval(() => { this.render(); }, 1000);
+            this.#timer.unref();
+            this.render();
             return;
         }
-        this.#run = run;
         this.#timer ??= setInterval(() => { this.render(); }, 80);
         this.#timer.unref();
         this.render();
@@ -385,9 +422,18 @@ class CliProgress {
     render() {
         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;
     }
@@ -406,18 +452,24 @@ class CliProgress {
 async function invokeWorkflow(fn, args, runtime, options, context) {
     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;
+    const announceRunId = (runId) => { 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) => { if (object(update) && object(update.details) && object(update.details.run))
             progress.update(update.details.run); }, context);
         const details = object(result.details) ? result.details : {};
+        const runId = typeof details.runId === "string" ? details.runId : undefined;
+        if (runId)
+            announceRunId(runId);
         if (has(details, "value"))
-            return details.value;
+            return { value: details.value, ...(runId ? { runId } : {}) };
         const first = result.content[0];
         if (!first || first.type !== "text")
             throw new Error("Workflow returned no result");
         try {
-            return parseJsonInput(first.text);
+            return { value: parseJsonInput(first.text), ...(runId ? { runId } : {}) };
         }
         catch {
             throw new Error("Workflow returned invalid JSON");
@@ -471,14 +523,16 @@ async function runWorkflowCli(rawArgs, options) {
             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;
     });
 }
 async function exportWorkflowCli(rawArgs, options) {
     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;
@@ -534,6 +588,80 @@ async function exportWorkflowCli(rawArgs, options) {
         return 0;
     });
 }
+async function bundleWorkflowCli(rawArgs, options) {
+    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];
+    return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
+        let name;
+        let output;
+        let force = false;
+        const requirements = { roles: [], aliases: [], tools: [], commands: [], environment: [] };
+        const resources = { extensions: [], skills: [], static: [], dependencies: [] };
+        for (let index = 1; index < args.length; index += 1) {
+            const arg = args[index];
+            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" };
+            const resourceOptions = { "--extension": "extensions", "--skill": "skills", "--resource": "static", "--dependency": "dependencies" };
+            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]].push(value);
+                else
+                    resources[resourceOptions[option]].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, options = {}, write = (text) => { process.stdout.write(text); }) {
     const stderr = options.stderr ?? ((text) => { process.stderr.write(text); });
     if (args[0] === "doctor" && args.length === 1) {
@@ -558,9 +686,13 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             return 1;
         }
     }
-    if (args[0] === "inspect" && args.length <= 2) {
+    if (args[0] === "inspect") {
         try {
-            await (options.inspect ?? runSessionInspector)(args[1]);
+            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) {
@@ -581,9 +713,11 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             return 1;
         }
     }
-    if (args[0] === "run" || args[0] === "export") {
+    if (args[0] === "bundle" || args[0] === "run" || args[0] === "export") {
         try {
-            const workflowOptions = { 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 = { 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) {
@@ -591,7 +725,7 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             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;
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {

package/dist/src/doctor-cleanup.js

@@ -10,7 +10,7 @@ import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, Run
 const TERMINAL_STATES = new Set(["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"];
-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([...REQUIRED_RUN_FILES, ...OPTIONAL_RUN_FILES]);
 const AGENT_STATES = new Set(["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"]);
@@ -63,35 +63,70 @@ function validateScheduledOptions(value, label) { if (!object(value) || typeof v
     optionalString(value.agentIdentity.parentBreadcrumb, `${label}.agentIdentity.parentBreadcrumb`);
     optionalString(value.agentIdentity.worktreeOwner, `${label}.agentIdentity.worktreeOwner`);
 } }
-function validateAgent(value, label) { 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`);
+function validateSessionReference(value, label) {
+    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, label) {
+    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, label) {
+    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.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 call of value.toolCalls)
-        if (!object(call) || typeof call.id !== "string" || typeof call.name !== "string" || !["running", "completed", "failed"].includes(call.state))
+    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`);
-} if (value.activity !== undefined && (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind) || typeof value.activity.text !== "string"))
-    throw new Error(`${label}.activity 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))
+                throw new Error(`${label}.toolCalls[${String(index)}] is invalid`);
+    }
+    if (value.activity !== undefined) {
+        if (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind) || typeof value.activity.text !== "string")
+            throw new Error(`${label}.activity is invalid`);
+    }
+    if (value.lastEventAt !== undefined)
+        finiteNumber(value.lastEventAt, `${label}.lastEventAt`);
+}
 function validateUsage(value, label) { if (!object(value))
     throw new Error(`${label} is invalid`); for (const key of ["tokens", "costUsd", "durationMs", "agentLaunches"])
     finiteNumber(value[key], `${label}.${key}`); }
@@ -106,7 +141,7 @@ function validateBudgetEvents(value) { if (value === undefined)
 } }
 function validateRunRecord(run) {
     const value = run;
-    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) || !Array.isArray(value.agents) || !Array.isArray(value.nativeSessions))
+    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) || !Array.isArray(value.agents) || !Array.isArray(value.agentSessions) || Object.hasOwn(value, "nativeSessions"))
         throw new Error("Persisted run state is invalid");
     const agents = value.agents;
     agents.forEach((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); });
@@ -131,10 +166,11 @@ function validateRunRecord(run) {
             parent = typeof parentAgent?.parentId === "string" ? parentAgent.parentId : undefined;
         }
     }
-    for (const [index, session] of value.nativeSessions.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;
+    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");
@@ -265,6 +301,7 @@ async function validateRunArtifacts(store, workflowScript, 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)

package/dist/src/eval-capture-extension.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { validateWorkflowLaunch, WorkflowError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_LABEL, WORKFLOW_TOOL_PARAMETERS, WORKFLOW_TOOL_PROMPT_SNIPPET } from "./index.js";
+import { validateWorkflowLaunch, WorkflowError, WORKFLOW_RETRY_PARAMETERS, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_LABEL, WORKFLOW_TOOL_PARAMETERS, WORKFLOW_TOOL_PROMPT_SNIPPET } from "./index.js";
 export const CAPTURE_IDENTITY = "pi-extensible-workflows-eval-capture-v1";
 export const CAPTURE_ERROR_PREFIX = `${CAPTURE_IDENTITY}:`;
 export function resolveWorkflowSkillPath() {
@@ -45,4 +45,19 @@ export default function evalCaptureExtension(pi) {
             }
         },
     });
+    pi.registerTool({
+        name: "workflow_retry",
+        label: "Workflow Retry",
+        description: "Capture a recovery selection without executing it",
+        parameters: WORKFLOW_RETRY_PARAMETERS,
+        async execute(_id, params) {
+            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", text: JSON.stringify({ captured: true, ...selection }) }],
+                details: { captured: true, captureIdentity: CAPTURE_IDENTITY, realWorkflowAgentsLaunched: 0, selection },
+            };
+        },
+    });
 }

package/dist/src/execution.d.ts

@@ -12,6 +12,6 @@ export declare function agentWorktree(identity: AgentIdentity): {
 };
 export declare function executeShellCommand(command: string, options: ShellOptions, signal: AbortSignal, cwd?: string): Promise<ShellResult>;
 export declare function runWorkflow(script: string, args?: JsonValue, bridge?: WorkflowBridge, signal?: AbortSignal): WorkflowExecution;
-export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): Promise<void>;
+export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: AgentAttempt): Promise<void>;
 export declare function persistAgentAttempts(store: RunStore, id: string, attempts: readonly AgentAttempt[]): Promise<void>;
 export type { AgentIdentity, ShellIdentity, WorkflowBridge, WorkflowExecution } from "./types.js";

package/dist/src/execution.js

@@ -9,6 +9,7 @@ import { asWorkflowError, errorText, fail, isWorkflowAuthored, jsonValue, markWo
 import { instrumentWorkflow, validateAgentOptions, validateShellCommand, validateShellOptions } from "./validation.js";
 export const RPC_LIMIT_BYTES = 10 * 1024 * 1024;
 export const HEARTBEAT_TIMEOUT_MS = 5000;
+const HEARTBEAT_INTERVAL_MS = 1000;
 const OUTCOME_ERRORS = new Set(["AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID"]);
 const WORK_RESULT_BRAND = "__workResult";
 const childSource = String.raw `
@@ -58,7 +59,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 });
@@ -458,7 +459,20 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
     const controller = new AbortController();
     let settled = false;
     let rejectResult = () => 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((resolve, reject) => {
         rejectResult = reject;
         child.on("message", (raw) => {
@@ -469,8 +483,7 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
                 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);
+                    lastHeartbeatAt = performance.now();
                     return;
                 }
                 if (message.type === "result") {
@@ -502,7 +515,7 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
                 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, message) { if (settled)
         return; controller.abort(); finish(); rejectResult(new WorkflowError(code, message)); }
     function branded(result) { return { ...result, [WORK_RESULT_BRAND]: true }; }
@@ -612,8 +625,8 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
         signal?.addEventListener("abort", cancel, { once: true });
     return { result, cancel };
 }
-function nativeSessionReference(attempt) {
-    return { sessionId: attempt.sessionId, sessionFile: attempt.sessionFile };
+function attemptSummary(attempt, accounting = attempt.accounting) {
+    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, id, active) {
     await store.updateState((run) => {
@@ -621,9 +634,11 @@ export async function persistActiveAgentAttempt(store, id, active) {
         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 };
     });
 }
 export async function persistAgentAttempts(store, id, attempts) {
@@ -632,8 +647,9 @@ export async function persistAgentAttempts(store, id, attempts) {
         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 !== 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] };
     });
 }