pi-extensible-workflows 1.0.0 → 2.0.0

package/README.md

@@ -20,7 +20,7 @@ For source installs and local development, see the [installation guide](https://
 
 ## Capabilities
 
-The main Pi agent acts as the orchestrator: it writes workflow scripts on the fly for each task. Pi extensions can add reusable functions and variables to those scripts, or register complete workflows that can be invoked by name.
+The main Pi agent acts as the orchestrator: it writes workflow scripts on the fly for each task. Pi extensions can add reusable functions and variables to those scripts; every registered function is also directly runnable as a top-level workflow.
 
 A workflow can fan out across specialized agents, combine their results, and resume without rerunning completed work.
 
@@ -61,9 +61,14 @@ Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.j
 ```sh
 npx pi-extensible-workflows doctor
 npx pi-extensible-workflows inspect [session-id]
+npx pi-extensible-workflows transcript <session-file>
+npx pi-extensible-workflows run <workflow-name> [workflow arguments]
+npx pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]
 ```
 
-`doctor` validates the installation and active Pi resources. `inspect` opens a read-only terminal view of persisted workflow runs.
+`doctor` validates the installation and active Pi resources. `inspect` opens a read-only terminal view of persisted workflow runs. `transcript` renders a session transcript to stdout. `run` derives flat CLI arguments and help from a registered function's input schema. Use `--input '<json>'` for nested or otherwise complex inputs. It executes in the current working directory, writes the final JSON result to stdout, and writes progress and errors to stderr. `export` creates an executable POSIX launcher in `~/.local/bin` by default.
+`run` and `export` accept the trust overrides `--approve` and `--no-approve`; the generated launcher forwards its arguments to `run`. `--` ends launcher option parsing, and later tokens are passed to workflow input instead of being interpreted as launcher options.
+Launch snapshots use identity version 4. A cold resume intentionally rejects persisted v3 runs with `RESUME_INCOMPATIBLE`; relaunch the workflow instead.
 
 ## Development
 

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

@@ -31,6 +31,15 @@ export interface AgentDefinition {
     tools?: readonly string[];
     disabledAgentResources?: AgentResourceExclusions;
 }
+export interface AgentProviderFailure {
+    label: string;
+    provider: string;
+    model: string;
+    error: string;
+}
+export type AgentProviderRecovery = "retry" | "abort" | {
+    model: string;
+};
 export interface AgentExecutionOptions {
     label: string;
     workflowName: string;
@@ -40,6 +49,8 @@ export interface AgentExecutionOptions {
     thinking?: ThinkingLevel;
     onProgress?: (progress: AgentProgress) => void | Promise<void>;
     onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => void | Promise<void>;
+    providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>;
+    modelOverride?: ModelSpec;
     tools?: readonly string[];
     effectiveTools?: readonly string[];
     role?: string;
@@ -179,6 +190,7 @@ export interface SessionInput {
         sessionFile: string;
         leafId: string;
     };
+    allowModelChange?: boolean;
 }
 export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
@@ -278,6 +290,7 @@ export declare class FairAgentScheduler {
     retry(id: string): void;
     attemptStarted(id: string): void;
     cancelRun(runId: string): Promise<void>;
+    removeRun(runId: string): void;
     toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], thinking: ThinkingLevel | undefined) => readonly string[]): ToolDefinition[];
     snapshot(): readonly OwnershipRecord[];
     restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void): void;

package/dist/src/agent-execution.js

@@ -25,10 +25,23 @@ function latestAssistantHasToolCall(messages) {
     const message = [...messages].reverse().find((item) => item.role === "assistant");
     return hasToolCall(message);
 }
-function throwIfTerminalAssistantError(session) {
+function throwIfTerminalAssistantError(session, fallbackModel) {
     const message = [...session.messages].reverse().find((item) => item.role === "assistant");
-    if (message?.stopReason === "error")
-        throw new WorkflowError("AGENT_FAILED", message.errorMessage ?? "Native Pi assistant ended with a terminal provider error");
+    if (message?.stopReason !== "error")
+        return;
+    const provider = session.model?.provider ?? fallbackModel.provider;
+    const model = session.model?.model ?? session.model?.id ?? fallbackModel.model;
+    const error = message.errorMessage ?? "Native Pi assistant ended with a terminal provider error";
+    const failure = new WorkflowError("AGENT_FAILED", error);
+    Object.defineProperty(failure, "terminalProviderError", { value: { provider, model, error }, configurable: true });
+    throw failure;
+}
+function terminalProviderError(error) {
+    const value = error.terminalProviderError;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value;
+    return typeof candidate.provider === "string" && typeof candidate.model === "string" && typeof candidate.error === "string" ? { provider: candidate.provider, model: candidate.model, error: candidate.error } : undefined;
 }
 function accounting(stats) {
     return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
@@ -50,8 +63,11 @@ export async function createNativeAgentSession(input) {
                 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 (context.model && (context.model.provider !== input.model.provider || context.model.modelId !== input.model.model)) {
+                if (!input.allowModelChange)
+                    throw new Error("Persisted transcript model does not match the conversation execution policy");
+                manager.appendModelChange(input.model.provider, input.model.model);
+            }
             if (input.model.thinking && context.thinkingLevel !== input.model.thinking)
                 throw new Error("Persisted transcript thinking level does not match the conversation execution policy");
         }
@@ -120,6 +136,43 @@ export async function createNativeAgentSession(input) {
 }
 function changedOption(options, baseline, key) { return JSON.stringify(options[key]) !== JSON.stringify(baseline[key]); }
 function validThinking(value) { return typeof value === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value); }
+function jsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || seen.has(value))
+        return false;
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+        return false;
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string"))
+        return false;
+    seen.add(value);
+    const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => value[key])).every((item) => jsonValue(item, seen));
+    seen.delete(value);
+    return valid;
+}
+function jsonObject(value) { return jsonValue(value) && typeof value === "object" && value !== null && !Array.isArray(value); }
+function isChildAgentToolParams(value) {
+    if (!jsonObject(value) || typeof value.prompt !== "string" || typeof value.label !== "string")
+        return false;
+    if (value.tools !== undefined && (!Array.isArray(value.tools) || value.tools.some((tool) => typeof tool !== "string")))
+        return false;
+    if (value.model !== undefined && typeof value.model !== "string")
+        return false;
+    if (value.thinking !== undefined && !validThinking(value.thinking))
+        return false;
+    if (value.role !== undefined && typeof value.role !== "string")
+        return false;
+    if (value.outputSchema !== undefined && !jsonObject(value.outputSchema))
+        return false;
+    if (value.retries !== undefined && (typeof value.retries !== "number" || !Number.isInteger(value.retries) || value.retries < 0))
+        return false;
+    if (value.timeoutMs !== undefined && (value.timeoutMs !== null && (typeof value.timeoutMs !== "number" || !Number.isInteger(value.timeoutMs) || value.timeoutMs < 1)))
+        return false;
+    return true;
+}
 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 });
@@ -156,6 +209,26 @@ function conversationExecutionPolicy(options, setup) {
         resourcePolicy: setup.sessionInput.resourcePolicy ? resourcePolicySummary(setup.sessionInput.resourcePolicy) : null,
     });
 }
+function conversationPolicyMatches(expected, current, allowModelChange) {
+    if (fingerprint(expected) === fingerprint(current))
+        return true;
+    if (!allowModelChange || !expected || typeof expected !== "object" || Array.isArray(expected) || !current || typeof current !== "object" || Array.isArray(current))
+        return false;
+    const expectedModel = conversationPolicyModel(expected);
+    const currentModel = conversationPolicyModel(current);
+    if (!expectedModel || !currentModel)
+        return false;
+    return fingerprint(expected) === fingerprint({ ...current, model: { ...currentModel, provider: expectedModel.provider, model: expectedModel.model } });
+}
+function conversationPolicyModel(policy) {
+    if (!policy || typeof policy !== "object" || Array.isArray(policy))
+        return undefined;
+    const model = policy.model;
+    if (!model || typeof model !== "object" || Array.isArray(model) || typeof model.provider !== "string" || typeof model.model !== "string")
+        return undefined;
+    const thinking = typeof model.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(model.thinking) ? model.thinking : undefined;
+    return thinking === undefined ? { provider: model.provider, model: model.model } : { provider: model.provider, model: model.model, thinking };
+}
 function conversationFailure(message) { return new WorkflowError("RESUME_INCOMPATIBLE", message); }
 async function prepareAgentSetup(root, createSession, task, options, resolved, cwd, attempt, signal, customTools, resultTool, continuation) {
     const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
@@ -224,7 +297,7 @@ export class WorkflowAgentExecutor {
             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 model = options.modelOverride ?? parseModel(requestedModel, this.root.model, options.thinking ?? (aliasThinking === undefined ? definition?.thinking : undefined), this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
         const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
         if (!availableModels.has(modelCapability(model)))
             throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
@@ -236,7 +309,8 @@ export class WorkflowAgentExecutor {
             throw new WorkflowError("INVALID_METADATA", "retries must be a non-negative integer");
         if (options.timeoutMs !== undefined && options.timeoutMs !== null && (!Number.isInteger(options.timeoutMs) || options.timeoutMs <= 0))
             throw new WorkflowError("INVALID_METADATA", "timeoutMs must be null or a positive integer");
-        const resolved = this.resolve(options);
+        let resolved = this.resolve(options);
+        let recoveryModel;
         let cwd;
         if (options.parent) {
             if (!options.cwd)
@@ -276,6 +350,11 @@ export class WorkflowAgentExecutor {
             catch (error) {
                 throw conversationFailure(`Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`);
             }
+            if (conversationRecord) {
+                const model = conversationPolicyModel(conversationRecord.policy);
+                if (model)
+                    resolved = this.resolve({ ...options, modelOverride: model });
+            }
             if (!Number.isInteger(options.conversation.turn) || options.conversation.turn < 1)
                 throw conversationFailure("Conversation turn must be a positive integer");
             if (conversationRecord ? conversationRecord.head.turn + 1 !== options.conversation.turn : options.conversation.turn !== 1)
@@ -283,10 +362,11 @@ export class WorkflowAgentExecutor {
         }
         const attempts = [];
         let conversationBaseline;
-        const maxAttempts = (options.retries ?? 0) + 1;
+        let maxAttempts = (options.retries ?? 0) + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            if (recoveryModel)
+                resolved = this.resolve({ ...options, modelOverride: recoveryModel });
             options.budget?.beforeAttempt();
-            let accepted = false;
             let schemaResult;
             let session;
             let setup;
@@ -302,10 +382,10 @@ export class WorkflowAgentExecutor {
             const resultTool = options.schema ? {
                 name: "workflow_result", label: "Workflow Result", description: "Submit the terminal structured workflow result", parameters: Type.Unsafe(options.schema),
                 async execute(_id, value) {
-                    if (!accepted)
-                        return { content: [{ type: "text", text: "Result acceptance is not enabled yet." }], details: {}, isError: true };
                     if (!Value.Check(options.schema, value))
                         return { content: [{ type: "text", text: "Result does not match the required schema." }], details: {}, isError: true };
+                    if (schemaResult !== undefined)
+                        return { content: [{ type: "text", text: "Result has already been accepted." }], details: {}, isError: true };
                     schemaResult = structuredClone(value);
                     void session?.abort?.();
                     return { content: [{ type: "text", text: "Result accepted." }], details: {} };
@@ -337,6 +417,8 @@ export class WorkflowAgentExecutor {
                 setupFailed = false;
                 if (executionSignal?.aborted)
                     throw new WorkflowError("CANCELLED", "Agent cancelled");
+                if (recoveryModel && conversationRecord)
+                    setup.sessionInput.allowModelChange = true;
                 const started = Date.now();
                 session = await setup.createSession(setup.sessionInput);
                 if (setup.sessionInput.resourcePolicy)
@@ -348,9 +430,9 @@ export class WorkflowAgentExecutor {
                     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)
+                        if (!session.getLeafId || (!recoveryModel && session.getLeafId() !== conversationRecord.head.leafId))
                             throw conversationFailure("Conversation transcript leaf identity changed");
-                        if (fingerprint(currentExecutionPolicy) !== fingerprint(conversationRecord.policy))
+                        if (!conversationPolicyMatches(conversationRecord.policy, currentExecutionPolicy, Boolean(recoveryModel)))
                             throw conversationFailure("Conversation execution policy changed");
                         if (!session.subscribe && (promptFingerprint(conversationSystemPrompt) !== conversationRecord.head.systemPromptSha256 || conversationSystemPrompt !== conversationRecord.head.systemPrompt))
                             throw conversationFailure("Conversation system prompt changed");
@@ -358,7 +440,7 @@ export class WorkflowAgentExecutor {
                             throw conversationFailure("Conversation tool definitions changed");
                     }
                     else if (conversationBaseline) {
-                        if (fingerprint(currentExecutionPolicy) !== fingerprint(conversationBaseline.executionPolicy))
+                        if (!conversationPolicyMatches(conversationBaseline.executionPolicy, currentExecutionPolicy, Boolean(recoveryModel)))
                             throw conversationFailure("Conversation execution policy changed");
                         if (conversationToolDefinitionsSha256 !== conversationBaseline.toolDefinitionsSha256)
                             throw conversationFailure("Conversation tool definitions changed");
@@ -417,7 +499,7 @@ export class WorkflowAgentExecutor {
                         activity = undefined;
                         if (event.message.role === "assistant") {
                             const needsMoreWork = hasToolCall(event.message);
-                            const final = !needsMoreWork || (options.schema !== undefined && accepted);
+                            const final = !needsMoreWork || (options.schema !== undefined && hasSchemaResult());
                             if (!budgetError) {
                                 try {
                                     options.budget?.afterTurn(accounting(activeSession.getSessionStats()), final);
@@ -459,34 +541,41 @@ export class WorkflowAgentExecutor {
                 const promptText = `${context}\n\nTask:\n${setup.prompt}${instruction ? `\n\n${instruction}` : ""}`;
                 options.budget?.beforeTurn();
                 turnStarted = true;
-                await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                try {
+                    await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                }
+                catch (error) {
+                    if (!hasSchemaResult())
+                        throw error;
+                }
                 if (conversationMismatch)
                     throw conversationMismatch;
-                throwIfTerminalAssistantError(session);
+                throwIfTerminalAssistantError(session, setup.sessionInput.model);
                 {
                     const completedAccounting = accounting(session.getSessionStats());
-                    options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? false : !latestAssistantHasToolCall(session.messages));
+                    options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? hasSchemaResult() : !latestAssistantHasToolCall(session.messages));
                     turnStarted = false;
                 }
                 if (budgetError)
                     throw budgetError;
                 if (options.schema) {
-                    accepted = true;
-                    try {
-                        options.budget?.beforeTurn();
-                        turnStarted = true;
-                        await promptWithProviderPause(session, "Submit the final result now by calling workflow_result exactly once. Do not return prose.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
-                        {
-                            const completedAccounting = accounting(session.getSessionStats());
-                            options.budget?.afterTurn(completedAccounting, true);
-                            turnStarted = false;
+                    if (!hasSchemaResult()) {
+                        try {
+                            options.budget?.beforeTurn();
+                            turnStarted = true;
+                            await promptWithProviderPause(session, "Submit the final result now by calling workflow_result exactly once. Do not return prose.", remaining(options.timeoutMs, started), executionSignal, this.root.providerPause);
+                            {
+                                const completedAccounting = accounting(session.getSessionStats());
+                                options.budget?.afterTurn(completedAccounting, true);
+                                turnStarted = false;
+                            }
+                        }
+                        catch (error) {
+                            if (!hasSchemaResult())
+                                throw error;
                         }
                     }
-                    catch (error) {
-                        if (!hasSchemaResult())
-                            throw error;
-                    }
-                    throwIfTerminalAssistantError(session);
+                    throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     if (!hasSchemaResult()) {
                         try {
                             options.budget?.beforeTurn();
@@ -502,7 +591,7 @@ export class WorkflowAgentExecutor {
                             if (!hasSchemaResult())
                                 throw error;
                         }
-                        throwIfTerminalAssistantError(session);
+                        throwIfTerminalAssistantError(session, setup.sessionInput.model);
                     }
                     if (schemaResult === undefined)
                         throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
@@ -557,6 +646,30 @@ export class WorkflowAgentExecutor {
                 }
                 if (options.worktreeOwner && typed.code !== "WORKTREE_FAILED")
                     await this.root.runStore?.snapshotWorktree(options.worktreeOwner).catch(() => undefined);
+                const terminal = terminalProviderError(typed);
+                if (terminal && options.providerErrorRecovery) {
+                    let recovery;
+                    try {
+                        recovery = await options.providerErrorRecovery({ label: options.label, ...terminal });
+                    }
+                    catch {
+                        throw Object.assign(typed, { attempts });
+                    }
+                    if (recovery === "retry" || typeof recovery === "object" && typeof recovery.model === "string") {
+                        if (typeof recovery === "object") {
+                            try {
+                                const selected = resolveModelReference(recovery.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
+                                recoveryModel = selected.thinking === undefined && resolved.model.thinking ? { ...selected, thinking: resolved.model.thinking } : selected;
+                            }
+                            catch {
+                                throw Object.assign(typed, { attempts });
+                            }
+                        }
+                        maxAttempts += 1;
+                        beforeRetry?.();
+                        continue;
+                    }
+                }
                 if (attempt === maxAttempts || setupFailed || typed.code === "CANCELLED" || typed.code === "WORKTREE_FAILED" || typed.code === "RESUME_INCOMPATIBLE")
                     throw Object.assign(typed, { attempts });
                 beforeRetry?.();
@@ -686,7 +799,26 @@ export class FairAgentScheduler {
         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 */
+    removeRun(runId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            return;
+        const nodes = [...this.#nodes.values()].filter((node) => node.runId === runId);
+        if (run.active > 0 || nodes.some(({ state }) => !["completed", "failed", "cancelled"].includes(state)))
+            throw new WorkflowError("INTERNAL_ERROR", `Cannot remove active scheduler run: ${runId}`);
+        for (const { id } of nodes)
+            this.#nodes.delete(id);
+        this.#runs.delete(runId);
+        const index = this.#runOrder.indexOf(runId);
+        if (index >= 0) {
+            this.#runOrder.splice(index, 1);
+            if (index < this.#cursor)
+                this.#cursor -= 1;
+            if (this.#cursor >= this.#runOrder.length)
+                this.#cursor = 0;
+        }
+        this.#dispatch();
+    }
     toolsFor(parentId, resolveTools) {
         const parent = this.#node(parentId);
         if (!parent.options.tools.includes("agent"))
@@ -694,11 +826,15 @@ export class FairAgentScheduler {
         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()])) }, { additionalProperties: true }),
-            execute: async (_id, params) => {
+            execute: async (_id, rawParams) => {
+                if (!isChildAgentToolParams(rawParams))
+                    throw new WorkflowError("INVALID_METADATA", "Invalid child agent parameters");
+                const params = rawParams;
                 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 agentOptions = Object.fromEntries(Object.entries(params).filter(([key]) => key !== "prompt"));
+                const agentOptions = { ...params };
+                Reflect.deleteProperty(agentOptions, "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 } };
@@ -745,17 +881,17 @@ export class FairAgentScheduler {
     #inherit(parent, options) {
         if (!options.label.trim() || !options.cwd || !Array.isArray(options.tools))
             throw new WorkflowError("INVALID_METADATA", "Agents require label, cwd, and tools");
+        const inheritedTools = options.tools;
         if (!parent)
-            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]) }) } : {}) });
+            return Object.freeze({ ...options, tools: Object.freeze([...inheritedTools]), ...(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));
+        const forbidden = inheritedTools.find((tool) => !parent.options.tools.includes(tool));
         if (forbidden)
             throw new WorkflowError("UNKNOWN_TOOL", `Child tool escalates parent boundary: ${forbidden}`);
         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 } : {}) });
+        return Object.freeze({ ...options, cwd: parent.options.cwd, tools: Object.freeze([...inheritedTools]), ...(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, node, start) { this.#runs.get(runId)?.queue.push({ ...(node ? { node } : {}), start }); this.#dispatch(); }
     #dispatch() {
         while (this.#active < this.sessionLimit && this.#runOrder.length) {
@@ -802,6 +938,7 @@ export class FairAgentScheduler {
             return;
         const heldPermit = node.state === "running" || node.state === "retrying";
         node.state = result.ok ? "completed" : result.error.code === "CANCELLED" ? "cancelled" : "failed";
+        Reflect.deleteProperty(node, "steer");
         this.#persist(node.runId);
         if (heldPermit)
             this.#release(node.runId);

package/dist/src/ambient-workflow-evals.js

@@ -1,12 +1,13 @@
 import { spawn } from "node:child_process";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CAPTURE_IDENTITY } from "./eval-capture-extension.js";
-import { extractCapturedWorkflows, extractParentOracleFile } from "./workflow-evals.js";
+import { isObject } from "./index.js";
+import { extractCapturedWorkflows, extractParentOracleFile, findSessionFile } from "./workflow-evals.js";
 export const AMBIENT_OPT_IN = "PI_WORKFLOW_EVAL_AMBIENT";
 export 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 const AMBIENT_INVOCATION_MODE = "ambient-capture-only";
@@ -234,34 +235,12 @@ function emptyAccounting() {
 function ambientAgentDir(environment) {
     return environment.PI_CODING_AGENT_DIR ?? process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
 }
-function isObject(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
-function findSessionFile(directory, sessionId) {
-    if (!existsSync(directory))
-        return undefined;
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-        const path = join(directory, entry.name);
-        if (entry.isDirectory()) {
-            const found = findSessionFile(path, sessionId);
-            if (found)
-                return found;
-        }
-        else if (entry.name.endsWith(".jsonl")) {
-            try {
-                const header = JSON.parse(readFileSync(path, "utf8").split("\n")[0] ?? "{}");
-                if (isObject(header) && header.id === sessionId)
-                    return path;
-            }
-            catch { /* Ignore incomplete sessions. */ }
-        }
-    }
-    return undefined;
-}
 function emptyResult(candidate, repository, worktree, environment, error) {
     const accounting = emptyAccounting();
     return {
         id: candidate.id, status: "failed", workflows: [], accounting, accountingTrustworthy: false, diagnostics: [], errors: [error],
         manifest: {
-            invocationMode: AMBIENT_INVOCATION_MODE, fixtureRoot: repository.fixtureRoot, worktreePath: worktree.path, ambientAgentDir: ambientAgentDir(environment), fixtureFileList: worktree.fixtureFiles, gitStatusBefore: worktree.gitStatusBefore, gitStatusAfter: worktree.gitStatusBefore, parentToolSequence: [], skillReads: [], workflowCalls: [], workflowCallCount: 0, tokenCost: accounting,
+            invocationMode: AMBIENT_INVOCATION_MODE, fixtureRoot: repository.fixtureRoot, worktreePath: worktree.path, ambientAgentDir: ambientAgentDir(environment), fixtureFileList: worktree.fixtureFiles, gitStatusBefore: worktree.gitStatusBefore, parentToolSequence: [], skillReads: [], workflowCalls: [], workflowCallCount: 0, tokenCost: accounting,
             cleanup: { processExited: false, processGroupTerminated: false, worktreeRemoved: false, fixtureRepoRemoved: false, tempRootRemoved: false, captureIdentityVerified: false, realWorkflowAgentsLaunched: 0 },
         },
     };
@@ -271,12 +250,13 @@ async function runAmbientCase(repository, candidate, artifactsDir, environment,
     const sessionId = randomUUID();
     const sessionDir = join(repository.root, "sessions", candidate.id);
     let result;
-    let gitStatusAfter = worktree.gitStatusBefore;
+    let failure;
+    let gitStatusAfter;
     try {
         const pi = await runAmbientPiProcess({ worktree: worktree.path, sessionDir, sessionId, prompt: candidate.prompt, provider, model, ...(thinking ? { thinking } : {}), ...(piCommand ? { piCommand } : {}), timeoutMs: candidate.timeoutMs, maxCost: candidate.maxCost, environment });
         const sessionFile = findSessionFile(sessionDir, sessionId);
         if (!sessionFile)
-            result = emptyResult(candidate, repository, worktree, environment, "Ambient parent session was not written.");
+            failure = "Ambient parent session was not written.";
         else {
             const oracle = extractParentOracleFile(sessionFile);
             const workflows = extractCapturedWorkflows(oracle);
@@ -286,14 +266,14 @@ async function runAmbientCase(repository, candidate, artifactsDir, environment,
             result = {
                 id: candidate.id, status, workflows, accounting: oracle.usage, accountingTrustworthy: !pi.timedOut && !pi.budgetExceeded && pi.exitCode === 0, diagnostics: [pi.stderr].filter(Boolean), errors,
                 manifest: {
-                    invocationMode: AMBIENT_INVOCATION_MODE, fixtureRoot: repository.fixtureRoot, worktreePath: worktree.path, ambientAgentDir: ambientAgentDir(environment), fixtureFileList: worktree.fixtureFiles, gitStatusBefore: worktree.gitStatusBefore, gitStatusAfter, parentToolSequence: oracle.parentToolSequence, skillReads: oracle.skillReads, workflowCalls: workflows, workflowCallCount: oracle.workflowCallCount, tokenCost: oracle.usage,
+                    invocationMode: AMBIENT_INVOCATION_MODE, fixtureRoot: repository.fixtureRoot, worktreePath: worktree.path, ambientAgentDir: ambientAgentDir(environment), fixtureFileList: worktree.fixtureFiles, gitStatusBefore: worktree.gitStatusBefore, parentToolSequence: oracle.parentToolSequence, skillReads: oracle.skillReads, workflowCalls: workflows, workflowCallCount: oracle.workflowCallCount, tokenCost: oracle.usage,
                     cleanup: { processExited: pi.exitCode !== null, processGroupTerminated: pi.processGroupTerminated, worktreeRemoved: false, fixtureRepoRemoved: false, tempRootRemoved: false, captureIdentityVerified, realWorkflowAgentsLaunched: 0 },
                 },
             };
         }
     }
     catch (error) {
-        result = emptyResult(candidate, repository, worktree, environment, error instanceof Error ? error.message : String(error));
+        failure = error instanceof Error ? error.message : String(error);
     }
     finally {
         try {
@@ -304,12 +284,13 @@ async function runAmbientCase(repository, candidate, artifactsDir, environment,
         }
         const worktreeRemoved = removeAmbientCaseWorktree(repository, worktree);
         if (!result)
-            result = emptyResult(candidate, repository, worktree, environment, "Ambient case produced no result.");
+            result = emptyResult(candidate, repository, worktree, environment, failure ?? "Ambient case produced no result.");
         const cleanup = { ...result.manifest.cleanup, worktreeRemoved };
-        result = { ...result, manifest: { ...result.manifest, gitStatusAfter, cleanup } };
-        writeFileSync(join(artifactsDir, `${candidate.id}.json`), `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+        result = { ...result, manifest: { ...result.manifest, cleanup } };
     }
-    return result;
+    const finalized = { ...result, manifest: { ...result.manifest, gitStatusAfter } };
+    writeFileSync(join(artifactsDir, `${candidate.id}.json`), `${JSON.stringify(finalized, null, 2)}\n`, { mode: 0o600 });
+    return finalized;
 }
 export function assertAmbientOptIn(environment = process.env) {
     if (environment[AMBIENT_OPT_IN] !== "1")

package/dist/src/cli.d.ts

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 import { type DoctorOptions } from "./doctor.js";
+import { type JsonSchema, type JsonValue } from "./index.js";
+import type { WorkflowCatalogFunction } from "./index.js";
 export interface CliOptions extends DoctorOptions {
     inspect?: (sessionId?: string) => Promise<void>;
+    transcript?: (sessionFile: string) => Promise<void>;
+    stderr?: (text: string) => void;
+    signal?: AbortSignal;
+    trustOverride?: boolean;
+    isTTY?: boolean;
 }
+export declare function formatWorkflowCliHelp(fn: WorkflowCatalogFunction, command?: string): string;
+export declare function parseWorkflowCliArgs(schema: JsonSchema, rawArgs: readonly string[]): Record<string, JsonValue>;
 export declare function runCli(args: readonly string[], options?: CliOptions, write?: (text: string) => void): Promise<number>;