pi-extensible-workflows 2.0.0 → 3.0.0

package/README.md

@@ -22,6 +22,8 @@ For source installs and local development, see the [installation guide](https://
 
 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.
 
 ```js
@@ -68,7 +70,7 @@ npx pi-extensible-workflows export <workflow-name> [--name <command>] [--output
 
 `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 4. A cold resume intentionally rejects persisted v3 runs with `RESUME_INCOMPATIBLE`; relaunch the workflow instead.
+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;
@@ -63,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;
@@ -185,12 +181,6 @@ export interface SessionInput {
     extensionFactories?: InlineExtension[];
     resourcePolicy?: AgentResourcePolicy;
     options?: Record<string, JsonValue>;
-    continuation?: {
-        sessionId: string;
-        sessionFile: string;
-        leafId: string;
-    };
-    allowModelChange?: boolean;
 }
 export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
@@ -222,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;

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))
@@ -54,33 +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)) {
-                if (!input.allowModelChange)
-                    throw new Error("Persisted transcript model does not match the conversation execution policy");
-                manager.appendModelChange(input.model.provider, input.model.model);
-            }
-            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)
@@ -126,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 } : {}) })),
@@ -136,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;
@@ -181,56 +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 conversationPolicyMatches(expected, current, allowModelChange) {
-    if (fingerprint(expected) === fingerprint(current))
-        return true;
-    if (!allowModelChange || !expected || typeof expected !== "object" || Array.isArray(expected) || !current || typeof current !== "object" || Array.isArray(current))
-        return false;
-    const expectedModel = conversationPolicyModel(expected);
-    const currentModel = conversationPolicyModel(current);
-    if (!expectedModel || !currentModel)
-        return false;
-    return fingerprint(expected) === fingerprint({ ...current, model: { ...currentModel, provider: expectedModel.provider, model: expectedModel.model } });
-}
-function conversationPolicyModel(policy) {
-    if (!policy || typeof policy !== "object" || Array.isArray(policy))
-        return undefined;
-    const model = policy.model;
-    if (!model || typeof model !== "object" || Array.isArray(model) || typeof model.provider !== "string" || typeof model.model !== "string")
-        return undefined;
-    const thinking = typeof model.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(model.thinking) ? model.thinking : undefined;
-    return thinking === undefined ? { provider: model.provider, model: model.model } : { provider: model.provider, model: model.model, thinking };
-}
-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?.();
@@ -265,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 };
@@ -291,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 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;
@@ -339,29 +243,7 @@ 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 (conversationRecord) {
-                const model = conversationPolicyModel(conversationRecord.policy);
-                if (model)
-                    resolved = this.resolve({ ...options, modelOverride: model });
-            }
-            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;
         let maxAttempts = (options.retries ?? 0) + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
             if (recoveryModel)
@@ -374,10 +256,6 @@ 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),
@@ -411,70 +289,21 @@ 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;
                 if (executionSignal?.aborted)
                     throw new WorkflowError("CANCELLED", "Agent cancelled");
-                if (recoveryModel && conversationRecord)
-                    setup.sessionInput.allowModelChange = true;
                 const started = Date.now();
                 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 || (!recoveryModel && session.getLeafId() !== conversationRecord.head.leafId))
-                            throw conversationFailure("Conversation transcript leaf identity changed");
-                        if (!conversationPolicyMatches(conversationRecord.policy, currentExecutionPolicy, Boolean(recoveryModel)))
-                            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 (!conversationPolicyMatches(conversationBaseline.executionPolicy, currentExecutionPolicy, Boolean(recoveryModel)))
-                            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 };
@@ -528,6 +357,7 @@ export class WorkflowAgentExecutor {
                         if (activity?.kind === "tool" && activity.text === event.toolName)
                             activity = undefined;
                         report(false);
+                        toolCalls.delete(event.toolCallId);
                     }
                 });
                 report(false);
@@ -548,8 +378,6 @@ export class WorkflowAgentExecutor {
                     if (!hasSchemaResult())
                         throw error;
                 }
-                if (conversationMismatch)
-                    throw conversationMismatch;
                 throwIfTerminalAssistantError(session, setup.sessionInput.model);
                 {
                     const completedAccounting = accounting(session.getSessionStats());
@@ -596,9 +424,6 @@ export class WorkflowAgentExecutor {
                     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);
@@ -607,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;

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;

package/dist/src/budget.js

@@ -0,0 +1,160 @@
+import { WorkflowError } from "./types.js";
+import { fail, object } from "./utils.js";
+function nonNegativeInteger(value) { return Number.isInteger(value) && value >= 0; }
+function nonNegativeFinite(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+export function validateBudget(value) {
+    if (value === undefined)
+        return undefined;
+    if (!object(value))
+        fail("INVALID_METADATA", "budget must be an object");
+    const result = {};
+    for (const [dimension, raw] of Object.entries(value)) {
+        if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension))
+            fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+        if (!object(raw))
+            fail("INVALID_METADATA", `${dimension} budget must be an object`);
+        if (Object.keys(raw).some((key) => key !== "soft" && key !== "hard"))
+            fail("INVALID_METADATA", `${dimension} budget has an unknown limit`);
+        const isCost = dimension === "costUsd";
+        for (const key of ["soft", "hard"])
+            if (raw[key] !== undefined && !(isCost ? nonNegativeFinite(raw[key]) : nonNegativeInteger(raw[key])))
+                fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${isCost ? "finite number" : "integer"}`);
+        if (raw.soft !== undefined && raw.soft !== null && raw.hard !== undefined && raw.hard !== null && raw.soft >= raw.hard)
+            fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+        const limits = {};
+        if (raw.soft !== undefined)
+            limits.soft = raw.soft;
+        if (raw.hard !== undefined)
+            limits.hard = raw.hard;
+        if (Object.keys(limits).length)
+            result[dimension] = limits;
+    }
+    return Object.freeze(result);
+}
+export function validateBudgetPatch(value) {
+    if (!object(value))
+        fail("INVALID_METADATA", "budget patch must be an object");
+    const result = {};
+    for (const [dimension, raw] of Object.entries(value)) {
+        if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension))
+            fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+        if (raw === null) {
+            result[dimension] = null;
+            continue;
+        }
+        if (!object(raw) || Object.keys(raw).some((key) => key !== "soft" && key !== "hard"))
+            fail("INVALID_METADATA", `${dimension} budget patch must contain only soft and hard`);
+        const limits = {};
+        for (const key of ["soft", "hard"])
+            if (Object.prototype.hasOwnProperty.call(raw, key)) {
+                if (raw[key] === null)
+                    limits[key] = null;
+                else {
+                    const checked = validateBudget({ [dimension]: { [key]: raw[key] } })?.[dimension];
+                    if (checked?.[key] !== undefined)
+                        limits[key] = checked[key];
+                }
+            }
+        if (limits.soft !== null && limits.hard !== null && limits.soft !== undefined && limits.hard !== undefined && limits.soft >= limits.hard)
+            fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+        result[dimension] = limits;
+    }
+    return result;
+}
+export function budgetUsage(value) { return { tokens: value?.tokens ?? 0, costUsd: value?.costUsd ?? 0, durationMs: value?.durationMs ?? 0, agentLaunches: value?.agentLaunches ?? 0 }; }
+export class WorkflowBudgetRuntime {
+    budget;
+    version;
+    #now;
+    #onChange;
+    #injected = new Set();
+    #seen = new Set();
+    #active;
+    #activeSince;
+    #usage;
+    #events;
+    #turnAccounting;
+    constructor(budget, version = 1, usage, events = [], options = {}) {
+        this.budget = budget;
+        this.version = version;
+        this.#now = options.now ?? (() => Date.now());
+        this.#onChange = options.onChange;
+        this.#active = options.active ?? true;
+        this.#activeSince = this.#active ? this.#now() : undefined;
+        this.#usage = budgetUsage(usage);
+        this.#events = [...events];
+        for (const event of events)
+            if (event.budgetVersion === version)
+                this.#seen.add(event.type);
+    }
+    get usage() { this.#syncDuration(); return { ...this.#usage }; }
+    get events() { return this.#events; }
+    get hardExhausted() { return this.#events.some((event) => event.type === "hard_exhausted" && event.budgetVersion === this.version); }
+    checkAgentLaunch() { this.#checkHard(["agentLaunches"]); }
+    beforeAttempt() { this.#checkHard(["agentLaunches"]); this.#usage.agentLaunches += 1; this.#evaluate(); }
+    beforeTurn() { this.#syncDuration(); this.#evaluate(); this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+    afterTurn(accounting, final) { this.#syncDuration(); this.#applyTurn(accounting, final, this.#turnAccounting); this.#turnAccounting = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }
+    #applyTurn(accounting, final, previous = { input: 0, output: 0, cost: 0 }) { this.#usage.tokens += Math.max(0, accounting.input - previous.input) + Math.max(0, accounting.output - previous.output); this.#usage.costUsd += Math.max(0, accounting.cost - previous.cost); this.#evaluate(); if (!final)
+        this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+    instruction(agentId = "agent") { if (!this.#hasSoftCrossed() || this.#injected.has(agentId))
+        return undefined; this.#injected.add(agentId); return `The workflow budget soft limit has been reached. Finish the requested output now, preserving any required output schema. Current usage: ${JSON.stringify(this.usage)}. Do not start additional model work unless it is required to produce the final requested result.`; }
+    forAgent(agentId) { let attempt = 0; let previous; return { beforeAttempt: () => { attempt += 1; previous = undefined; this.beforeAttempt(); }, beforeTurn: () => { this.beforeTurn(); }, afterTurn: (accounting, final) => { this.#applyTurn(accounting, final, previous); previous = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }, instruction: () => this.instruction(`${agentId}:${String(attempt + 1)}`) }; }
+    transition(state) { const active = state === "running"; if (active === this.#active)
+        return; if (active) {
+        this.#active = true;
+        this.#activeSince = this.#now();
+    }
+    else {
+        this.#syncDuration();
+        this.#evaluate();
+        this.#active = false;
+        this.#activeSince = undefined;
+    } this.#onChange?.(); }
+    #syncDuration() { if (this.#active && this.#activeSince !== undefined) {
+        const now = this.#now();
+        this.#usage.durationMs += Math.max(0, now - this.#activeSince);
+        this.#activeSince = now;
+    } }
+    #hasSoftCrossed() { return !!this.budget && Object.entries(this.budget).some(([dimension, limits]) => limits.soft !== undefined && this.#usage[dimension] >= limits.soft); }
+    #checkHard(dimensions) { const exhausted = dimensions.filter((dimension) => { const hard = this.budget?.[dimension]?.hard; return hard !== undefined && this.#usage[dimension] >= hard; }); if (!exhausted.length)
+        return; this.#record("hard_exhausted", exhausted); const detail = exhausted.map((dimension) => `${dimension} usage=${String(this.#usage[dimension])} hard=${String(this.budget?.[dimension]?.hard)}`).join(", "); throw new WorkflowError("BUDGET_EXHAUSTED", `Budget version ${String(this.version)} exhausted: ${detail}`); }
+    #evaluate() { const budget = this.budget; if (!budget)
+        return; const soft = Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.soft !== undefined && this.#usage[dimension] >= limits.soft; }); if (soft.length)
+        this.#record("soft_crossed", soft); const overrun = Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && this.#usage[dimension] > limits.hard; }); if (overrun.length)
+        this.#record("hard_overrun", overrun); }
+    #record(type, dimensions) { if (this.#seen.has(type))
+        return; this.#seen.add(type); this.#events.push({ type, budgetVersion: this.version, dimensions: [...dimensions], usage: this.usage, limits: structuredClone(this.budget ?? {}), at: this.#now() }); this.#onChange?.(); }
+    recordEvent(event) { this.#events.push(structuredClone(event)); }
+    snapshot() { return { usage: this.usage, budgetEvents: [...this.#events] }; }
+}
+export function mergeBudget(budget, patch) { const merged = structuredClone(budget ?? {}); for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"])
+    if (Object.prototype.hasOwnProperty.call(patch, dimension)) {
+        const value = patch[dimension];
+        if (value === null) {
+            Reflect.deleteProperty(merged, dimension);
+            continue;
+        }
+        const next = { ...(merged[dimension] ?? {}) };
+        for (const key of ["soft", "hard"])
+            if (value && Object.prototype.hasOwnProperty.call(value, key)) {
+                const limit = value[key];
+                if (limit === null)
+                    Reflect.deleteProperty(next, key);
+                else if (limit !== undefined)
+                    next[key] = limit;
+            }
+        if (Object.keys(next).length)
+            merged[dimension] = next;
+        else
+            Reflect.deleteProperty(merged, dimension);
+    } return validateBudget(merged); }
+export function budgetRelaxed(previous, next) { for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"]) {
+    const oldLimit = previous?.[dimension];
+    const newLimit = next?.[dimension];
+    for (const key of ["soft", "hard"])
+        if ((oldLimit?.[key] !== undefined && newLimit?.[key] === undefined) || (oldLimit?.[key] !== undefined && newLimit?.[key] !== undefined && newLimit[key] > oldLimit[key]))
+            return true;
+} return false; }
+export function exhaustedBudgetDimensions(budget, usage) { if (!budget)
+    return []; return Object.keys(budget).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && usage[dimension] >= limits.hard; }); }
+export function resumeBudgetAllowed(budget, usage) { return exhaustedBudgetDimensions(budget, usage).length === 0; }