pi-extensible-workflows 3.1.0 → 3.3.0

package/README.md

@@ -6,7 +6,7 @@
 
 Turn multi-agent tasks into deterministic jobs that fan out in parallel, pause for approval, and resume without rerunning completed work.
 
-[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html) | [Extension authoring](https://vekexasia.github.io/pi-extensible-workflows/extensions.html)
+[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html) | [Extension authoring](https://vekexasia.github.io/pi-extensible-workflows/extensions.html) | [Video overview](https://youtu.be/qAiivspEHmU)
 
 Requires Node.js 22.19 or newer. This is a trusted Pi extension with the same filesystem and process access as Pi.
 
@@ -20,32 +20,24 @@ For source installs and local development, see the [installation guide](https://
 
 ## Capabilities
 
-The main Pi agent acts as the orchestrator: it writes workflow scripts on the fly for each task. Pi extensions can add reusable functions and variables to those scripts; every registered function is also directly runnable as a top-level workflow.
-
-Inline workflow launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
-
-A workflow can fan out across specialized agents, combine their results, and resume without rerunning completed work.
+The default path is a named inline workflow: write a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns. Inline launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Runs are backgrounded by default; set `foreground: true` when the final value must be returned in the same tool call. If a foreground tool call detaches before its result is accepted by the next event-loop turn, the terminal success or failure is promoted to exactly one follow-up message.
 
 ```js
 const reviews = await parallel("review", {
-  correctness: () =>
-    agent("Review the current changes for correctness issues."),
-  security: () =>
-    agent("Review the current changes for security risks.", {
-      role: "security-specialist",
-    }),
+  correctness: () => agent("Review the current changes for correctness issues."),
+  security: () => agent("Review the current changes for security risks."),
   tests: () => agent("Review the current changes for missing test coverage."),
 });
 
-const summary = await agent(
-  prompt("Deduplicate and prioritize these findings:\n\n{reviews}", {
-    reviews,
-  }),
+return await agent(
+  prompt("Summarize and prioritize these findings:\n\n{reviews}", { reviews }),
 );
-
-return summary;
 ```
 
+**Advanced capabilities:** Use registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` when the task requires them. They remain available without complicating the basic inline path. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
+
+The main Pi agent writes these scripts on the fly for each task; extensions can add reusable functions and variables, and completed workflows can resume without rerunning completed work.
+
 Learn more about roles, workflow contracts, and extension APIs in the documentation:
 
 - [Workflow tool and invocation API](https://vekexasia.github.io/pi-extensible-workflows/developers.html#tool-api)
@@ -53,40 +45,12 @@ Learn more about roles, workflow contracts, and extension APIs in the documentat
 - [Aggregate run budgets](https://vekexasia.github.io/pi-extensible-workflows/developers.html#budgets)
 - [Workflow DSL and worktrees](https://vekexasia.github.io/pi-extensible-workflows/developers.html#dsl)
 - [Extension authoring guide](https://vekexasia.github.io/pi-extensible-workflows/extensions.html)
+- [Copy-paste extension template](https://github.com/vekexasia/pi-extensible-workflows/tree/main/examples/workflow-extension-template)
 - [Run artifacts and lifecycle events](https://vekexasia.github.io/pi-extensible-workflows/developers.html#lifecycle)
 - [Run inspection and recovery](https://vekexasia.github.io/pi-extensible-workflows/developers.html#operations)
 - [Agent patterns and model selection](https://vekexasia.github.io/pi-extensible-workflows/agents.html#patterns)
 - [Checkpoints](https://vekexasia.github.io/pi-extensible-workflows/agents.html#checkpoints)
 
-## Configuration
-
-Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.json` by default. Trusted projects can add partial overrides at `<project>/.pi/pi-extensible-workflows/settings.json`; precedence is defaults < global < trusted project < per-run options. Project collections replace global collections, so `{}` and empty arrays clear inherited aliases or resource exclusions. Untrusted project settings are ignored. See [global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings) for the schema, trust gate, source reporting, and merge rules.
-
-## CLI
-
-```sh
-npx pi-extensible-workflows doctor
-npx pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]
-npx pi-extensible-workflows inspect [session-id]
-npx pi-extensible-workflows transcript <session-file>
-npx pi-extensible-workflows run <workflow-name> [workflow arguments]
-npx pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]
-```
-
-`doctor` validates the installation and active Pi resources and remains read-only. `doctor cleanup` is an explicit, dry-run-first maintenance command: it previews terminal workflow runs older than 90 days across the current project's stored sessions and deletes them only with `--yes`; use `--older-than-days` to change the positive age threshold. It protects active, corrupt, leased, and dependency-linked runs. `inspect` opens a read-only terminal view of persisted workflow runs. `transcript` renders a session transcript to stdout. `run` derives flat CLI arguments and help from a registered function's input schema. Use `--input '<json>'` for nested or otherwise complex inputs. It executes in the current working directory, writes the final JSON result to stdout, and writes progress and errors to stderr. `export` creates an executable POSIX launcher in `~/.local/bin` by default.
-`run` and `export` accept the trust overrides `--approve` and `--no-approve`; the generated launcher forwards its arguments to `run`. `--` ends launcher option parsing, and later tokens are passed to workflow input instead of being interpreted as launcher options. Headless `run` and generated `export` launchers cannot execute workflows containing checkpoints; use the Pi workflow tool/UI path for checkpointed workflows.
-Launch snapshots use identity version 5. Cold resume rejects older snapshots, including v4 snapshots created with the previous worktree or registered-function naming contracts, with `RESUME_INCOMPATIBLE`; relaunch the workflow instead.
-
-## Development
-
-```sh
-npm ci
-npm run check
-npm run acceptance
-npm pack --dry-run --json
-```
-
-Model-backed evaluations are optional. See the [evaluation guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html#evaluation).
 
 ## License
 

package/dist/src/agent-execution.d.ts

@@ -15,6 +15,7 @@ export interface AgentDefinition {
     model?: string;
     thinking?: ThinkingLevel;
     tools?: readonly string[];
+    overrideSystemPrompt?: boolean;
     disabledAgentResources?: AgentResourceExclusions;
 }
 export interface AgentProviderFailure {
@@ -56,6 +57,7 @@ export interface AgentExecutionRoot {
     tools: ReadonlySet<string>;
     agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
     agentDir?: string;
+    additionalSkillPaths?: readonly string[];
     availableModels?: ReadonlySet<string>;
     knownModels?: ReadonlySet<string>;
     modelAliases?: Readonly<Record<string, string>>;
@@ -88,6 +90,7 @@ export interface AgentProgress {
     accounting: AgentAccounting;
     toolCalls: readonly AgentToolCallProgress[];
     activity?: AgentActivity;
+    lastEventAt?: number;
     persist: boolean;
 }
 export interface AgentAttempt {
@@ -117,6 +120,7 @@ export declare class WorkflowAgentExecutor {
         model: ModelSpec;
         requestedModel?: string;
         tools: readonly string[];
+        systemPrompt?: string;
         systemPromptAppend: string;
     };
     execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools?: readonly ToolDefinition[], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult>;

package/dist/src/agent-execution.js

@@ -1,4 +1,5 @@
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
@@ -42,6 +43,37 @@ function terminalProviderError(error) {
     const candidate = value;
     return typeof candidate.provider === "string" && typeof candidate.model === "string" && typeof candidate.error === "string" ? { provider: candidate.provider, model: candidate.model, error: candidate.error } : undefined;
 }
+const providerContinuationPrompt = "The provider error was transient. Continue the task from your current state.";
+async function recoverTerminalProviderError(session, fallbackModel, label, recovery, continuePrompt) {
+    let continued = false;
+    for (;;) {
+        try {
+            throwIfTerminalAssistantError(session, fallbackModel);
+            return continued;
+        }
+        catch (error) {
+            const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+            const terminal = terminalProviderError(typed);
+            if (!terminal || !recovery)
+                throw error;
+            let action;
+            try {
+                action = await recovery({ label, ...terminal });
+            }
+            catch {
+                Object.assign(typed, { providerRecoveryHandled: true, providerRecoveryFailed: true });
+                throw typed;
+            }
+            if (action === "retry") {
+                continued = true;
+                await continuePrompt();
+                continue;
+            }
+            Object.assign(typed, { providerRecoveryHandled: true, providerRecovery: action });
+            throw typed;
+        }
+    }
+}
 function accounting(stats) {
     return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
@@ -51,8 +83,18 @@ function canonicalSourcePath(path) { try {
 catch {
     return resolve(path);
 } }
+const WORKFLOW_DIRECTORY = "pi-extensible-workflows";
+function workflowSystemPromptPath(cwd, agentDir, projectTrusted) {
+    const projectPath = join(cwd, ".pi", WORKFLOW_DIRECTORY, "SYSTEM.md");
+    if (projectTrusted && existsSync(projectPath))
+        return projectPath;
+    const globalPaths = [join(homedir(), ".pi", WORKFLOW_DIRECTORY, "SYSTEM.md"), join(agentDir, WORKFLOW_DIRECTORY, "SYSTEM.md")];
+    return globalPaths.find((path) => existsSync(path));
+}
 export async function createNativeAgentSession(input) {
     const agentDir = input.agentDir ?? getAgentDir();
+    const systemPromptSource = workflowSystemPromptPath(input.cwd, agentDir, input.resourcePolicy?.projectTrusted ?? true);
+    const systemPromptOptions = input.systemPrompt !== undefined ? { systemPromptOverride: () => input.systemPrompt } : systemPromptSource !== undefined ? { systemPrompt: systemPromptSource } : {};
     const manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
     manager.appendSessionInfo(input.sessionLabel);
     const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") });
@@ -87,18 +129,19 @@ export async function createNativeAgentSession(input) {
             noExtensions: true,
             additionalExtensionPaths: extensionPaths,
             noSkills: true,
-            additionalSkillPaths: skillPaths,
+            additionalSkillPaths: [...new Set([...skillPaths, ...(input.additionalSkillPaths ?? [])])],
             ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
             skillsOverride: (base) => {
                 const disabledSkills = updateSkillMatches(base.skills);
                 return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
             },
             ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
+            ...systemPromptOptions,
         });
         await resourceLoader.reload();
     }
-    else if (input.systemPromptAppend || input.extensionFactories?.length) {
-        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
+    else if (input.systemPrompt !== undefined || systemPromptSource !== undefined || input.systemPromptAppend || input.extensionFactories?.length || input.additionalSkillPaths?.length) {
+        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
         await resourceLoader.reload();
     }
     const { session } = await createAgentSession({ ...(input.options ?? {}), cwd: input.cwd, agentDir, modelRuntime, model, ...(settingsManager ? { settingsManager } : {}), ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(resourceLoader ? { resourceLoader } : {}), sessionManager: manager });
@@ -142,7 +185,7 @@ async function prepareAgentSetup(root, createSession, task, options, resolved, c
     const baseResourcePolicy = await root.agentResourcePolicy?.();
     const roleExclusions = options.role ? root.agentDefinitions?.[options.role]?.disabledAgentResources : undefined;
     const resourcePolicy = baseResourcePolicy && roleExclusions ? { ...baseResourcePolicy, effective: mergeAgentResourceExclusions(baseResourcePolicy.effective, roleExclusions) } : baseResourcePolicy;
-    const sessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), systemPromptAppend: resolved.systemPromptAppend, ...(resourcePolicy ? { resourcePolicy } : {}), options: structuredClone(baselineOptions) };
+    const sessionInput = { cwd, model: { ...resolved.model }, tools: [...resolved.tools], sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(root.agentDir ? { agentDir: root.agentDir } : {}), ...(root.additionalSkillPaths?.length ? { additionalSkillPaths: [...root.additionalSkillPaths] } : {}), ...(customTools.length ? { customTools: [...customTools] } : {}), ...(resultTool ? { resultTool } : {}), ...(resolved.systemPrompt !== undefined ? { systemPrompt: resolved.systemPrompt } : {}), systemPromptAppend: resolved.systemPromptAppend, ...(resourcePolicy ? { resourcePolicy } : {}), options: structuredClone(baselineOptions) };
     const setup = { prompt: task, options: sessionInput.options ?? {}, sessionInput, createSession };
     const base = fallbackSetupContext(root, options, setupSignal);
     const context = Object.freeze({ run: base.run, identity: base.identity, attempt, signal: setupSignal });
@@ -206,7 +249,8 @@ export class WorkflowAgentExecutor {
         const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
         if (!availableModels.has(modelCapability(model)))
             throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-        return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+        const overrideSystemPrompt = definition?.overrideSystemPrompt === true;
+        return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], ...(overrideSystemPrompt ? { systemPrompt: definition.prompt ?? "" } : {}), systemPromptAppend: overrideSystemPrompt ? "" : definition?.prompt ?? "" };
     }
     async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
         const executionSignal = signal ?? this.root.runContext?.signal;
@@ -272,6 +316,8 @@ export class WorkflowAgentExecutor {
             } : undefined;
             const toolCalls = new Map();
             let activity;
+            let lastEventAt;
+            let lastReportedEventAt;
             let progress = Promise.resolve();
             let unsubscribe;
             let systemPromptTurn = 0;
@@ -285,9 +331,17 @@ export class WorkflowAgentExecutor {
             const report = (persist) => {
                 if (!session || !options.onProgress)
                     return;
-                const update = { accounting: accounting(session.getSessionStats()), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), persist };
+                const update = { accounting: accounting(session.getSessionStats()), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), ...(lastEventAt === undefined ? {} : { lastEventAt }), persist };
+                if (lastEventAt !== undefined)
+                    lastReportedEventAt = lastEventAt;
                 progress = progress.then(() => options.onProgress?.(update)).then(() => undefined);
             };
+            const reportTimestamp = () => {
+                if (lastEventAt !== undefined && lastReportedEventAt !== undefined && lastEventAt - lastReportedEventAt < 1000)
+                    return;
+                report(false);
+            };
+            const activityChanged = (previous) => previous?.kind !== activity?.kind || previous?.text !== activity?.text;
             try {
                 setupFailed = true;
                 const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool);
@@ -303,7 +357,33 @@ export class WorkflowAgentExecutor {
                 const includeAttemptSetup = Boolean(this.root.agentSetupHooks?.length || setup.sessionInput.resourcePolicy);
                 await options.onAttempt?.({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), ...(includeAttemptSetup ? { setup: setupSummary } : {}) });
                 const activeSession = session;
+                const sessionModel = setup.sessionInput.model;
+                const recoverTerminal = () => recoverTerminalProviderError(activeSession, sessionModel, options.label, options.providerErrorRecovery, async () => { try {
+                    await promptWithProviderPause(activeSession, providerContinuationPrompt, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                }
+                catch (error) {
+                    if (!hasSchemaResult())
+                        throw error;
+                } });
+                const promptAndRecover = async (prompt) => {
+                    let promptFailed = false;
+                    let promptError;
+                    try {
+                        await promptWithProviderPause(activeSession, prompt, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                    }
+                    catch (error) {
+                        promptFailed = true;
+                        promptError = error;
+                    }
+                    const recovered = await recoverTerminal();
+                    if (promptFailed && !hasSchemaResult() && !recovered)
+                        throw promptError;
+                };
                 unsubscribe = activeSession.subscribe?.((event) => {
+                    lastEventAt = Date.now();
+                    let persist = false;
+                    let shouldReport = false;
+                    let removeToolCallId;
                     if (event.type === "agent_start" && session?.systemPrompt !== undefined) {
                         if (this.root.runStore) {
                             systemPromptTurn += 1;
@@ -323,10 +403,20 @@ export class WorkflowAgentExecutor {
                             }
                         }
                         activity = { kind: "text", text: "responding" };
-                        report(false);
+                        shouldReport = true;
+                    }
+                    if (event.type === "message_update") {
+                        const previousActivity = activity;
+                        if (["thinking_start", "thinking_delta", "thinking_end"].includes(event.assistantMessageEvent.type))
+                            activity = { kind: "reasoning", text: "reasoning" };
+                        else if (["text_start", "text_delta", "text_end", "toolcall_start", "toolcall_delta", "toolcall_end"].includes(event.assistantMessageEvent.type))
+                            activity = { kind: "text", text: "responding" };
+                        shouldReport = activityChanged(previousActivity);
                     }
                     if (event.type === "message_end") {
+                        const previousActivity = activity;
                         activity = undefined;
+                        shouldReport = activityChanged(previousActivity);
                         if (event.message.role === "assistant") {
                             const needsMoreWork = hasToolCall(event.message);
                             const final = !needsMoreWork || (options.schema !== undefined && hasSchemaResult());
@@ -345,21 +435,32 @@ export class WorkflowAgentExecutor {
                                 }
                             }
                             turnStarted = false;
-                            report(true);
+                            persist = true;
                         }
                     }
                     if (event.type === "tool_execution_start") {
                         toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" });
                         activity = { kind: "tool", text: event.toolName };
-                        report(false);
+                        shouldReport = true;
+                    }
+                    if (event.type === "tool_execution_update") {
+                        const previousActivity = activity;
+                        activity = { kind: "tool", text: event.toolName };
+                        shouldReport = activityChanged(previousActivity);
                     }
                     if (event.type === "tool_execution_end") {
                         toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" });
                         if (activity?.kind === "tool" && activity.text === event.toolName)
                             activity = undefined;
-                        report(false);
-                        toolCalls.delete(event.toolCallId);
+                        shouldReport = true;
+                        removeToolCallId = event.toolCallId;
                     }
+                    if (shouldReport || persist)
+                        report(persist);
+                    else
+                        reportTimestamp();
+                    if (removeToolCallId)
+                        toolCalls.delete(removeToolCallId);
                 });
                 report(false);
                 if (setSteer) {
@@ -372,14 +473,7 @@ export class WorkflowAgentExecutor {
                 const promptText = `${context}\n\nTask:\n${setup.prompt}${instruction ? `\n\n${instruction}` : ""}`;
                 options.budget?.beforeTurn();
                 turnStarted = true;
-                try {
-                    await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
-                }
-                catch (error) {
-                    if (!hasSchemaResult())
-                        throw error;
-                }
-                throwIfTerminalAssistantError(session, setup.sessionInput.model);
+                await promptAndRecover(promptText);
                 {
                     const completedAccounting = accounting(session.getSessionStats());
                     options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? hasSchemaResult() : !latestAssistantHasToolCall(session.messages));
@@ -389,38 +483,24 @@ export class WorkflowAgentExecutor {
                     throw budgetError;
                 if (options.schema) {
                     if (!hasSchemaResult()) {
-                        try {
-                            options.budget?.beforeTurn();
-                            turnStarted = true;
-                            await promptWithProviderPause(session, "Submit the final result now by calling workflow_result exactly once. Do not return prose.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
-                            {
-                                const completedAccounting = accounting(session.getSessionStats());
-                                options.budget?.afterTurn(completedAccounting, true);
-                                turnStarted = false;
-                            }
-                        }
-                        catch (error) {
-                            if (!hasSchemaResult())
-                                throw error;
+                        options.budget?.beforeTurn();
+                        turnStarted = true;
+                        await promptAndRecover("Submit the final result now by calling workflow_result exactly once. Do not return prose.");
+                        {
+                            const completedAccounting = accounting(session.getSessionStats());
+                            options.budget?.afterTurn(completedAccounting, true);
+                            turnStarted = false;
                         }
                     }
-                    throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     if (!hasSchemaResult()) {
-                        try {
-                            options.budget?.beforeTurn();
-                            turnStarted = true;
-                            await promptWithProviderPause(session, "Your result was missing or invalid. Repair it by calling workflow_result exactly once with a schema-valid value.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
-                            {
-                                const completedAccounting = accounting(session.getSessionStats());
-                                options.budget?.afterTurn(completedAccounting, true);
-                                turnStarted = false;
-                            }
-                        }
-                        catch (error) {
-                            if (!hasSchemaResult())
-                                throw error;
+                        options.budget?.beforeTurn();
+                        turnStarted = true;
+                        await promptAndRecover("Your result was missing or invalid. Repair it by calling workflow_result exactly once with a schema-valid value.");
+                        {
+                            const completedAccounting = accounting(session.getSessionStats());
+                            options.budget?.afterTurn(completedAccounting, true);
+                            turnStarted = false;
                         }
-                        throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     }
                     if (schemaResult === undefined)
                         throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
@@ -464,29 +544,35 @@ export class WorkflowAgentExecutor {
                 if (options.worktreeOwner && typed.code !== "WORKTREE_FAILED")
                     await this.root.runStore?.snapshotWorktree(options.worktreeOwner).catch(() => undefined);
                 const terminal = terminalProviderError(typed);
-                if (terminal && options.providerErrorRecovery) {
-                    let recovery;
+                const recoveryState = typed;
+                let recovery = recoveryState.providerRecovery;
+                if (terminal && options.providerErrorRecovery && !recoveryState.providerRecoveryHandled) {
                     try {
                         recovery = await options.providerErrorRecovery({ label: options.label, ...terminal });
                     }
                     catch {
                         throw Object.assign(typed, { attempts });
                     }
-                    if (recovery === "retry" || typeof recovery === "object" && typeof recovery.model === "string") {
-                        if (typeof recovery === "object") {
-                            try {
-                                const selected = resolveModelReference(recovery.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
-                                recoveryModel = selected.thinking === undefined && resolved.model.thinking ? { ...selected, thinking: resolved.model.thinking } : selected;
-                            }
-                            catch {
-                                throw Object.assign(typed, { attempts });
-                            }
-                        }
+                    if (recovery === "retry") {
                         maxAttempts += 1;
                         beforeRetry?.();
                         continue;
                     }
                 }
+                if (recoveryState.providerRecoveryFailed || recovery === "abort")
+                    throw Object.assign(typed, { attempts });
+                if (typeof recovery === "object" && typeof recovery.model === "string") {
+                    try {
+                        const selected = resolveModelReference(recovery.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
+                        recoveryModel = selected.thinking === undefined && resolved.model.thinking ? { ...selected, thinking: resolved.model.thinking } : selected;
+                    }
+                    catch {
+                        throw Object.assign(typed, { attempts });
+                    }
+                    maxAttempts += 1;
+                    beforeRetry?.();
+                    continue;
+                }
                 if (attempt === maxAttempts || setupFailed || typed.code === "CANCELLED" || typed.code === "WORKTREE_FAILED" || typed.code === "RESUME_INCOMPATIBLE")
                     throw Object.assign(typed, { attempts });
                 beforeRetry?.();

package/dist/src/bundles.d.ts

@@ -0,0 +1,53 @@
+import type { AgentDefinition, WorkflowCatalogFunction } from "./types.js";
+export interface PortableWorkflowManifest {
+    format: "pi-extensible-workflows-bundle";
+    version: 1;
+    command: string;
+    workflow: {
+        name: string;
+        description: string;
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+    };
+    runtime: {
+        pi: string;
+        "pi-extensible-workflows": string;
+    };
+    requirements: {
+        roles: readonly string[];
+        aliases: readonly string[];
+        tools: readonly string[];
+        commands: readonly string[];
+        environment: readonly string[];
+    };
+    aliasTargets?: Readonly<Record<string, string>>;
+    payload?: {
+        extensions?: readonly string[];
+        skills?: readonly string[];
+        static?: readonly string[];
+        dependencies?: readonly string[];
+    };
+}
+export interface PortableWorkflowBundleResources {
+    extensions?: readonly string[];
+    skills?: readonly string[];
+    static?: readonly string[];
+    dependencies?: readonly string[];
+}
+export interface PortableWorkflowBundleInput {
+    destination: string;
+    command: string;
+    workflow: WorkflowCatalogFunction;
+    functionSource: string;
+    piVersion?: string;
+    engineVersion?: string;
+    force?: boolean;
+    requirements?: Partial<PortableWorkflowManifest["requirements"]>;
+    aliasTargets?: Readonly<Record<string, string>>;
+    roles?: Readonly<Record<string, AgentDefinition>>;
+    resources?: PortableWorkflowBundleResources;
+}
+export declare function portableEngineVersion(): string;
+export declare function portablePiVersion(): string;
+export declare function normalizePortableFunctionSource(functionSource: string): string;
+export declare function writePortableWorkflowBundle(input: PortableWorkflowBundleInput): PortableWorkflowManifest;