pi-extensible-workflows 0.3.0

package/dist/src/agent-execution.js

@@ -0,0 +1,537 @@
+import { join } 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) {
+    if (!value)
+        return { ...fallback, ...(thinking ? { thinking } : {}) };
+    const parsed = parseModelReference(value);
+    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))
+        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;
+}
+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);
+    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)
+        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;
+}
+export class WorkflowAgentExecutor {
+    root;
+    createSession;
+    constructor(root, createSession = createNativeAgentSession) {
+        this.root = root;
+        this.createSession = createSession;
+    }
+    resolve(options, inheritedTools) {
+        const role = options.role;
+        const definition = role ? this.root.agentDefinitions?.[role] : undefined;
+        if (role && !definition)
+            throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${role}`);
+        if (role && (options.model !== undefined || options.thinking !== undefined || options.tools !== undefined))
+            throw new WorkflowError("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
+        const requested = options.tools !== undefined ? options.tools : definition?.tools !== undefined ? definition.tools : options.effectiveTools !== undefined ? options.effectiveTools : inheritedTools !== undefined ? inheritedTools : [...this.root.tools];
+        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)]);
+        if (!availableModels.has(modelCapability(model)))
+            throw new WorkflowError("UNKNOWN_MODEL", `Unknown model: ${modelCapability(model)}`);
+        return { model, tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+    }
+    async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
+        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))
+            throw new WorkflowError("INVALID_METADATA", "timeoutMs must be null or a positive integer");
+        const resolved = this.resolve(options);
+        let cwd;
+        if (options.parent) {
+            if (!options.cwd)
+                throw new WorkflowError("INVALID_METADATA", "Child agents require their parent cwd");
+            if (options.worktreeOwner) {
+                if (!this.root.runStore)
+                    throw new WorkflowError("WORKTREE_FAILED", "Worktree inheritance requires a persisted run");
+                cwd = (await this.root.runStore.validateWorktree(options.worktreeOwner, options.cwd)).cwd;
+            }
+            else {
+                if (options.cwd !== this.root.cwd)
+                    throw new WorkflowError("INVALID_METADATA", "Shared-tree children must inherit the root cwd");
+                cwd = this.root.cwd;
+            }
+        }
+        else if (options.worktreeOwner) {
+            if (!this.root.runStore)
+                throw new WorkflowError("WORKTREE_FAILED", "Worktree scope requires a persisted run");
+            const worktree = await this.root.runStore.worktree(options.worktreeOwner);
+            if (options.cwd && resolvePath(options.cwd) !== resolvePath(worktree.cwd))
+                throw new WorkflowError("WORKTREE_FAILED", "Agent cwd does not match its owned worktree");
+            cwd = worktree.cwd;
+        }
+        else {
+            if (options.cwd)
+                throw new WorkflowError("INVALID_METADATA", "Only child agents or worktree scopes may provide a cwd");
+            cwd = this.root.cwd;
+        }
+        const attempts = [];
+        const maxAttempts = (options.retries ?? 0) + 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            const started = Date.now();
+            let accepted = false;
+            let schemaResult;
+            const hasSchemaResult = () => schemaResult !== undefined;
+            const resultTool = options.schema ? {
+                name: "workflow_result", label: "Workflow Result", description: "Submit the terminal structured workflow result", parameters: Type.Unsafe(options.schema),
+                async execute(_id, value) {
+                    if (!accepted)
+                        return { content: [{ type: "text", text: "Result acceptance is not enabled yet." }], details: {}, isError: true };
+                    if (!Value.Check(options.schema, value))
+                        return { content: [{ type: "text", text: "Result does not match the required schema." }], details: {}, isError: true };
+                    schemaResult = structuredClone(value);
+                    void session?.abort?.();
+                    return { content: [{ type: "text", text: "Result accepted." }], details: {} };
+                },
+            } : undefined;
+            let session;
+            const toolCalls = new Map();
+            let activity;
+            let progress = Promise.resolve();
+            let unsubscribe;
+            let systemPromptTurn = 0;
+            let systemPromptWrite = Promise.resolve();
+            let systemPromptWriteError;
+            const flushSystemPrompts = async () => {
+                await systemPromptWrite;
+                if (systemPromptWriteError)
+                    throw new WorkflowError("INTERNAL_ERROR", `Failed to persist effective system prompt: ${systemPromptWriteError instanceof Error ? systemPromptWriteError.message : typeof systemPromptWriteError === "string" ? systemPromptWriteError : "unknown error"}`);
+            };
+            const report = (persist) => {
+                if (!session || !options.onProgress)
+                    return;
+                const update = { accounting: accounting(session.messages), 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; });
+                    }
+                    if (event.type === "message_start" && event.message.role === "assistant") {
+                        activity = { kind: "text", text: "responding" };
+                        report(false);
+                    }
+                    if (event.type === "message_end") {
+                        activity = undefined;
+                        if (event.message.role === "assistant")
+                            report(true);
+                    }
+                    if (event.type === "tool_execution_start") {
+                        toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" });
+                        activity = { kind: "tool", text: event.toolName };
+                        report(false);
+                    }
+                    if (event.type === "tool_execution_end") {
+                        toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" });
+                        if (activity?.kind === "tool" && activity.text === event.toolName)
+                            activity = undefined;
+                        report(false);
+                    }
+                });
+                report(false);
+                if (setSteer) {
+                    if (!session.steer)
+                        throw new WorkflowError("INTERNAL_ERROR", "Native Pi session does not support steering");
+                    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);
+                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);
+                    }
+                    catch (error) {
+                        if (!hasSchemaResult())
+                            throw error;
+                    }
+                    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);
+                        }
+                        catch (error) {
+                            if (!hasSchemaResult())
+                                throw error;
+                        }
+                    }
+                    if (schemaResult === undefined)
+                        throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
+                }
+                const value = options.schema ? schemaResult : text(session.messages);
+                if (options.worktreeOwner)
+                    await this.root.runStore?.snapshotWorktree(options.worktreeOwner);
+                report(true);
+                await progress;
+                await flushSystemPrompts();
+                unsubscribe?.();
+                const attemptAccounting = accounting(session.messages);
+                attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), result: value, accounting: attemptAccounting });
+                session.dispose();
+                return { value, attempts, cwd };
+            }
+            catch (error) {
+                const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+                if (session) {
+                    report(true);
+                    await progress;
+                    try {
+                        await flushSystemPrompts();
+                    }
+                    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 });
+                    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")
+                    throw Object.assign(typed, { attempts });
+                beforeRetry?.();
+            }
+        }
+        throw new WorkflowError("AGENT_FAILED", "Agent execution failed");
+    }
+}
+export class FairAgentScheduler {
+    runner;
+    sessionLimit;
+    writeOwnership;
+    #runs = new Map();
+    #nodes = new Map();
+    #runOrder = [];
+    #cursor = 0;
+    #active = 0;
+    #nextId = 0;
+    #persistence = Promise.resolve();
+    constructor(runner, sessionLimit = 16, writeOwnership) {
+        this.runner = runner;
+        this.sessionLimit = sessionLimit;
+        this.writeOwnership = writeOwnership;
+        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) {
+        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: [] });
+        this.#runOrder.push(runId);
+    }
+    spawn(runId, prompt, options, parentId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
+        const parent = parentId ? this.#nodes.get(parentId) : undefined;
+        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; });
+        const node = { id, runId, ...(parentId ? { parentId } : {}), options: effective, children: new Set(), collected: false, state: "queued", controller: new AbortController(), promise, resolve: resolveResult, task: async () => undefined, restored: false };
+        node.task = async () => {
+            if (node.controller.signal.aborted) {
+                this.#release(node.runId);
+                return;
+            }
+            node.state = "running";
+            this.#persist(runId);
+            try {
+                const value = await this.runner({ id, runId, ...(parentId ? { parentId } : {}), prompt, options: effective, signal: node.controller.signal, setSteer: (handler) => { node.steer = handler; } });
+                this.#settle(node, { id, ok: true, value });
+            }
+            catch (error) {
+                const typed = error instanceof WorkflowError ? error : new WorkflowError("AGENT_FAILED", error instanceof Error ? error.message : String(error));
+                this.#settle(node, { id, ok: false, error: { code: typed.code, message: typed.message } });
+            }
+        };
+        this.#nodes.set(id, node);
+        parent?.children.add(id);
+        this.#persist(runId);
+        this.#enqueue(runId, () => { void node.task(); });
+        return { id, result: promise };
+    }
+    async result(parentId, childId) {
+        const parent = this.#node(parentId);
+        const child = this.#node(childId);
+        if (child.parentId !== parentId)
+            throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Results are scoped to direct children");
+        child.collected = true;
+        parent.state = "waiting_for_child";
+        this.#persist(parent.runId);
+        this.#release(parent.runId);
+        const outcome = await child.promise;
+        await new Promise((resolve) => { this.#enqueue(parent.runId, () => { resolve(); }); });
+        parent.state = "running";
+        if (parent.controller.signal.aborted)
+            throw new WorkflowError("CANCELLED", "Parent agent cancelled");
+        this.#persist(parent.runId);
+        return outcome;
+    }
+    async steer(parentId, childId, message) {
+        const child = this.#node(childId);
+        if (child.parentId !== parentId)
+            throw new WorkflowError("UNKNOWN_AGENT_TYPE", "Steering is scoped to direct children");
+        if (child.state !== "running" && child.state !== "waiting_for_child")
+            throw new WorkflowError("AGENT_FAILED", "Child is not running");
+        if (!child.steer)
+            throw new WorkflowError("AGENT_FAILED", "Child has not registered a steering handler");
+        await child.steer(message);
+    }
+    cancel(id) { this.#cancelTree(this.#node(id)); }
+    cancelChildren(id) {
+        for (const childId of this.#node(id).children) {
+            const child = this.#nodes.get(childId);
+            if (child)
+                this.#cancelTree(child);
+        }
+    }
+    async cancelRun(runId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
+        const nodes = [...this.#nodes.values()].filter((node) => node.runId === runId);
+        for (const node of nodes)
+            if (!node.parentId)
+                this.#cancelTree(node);
+        await Promise.all(nodes.map(({ promise }) => promise));
+        if (nodes.every(({ restored }) => restored))
+            run.logical = 0;
+    }
+    /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument, @typescript-eslint/restrict-template-expressions */
+    toolsFor(parentId, resolveTools) {
+        const parent = this.#node(parentId);
+        if (!parent.options.tools.includes("agent"))
+            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()])) }),
+            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 child = this.spawn(parent.runId, params.prompt, options, parentId);
+                return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id } };
+            },
+        };
+        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 }; },
+        };
+        const steerTool = {
+            name: "steer_subagent", label: "Steer Child", description: "Steer a running direct child",
+            parameters: Type.Object({ id: Type.String(), message: Type.String() }),
+            execute: async (_id, params) => { await this.steer(parentId, params.id, params.message); return { content: [{ type: "text", text: "Steering delivered." }], details: {} }; },
+        };
+        return [agentTool, resultTool, steerTool];
+    }
+    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);
+        const run = this.#runs.get(runId);
+        for (const record of ownership) {
+            if (record.id.split(":").slice(0, -1).join(":") !== runId)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", `Persisted agent belongs to another run: ${record.id}`);
+            let resolveResult = () => undefined;
+            const promise = new Promise((resolve) => { resolveResult = resolve; });
+            const node = { id: record.id, runId, ...(record.parentId ? { parentId: record.parentId } : {}), options: this.#inherit(undefined, record.options), children: new Set(), collected: false, state: record.state, controller: new AbortController(), promise, resolve: resolveResult, task: async () => undefined, restored: true };
+            this.#nodes.set(node.id, node);
+            run.logical += 1;
+            this.#nextId = Math.max(this.#nextId, Number(node.id.slice(node.id.lastIndexOf(":") + 1)) || 0);
+            if (record.state === "completed")
+                resolveResult({ id: node.id, ok: true, value: null });
+            else if (record.state === "failed" || record.state === "cancelled")
+                resolveResult({ id: node.id, ok: false, error: { code: record.state === "cancelled" ? "CANCELLED" : "AGENT_FAILED", message: `Persisted agent ${record.state}` } });
+        }
+        for (const node of this.#nodes.values())
+            if (node.runId === runId && node.parentId)
+                this.#nodes.get(node.parentId)?.children.add(node.id);
+    }
+    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]) });
+        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 } : {}) });
+    }
+    /* 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(); }
+    #dispatch() {
+        while (this.#active < this.sessionLimit && this.#runOrder.length) {
+            let selected;
+            for (let checked = 0; checked < this.#runOrder.length; checked += 1) {
+                const index = (this.#cursor + checked) % this.#runOrder.length;
+                const id = this.#runOrder[index];
+                const run = id ? this.#runs.get(id) : undefined;
+                if (id && run && run.active < run.limit && run.queue.length) {
+                    selected = id;
+                    this.#cursor = (index + 1) % this.#runOrder.length;
+                    break;
+                }
+            }
+            if (!selected)
+                return;
+            const run = this.#runs.get(selected);
+            const start = run.queue.shift();
+            run.active += 1;
+            this.#active += 1;
+            start();
+        }
+    }
+    #release(runId) {
+        const run = this.#runs.get(runId);
+        if (run && run.active > 0) {
+            run.active -= 1;
+            this.#active -= 1;
+            this.#dispatch();
+        }
+    }
+    #settle(node, result) {
+        if (["completed", "failed", "cancelled"].includes(node.state))
+            return;
+        const heldPermit = node.state === "running";
+        node.state = result.ok ? "completed" : result.error.code === "CANCELLED" ? "cancelled" : "failed";
+        this.#persist(node.runId);
+        if (heldPermit)
+            this.#release(node.runId);
+        for (const childId of node.children) {
+            const child = this.#nodes.get(childId);
+            if (child && !child.collected)
+                this.#cancelTree(child);
+        }
+        node.resolve(result);
+    }
+    #cancelTree(node) {
+        if (["completed", "failed", "cancelled"].includes(node.state))
+            return;
+        node.controller.abort();
+        for (const childId of node.children) {
+            const child = this.#nodes.get(childId);
+            if (child)
+                this.#cancelTree(child);
+        }
+        if (node.state === "queued" || node.restored)
+            this.#settle(node, { id: node.id, ok: false, error: { code: "CANCELLED", message: "Agent cancelled" } });
+    }
+    #node(id) {
+        const node = this.#nodes.get(id);
+        if (!node)
+            throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown owned agent: ${id}`);
+        return node;
+    }
+    #persist(runId) {
+        if (!this.writeOwnership)
+            return;
+        const ownership = this.snapshot().filter(({ id }) => id.startsWith(`${runId}:`));
+        this.#persistence = this.#persistence.then(() => this.writeOwnership?.(runId, ownership)).then(() => undefined);
+    }
+}
+function resolvePath(path) { return path.replace(/[\\/]+$/, ""); }
+function requiredFile(file) {
+    if (!file)
+        throw new WorkflowError("INTERNAL_ERROR", "Workflow agents require persisted native Pi sessions");
+    return file;
+}
+function remaining(timeoutMs, started) {
+    return timeoutMs === null || timeoutMs === undefined ? timeoutMs : Math.max(1, timeoutMs - (Date.now() - started));
+}
+function providerLimited(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return candidate.status === 429 || candidate.code === 429 || candidate.code === "rate_limit_exceeded" || candidate.code === "RATE_LIMITED";
+}
+async function promptWithProviderPause(session, text, timeoutMs, signal, pause) {
+    for (;;) {
+        try {
+            await withTimeout(session.prompt(text), timeoutMs, signal, session);
+            return;
+        }
+        catch (error) {
+            if (!pause || !providerLimited(error))
+                throw error;
+            await pause();
+        }
+    }
+}
+async function withTimeout(work, timeoutMs, signal, session) {
+    if (signal?.aborted)
+        throw new WorkflowError("CANCELLED", "Agent cancelled");
+    let timer;
+    let abort;
+    const state = { interrupted: false };
+    const timeout = timeoutMs ? new Promise((_, reject) => { timer = setTimeout(() => { state.interrupted = true; reject(new WorkflowError("AGENT_TIMEOUT", "Agent attempt timed out")); }, timeoutMs); }) : new Promise(() => { });
+    const cancelled = signal ? new Promise((_, reject) => { abort = () => { state.interrupted = true; reject(new WorkflowError("CANCELLED", "Agent cancelled")); }; signal.addEventListener("abort", abort, { once: true }); }) : new Promise(() => { });
+    try {
+        await Promise.race([work, timeout, cancelled]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (abort)
+            signal?.removeEventListener("abort", abort);
+        if (state.interrupted)
+            await session.abort?.();
+    }
+}

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

@@ -0,0 +1,112 @@
+export declare const AMBIENT_OPT_IN = "PI_WORKFLOW_EVAL_AMBIENT";
+export declare const AMBIENT_CAPTURE_NOTE = "Ambient Tier D uses the explicit capture extension. Pi 0.80.6 orders CLI extensions before discovered extensions and the first tool registration wins, so ambient tools and skills remain available while workflow execution stays capture-only.";
+export declare const AMBIENT_INVOCATION_MODE = "ambient-capture-only";
+export interface AmbientEvalCase {
+    id: string;
+    prompt: string;
+    timeoutMs: number;
+    maxCost: number;
+}
+export declare const AMBIENT_WORKFLOW_EVAL_CASES: readonly AmbientEvalCase[];
+export interface AmbientFixtureRepository {
+    root: string;
+    fixtureRoot: string;
+    worktreesRoot: string;
+    fixtureFiles: readonly string[];
+}
+export interface AmbientCaseWorktree {
+    id: string;
+    path: string;
+    fixtureFiles: readonly string[];
+    gitStatusBefore: readonly string[];
+}
+export interface AmbientCleanup {
+    processExited: boolean;
+    processGroupTerminated: boolean;
+    worktreeRemoved: boolean;
+    fixtureRepoRemoved: boolean;
+    tempRootRemoved: boolean;
+    captureIdentityVerified: boolean;
+    realWorkflowAgentsLaunched: number;
+}
+export interface AmbientManifest {
+    invocationMode: string;
+    fixtureRoot: string;
+    worktreePath: string;
+    ambientAgentDir: string;
+    fixtureFileList: readonly string[];
+    gitStatusBefore: readonly string[];
+    gitStatusAfter: readonly string[];
+    parentToolSequence: readonly string[];
+    skillReads: readonly string[];
+    workflowCalls: readonly unknown[];
+    workflowCallCount: number;
+    tokenCost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        totalTokens: number;
+        cost: number;
+        models: readonly {
+            model: string;
+            cost: number;
+        }[];
+    };
+    cleanup: AmbientCleanup;
+}
+export interface AmbientCaseResult {
+    id: string;
+    status: "passed" | "failed" | "timed_out" | "budget_exceeded";
+    workflows: readonly unknown[];
+    accounting: AmbientManifest["tokenCost"];
+    accountingTrustworthy: boolean;
+    diagnostics: readonly string[];
+    errors: readonly string[];
+    manifest: AmbientManifest;
+}
+export interface AmbientWorkflowEvalRunOptions {
+    cases?: readonly AmbientEvalCase[];
+    caseIds?: readonly string[];
+    provider?: string;
+    model?: string;
+    thinking?: string;
+    piCommand?: string;
+    artifactsDir?: string;
+    environment?: NodeJS.ProcessEnv;
+}
+export interface AmbientWorkflowEvalRunResult {
+    artifactDir: string;
+    cases: readonly AmbientCaseResult[];
+    spent: number;
+    mode: string;
+}
+export declare function createAmbientFixtureRepository(parent?: string): AmbientFixtureRepository;
+export declare function createAmbientCaseWorktree(repository: AmbientFixtureRepository, id: string): AmbientCaseWorktree;
+export declare function removeAmbientCaseWorktree(repository: AmbientFixtureRepository, worktree: AmbientCaseWorktree): boolean;
+export declare function removeAmbientFixtureRepository(repository: AmbientFixtureRepository): boolean;
+export interface AmbientPiProcessInput {
+    worktree: string;
+    sessionDir: string;
+    sessionId?: string;
+    prompt: string;
+    provider: string;
+    model: string;
+    thinking?: string;
+    piCommand?: string;
+    timeoutMs: number;
+    maxCost: number;
+    environment?: NodeJS.ProcessEnv;
+}
+export interface AmbientPiProcessResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    budgetExceeded: boolean;
+    processGroupTerminated: boolean;
+    stdout: string;
+    stderr: string;
+}
+export declare function runAmbientPiProcess(input: AmbientPiProcessInput): Promise<AmbientPiProcessResult>;
+export declare function assertAmbientOptIn(environment?: NodeJS.ProcessEnv): void;
+export declare function runAmbientWorkflowEvals(options?: AmbientWorkflowEvalRunOptions): Promise<AmbientWorkflowEvalRunResult>;
+export declare function formatAmbientSummary(result: AmbientWorkflowEvalRunResult): string;