pi-extensible-workflows 1.0.1 → 3.0.0

package/README.md

@@ -20,7 +20,9 @@ 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, or register complete workflows that can be invoked by name.
+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.
 
@@ -61,9 +63,14 @@ Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.j
 ```sh
 npx pi-extensible-workflows doctor
 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. `inspect` opens a read-only terminal view of persisted workflow runs.
+`doctor` validates the installation and active Pi resources. `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.
+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
 

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

@@ -15,7 +15,7 @@ type AgentMessage = {
         };
     };
 };
-import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./index.js";
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./types.js";
 import type { RunStore } from "./persistence.js";
 export interface AgentBudgetHooks {
     beforeAttempt(): void;
@@ -31,6 +31,15 @@ export interface AgentDefinition {
     tools?: readonly string[];
     disabledAgentResources?: AgentResourceExclusions;
 }
+export interface AgentProviderFailure {
+    label: string;
+    provider: string;
+    model: string;
+    error: string;
+}
+export type AgentProviderRecovery = "retry" | "abort" | {
+    model: string;
+};
 export interface AgentExecutionOptions {
     label: string;
     workflowName: string;
@@ -40,6 +49,8 @@ export interface AgentExecutionOptions {
     thinking?: ThinkingLevel;
     onProgress?: (progress: AgentProgress) => void | Promise<void>;
     onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => void | Promise<void>;
+    providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>;
+    modelOverride?: ModelSpec;
     tools?: readonly string[];
     effectiveTools?: readonly string[];
     role?: string;
@@ -52,10 +63,6 @@ export interface AgentExecutionOptions {
     budget?: AgentBudgetHooks;
     agentOptions?: Readonly<Record<string, JsonValue>>;
     agentIdentity?: AgentIdentity;
-    conversation?: {
-        id: string;
-        turn: number;
-    };
 }
 export interface AgentExecutionRoot {
     cwd: string;
@@ -174,11 +181,6 @@ export interface SessionInput {
     extensionFactories?: InlineExtension[];
     resourcePolicy?: AgentResourcePolicy;
     options?: Record<string, JsonValue>;
-    continuation?: {
-        sessionId: string;
-        sessionFile: string;
-        leafId: string;
-    };
 }
 export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
@@ -210,10 +212,6 @@ export interface ScheduledAgentOptions {
     timeoutMs?: number | null;
     agentOptions?: Readonly<Record<string, JsonValue>>;
     agentIdentity?: AgentIdentity;
-    conversation?: {
-        id: string;
-        turn: number;
-    };
 }
 export type ScheduledAgentResult = {
     id: string;
@@ -278,6 +276,7 @@ export declare class FairAgentScheduler {
     retry(id: string): void;
     attemptStarted(id: string): void;
     cancelRun(runId: string): Promise<void>;
+    removeRun(runId: string): void;
     toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], thinking: ThinkingLevel | undefined) => readonly string[]): ToolDefinition[];
     snapshot(): readonly OwnershipRecord[];
     restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void): void;

package/dist/src/agent-execution.js

@@ -1,17 +1,16 @@
-import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
 import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
-import { mergeAgentResourceExclusions, resolveModelReference, WorkflowError } from "./index.js";
+import { jsonObject, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference } from "./utils.js";
+import { WorkflowError } from "./types.js";
 function parseModel(value, fallback, thinking, aliases = {}, knownModels, settingsPath) {
     if (!value)
         return { ...fallback, ...(thinking ? { thinking } : {}) };
     const parsed = resolveModelReference(value, aliases, knownModels, settingsPath);
     return { ...parsed, ...(thinking ? { thinking } : !parsed.thinking && fallback.thinking ? { thinking: fallback.thinking } : {}) };
 }
-function modelCapability(model) { return `${model.provider}/${model.model}`; }
 function text(messages) {
     const message = [...messages].reverse().find((item) => item.role === "assistant");
     if (!message || !Array.isArray(message.content))
@@ -25,10 +24,23 @@ function latestAssistantHasToolCall(messages) {
     const message = [...messages].reverse().find((item) => item.role === "assistant");
     return hasToolCall(message);
 }
-function throwIfTerminalAssistantError(session) {
+function throwIfTerminalAssistantError(session, fallbackModel) {
     const message = [...session.messages].reverse().find((item) => item.role === "assistant");
-    if (message?.stopReason === "error")
-        throw new WorkflowError("AGENT_FAILED", message.errorMessage ?? "Native Pi assistant ended with a terminal provider error");
+    if (message?.stopReason !== "error")
+        return;
+    const provider = session.model?.provider ?? fallbackModel.provider;
+    const model = session.model?.model ?? session.model?.id ?? fallbackModel.model;
+    const error = message.errorMessage ?? "Native Pi assistant ended with a terminal provider error";
+    const failure = new WorkflowError("AGENT_FAILED", error);
+    Object.defineProperty(failure, "terminalProviderError", { value: { provider, model, error }, configurable: true });
+    throw failure;
+}
+function terminalProviderError(error) {
+    const value = error.terminalProviderError;
+    if (!value || typeof value !== "object")
+        return undefined;
+    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;
 }
 function accounting(stats) {
     return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
@@ -41,30 +53,8 @@ catch {
 } }
 export async function createNativeAgentSession(input) {
     const agentDir = input.agentDir ?? getAgentDir();
-    let manager;
-    if (input.continuation) {
-        try {
-            manager = SessionManager.open(input.continuation.sessionFile, input.agentDir ? join(agentDir, "sessions") : undefined, input.cwd);
-            const header = manager.getHeader();
-            if (!header || canonicalSourcePath(header.cwd) !== canonicalSourcePath(input.cwd) || manager.getSessionId() !== input.continuation.sessionId || !manager.getEntry(input.continuation.leafId))
-                throw new Error("Persisted transcript identity does not match the conversation head");
-            manager.branch(input.continuation.leafId);
-            const context = manager.buildSessionContext();
-            if (context.model && (context.model.provider !== input.model.provider || context.model.modelId !== input.model.model))
-                throw new Error("Persisted transcript model does not match the conversation execution policy");
-            if (input.model.thinking && context.thinkingLevel !== input.model.thinking)
-                throw new Error("Persisted transcript thinking level does not match the conversation execution policy");
-        }
-        catch (error) {
-            if (error instanceof WorkflowError && error.code === "RESUME_INCOMPATIBLE")
-                throw error;
-            throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot reopen conversation transcript: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    else {
-        manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
-        manager.appendSessionInfo(input.sessionLabel);
-    }
+    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") });
     const model = modelRuntime.getModel(input.model.provider, input.model.model);
     if (!model)
@@ -110,9 +100,7 @@ export async function createNativeAgentSession(input) {
         resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
         await resourceLoader.reload();
     }
-    const { session, modelFallbackMessage } = 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 });
-    if (input.continuation && modelFallbackMessage)
-        throw new WorkflowError("RESUME_INCOMPATIBLE", modelFallbackMessage);
+    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 });
     return Object.assign(session, {
         getLeafId: () => manager.getLeafId(),
         getToolDefinitions: () => session.getAllTools().map(({ name, description, parameters, promptGuidelines }) => ({ name, description, parameters, ...(promptGuidelines ? { promptGuidelines } : {}) })),
@@ -120,24 +108,6 @@ export async function createNativeAgentSession(input) {
 }
 function changedOption(options, baseline, key) { return JSON.stringify(options[key]) !== JSON.stringify(baseline[key]); }
 function validThinking(value) { return typeof value === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value); }
-function jsonValue(value, seen = new Set()) {
-    if (value === null || typeof value === "boolean" || typeof value === "string")
-        return true;
-    if (typeof value === "number")
-        return Number.isFinite(value);
-    if (typeof value !== "object" || seen.has(value))
-        return false;
-    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
-        return false;
-    const keys = Reflect.ownKeys(value);
-    if (keys.some((key) => typeof key !== "string"))
-        return false;
-    seen.add(value);
-    const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => value[key])).every((item) => jsonValue(item, seen));
-    seen.delete(value);
-    return valid;
-}
-function jsonObject(value) { return jsonValue(value) && typeof value === "object" && value !== null && !Array.isArray(value); }
 function isChildAgentToolParams(value) {
     if (!jsonObject(value) || typeof value.prompt !== "string" || typeof value.label !== "string")
         return false;
@@ -165,36 +135,7 @@ function fallbackSetupContext(root, options, signal) {
 function resourcePolicySummary(policy) {
     return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
 }
-function canonicalJson(value) {
-    if (Array.isArray(value))
-        return value.map((item) => canonicalJson(item));
-    if (value && typeof value === "object")
-        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonicalJson(item)]));
-    return value;
-}
-function fingerprint(value) { return createHash("sha256").update(JSON.stringify(canonicalJson(value))).digest("hex"); }
-function promptFingerprint(value) { return createHash("sha256").update(value).digest("hex"); }
-function fixedConversationOptions(options) {
-    const fixedOptions = structuredClone(options);
-    delete fixedOptions.timeoutMs;
-    delete fixedOptions.retries;
-    return fixedOptions;
-}
-function conversationExecutionPolicy(options, setup) {
-    return structuredClone({
-        model: setup.sessionInput.model,
-        tools: [...setup.sessionInput.tools],
-        cwd: setup.sessionInput.cwd,
-        role: options.role ?? null,
-        worktreeOwner: options.worktreeOwner ?? null,
-        parent: options.parent ?? null,
-        systemPromptAppend: setup.sessionInput.systemPromptAppend ?? "",
-        options: fixedConversationOptions(setup.options),
-        resourcePolicy: setup.sessionInput.resourcePolicy ? resourcePolicySummary(setup.sessionInput.resourcePolicy) : null,
-    });
-}
-function conversationFailure(message) { return new WorkflowError("RESUME_INCOMPATIBLE", message); }
-async function prepareAgentSetup(root, createSession, task, options, resolved, cwd, attempt, signal, customTools, resultTool, continuation) {
+async function prepareAgentSetup(root, createSession, task, options, resolved, cwd, attempt, signal, customTools, resultTool) {
     const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
     const baselineOptions = structuredClone(options.agentOptions ?? {});
     const baseResourcePolicy = await root.agentResourcePolicy?.();
@@ -229,8 +170,6 @@ async function prepareAgentSetup(root, createSession, task, options, resolved, c
         setup.sessionInput.tools = [...setup.options.tools];
     if (changedOption(setup.options, baselineOptions, "cwd") && typeof setup.options.cwd === "string")
         setup.sessionInput.cwd = setup.options.cwd;
-    if (continuation)
-        setup.sessionInput.continuation = { sessionId: continuation.sessionId, sessionFile: continuation.sessionFile, leafId: continuation.leafId };
     const model = setup.sessionInput.model;
     const summary = { hookNames: [...hookNames], model: { provider: model.provider, model: model.model, ...(model.thinking ? { thinking: model.thinking } : {}) }, tools: [...setup.sessionInput.tools], cwd: setup.sessionInput.cwd, ...(setup.sessionInput.resourcePolicy ? { disabledAgentResources: resourcePolicySummary(setup.sessionInput.resourcePolicy) } : {}) };
     return { setup, summary };
@@ -255,17 +194,18 @@ export class WorkflowAgentExecutor {
         if (forbidden)
             throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${forbidden}`);
         const requestedModel = options.model ?? definition?.model;
-        const hasAlias = requestedModel !== undefined && Object.prototype.hasOwnProperty.call(this.root.modelAliases ?? {}, requestedModel);
-        if (requestedModel !== undefined && this.root.blockedAliases?.has(requestedModel) && !hasAlias) {
-            const target = this.root.blockedAliasTargets?.[requestedModel];
+        const alias = requestedModel === undefined ? undefined : modelAliasName(requestedModel, this.root.modelAliases ?? {});
+        const blockedAlias = requestedModel?.split(":", 1)[0];
+        if (requestedModel !== undefined && blockedAlias && this.root.blockedAliases?.has(blockedAlias) && !alias) {
+            const target = this.root.blockedAliasTargets?.[blockedAlias];
             throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
         }
-        const aliasThinking = requestedModel !== undefined && hasAlias ? resolveModelReference(requestedModel, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath).thinking : undefined;
-        const model = parseModel(requestedModel, this.root.model, options.thinking ?? (aliasThinking === undefined ? definition?.thinking : undefined), this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
+        const aliasThinking = requestedModel !== undefined && alias ? resolveModelReference(requestedModel, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath).thinking : undefined;
+        const model = options.modelOverride ?? parseModel(requestedModel, this.root.model, options.thinking ?? (aliasThinking === undefined ? definition?.thinking : undefined), this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
         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, ...(hasAlias ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+        return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
     }
     async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
         const executionSignal = signal ?? this.root.runContext?.signal;
@@ -273,7 +213,8 @@ export class WorkflowAgentExecutor {
             throw new WorkflowError("INVALID_METADATA", "retries must be a non-negative integer");
         if (options.timeoutMs !== undefined && options.timeoutMs !== null && (!Number.isInteger(options.timeoutMs) || options.timeoutMs <= 0))
             throw new WorkflowError("INVALID_METADATA", "timeoutMs must be null or a positive integer");
-        const resolved = this.resolve(options);
+        let resolved = this.resolve(options);
+        let recoveryModel;
         let cwd;
         if (options.parent) {
             if (!options.cwd)
@@ -302,28 +243,12 @@ export class WorkflowAgentExecutor {
                 throw new WorkflowError("INVALID_METADATA", "Only child agents or worktree scopes may provide a cwd");
             cwd = this.root.cwd;
         }
-        let conversationRecord;
-        if (options.conversation) {
-            const store = this.root.runStore;
-            if (!store)
-                throw conversationFailure("Conversation persistence is unavailable");
-            try {
-                conversationRecord = await store.conversation(options.conversation.id);
-            }
-            catch (error) {
-                throw conversationFailure(`Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`);
-            }
-            if (!Number.isInteger(options.conversation.turn) || options.conversation.turn < 1)
-                throw conversationFailure("Conversation turn must be a positive integer");
-            if (conversationRecord ? conversationRecord.head.turn + 1 !== options.conversation.turn : options.conversation.turn !== 1)
-                throw conversationFailure(`Conversation turn ${String(options.conversation.turn)} does not continue its persisted head`);
-        }
         const attempts = [];
-        let conversationBaseline;
-        const maxAttempts = (options.retries ?? 0) + 1;
+        let maxAttempts = (options.retries ?? 0) + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            if (recoveryModel)
+                resolved = this.resolve({ ...options, modelOverride: recoveryModel });
             options.budget?.beforeAttempt();
-            let accepted = false;
             let schemaResult;
             let session;
             let setup;
@@ -331,18 +256,14 @@ export class WorkflowAgentExecutor {
             let setupFailed = false;
             let budgetError;
             let turnStarted = false;
-            let conversationSystemPrompt = "";
-            let conversationToolDefinitionsSha256 = "";
-            let conversationMismatch;
-            const conversationMismatchError = () => conversationMismatch ? new WorkflowError("RESUME_INCOMPATIBLE", conversationMismatch.message) : undefined;
             const hasSchemaResult = () => schemaResult !== undefined;
             const resultTool = options.schema ? {
                 name: "workflow_result", label: "Workflow Result", description: "Submit the terminal structured workflow result", parameters: Type.Unsafe(options.schema),
                 async execute(_id, value) {
-                    if (!accepted)
-                        return { content: [{ type: "text", text: "Result acceptance is not enabled yet." }], details: {}, isError: true };
                     if (!Value.Check(options.schema, value))
                         return { content: [{ type: "text", text: "Result does not match the required schema." }], details: {}, isError: true };
+                    if (schemaResult !== undefined)
+                        return { content: [{ type: "text", text: "Result has already been accepted." }], details: {}, isError: true };
                     schemaResult = structuredClone(value);
                     void session?.abort?.();
                     return { content: [{ type: "text", text: "Result accepted." }], details: {} };
@@ -368,7 +289,7 @@ export class WorkflowAgentExecutor {
             };
             try {
                 setupFailed = true;
-                const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool, conversationRecord?.head);
+                const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool);
                 setup = prepared.setup;
                 setupSummary = prepared.summary;
                 setupFailed = false;
@@ -378,58 +299,11 @@ export class WorkflowAgentExecutor {
                 session = await setup.createSession(setup.sessionInput);
                 if (setup.sessionInput.resourcePolicy)
                     setupSummary = { ...setupSummary, disabledAgentResources: resourcePolicySummary(setup.sessionInput.resourcePolicy) };
-                if (options.conversation) {
-                    conversationSystemPrompt = session.systemPrompt ?? "";
-                    conversationToolDefinitionsSha256 = fingerprint(session.getToolDefinitions?.() ?? session.agent?.state.tools ?? []);
-                    const currentExecutionPolicy = conversationExecutionPolicy(options, setup);
-                    if (conversationRecord) {
-                        if (session.sessionId !== conversationRecord.head.sessionId || requiredFile(session.sessionFile) !== conversationRecord.head.sessionFile)
-                            throw conversationFailure("Conversation transcript identity changed");
-                        if (!session.getLeafId || session.getLeafId() !== conversationRecord.head.leafId)
-                            throw conversationFailure("Conversation transcript leaf identity changed");
-                        if (fingerprint(currentExecutionPolicy) !== fingerprint(conversationRecord.policy))
-                            throw conversationFailure("Conversation execution policy changed");
-                        if (!session.subscribe && (promptFingerprint(conversationSystemPrompt) !== conversationRecord.head.systemPromptSha256 || conversationSystemPrompt !== conversationRecord.head.systemPrompt))
-                            throw conversationFailure("Conversation system prompt changed");
-                        if (conversationToolDefinitionsSha256 !== conversationRecord.head.toolDefinitionsSha256)
-                            throw conversationFailure("Conversation tool definitions changed");
-                    }
-                    else if (conversationBaseline) {
-                        if (fingerprint(currentExecutionPolicy) !== fingerprint(conversationBaseline.executionPolicy))
-                            throw conversationFailure("Conversation execution policy changed");
-                        if (conversationToolDefinitionsSha256 !== conversationBaseline.toolDefinitionsSha256)
-                            throw conversationFailure("Conversation tool definitions changed");
-                    }
-                    else {
-                        conversationBaseline = { executionPolicy: currentExecutionPolicy, toolDefinitionsSha256: conversationToolDefinitionsSha256 };
-                    }
-                    if (!session.subscribe) {
-                        const expectedPrompt = conversationRecord?.head.systemPrompt ?? conversationBaseline?.systemPrompt;
-                        const expectedDigest = conversationRecord?.head.systemPromptSha256 ?? conversationBaseline?.systemPromptSha256;
-                        if (expectedPrompt !== undefined && expectedDigest !== undefined && (promptFingerprint(conversationSystemPrompt) !== expectedDigest || expectedPrompt !== conversationSystemPrompt))
-                            throw conversationFailure("Conversation system prompt changed");
-                        if (!conversationRecord && conversationBaseline && conversationBaseline.systemPrompt === undefined)
-                            conversationBaseline = { ...conversationBaseline, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt) };
-                    }
-                    if (conversationRecord && (!session.model || session.model.provider !== setup.sessionInput.model.provider || (session.model.model ?? session.model.id) !== setup.sessionInput.model.model))
-                        throw conversationFailure("Conversation model changed");
-                }
                 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;
                 unsubscribe = activeSession.subscribe?.((event) => {
                     if (event.type === "agent_start" && session?.systemPrompt !== undefined) {
-                        if (options.conversation) {
-                            conversationSystemPrompt = session.systemPrompt;
-                            const expectedPrompt = conversationRecord?.head.systemPrompt ?? conversationBaseline?.systemPrompt;
-                            const expectedDigest = conversationRecord?.head.systemPromptSha256 ?? conversationBaseline?.systemPromptSha256;
-                            if (expectedPrompt !== undefined && expectedDigest !== undefined && (promptFingerprint(conversationSystemPrompt) !== expectedDigest || expectedPrompt !== conversationSystemPrompt)) {
-                                conversationMismatch = conversationFailure("Conversation system prompt changed");
-                                void session.abort?.();
-                            }
-                            if (!conversationRecord && conversationBaseline && conversationBaseline.systemPrompt === undefined)
-                                conversationBaseline = { ...conversationBaseline, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt) };
-                        }
                         if (this.root.runStore) {
                             systemPromptTurn += 1;
                             const entry = { sessionId: session.sessionId, attempt, turn: systemPromptTurn, prompt: session.systemPrompt };
@@ -454,7 +328,7 @@ export class WorkflowAgentExecutor {
                         activity = undefined;
                         if (event.message.role === "assistant") {
                             const needsMoreWork = hasToolCall(event.message);
-                            const final = !needsMoreWork || (options.schema !== undefined && accepted);
+                            const final = !needsMoreWork || (options.schema !== undefined && hasSchemaResult());
                             if (!budgetError) {
                                 try {
                                     options.budget?.afterTurn(accounting(activeSession.getSessionStats()), final);
@@ -483,6 +357,7 @@ export class WorkflowAgentExecutor {
                         if (activity?.kind === "tool" && activity.text === event.toolName)
                             activity = undefined;
                         report(false);
+                        toolCalls.delete(event.toolCallId);
                     }
                 });
                 report(false);
@@ -496,34 +371,39 @@ export class WorkflowAgentExecutor {
                 const promptText = `${context}\n\nTask:\n${setup.prompt}${instruction ? `\n\n${instruction}` : ""}`;
                 options.budget?.beforeTurn();
                 turnStarted = true;
-                await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
-                if (conversationMismatch)
-                    throw conversationMismatch;
-                throwIfTerminalAssistantError(session);
+                try {
+                    await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                }
+                catch (error) {
+                    if (!hasSchemaResult())
+                        throw error;
+                }
+                throwIfTerminalAssistantError(session, setup.sessionInput.model);
                 {
                     const completedAccounting = accounting(session.getSessionStats());
-                    options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? false : !latestAssistantHasToolCall(session.messages));
+                    options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? hasSchemaResult() : !latestAssistantHasToolCall(session.messages));
                     turnStarted = false;
                 }
                 if (budgetError)
                     throw budgetError;
                 if (options.schema) {
-                    accepted = true;
-                    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;
+                    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;
                         }
                     }
-                    catch (error) {
-                        if (!hasSchemaResult())
-                            throw error;
-                    }
-                    throwIfTerminalAssistantError(session);
+                    throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     if (!hasSchemaResult()) {
                         try {
                             options.budget?.beforeTurn();
@@ -539,14 +419,11 @@ export class WorkflowAgentExecutor {
                             if (!hasSchemaResult())
                                 throw error;
                         }
-                        throwIfTerminalAssistantError(session);
+                        throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     }
                     if (schemaResult === undefined)
                         throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
                 }
-                const mismatch = conversationMismatchError();
-                if (mismatch)
-                    throw mismatch;
                 const value = options.schema ? schemaResult : text(session.messages);
                 if (options.worktreeOwner)
                     await this.root.runStore?.snapshotWorktree(options.worktreeOwner);
@@ -555,22 +432,13 @@ export class WorkflowAgentExecutor {
                 await flushSystemPrompts();
                 unsubscribe?.();
                 const attemptAccounting = accounting(session.getSessionStats());
-                const leafId = session.getLeafId?.() ?? undefined;
-                if (options.conversation) {
-                    if (!leafId)
-                        throw conversationFailure("Conversation transcript has no persisted leaf");
-                    const store = this.root.runStore;
-                    if (!store)
-                        throw conversationFailure("Conversation persistence is unavailable");
-                    await store.saveConversation({ id: options.conversation.id, policy: conversationExecutionPolicy(options, setup), head: { turn: options.conversation.turn, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), leafId, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt), toolDefinitionsSha256: conversationToolDefinitionsSha256 } });
-                }
                 const includeCompletedSetup = Boolean(this.root.agentSetupHooks?.length || setup.sessionInput.resourcePolicy);
                 attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), result: value, accounting: attemptAccounting, ...(includeCompletedSetup ? { setup: setupSummary } : {}) });
                 session.dispose();
                 return { value, attempts, cwd: setupSummary.cwd };
             }
             catch (error) {
-                const typed = budgetError ?? conversationMismatch ?? (error instanceof WorkflowError ? error : new WorkflowError(executionSignal?.aborted && setupFailed ? "CANCELLED" : "AGENT_FAILED", error instanceof Error ? error.message : String(error)));
+                const typed = budgetError ?? (error instanceof WorkflowError ? error : new WorkflowError(executionSignal?.aborted && setupFailed ? "CANCELLED" : "AGENT_FAILED", error instanceof Error ? error.message : String(error)));
                 if (session) {
                     report(true);
                     await progress;
@@ -594,6 +462,30 @@ 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;
+                    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 });
+                            }
+                        }
+                        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?.();
@@ -723,6 +615,26 @@ export class FairAgentScheduler {
         if (nodes.every(({ restored }) => restored))
             run.logical = 0;
     }
+    removeRun(runId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            return;
+        const nodes = [...this.#nodes.values()].filter((node) => node.runId === runId);
+        if (run.active > 0 || nodes.some(({ state }) => !["completed", "failed", "cancelled"].includes(state)))
+            throw new WorkflowError("INTERNAL_ERROR", `Cannot remove active scheduler run: ${runId}`);
+        for (const { id } of nodes)
+            this.#nodes.delete(id);
+        this.#runs.delete(runId);
+        const index = this.#runOrder.indexOf(runId);
+        if (index >= 0) {
+            this.#runOrder.splice(index, 1);
+            if (index < this.#cursor)
+                this.#cursor -= 1;
+            if (this.#cursor >= this.#runOrder.length)
+                this.#cursor = 0;
+        }
+        this.#dispatch();
+    }
     toolsFor(parentId, resolveTools) {
         const parent = this.#node(parentId);
         if (!parent.options.tools.includes("agent"))
@@ -842,6 +754,7 @@ export class FairAgentScheduler {
             return;
         const heldPermit = node.state === "running" || node.state === "retrying";
         node.state = result.ok ? "completed" : result.error.code === "CANCELLED" ? "cancelled" : "failed";
+        Reflect.deleteProperty(node, "steer");
         this.#persist(node.runId);
         if (heldPermit)
             this.#release(node.runId);

package/dist/src/budget.d.ts

@@ -0,0 +1,38 @@
+import { type BudgetDimension, type BudgetEvent, type WorkflowBudget, type WorkflowBudgetPatch, type WorkflowBudgetUsage, type AgentAccounting, type RunState } from "./types.js";
+export declare function validateBudget(value: unknown): WorkflowBudget | undefined;
+export declare function validateBudgetPatch(value: unknown): WorkflowBudgetPatch;
+export declare function budgetUsage(value?: Partial<WorkflowBudgetUsage>): WorkflowBudgetUsage;
+export declare class WorkflowBudgetRuntime {
+    #private;
+    readonly budget: WorkflowBudget | undefined;
+    readonly version: number;
+    constructor(budget: WorkflowBudget | undefined, version?: number, usage?: Partial<WorkflowBudgetUsage>, events?: readonly BudgetEvent[], options?: {
+        now?: () => number;
+        onChange?: () => void;
+        active?: boolean;
+    });
+    get usage(): WorkflowBudgetUsage;
+    get events(): readonly BudgetEvent[];
+    get hardExhausted(): boolean;
+    checkAgentLaunch(): void;
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(agentId?: string): string | undefined;
+    forAgent(agentId: string): {
+        beforeAttempt: () => void;
+        beforeTurn: () => void;
+        afterTurn: (accounting: AgentAccounting, final: boolean) => void;
+        instruction: () => string | undefined;
+    };
+    transition(state: RunState): void;
+    recordEvent(event: BudgetEvent): void;
+    snapshot(): {
+        usage: WorkflowBudgetUsage;
+        budgetEvents: readonly BudgetEvent[];
+    };
+}
+export declare function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined;
+export declare function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean;
+export declare function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[];
+export declare function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean;