pi-extensible-workflows 0.3.2 → 1.0.0

package/dist/src/agent-execution.js

@@ -1,12 +1,14 @@
-import { join } from "node:path";
+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, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
-import { parseModelReference, WorkflowError } from "./index.js";
-function parseModel(value, fallback, thinking) {
+import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { mergeAgentResourceExclusions, resolveModelReference, WorkflowError } from "./index.js";
+function parseModel(value, fallback, thinking, aliases = {}, knownModels, settingsPath) {
     if (!value)
         return { ...fallback, ...(thinking ? { thinking } : {}) };
-    const parsed = parseModelReference(value);
+    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}`; }
@@ -16,33 +18,185 @@ function text(messages) {
         return "";
     return message.content.filter((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && "text" in part && typeof part.text === "string").map((part) => part.text).join("");
 }
-function accounting(messages) {
-    const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
-    for (const message of messages)
-        if (message.role === "assistant" && message.usage) {
-            total.input += message.usage.input;
-            total.output += message.usage.output;
-            total.cacheRead += message.usage.cacheRead;
-            total.cacheWrite += message.usage.cacheWrite;
-            total.cost += message.usage.cost.total;
-        }
-    return total;
+function hasToolCall(message) {
+    return typeof message === "object" && message !== null && Array.isArray(message.content) && message.content.some((part) => typeof part === "object" && part !== null && part.type === "toolCall");
+}
+function latestAssistantHasToolCall(messages) {
+    const message = [...messages].reverse().find((item) => item.role === "assistant");
+    return hasToolCall(message);
+}
+function throwIfTerminalAssistantError(session) {
+    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");
 }
+function accounting(stats) {
+    return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
+}
+function canonicalSourcePath(path) { try {
+    return realpathSync(path);
+}
+catch {
+    return resolve(path);
+} }
 export async function createNativeAgentSession(input) {
     const agentDir = input.agentDir ?? getAgentDir();
-    const manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
-    manager.appendSessionInfo(input.sessionLabel);
+    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 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)
         throw new WorkflowError("UNKNOWN_MODEL", `Unknown model: ${input.model.provider}/${input.model.model}`);
     const customTools = [...(input.customTools ?? []), ...(input.resultTool ? [input.resultTool] : [])];
     const tools = [...new Set([...input.tools, ...customTools.map(({ name }) => name)])];
-    const resourceLoader = input.systemPromptAppend ? new DefaultResourceLoader({ cwd: input.cwd, agentDir, appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] }) : undefined;
-    if (resourceLoader)
+    let settingsManager;
+    let resourceLoader;
+    const policy = input.resourcePolicy;
+    if (policy) {
+        settingsManager = SettingsManager.create(input.cwd, agentDir, { projectTrusted: false });
+        settingsManager.setProjectTrusted(policy.projectTrusted);
+        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
+        const resolved = await packageManager.resolve();
+        const disabledExtensions = new Set(policy.effective.extensions);
+        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)).filter((path) => !disabledExtensions.has(canonicalSourcePath(path))))];
+        const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
+        const updateSkillMatches = (skills) => {
+            const names = new Set(skills.map(({ name }) => name));
+            Object.assign(policy, { unmatchedSkills: policy.effective.skills.filter((name) => !names.has(name)) });
+        };
+        const disabledSkills = new Set(policy.effective.skills);
+        resourceLoader = new DefaultResourceLoader({
+            cwd: input.cwd,
+            agentDir,
+            settingsManager,
+            noExtensions: true,
+            additionalExtensionPaths: extensionPaths,
+            noSkills: true,
+            additionalSkillPaths: skillPaths,
+            ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
+            skillsOverride: (base) => {
+                updateSkillMatches(base.skills);
+                return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
+            },
+            ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
+        });
+        await resourceLoader.reload();
+        const discoveredExtensions = new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)));
+        Object.assign(policy, { unmatchedExtensions: policy.effective.extensions.filter((path) => !discoveredExtensions.has(canonicalSourcePath(path))) });
+    }
+    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 ?? ""] } : {}) });
         await resourceLoader.reload();
-    const { session } = await createAgentSession({ cwd: input.cwd, agentDir, modelRuntime, model, ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(resourceLoader ? { resourceLoader } : {}), sessionManager: manager });
-    return session;
+    }
+    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);
+    return Object.assign(session, {
+        getLeafId: () => manager.getLeafId(),
+        getToolDefinitions: () => session.getAllTools().map(({ name, description, parameters, promptGuidelines }) => ({ name, description, parameters, ...(promptGuidelines ? { promptGuidelines } : {}) })),
+    });
+}
+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 fallbackSetupContext(root, options, signal) {
+    const identity = options.agentIdentity ?? { structuralPath: [], callSite: options.label, occurrence: 1 };
+    const run = root.runContext ?? Object.freeze({ cwd: root.cwd, sessionId: "", runId: "", workflow: Object.freeze({ name: options.workflowName }), args: null, signal });
+    return { run, identity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) };
+}
+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) {
+    const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
+    const baselineOptions = structuredClone(options.agentOptions ?? {});
+    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 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 });
+    const hookNames = [];
+    for (const hook of [...(root.agentSetupHooks ?? [])].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+        if (setupSignal.aborted)
+            throw new WorkflowError("CANCELLED", "Agent cancelled");
+        try {
+            await hook.setup(setup, context);
+        }
+        catch (error) {
+            if (setupSignal.reason !== undefined)
+                throw new WorkflowError("CANCELLED", "Agent cancelled");
+            throw error;
+        }
+        hookNames.push(hook.name);
+        if (setupSignal.reason !== undefined)
+            throw new WorkflowError("CANCELLED", "Agent cancelled");
+    }
+    setup.sessionInput.options = setup.options;
+    if (changedOption(setup.options, baselineOptions, "model") && typeof setup.options.model === "string")
+        setup.sessionInput.model = parseModel(setup.options.model, setup.sessionInput.model, changedOption(setup.options, baselineOptions, "thinking") && validThinking(setup.options.thinking) ? setup.options.thinking : undefined, root.modelAliases, root.knownModels ?? root.availableModels, root.settingsPath);
+    if (changedOption(setup.options, baselineOptions, "thinking") && validThinking(setup.options.thinking))
+        setup.sessionInput.model = { ...setup.sessionInput.model, thinking: setup.options.thinking };
+    if (changedOption(setup.options, baselineOptions, "tools") && Array.isArray(setup.options.tools) && setup.options.tools.every((tool) => typeof tool === "string"))
+        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 };
 }
 export class WorkflowAgentExecutor {
     root;
@@ -51,6 +205,7 @@ export class WorkflowAgentExecutor {
         this.root = root;
         this.createSession = createSession;
     }
+    setRunContext(runContext) { this.root.runContext = runContext; }
     resolve(options, inheritedTools) {
         const role = options.role;
         const definition = role ? this.root.agentDefinitions?.[role] : undefined;
@@ -62,13 +217,21 @@ export class WorkflowAgentExecutor {
         const forbidden = requested.find((tool) => !this.root.tools.has(tool));
         if (forbidden)
             throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${forbidden}`);
-        const model = parseModel(options.model ?? definition?.model, this.root.model, options.thinking ?? definition?.thinking);
-        const availableModels = this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
+        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];
+            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 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: ${modelCapability(model)}`);
-        return { model, tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+            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 ?? "" };
     }
     async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
+        const executionSignal = signal ?? this.root.runContext?.signal;
         if (!Number.isInteger(options.retries ?? 0) || (options.retries ?? 0) < 0)
             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))
@@ -102,12 +265,39 @@ 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;
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-            const started = Date.now();
+            options.budget?.beforeAttempt();
             let accepted = false;
             let schemaResult;
+            let session;
+            let setup;
+            let setupSummary;
+            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),
@@ -121,7 +311,6 @@ export class WorkflowAgentExecutor {
                     return { content: [{ type: "text", text: "Result accepted." }], details: {} };
                 },
             } : undefined;
-            let session;
             const toolCalls = new Map();
             let activity;
             let progress = Promise.resolve();
@@ -137,26 +326,115 @@ export class WorkflowAgentExecutor {
             const report = (persist) => {
                 if (!session || !options.onProgress)
                     return;
-                const update = { accounting: accounting(session.messages), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), persist };
+                const update = { accounting: accounting(session.getSessionStats()), toolCalls: [...toolCalls.values()], ...(activity ? { activity } : {}), persist };
                 progress = progress.then(() => options.onProgress?.(update)).then(() => undefined);
             };
             try {
-                session = await this.createSession({ cwd, model: resolved.model, tools: resolved.tools, sessionLabel: `${options.workflowName}:${options.label}:attempt-${String(attempt)}`, ...(this.root.agentDir ? { agentDir: this.root.agentDir } : {}), ...(customTools.length ? { customTools } : {}), ...(resultTool ? { resultTool } : {}), ...(resolved.systemPromptAppend ? { systemPromptAppend: resolved.systemPromptAppend } : {}) });
-                await options.onAttempt?.({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile) });
-                unsubscribe = session.subscribe?.((event) => {
-                    if (event.type === "agent_start" && session?.systemPrompt !== undefined && this.root.runStore) {
-                        systemPromptTurn += 1;
-                        const entry = { sessionId: session.sessionId, attempt, turn: systemPromptTurn, prompt: session.systemPrompt };
-                        systemPromptWrite = systemPromptWrite.then(() => this.root.runStore?.recordSystemPrompt(entry)).then(() => undefined).catch((error) => { systemPromptWriteError ??= error; });
+                setupFailed = true;
+                const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool, conversationRecord?.head);
+                setup = prepared.setup;
+                setupSummary = prepared.summary;
+                setupFailed = false;
+                if (executionSignal?.aborted)
+                    throw new WorkflowError("CANCELLED", "Agent cancelled");
+                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 || 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 };
+                            systemPromptWrite = systemPromptWrite.then(() => this.root.runStore?.recordSystemPrompt(entry)).then(() => undefined).catch((error) => { systemPromptWriteError ??= error; });
+                        }
                     }
                     if (event.type === "message_start" && event.message.role === "assistant") {
+                        if (!turnStarted) {
+                            try {
+                                options.budget?.beforeTurn();
+                                turnStarted = true;
+                            }
+                            catch (error) {
+                                budgetError ??= error instanceof WorkflowError ? error : new WorkflowError("BUDGET_EXHAUSTED", error instanceof Error ? error.message : String(error));
+                                void session?.abort?.();
+                            }
+                        }
                         activity = { kind: "text", text: "responding" };
                         report(false);
                     }
                     if (event.type === "message_end") {
                         activity = undefined;
-                        if (event.message.role === "assistant")
+                        if (event.message.role === "assistant") {
+                            const needsMoreWork = hasToolCall(event.message);
+                            const final = !needsMoreWork || (options.schema !== undefined && accepted);
+                            if (!budgetError) {
+                                try {
+                                    options.budget?.afterTurn(accounting(activeSession.getSessionStats()), final);
+                                    if (!final) {
+                                        const instruction = options.budget?.instruction();
+                                        if (instruction)
+                                            void session?.steer?.(instruction);
+                                    }
+                                }
+                                catch (error) {
+                                    budgetError ??= error instanceof WorkflowError ? error : new WorkflowError("BUDGET_EXHAUSTED", error instanceof Error ? error.message : String(error));
+                                    void session?.abort?.();
+                                }
+                            }
+                            turnStarted = false;
                             report(true);
+                        }
                     }
                     if (event.type === "tool_execution_start") {
                         toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" });
@@ -177,28 +455,61 @@ export class WorkflowAgentExecutor {
                     setSteer((message) => session?.steer?.(message));
                 }
                 const context = [`Workflow: ${options.workflowName}`, `Agent: ${options.label}`, options.phase ? `Phase: ${options.phase}` : "", options.parent ? `Parent: ${options.parent}` : "", "You own this task and any direct child agents you create. Return child results to your parent; do not leave descendants running.", attempt > 1 ? `Retry attempt ${String(attempt)}. Previous state: ${options.retryState ?? attempts.at(-1)?.error?.message ?? "failed attempt"}` : ""].filter(Boolean).join("\n");
-                await promptWithProviderPause(session, `${context}\n\nTask:\n${task}`, remaining(options.timeoutMs, started), signal, this.root.providerPause);
+                const instruction = options.budget?.instruction();
+                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);
+                {
+                    const completedAccounting = accounting(session.getSessionStats());
+                    options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? false : !latestAssistantHasToolCall(session.messages));
+                    turnStarted = false;
+                }
+                if (budgetError)
+                    throw budgetError;
                 if (options.schema) {
                     accepted = true;
                     try {
-                        await promptWithProviderPause(session, "Submit the final result now by calling workflow_result exactly once. Do not return prose.", remaining(options.timeoutMs, started), signal, this.root.providerPause);
+                        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;
                     }
+                    throwIfTerminalAssistantError(session);
                     if (!hasSchemaResult()) {
                         try {
-                            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), signal, this.root.providerPause);
+                            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;
                         }
+                        throwIfTerminalAssistantError(session);
                     }
                     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);
@@ -206,13 +517,23 @@ export class WorkflowAgentExecutor {
                 await progress;
                 await flushSystemPrompts();
                 unsubscribe?.();
-                const attemptAccounting = accounting(session.messages);
-                attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), result: value, accounting: attemptAccounting });
+                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 };
+                return { value, attempts, cwd: setupSummary.cwd };
             }
             catch (error) {
-                const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+                const typed = budgetError ?? conversationMismatch ?? (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;
@@ -221,13 +542,22 @@ export class WorkflowAgentExecutor {
                     }
                     catch { /* Preserve the agent failure that prompted this cleanup. */ }
                     unsubscribe?.();
-                    const attemptAccounting = accounting(session.messages);
-                    attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), error: { code: typed.code, message: typed.message }, accounting: attemptAccounting });
+                    const attemptAccounting = accounting(session.getSessionStats());
+                    if (!budgetError && typed.code !== "BUDGET_EXHAUSTED") {
+                        try {
+                            options.budget?.afterTurn(attemptAccounting, true);
+                        }
+                        catch (budgetFailure) {
+                            budgetError ??= budgetFailure instanceof WorkflowError ? budgetFailure : new WorkflowError("BUDGET_EXHAUSTED", budgetFailure instanceof Error ? budgetFailure.message : String(budgetFailure));
+                        }
+                    }
+                    const includeFailedSetup = Boolean(this.root.agentSetupHooks?.length || setup?.sessionInput.resourcePolicy);
+                    attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), error: { code: typed.code, message: typed.message }, accounting: attemptAccounting, ...(includeFailedSetup && setupSummary ? { setup: setupSummary } : {}) });
                     session.dispose();
                 }
                 if (options.worktreeOwner && typed.code !== "WORKTREE_FAILED")
                     await this.root.runStore?.snapshotWorktree(options.worktreeOwner).catch(() => undefined);
-                if (attempt === maxAttempts || typed.code === "CANCELLED" || typed.code === "WORKTREE_FAILED")
+                if (attempt === maxAttempts || setupFailed || typed.code === "CANCELLED" || typed.code === "WORKTREE_FAILED" || typed.code === "RESUME_INCOMPATIBLE")
                     throw Object.assign(typed, { attempts });
                 beforeRetry?.();
             }
@@ -253,12 +583,12 @@ export class FairAgentScheduler {
         if (!Number.isInteger(sessionLimit) || sessionLimit < 1 || sessionLimit > 16)
             throw new WorkflowError("INVALID_SETTINGS", "Session concurrency must be an integer from 1 to 16");
     }
-    addRun(runId, limit = 8, maxAgentLaunches = 1000) {
+    addRun(runId, limit = 8, beforeLaunch) {
         if (this.#runs.has(runId))
             throw new WorkflowError("DUPLICATE_NAME", `Scheduler run already exists: ${runId}`);
-        if (!Number.isInteger(limit) || limit < 1 || limit > this.sessionLimit || !Number.isInteger(maxAgentLaunches) || maxAgentLaunches < 1)
-            throw new WorkflowError("INVALID_SETTINGS", "Invalid run concurrency or maxAgentLaunches");
-        this.#runs.set(runId, { limit, maxAgentLaunches, logical: 0, active: 0, queue: [] });
+        if (!Number.isInteger(limit) || limit < 1 || limit > this.sessionLimit)
+            throw new WorkflowError("INVALID_SETTINGS", "Invalid run concurrency");
+        this.#runs.set(runId, { limit, ...(beforeLaunch ? { beforeLaunch } : {}), logical: 0, active: 0, queue: [] });
         this.#runOrder.push(runId);
     }
     spawn(runId, prompt, options, parentId) {
@@ -269,10 +599,6 @@ export class FairAgentScheduler {
         if (parentId && (!parent || parent.runId !== runId))
             throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Parent agent is not owned by this run");
         const effective = this.#inherit(parent, options);
-        if (++run.logical > run.maxAgentLaunches) {
-            run.logical -= 1;
-            throw new WorkflowError("RUN_LIMIT_EXCEEDED", `Run ${runId} exceeded maxAgentLaunches`);
-        }
         const id = `${runId}:${String(++this.#nextId)}`;
         let resolveResult = () => undefined;
         const promise = new Promise((resolve) => { resolveResult = resolve; });
@@ -296,7 +622,7 @@ export class FairAgentScheduler {
         this.#nodes.set(id, node);
         parent?.children.add(id);
         this.#persist(runId);
-        this.#enqueue(runId, () => { void node.task(); });
+        this.#enqueue(runId, node, () => { void node.task(); });
         return { id, result: promise };
     }
     async result(parentId, childId) {
@@ -309,7 +635,7 @@ export class FairAgentScheduler {
         this.#persist(parent.runId);
         this.#release(parent.runId);
         const outcome = await child.promise;
-        await new Promise((resolve) => { this.#enqueue(parent.runId, () => { resolve(); }); });
+        await new Promise((resolve) => { this.#enqueue(parent.runId, undefined, () => { resolve(); }); });
         parent.state = "running";
         if (parent.controller.signal.aborted)
             throw new WorkflowError("CANCELLED", "Parent agent cancelled");
@@ -334,6 +660,20 @@ export class FairAgentScheduler {
                 this.#cancelTree(child);
         }
     }
+    retry(id) {
+        const node = this.#node(id);
+        if (node.state === "running") {
+            node.state = "retrying";
+            this.#persist(node.runId);
+        }
+    }
+    attemptStarted(id) {
+        const node = this.#node(id);
+        if (node.state === "retrying") {
+            node.state = "running";
+            this.#persist(node.runId);
+        }
+    }
     async cancelRun(runId) {
         const run = this.#runs.get(runId);
         if (!run)
@@ -353,12 +693,13 @@ export class FairAgentScheduler {
             return [];
         const agentTool = {
             name: "agent", label: "Child Agent", description: "Start a direct child agent",
-            parameters: Type.Object({ prompt: Type.String(), label: Type.String(), tools: Type.Optional(Type.Array(Type.String())), model: Type.Optional(Type.String()), thinking: Type.Optional(Type.String()), role: Type.Optional(Type.String()), outputSchema: Type.Optional(Type.Unsafe({})), retries: Type.Optional(Type.Integer({ minimum: 0 })), timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.Null()])) }),
+            parameters: Type.Object({ prompt: Type.String(), label: Type.String(), tools: Type.Optional(Type.Array(Type.String())), model: Type.Optional(Type.String()), thinking: Type.Optional(Type.String()), role: Type.Optional(Type.String()), outputSchema: Type.Optional(Type.Unsafe({})), retries: Type.Optional(Type.Integer({ minimum: 0 })), timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.Null()])) }, { additionalProperties: true }),
             execute: async (_id, params) => {
                 if (params.role !== undefined && (params.model !== undefined || params.thinking !== undefined || params.tools !== undefined))
                     throw new WorkflowError("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
                 const tools = (params.tools !== undefined || params.role !== undefined ? resolveTools?.(params.role, params.tools, params.model, parent.options.tools, params.thinking) : undefined) ?? params.tools ?? parent.options.tools;
-                const options = { label: params.label, requestedLabel: params.label, cwd: parent.options.cwd, tools, ...(params.model ? { model: params.model } : {}), ...(params.thinking ? { thinking: params.thinking } : {}), ...(params.role ? { role: params.role } : {}), ...(params.outputSchema ? { schema: params.outputSchema } : {}), ...(params.retries === undefined ? {} : { retries: params.retries }), ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }) };
+                const agentOptions = Object.fromEntries(Object.entries(params).filter(([key]) => key !== "prompt"));
+                const options = { label: params.label, requestedLabel: params.label, cwd: parent.options.cwd, tools, agentOptions, ...(params.model ? { model: params.model } : {}), ...(params.thinking ? { thinking: params.thinking } : {}), ...(params.role ? { role: params.role } : {}), ...(params.outputSchema ? { schema: params.outputSchema } : {}), ...(params.retries === undefined ? {} : { retries: params.retries }), ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }) };
                 const child = this.spawn(parent.runId, params.prompt, options, parentId);
                 return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id } };
             },
@@ -366,7 +707,8 @@ export class FairAgentScheduler {
         const resultTool = {
             name: "get_subagent_result", label: "Child Result", description: "Wait for a direct child and return its result",
             parameters: Type.Object({ id: Type.String() }),
-            execute: async (_id, params) => { const value = await this.result(parentId, params.id); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value }; },
+            execute: async (_id, params) => { const value = await this.result(parentId, params.id); if (!value.ok && value.error.code === "BUDGET_EXHAUSTED")
+                throw new WorkflowError("BUDGET_EXHAUSTED", value.error.message); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value }; },
         };
         const steerTool = {
             name: "steer_subagent", label: "Steer Child", description: "Steer a running direct child",
@@ -378,8 +720,8 @@ export class FairAgentScheduler {
     snapshot() {
         return [...this.#nodes.values()].map(({ id, parentId, options, state }) => ({ id, ...(parentId ? { parentId } : {}), label: options.label, state, options }));
     }
-    restoreRun(runId, limit, maxAgentLaunches, ownership) {
-        this.addRun(runId, limit, maxAgentLaunches);
+    restoreRun(runId, limit, ownership, beforeLaunch) {
+        this.addRun(runId, limit, beforeLaunch);
         const run = this.#runs.get(runId);
         for (const record of ownership) {
             if (record.id.split(":").slice(0, -1).join(":") !== runId)
@@ -401,22 +743,20 @@ export class FairAgentScheduler {
     }
     async flush() { await this.#persistence; }
     #inherit(parent, options) {
-        const unknown = Object.keys(options).find((key) => !["label", "requestedLabel", "parentBreadcrumb", "cwd", "tools", "worktreeOwner", "model", "thinking", "role", "schema", "retries", "timeoutMs"].includes(key));
-        if (unknown)
-            throw new WorkflowError("INVALID_METADATA", `Unsupported child agent option: ${unknown}`);
         if (!options.label.trim() || !options.cwd || !Array.isArray(options.tools))
             throw new WorkflowError("INVALID_METADATA", "Agents require label, cwd, and tools");
         if (!parent)
-            return Object.freeze({ ...options, tools: Object.freeze([...options.tools]) });
+            return Object.freeze({ ...options, tools: Object.freeze([...options.tools]), ...(options.agentOptions ? { agentOptions: structuredClone(options.agentOptions) } : {}), ...(options.agentIdentity ? { agentIdentity: Object.freeze({ ...options.agentIdentity, structuralPath: Object.freeze([...options.agentIdentity.structuralPath]) }) } : {}) });
         if (options.cwd !== parent.options.cwd)
             throw new WorkflowError("UNKNOWN_TOOL", "Child cwd cannot differ from its parent");
         const forbidden = options.tools.find((tool) => !parent.options.tools.includes(tool));
         if (forbidden)
             throw new WorkflowError("UNKNOWN_TOOL", `Child tool escalates parent boundary: ${forbidden}`);
-        return Object.freeze({ ...options, cwd: parent.options.cwd, tools: Object.freeze([...options.tools]), ...(parent.options.worktreeOwner ? { worktreeOwner: parent.options.worktreeOwner } : {}) });
+        const identity = options.agentIdentity ?? parent.options.agentIdentity;
+        return Object.freeze({ ...options, cwd: parent.options.cwd, tools: Object.freeze([...options.tools]), ...(options.agentOptions ? { agentOptions: structuredClone(options.agentOptions) } : {}), ...(parent.options.parentBreadcrumb && !options.parentBreadcrumb ? { parentBreadcrumb: parent.options.parentBreadcrumb } : {}), ...(identity ? { agentIdentity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) } : {}), ...(parent.options.worktreeOwner ? { worktreeOwner: parent.options.worktreeOwner } : {}) });
     }
     /* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument, @typescript-eslint/restrict-template-expressions */
-    #enqueue(runId, start) { this.#runs.get(runId)?.queue.push(start); this.#dispatch(); }
+    #enqueue(runId, node, start) { this.#runs.get(runId)?.queue.push({ ...(node ? { node } : {}), start }); this.#dispatch(); }
     #dispatch() {
         while (this.#active < this.sessionLimit && this.#runOrder.length) {
             let selected;
@@ -433,10 +773,20 @@ export class FairAgentScheduler {
             if (!selected)
                 return;
             const run = this.#runs.get(selected);
-            const start = run.queue.shift();
+            const item = run.queue.shift();
+            if (item.node) {
+                try {
+                    run.beforeLaunch?.();
+                }
+                catch (error) {
+                    const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+                    this.#settle(item.node, { id: item.node.id, ok: false, error: { code: typed.code, message: typed.message } });
+                    continue;
+                }
+            }
             run.active += 1;
             this.#active += 1;
-            start();
+            item.start();
         }
     }
     #release(runId) {
@@ -450,7 +800,7 @@ export class FairAgentScheduler {
     #settle(node, result) {
         if (["completed", "failed", "cancelled"].includes(node.state))
             return;
-        const heldPermit = node.state === "running";
+        const heldPermit = node.state === "running" || node.state === "retrying";
         node.state = result.ok ? "completed" : result.error.code === "CANCELLED" ? "cancelled" : "failed";
         this.#persist(node.runId);
         if (heldPermit)