pi-extensible-workflows 3.2.0 → 3.4.0

package/dist/src/types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSessionEvent, CreateAgentSessionOptions, InlineExtension, SessionStats, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CreateAgentSessionOptions, InlineExtension, ToolDefinition } from "@earendil-works/pi-coding-agent";
 export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export declare const AGENT_STATES: readonly ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
 export declare const WORKFLOW_CALL_KINDS: readonly ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
@@ -83,6 +83,7 @@ export interface BudgetApprovalRequest {
 export interface WorkflowErrorShape {
     code: WorkflowErrorCode;
     message: string;
+    failedAt?: string;
 }
 export interface WorkflowEventBase {
     runId: string;
@@ -192,15 +193,16 @@ export interface AgentResourcePolicy {
     global: AgentResourceExclusions;
     project: AgentResourceExclusions;
     effective: AgentResourceExclusions;
-    unmatchedSkills: string[];
-    unmatchedExtensions: string[];
-    excludedSkills?: string[];
-    excludedExtensions?: string[];
+    unmatchedSkills: readonly string[];
+    unmatchedExtensions: readonly string[];
+    excludedSkills?: readonly string[];
+    excludedExtensions?: readonly string[];
 }
 export interface AgentActivity {
     kind: "reasoning" | "tool" | "text";
     text: string;
 }
+export declare const WORKFLOW_AGENT_STALL_THRESHOLD_MS: number;
 export interface AgentAccounting {
     input: number;
     output: number;
@@ -222,22 +224,17 @@ export interface AgentSetupSummary {
         unmatchedExtensions: readonly string[];
     };
 }
+export interface AgentAttemptError {
+    code: string;
+    message: string;
+}
 export interface AgentAttemptSummary {
     attempt: number;
-    sessionId: string;
-    sessionFile: string;
-    error?: {
-        code: string;
-        message: string;
-    };
-    accounting: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: number;
-    };
-    setup?: AgentSetupSummary;
+    transport: string;
+    session?: WorkflowAgentSessionReference;
+    setup: AgentSetupSummary;
+    error?: AgentAttemptError;
+    accounting: AgentAccounting;
 }
 export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase {
     owner: string;
@@ -250,6 +247,8 @@ export interface WorkflowWorktreeReference {
     readonly branch: string;
 }
 export interface AgentRecord {
+    systemPrompt?: string;
+    prompt?: string;
     id: string;
     name: string;
     label?: string;
@@ -279,6 +278,14 @@ export interface AgentRecord {
         state: "running" | "completed" | "failed";
     }[];
     activity?: AgentActivity | undefined;
+    lastEventAt?: number;
+}
+export type WorkflowDeliveryMode = "foreground" | "background";
+export type WorkflowDeliveryStatus = "attached" | "pending" | "delivered";
+export interface WorkflowRunDelivery {
+    mode: WorkflowDeliveryMode;
+    state: WorkflowDeliveryStatus;
+    toolCallId?: string;
 }
 export interface WorkflowRunEvent {
     type: string;
@@ -301,31 +308,38 @@ export interface RunRecord {
     cwd: string;
     sessionId: string;
     state: RunState;
+    agentSessions: readonly WorkflowAgentSessionReference[];
     parentRunId?: string;
     retry?: WorkflowRetryProvenance;
     phase?: string;
     phaseHistory?: readonly WorkflowPhaseRecord[];
     agents: readonly AgentRecord[];
+    activeShells?: number;
     error?: WorkflowErrorShape;
+    failedAt?: string;
     budget?: WorkflowBudget;
     budgetVersion?: number;
     usage?: WorkflowBudgetUsage;
     budgetEvents?: readonly BudgetEvent[];
     events?: readonly WorkflowRunEvent[];
+    delivery?: WorkflowRunDelivery;
 }
 export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export type WorkflowLaunchMode = "foreground" | "background";
 export interface AgentDefinition {
     prompt?: string;
     description?: string;
     model?: string;
     thinking?: NonNullable<ModelSpec["thinking"]>;
     tools?: readonly string[];
+    overrideSystemPrompt?: boolean;
     disabledAgentResources?: AgentResourceExclusions;
 }
 export interface LaunchSnapshot {
     identityVersion?: number;
     launchKind?: "inline" | "function";
     functionName?: string;
+    launchMode?: WorkflowLaunchMode;
     script: string;
     args: JsonValue;
     metadata: WorkflowMetadata;
@@ -397,47 +411,65 @@ export interface WorkflowVariable {
     schema: JsonSchema;
     resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue;
 }
-type NativeAgentMessage = {
-    role: string;
-    content?: unknown;
-    stopReason?: string;
-    errorMessage?: string;
-    usage?: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: {
-            total: number;
-        };
-    };
-};
-type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
-export interface NativeSession {
+export interface WorkflowAgentSessionReference {
+    readonly transport: string;
     readonly sessionId: string;
-    readonly sessionFile: string | undefined;
-    readonly messages: readonly NativeAgentMessage[];
-    getSessionStats(): NativeSessionStats;
-    readonly systemPrompt?: string;
-    readonly model?: {
-        provider: string;
-        model?: string;
-        id?: string;
+    readonly locator?: JsonValue;
+}
+export interface WorkflowAgentSessionStats {
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly total: number;
     };
-    readonly agent?: {
-        state: {
-            tools: readonly {
-                name: string;
-            }[];
+    readonly cost: number;
+}
+export interface WorkflowAgentMessage {
+    readonly role: string;
+    readonly content?: unknown;
+    readonly stopReason?: string;
+    readonly errorMessage?: string;
+    readonly usage?: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly cost: {
+            readonly total: number;
         };
     };
-    getLeafId?: () => string | null;
-    getToolDefinitions?: () => unknown;
-    subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
-    prompt(text: string): Promise<void>;
-    steer?(text: string): Promise<void>;
-    abort?(): Promise<void>;
-    dispose(): void;
+}
+export interface WorkflowAgentSessionState {
+    readonly model: ModelSpec;
+    readonly thinking?: ModelSpec["thinking"];
+    readonly tools: readonly string[];
+    readonly systemPrompt?: string;
+}
+export interface WorkflowAgentSessionEvent {
+    readonly type: string;
+    readonly state?: Readonly<WorkflowAgentSessionState>;
+    readonly message?: WorkflowAgentMessage;
+    readonly assistantMessageEvent?: {
+        readonly type: string;
+    };
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly isError?: boolean;
+}
+export interface WorkflowAgentTurnResult {
+    readonly assistant?: WorkflowAgentMessage;
+}
+export interface WorkflowAgentSession {
+    readonly reference: WorkflowAgentSessionReference;
+    getState(): Readonly<WorkflowAgentSessionState>;
+    getSessionStats(): WorkflowAgentSessionStats;
+    subscribe(listener: (event: WorkflowAgentSessionEvent) => void): () => void;
+    prompt(text: string): Promise<WorkflowAgentTurnResult>;
+    steer(text: string): Promise<void>;
+    abort(): Promise<void>;
+    dispose(): Promise<void>;
 }
 type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
 type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
@@ -449,17 +481,44 @@ export interface SessionInput {
     agentDir?: string;
     customTools?: SessionCustomTools;
     resultTool?: ToolDefinition;
+    systemPrompt?: string;
     systemPromptAppend?: string;
     extensionFactories?: InlineExtension[];
+    additionalSkillPaths?: readonly string[];
     resourcePolicy?: AgentResourcePolicy;
     options?: AgentOptions;
 }
-export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
+export interface PreparedAgentSession {
+    readonly cwd: string;
+    readonly model: ModelSpec;
+    readonly tools: readonly string[];
+    readonly sessionLabel: string;
+    readonly agentDir?: string;
+    readonly customTools?: readonly ToolDefinition[];
+    readonly resultTool?: ToolDefinition;
+    readonly options?: Readonly<Record<string, JsonValue>>;
+    readonly systemPrompt?: string;
+    readonly systemPromptAppend?: string;
+    readonly extensionFactories?: readonly InlineExtension[];
+    readonly additionalSkillPaths?: readonly string[];
+    readonly resourcePolicy?: Readonly<AgentResourcePolicy>;
+}
+export interface AgentTransportContext {
+    readonly run: Readonly<WorkflowRunContext>;
+    readonly identity: Readonly<AgentIdentity>;
+    readonly attempt: number;
+    readonly signal: AbortSignal;
+}
+export interface AgentTransport {
+    readonly id: string;
+    createSession(prepared: Readonly<PreparedAgentSession>, context: Readonly<AgentTransportContext>): Promise<WorkflowAgentSession>;
+}
 export interface AgentSetup {
     prompt: string;
     options: AgentOptions;
     sessionInput: SessionInput;
-    createSession: SessionFactory;
+    prepared: Readonly<PreparedAgentSession>;
+    transport: AgentTransport;
 }
 export interface AgentSetupContext {
     readonly run: Readonly<WorkflowRunContext>;
@@ -485,11 +544,32 @@ export interface WorkflowRoleDirectoryRegistration {
     path: string;
     extension: WorkflowExtensionMetadata;
 }
+export interface AgentAttemptActionUi {
+    notify(message: string, level?: "info" | "warning" | "error"): void;
+    confirm(title: string, message: string): Promise<boolean>;
+    select(title: string, options: readonly string[]): Promise<string | undefined>;
+    input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+export interface AgentAttemptActionContext {
+    readonly run: Readonly<RunRecord>;
+    readonly agent: Readonly<AgentRecord>;
+    readonly attempt: Readonly<AgentAttemptSummary>;
+    readonly session?: WorkflowAgentSessionReference;
+    readonly liveSession?: WorkflowAgentSession;
+    readonly signal: AbortSignal;
+    readonly ui: Readonly<AgentAttemptActionUi>;
+}
+export interface AgentAttemptAction {
+    readonly label: string;
+    visible(context: Readonly<AgentAttemptActionContext>): boolean;
+    run(context: Readonly<AgentAttemptActionContext>): void | Promise<void>;
+}
 export interface WorkflowExtension extends WorkflowExtensionMetadata {
     functions?: Readonly<Record<string, WorkflowFunction>>;
     variables?: Readonly<Record<string, WorkflowVariable>>;
     modelAliases?: Readonly<Record<string, WorkflowModelAlias>>;
     agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
+    agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>>;
     roleDirectories?: readonly (string | URL)[];
 }
 export interface WorkflowJournal {
@@ -506,8 +586,8 @@ export interface WorkflowFailureAgent {
     role?: string;
     structuralPath: readonly string[];
     attempt: number;
-    sessionId?: string;
-    sessionFile?: string;
+    transport?: string;
+    session?: WorkflowAgentSessionReference;
 }
 export interface WorkflowSiblingAgent {
     id: string;
@@ -669,6 +749,7 @@ export interface WorkflowValidationParameters {
     name?: string;
     description?: string;
     script?: string;
+    scriptPath?: string;
     workflow?: string;
     args?: unknown;
 }

package/dist/src/types.js

@@ -16,6 +16,7 @@ export const ERROR_CODES = [
     "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
     "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
 ];
+export const WORKFLOW_AGENT_STALL_THRESHOLD_MS = 10 * 60 * 1000;
 export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
 export class WorkflowError extends Error {
     code;

package/dist/src/validation.js

@@ -180,7 +180,7 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
             return { prompt: content };
         const meta = {};
         for (const line of content.slice(4, end).split("\n")) {
-            const match = /^(model|thinking|tools|description)\s*:\s*(.+)$/.exec(line.trim());
+            const match = /^(model|thinking|tools|description|overrideSystemPrompt|override_system_prompt|is_system_prompt)\s*:\s*(.+)$/.exec(line.trim());
             if (match?.[1] && match[2])
                 meta[match[1]] = match[2].trim();
         }
@@ -197,6 +197,9 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
             definition.thinking = thinking;
         if (tools)
             definition.tools = tools;
+        const overrideSystemPrompt = meta.overrideSystemPrompt ?? meta.override_system_prompt ?? meta.is_system_prompt;
+        if (overrideSystemPrompt)
+            definition.overrideSystemPrompt = overrideSystemPrompt === "true";
         return definition;
     }
     const normalized = content.replace(/\r\n?/g, "\n");
@@ -212,16 +215,19 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
     if (!object(parsed.frontmatter))
         fail("INVALID_METADATA", "Role frontmatter must be an object");
     const { model, thinking, tools, description, disabledAgentResources } = parsed.frontmatter;
+    const overrideSystemPrompt = parsed.frontmatter.overrideSystemPrompt ?? parsed.frontmatter.override_system_prompt ?? parsed.frontmatter.is_system_prompt;
     if (model !== undefined && (typeof model !== "string" || model.trim() === ""))
         fail("INVALID_METADATA", "Role model must be a non-empty string");
     if (thinking !== undefined && (typeof thinking !== "string" || !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinking)))
         fail("INVALID_METADATA", `Invalid role thinking level: ${typeof thinking === "string" ? thinking : typeof thinking}`);
     if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description)))
         fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
+    if (overrideSystemPrompt !== undefined && typeof overrideSystemPrompt !== "boolean")
+        fail("INVALID_METADATA", "Role overrideSystemPrompt must be a boolean");
     if (tools !== undefined && (!Array.isArray(tools) || tools.some((tool) => typeof tool !== "string" || tool.trim() === "")))
         fail("INVALID_METADATA", "Role tools must be an array of non-empty strings");
     const normalizedResources = validateAgentResourceExclusions(disabledAgentResources, rolePath ?? "<role>", "INVALID_METADATA");
-    return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => tool.trim()) } : {}), ...(normalizedResources ? { disabledAgentResources: normalizedResources } : {}) };
+    return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => tool.trim()) } : {}), ...(typeof overrideSystemPrompt === "boolean" ? { overrideSystemPrompt } : {}), ...(normalizedResources ? { disabledAgentResources: normalizedResources } : {}) };
 }
 const ROLE_DIRECTORY = "pi-extensible-workflows";
 export function workflowRoleDirectories(agentDir = getAgentDir()) {
@@ -819,10 +825,25 @@ export function validateWorkflowLaunchWithRegistry(params, context, registry) {
         fail("INVALID_METADATA", "maxAgentLaunches has been removed; use budget.agentLaunches");
     if (params.script !== undefined && params.workflow !== undefined)
         fail("INVALID_METADATA", "Provide either script or workflow, not both");
+    if (params.scriptPath !== undefined && (typeof params.scriptPath !== "string" || !params.scriptPath.trim()))
+        fail("INVALID_METADATA", "scriptPath must be a non-empty path");
+    if ((params.script !== undefined || params.workflow !== undefined) && params.scriptPath !== undefined)
+        fail("INVALID_METADATA", "Provide either script, scriptPath, or workflow, not more than one");
+    const scriptPath = typeof params.scriptPath === "string" ? params.scriptPath.trim() : undefined;
+    let fileScript;
+    if (scriptPath !== undefined) {
+        try {
+            fileScript = readFileSync(resolve(context.cwd, scriptPath), "utf8");
+        }
+        catch (error) {
+            fail("INVALID_SYNTAX", `Cannot read workflow script file ${scriptPath}: ${errorText(error)}`);
+        }
+    }
     const functionName = typeof params.workflow === "string" ? params.workflow : undefined;
-    if (functionName !== undefined && params.name !== undefined)
-        fail("INVALID_METADATA", "Registered function launches do not accept name; workflow is the run name");
-    const workflowName = functionName ?? (typeof params.name === "string" ? params.name.trim() : "");
+    const explicitName = params.name === undefined ? undefined : typeof params.name === "string" ? params.name.trim() : "";
+    if (params.name !== undefined && !explicitName)
+        fail("INVALID_METADATA", "Workflow name must be non-empty when provided");
+    const workflowName = explicitName ?? functionName ?? "";
     if (functionName === undefined && !workflowName)
         fail("INVALID_METADATA", "Inline workflow launches require a non-empty name");
     const fn = functionName === undefined ? undefined : registry?.function(functionName);
@@ -831,9 +852,9 @@ export function validateWorkflowLaunchWithRegistry(params, context, registry) {
     const args = params.args === undefined ? null : params.args;
     if (functionName !== undefined && fn && (!object(args) || !jsonValue(args) || !Value.Check(fn.input, args)))
         fail("RESULT_INVALID", `Invalid input for ${functionName}`);
-    const script = functionName !== undefined && fn ? functionLaunchScript(functionName) : typeof params.script === "string" && params.script.trim() ? params.script : "";
+    const script = functionName !== undefined && fn ? functionLaunchScript(functionName) : typeof params.script === "string" && params.script.trim() ? params.script : fileScript ?? "";
     if (!script)
-        fail("INVALID_SYNTAX", "Provide script or registered function");
+        fail("INVALID_SYNTAX", "Provide script, scriptPath, or registered function");
     const metadata = validateWorkflowMetadata({ name: workflowName, ...(typeof params.description === "string" ? { description: params.description } : fn?.description ? { description: fn.description } : {}) });
     const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false, registry && typeof registry.roleDirectoryRegistrations === "function" ? registry.roleDirectoryRegistrations() : registry && typeof registry.roleDirectories === "function" ? registry.roleDirectories() : undefined);
     const projectAgentDefinitions = context.projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(context.cwd, ".pi"))) : {};

package/dist/src/workflow-artifacts.d.ts

@@ -9,5 +9,6 @@ export type WorkflowTui = {
     requestRender(force?: boolean): void;
 };
 export declare function workflowScriptArtifact(script: string): WorkflowArtifact;
+export declare function workflowPromptArtifact(prompt: string): WorkflowArtifact;
 export declare function workflowResultArtifact(value: JsonValue): WorkflowArtifact;
 export declare function openWorkflowArtifact(tui: WorkflowTui, command: string, artifact: WorkflowArtifact): Promise<number | null>;

package/dist/src/workflow-artifacts.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 export function workflowScriptArtifact(script) { return { extension: ".js", content: script }; }
+export function workflowPromptArtifact(prompt) { return { extension: ".md", content: prompt }; }
 export function workflowResultArtifact(value) { return typeof value === "string" ? { extension: ".md", content: value } : { extension: ".json", content: `${JSON.stringify(value, null, 2)}\n` }; }
 async function spawnWorkflowEditor(command, path) {
     const [editor, ...editorArgs] = command.split(" ");

package/dist/src/workflow-evals.d.ts

@@ -74,6 +74,10 @@ export interface ParentToolResult {
     isError?: boolean;
     text?: string;
 }
+export interface ParentToolCall {
+    name: string;
+    arguments: JsonValue;
+}
 export interface ParentUsage {
     input: number;
     output: number;
@@ -216,13 +220,14 @@ export interface EvalCaseResult {
         realWorkflowAgentsLaunched: number | null;
     };
 }
-export declare const SAFE_PARENT_EVAL_TOOLS: readonly ["read", "grep", "find", "bash", "workflow"];
+export declare const SAFE_PARENT_EVAL_TOOLS: readonly ["read", "grep", "find", "bash", "workflow", "workflow_retry"];
 export declare function validateWorkflowEvalCases(values: readonly unknown[], source?: string): readonly WorkflowEvalCase[];
 export declare function loadWorkflowEvalCases(directory?: string): readonly WorkflowEvalCase[];
 export declare const INITIAL_WORKFLOW_EVAL_CASES: readonly WorkflowEvalCase[];
 export declare function matchesJsonResult(shape: JsonResultShape, value: JsonValue): boolean;
 export declare function matchesOutputSchema(shape: OutputSchemaShape, schema: JsonSchema): boolean;
 export declare function extractParentOracle(entries: readonly unknown[]): ParentOracle;
+export declare function extractParentToolCalls(oracle: ParentOracle): ParentToolCall[];
 export declare function extractParentOracleFile(path: string): ParentOracle;
 export declare function extractCapturedWorkflows(oracle: ParentOracle): CapturedWorkflowCall[];
 export declare function captureValidationReports(oracle: ParentOracle, calls: readonly CapturedWorkflowCall[]): {
@@ -231,6 +236,7 @@ export declare function captureValidationReports(oracle: ParentOracle, calls: re
     verified: boolean;
 };
 export declare function evalExpectationErrors(oracle: ParentOracle, expectations: EvalExpectations): string[];
+export declare function recoverySelectionErrors(evalCase: Pick<WorkflowEvalCase, "id">, oracle: ParentOracle): string[];
 export declare function replayExpectationErrors(calls: readonly CapturedWorkflowCall[], reports: readonly ReplayReport[], expectations: EvalExpectations): string[];
 export declare function staticExpectationResults(calls: readonly CapturedWorkflowCall[], expectations: EvalExpectations): CriterionResult[];
 export declare function selectStaticCandidate(calls: readonly CapturedWorkflowCall[], validations: readonly ProductionValidationReport[], expectations: EvalExpectations, requiredCount?: number): {

package/dist/src/workflow-evals.js

@@ -10,7 +10,7 @@ import { CAPTURE_ERROR_PREFIX, CAPTURE_IDENTITY, resolveWorkflowSkillPath } from
 export { resolveWorkflowSkillPath } from "./eval-capture-extension.js";
 import { ERROR_CODES, inspectWorkflowScript, isObject, loadAgentDefinitions, runWorkflow, WORKFLOW_CALL_KINDS, WorkflowError } from "./index.js";
 const CASE_PROCESS_GRACE_MS = 1_000;
-export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "bash", "workflow"]);
+export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "bash", "workflow", "workflow_retry"]);
 const EVAL_MODEL_TOKEN = "$EVAL_MODEL";
 const semantic = (description) => [{ id: "intent", description }];
 const JSON_RESULT_TYPES = ["null", "boolean", "number", "integer", "string", "array", "object"];
@@ -367,6 +367,13 @@ export function extractParentOracle(entries) {
     }
     return { assistantBatches: batches, workflowToolResults, skillReads, ...(firstSignificantAction ? { firstSignificantAction } : {}), ...(parentToolSequence[0] ? { firstTool: parentToolSequence[0] } : {}), firstBatchToolSequence: firstBatch?.tools ?? [], toolsBeforeFirstWorkflow: firstWorkflowIndex < 0 ? parentToolSequence : parentToolSequence.slice(0, firstWorkflowIndex), firstWorkflowBatchToolSequence: firstWorkflowBatch?.tools ?? [], parentToolSequence, workflowCallCount: parentToolSequence.filter((name) => name === "workflow").length, usage: { ...totals, models: [...modelCosts].map(([model, cost]) => ({ model, cost })) } };
 }
+export function extractParentToolCalls(oracle) {
+    return oracle.assistantBatches.flatMap(({ parts }) => parts.flatMap((part) => {
+        if (!isObject(part) || part.type !== "toolCall" || typeof part.name !== "string")
+            return [];
+        return [{ name: part.name, arguments: isJson(part.arguments) ? part.arguments : null }];
+    }));
+}
 export function extractParentOracleFile(path) {
     const entries = readFileSync(path, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
     return extractParentOracle(entries);
@@ -434,6 +441,19 @@ export function evalExpectationErrors(oracle, expectations) {
     }
     return errors;
 }
+const RECOVERY_SELECTIONS = {
+    "recovery-failed-run": { tool: "workflow_retry", arguments: { runId: "failed-run-42" } },
+    "recovery-completed-worktree": { tool: "workflow", arguments: { name: "borrow-worktree", script: "return true;", parentRunId: "completed-run-42" } },
+};
+export function recoverySelectionErrors(evalCase, oracle) {
+    const expected = RECOVERY_SELECTIONS[evalCase.id];
+    if (!expected)
+        return [];
+    const actual = extractParentToolCalls(oracle);
+    if (actual.length === 1 && actual[0]?.name === expected.tool && equalJson(actual[0].arguments, expected.arguments))
+        return [];
+    return [`${evalCase.id} parent tool calls were ${JSON.stringify(actual)}; expected ${JSON.stringify([expected])}`];
+}
 export function replayExpectationErrors(calls, reports, expectations) {
     const errors = [];
     const staticCalls = calls.flatMap((call) => { try {
@@ -862,7 +882,7 @@ function semanticJudgePrompt(evalCase, calls, cwd, home) {
     } }));
     const roleText = [...usedRoles].map((role) => `${role}: ${roles[role]?.description ?? "no description"}`).join("\n") || "none";
     const docs = "agent(prompt, options) delegates; shell(command, options) runs a deterministic host command and returns exitCode/stdout/stderr; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
-    return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow script(s):\n${calls.map((call, index) => `--- ${String(index)} ---\n${call.script ?? "<missing>"}`).join("\n")}`;
+    return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow call(s):\n${calls.map((call, index) => `--- ${String(index)} ---\nArguments:\n${JSON.stringify(call.arguments)}\nScript:\n${call.script ?? "<missing>"}`).join("\n")}`;
 }
 async function runSemanticJudge(input, calls, cwd, home, sessionDir, maxCost) {
     const args = ["--offline", "--no-extensions", "--no-skills", "--no-context-files", "--no-tools", "--mode", "json", "--session-dir", sessionDir, "--session-id", randomUUID()];
@@ -1045,7 +1065,7 @@ export async function captureEvalCase(input) {
         const parentUsageThroughCandidate = usageThroughCandidate(oracle, workflows, selection.callIndices);
         const parentAccounting = parentUsageThroughCandidate ?? oracle.usage;
         const unsafeTool = oracle.parentToolSequence.find((tool) => !SAFE_PARENT_EVAL_TOOLS.includes(tool));
-        const errors = [...evalExpectationErrors(oracle, input.case.expectations), ...validation.errors, ...(unsafeTool ? [`parent tool is outside the safe eval allowlist: ${unsafeTool}`] : [])];
+        const errors = [...evalExpectationErrors(oracle, input.case.expectations), ...recoverySelectionErrors(input.case, oracle), ...validation.errors, ...(unsafeTool ? [`parent tool is outside the safe eval allowlist: ${unsafeTool}`] : [])];
         if (requiredCount > 0 && selection.callIndices.length === 0)
             errors.push("Catastrophic validity failure: no production-valid workflow candidate satisfied static expectations.");
         let judge;

package/evals/cases/recovery-completed-worktree.yaml

@@ -0,0 +1,17 @@
+id: recovery-completed-worktree
+prompt: >-
+  The completed workflow run ID is "completed-run-42". You need a new workflow to do named worktree work,
+  so launch the workflow with exactly parentRunId "completed-run-42". Use exactly the workflow arguments {"name":"borrow-worktree","script":"return true;","parentRunId":"completed-run-42"}.
+  Do not call workflow_retry because the source is completed and parentRunId only borrows the named worktree; it does not replay or resume.
+maxCost: 0.1
+expectations:
+  firstTool: workflow
+  firstBatchToolSequence:
+    startsWith: [workflow]
+  parentToolSequence:
+    startsWith: [workflow]
+  workflowCallCount: 1
+expectedWorkflowCalls: 1
+semanticCriteria:
+  - id: parent-run-id
+    description: The captured workflow call has exactly name borrow-worktree, script return true;, and parentRunId completed-run-42; it does not call workflow_retry.

package/evals/cases/recovery-failed-run.yaml

@@ -0,0 +1,14 @@
+id: recovery-failed-run
+prompt: >-
+  A workflow failure diagnostic identifies the persisted failed run ID "failed-run-42" and says the exact next action is
+  workflow_retry({ runId: "failed-run-42" }). Select that recovery tool now with exactly {"runId":"failed-run-42"}.
+  Do not launch a new workflow, use parentRunId, or answer with prose.
+maxCost: 0.1
+expectedWorkflowCalls: 0
+expectations:
+  firstTool: workflow_retry
+  firstBatchToolSequence:
+    equals: [workflow_retry]
+  parentToolSequence:
+    equals: [workflow_retry]
+  workflowCallCount: 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {

package/skills/pi-extensible-workflows/SKILL.md

@@ -27,15 +27,23 @@ Await `parallel(...)` or `pipeline(...)` results before interpolation. Runs are
 ## Runtime and safety rules
 
 
-Inline launches require a non-empty `name`. Registered function launches must omit `name`; they use `workflow` as the run name:
 
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId })` replays a failed run into a child; `workflow_resume({ runId, budget? })` continues a `budget_exhausted` run; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
-For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
-Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
+
+A reviewed JavaScript file on disk can use `scriptPath` instead of `script`.
+
+Recovery map:
+  - `agent(..., { retries })` reruns one agent call in the same run for transient failures;
+  - `workflow_retry({ runId, foreground? })` replays a failed run into a child;
+  - `workflow_resume({ runId, budget?, foreground? })` continues a `budget_exhausted` run;
+  - recovery inherits the source snapshot's foreground/background launch mode, while legacy snapshots without `launchMode` recover in background; set `foreground: true` or `false` to override it;
+  - `parentRunId` on a new launch only borrows named worktrees and never replays or resumes.
+
+For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId, foreground: <prevValue> })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
+`workflow_stop` requires the exact run ID; foreground launches and foreground recovery retain their terminal value and completed `runId`, while background launches and recovery return `runId` immediately and deliver completion or failure as a follow-up. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
+Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task. Make sure to call workflow_catalog more than once if you need to inspect details about a global function.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.