pi-extensible-workflows 0.3.0 → 1.0.0

package/dist/src/persistence.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue, LaunchSnapshot, RunRecord } from "./index.js";
+import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./index.js";
 import type { OwnershipRecord } from "./agent-execution.js";
 export interface NativeSessionReference {
     sessionId: string;
@@ -11,6 +11,20 @@ export interface EffectiveSystemPrompt {
     sha256: string;
     prompt: string;
 }
+export interface ConversationHead {
+    turn: number;
+    sessionId: string;
+    sessionFile: string;
+    leafId: string;
+    systemPrompt: string;
+    systemPromptSha256: string;
+    toolDefinitionsSha256: string;
+}
+export interface PersistedConversation {
+    id: string;
+    policy: JsonValue;
+    head: ConversationHead;
+}
 export interface PersistedRun extends RunRecord {
     nativeSessions: readonly NativeSessionReference[];
 }
@@ -24,6 +38,7 @@ export interface AwaitingCheckpoint {
     prompt: string;
     context: JsonValue;
 }
+export type PendingWorkflowDecision = BudgetApprovalRequest;
 export type PersistedOwnershipNode = OwnershipRecord;
 export interface WorktreeReference {
     owner: string;
@@ -54,7 +69,9 @@ export declare class RunStore {
     private stateWrite;
     private worktreeWrite;
     private snapshotWrite;
+    private launchSnapshotWrite;
     private systemPromptWrite;
+    private conversationWrite;
     constructor(cwd: string, sessionId: string, runId: string, home?: string);
     create(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>): Promise<void>;
     isComplete(): Promise<boolean>;
@@ -64,16 +81,24 @@ export declare class RunStore {
     }>;
     saveState(run: PersistedRun): Promise<void>;
     updateState(update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun>;
+    saveSnapshot(snapshot: Readonly<LaunchSnapshot>): Promise<void>;
+    appendEvent(event: WorkflowRunEvent): Promise<void>;
     saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void>;
     loadOwnership(): Promise<readonly PersistedOwnershipNode[]>;
     systemPromptPath(): string;
     recordSystemPrompt(entry: Omit<EffectiveSystemPrompt, "sha256">): Promise<void>;
     systemPrompts(): Promise<readonly EffectiveSystemPrompt[]>;
+    conversationPath(): string;
+    conversation(id: string): Promise<PersistedConversation | undefined>;
+    saveConversation(conversation: PersistedConversation): Promise<void>;
     private updateJournal;
     complete(path: string, value: JsonValue): Promise<void>;
     replay(path: string): Promise<CompletedOperation | undefined>;
     awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined>;
     awaitingCheckpoints(): Promise<readonly AwaitingCheckpoint[]>;
+    requestWorkflowDecision(request: PendingWorkflowDecision): Promise<void>;
+    pendingWorkflowDecisions(): Promise<readonly PendingWorkflowDecision[]>;
+    answerWorkflowDecision(proposalId: string, approved: boolean): Promise<PendingWorkflowDecision | undefined>;
     answerCheckpoint(name: string, approved: boolean): Promise<AwaitingCheckpoint | undefined>;
     private expectedWorktree;
     private markerPath;

package/dist/src/persistence.js

@@ -5,6 +5,12 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
 import { loadLaunchSnapshot, WorkflowError } from "./index.js";
+function isConversationArtifact(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const artifact = value;
+    return artifact.version === 1 && Boolean(artifact.conversations) && typeof artifact.conversations === "object" && !Array.isArray(artifact.conversations);
+}
 const execute = promisify(execFile);
 const gitIdentity = {
     GIT_AUTHOR_NAME: "pi-extensible-workflows", GIT_AUTHOR_EMAIL: "pi-extensible-workflows@localhost", GIT_COMMITTER_NAME: "pi-extensible-workflows", GIT_COMMITTER_EMAIL: "pi-extensible-workflows@localhost",
@@ -192,8 +198,10 @@ export class RunStore {
     stateWrite = Promise.resolve();
     worktreeWrite = Promise.resolve();
     snapshotWrite = Promise.resolve();
+    launchSnapshotWrite = Promise.resolve();
     // ponytail: the session lease prevents concurrent RunStore writers for one run.
     systemPromptWrite = Promise.resolve();
+    conversationWrite = Promise.resolve();
     constructor(cwd, sessionId, runId, home = homedir()) {
         this.cwd = cwd;
         this.sessionId = sessionId;
@@ -208,12 +216,14 @@ export class RunStore {
         await mkdir(dirname(this.directory), { recursive: true, mode: 0o700 });
         await mkdir(temporary, { mode: 0o700 });
         try {
+            await writeFile(join(temporary, "workflow.js"), snapshot.script, { encoding: "utf8", mode: 0o600 });
             await atomicJson(join(temporary, "snapshot.json"), snapshot);
-            await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {} });
+            await atomicJson(join(temporary, "journal.json"), { completed: {}, awaiting: {}, decisions: {} });
             await atomicJson(join(temporary, "ownership.json"), []);
             await atomicJson(join(temporary, "worktrees.json"), []);
             await atomicJson(join(temporary, "state.json"), run);
             await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
+            await atomicJson(join(temporary, "conversations.json"), { version: 1, conversations: {} });
             await rename(temporary, this.directory);
         }
         catch (error) {
@@ -261,6 +271,14 @@ export class RunStore {
         await write;
         return result;
     }
+    async saveSnapshot(snapshot) {
+        const write = this.launchSnapshotWrite.then(() => atomicJson(join(this.directory, "snapshot.json"), snapshot));
+        this.launchSnapshotWrite = write.catch(() => undefined);
+        await write;
+    }
+    async appendEvent(event) {
+        await this.updateState((run) => ({ ...run, events: [...(run.events ?? []), ...(run.events?.some((current) => current.message === event.message) ? [] : [event])] }));
+    }
     async saveOwnership(nodes) {
         await atomicJson(join(this.directory, "ownership.json"), nodes);
     }
@@ -284,6 +302,54 @@ export class RunStore {
         return (await json(this.systemPromptPath()).catch((error) => { if (error.code === "ENOENT")
             return { version: 1, entries: [] }; throw error; })).entries;
     }
+    conversationPath() { return join(this.directory, "conversations.json"); }
+    async conversation(id) {
+        await this.conversationWrite;
+        let artifact;
+        try {
+            const raw = await json(this.conversationPath());
+            if (!isConversationArtifact(raw))
+                throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt");
+            artifact = raw;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            if (error instanceof WorkflowError)
+                throw error;
+            throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return artifact.conversations[id];
+    }
+    async saveConversation(conversation) {
+        const write = this.conversationWrite.then(async () => {
+            const path = this.conversationPath();
+            let artifact;
+            try {
+                const raw = await json(path);
+                if (!isConversationArtifact(raw))
+                    throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt");
+                artifact = raw;
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    artifact = { version: 1, conversations: {} };
+                else if (error instanceof WorkflowError)
+                    throw error;
+                else
+                    throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const previous = artifact.conversations[conversation.id];
+            if (previous && previous.head.turn + 1 !== conversation.head.turn)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation head is not the previous turn: ${conversation.id}`);
+            if (!previous && conversation.head.turn !== 1)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation must start at turn one: ${conversation.id}`);
+            artifact.conversations[conversation.id] = structuredClone(conversation);
+            await atomicJson(path, artifact);
+        });
+        this.conversationWrite = write.catch(() => undefined);
+        await write;
+    }
     async updateJournal(update) {
         let result;
         const write = this.journalWrite.then(async () => {
@@ -322,13 +388,31 @@ export class RunStore {
         const journal = await json(join(this.directory, "journal.json"));
         return Object.values(journal.awaiting ?? {});
     }
+    async requestWorkflowDecision(request) {
+        await this.updateJournal((journal) => { journal.decisions ??= {}; journal.decisions[request.proposalId] = request; });
+    }
+    async pendingWorkflowDecisions() {
+        await this.journalWrite;
+        const journal = await json(join(this.directory, "journal.json"));
+        return Object.values(journal.decisions ?? {});
+    }
+    async answerWorkflowDecision(proposalId, approved) {
+        return this.updateJournal((journal) => {
+            const request = journal.decisions?.[proposalId];
+            if (!request)
+                return undefined;
+            journal.completed[`decision/${proposalId}`] = { path: `decision/${proposalId}`, value: approved };
+            delete journal.decisions?.[proposalId];
+            return request;
+        });
+    }
     async answerCheckpoint(name, approved) {
         return this.updateJournal((journal) => {
-            const checkpoint = Object.values(journal.awaiting).find((item) => item.name === name);
+            const checkpoint = Object.values(journal.awaiting ?? {}).find((item) => item.name === name);
             if (!checkpoint || journal.completed[checkpoint.path])
                 return undefined;
             journal.completed[checkpoint.path] = { path: checkpoint.path, value: approved };
-            journal.awaiting = Object.fromEntries(Object.entries(journal.awaiting).filter(([path]) => path !== checkpoint.path));
+            journal.awaiting = Object.fromEntries(Object.entries(journal.awaiting ?? {}).filter(([path]) => path !== checkpoint.path));
             return checkpoint;
         });
     }
@@ -461,9 +545,19 @@ export class RunStore {
         try {
             const write = this.snapshotWrite.then(async () => {
                 const record = await this.worktree(owner);
-                await git(record.path, ["add", "-A"]);
-                if ((await git(record.path, ["status", "--porcelain"])).trim())
-                    await git(record.path, ["commit", "-m", "pi-extensible-workflows runtime snapshot"], gitIdentity);
+                for (let attempt = 0; attempt < 3; attempt += 1) {
+                    await git(record.path, ["add", "-A"]);
+                    if (!(await git(record.path, ["status", "--porcelain"])).trim())
+                        break;
+                    try {
+                        await git(record.path, ["commit", "-m", "pi-extensible-workflows runtime snapshot"], gitIdentity);
+                        break;
+                    }
+                    catch (error) {
+                        if (attempt === 2)
+                            throw error;
+                    }
+                }
                 return (await git(record.path, ["rev-parse", "HEAD"])).trim();
             });
             this.snapshotWrite = write.then(() => undefined, () => undefined);

package/dist/src/session-inspector.d.ts

@@ -1,5 +1,6 @@
 import { type SessionEntry, type SessionInfo } from "@earendil-works/pi-coding-agent";
-import { type ModelSpec, type StaticWorkflowCall } from "./index.js";
+import { type AgentSetupSummary, type ModelSpec, type StaticWorkflowCall } from "./index.js";
+import { type PersistedRun } from "./persistence.js";
 export interface ModelUsage {
     model: string;
     cost: number;
@@ -12,16 +13,19 @@ export interface AttemptReport {
     cost: number;
     models: readonly ModelUsage[];
     error?: string;
+    setup?: AgentSetupSummary;
 }
 export interface AgentReport {
     name: string;
     label?: string;
     state: string;
     role?: string;
+    requestedModel?: string;
     model: string;
     thinking?: ModelSpec["thinking"];
     cost: number;
     attempts: readonly AttemptReport[];
+    setup?: AgentSetupSummary;
 }
 export interface WorkflowReport {
     name: string;
@@ -34,6 +38,14 @@ export interface WorkflowReport {
     cost: number;
     models: readonly ModelUsage[];
     agents: readonly AgentReport[];
+    budget?: PersistedRun["budget"];
+    budgetVersion?: number;
+    usage?: PersistedRun["usage"];
+    budgetEvents?: PersistedRun["budgetEvents"];
+    events?: readonly {
+        type: string;
+        message: string;
+    }[];
 }
 export interface SessionReport {
     id: string;

package/dist/src/session-inspector.js

@@ -4,7 +4,7 @@ import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { highlightCode, initTheme, SessionManager, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
-import { inspectWorkflowScript } from "./index.js";
+import { formatBudgetStatus, inspectWorkflowScript } from "./index.js";
 import { listRunIds, RunStore } from "./persistence.js";
 function text(content) {
     if (typeof content === "string")
@@ -170,6 +170,7 @@ async function agentReport(agent) {
                 cost,
                 models: log.models.length ? log.models : [{ model, cost }],
                 ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
+                ...(attempt.setup ? { setup: attempt.setup } : {}),
             });
             continue;
         }
@@ -182,6 +183,7 @@ async function agentReport(agent) {
             cost,
             models: [{ model: fallbackModel, cost }],
             ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
+            ...(attempt.setup ? { setup: attempt.setup } : {}),
         });
     }
     if (!attempts.length) {
@@ -189,7 +191,7 @@ async function agentReport(agent) {
         attempts.push({ attempt: 1, prompt: "(transcript unavailable)", model: fallbackModel, ...(fallbackThinking !== undefined ? { thinking: fallbackThinking } : {}), cost, models: [{ model: fallbackModel, cost }] });
     }
     const latest = attempts[attempts.length - 1];
-    return { name: agent.name, ...(agent.label ? { label: agent.label } : {}), state: agent.state, ...(agent.role ? { role: agent.role } : {}), model: latest?.model ?? fallbackModel, ...(latest?.thinking !== undefined ? { thinking: latest.thinking } : {}), cost: attempts.reduce((sum, attempt) => sum + attempt.cost, 0), attempts };
+    return { name: agent.name, ...(agent.label ? { label: agent.label } : {}), state: agent.state, ...(agent.role ? { role: agent.role } : {}), ...(agent.requestedModel ? { requestedModel: agent.requestedModel } : {}), model: latest?.model ?? fallbackModel, ...(latest?.thinking !== undefined ? { thinking: latest.thinking } : {}), cost: attempts.reduce((sum, attempt) => sum + attempt.cost, 0), attempts, ...(latest?.setup ? { setup: latest.setup } : {}) };
 }
 export function matchSession(query, sessions) {
     const exact = sessions.filter(({ id }) => id === query);
@@ -242,6 +244,11 @@ export async function loadSessionReport(path, home = homedir()) {
             cost: agents.reduce((sum, agent) => sum + agent.cost, 0),
             models,
             agents,
+            ...(loaded?.run.budget ? { budget: loaded.run.budget } : {}),
+            ...(loaded?.run.budgetVersion !== undefined ? { budgetVersion: loaded.run.budgetVersion } : {}),
+            ...(loaded?.run.usage ? { usage: loaded.run.usage } : {}),
+            ...(loaded?.run.budgetEvents ? { budgetEvents: loaded.run.budgetEvents } : {}),
+            ...(loaded?.run.events?.length ? { events: loaded.run.events } : {})
         });
     }
     const workflowCost = workflows.reduce((sum, workflow) => sum + workflow.cost, 0);
@@ -263,7 +270,9 @@ function detailLines(workflow) {
         style(ansi.bold + ansi.cyan, workflow.name),
         `${workflow.status} · ${money(workflow.cost)}${workflow.runId ? ` · ${workflow.runId}` : ""}`,
         workflow.description ?? "",
+        ...(workflow.events?.length ? ["", style(ansi.bold, "Run events"), ...workflow.events.map((event) => `${event.type}: ${event.message}`)] : []),
         "",
+        ...(workflow.budget ? formatBudgetStatus({ budget: workflow.budget, ...(workflow.budgetVersion !== undefined ? { budgetVersion: workflow.budgetVersion } : {}), ...(workflow.usage ? { usage: workflow.usage } : {}), ...(workflow.budgetEvents ? { budgetEvents: workflow.budgetEvents } : {}) }).map((line) => `Budget ${line}`) : []),
         style(ansi.bold, "Models"),
         modelSummary(workflow.models),
         "",
@@ -278,9 +287,18 @@ function detailLines(workflow) {
     if (!workflow.agents.length)
         lines.push("(no agent run was persisted)");
     for (const agent of workflow.agents) {
-        lines.push("", style(agent.state === "completed" ? ansi.green : agent.state === "failed" ? ansi.red : ansi.yellow, `${agent.label ?? agent.name} [${agent.state}]`), `${agent.role ? `role=${agent.role} · ` : ""}${agent.model}${agent.thinking !== undefined ? `:${agent.thinking}` : ""} · ${money(agent.cost)}`);
+        lines.push("", style(agent.state === "completed" ? ansi.green : agent.state === "failed" ? ansi.red : ansi.yellow, `${agent.label ?? agent.name} [${agent.state}]`), `${agent.role ? `role=${agent.role} · ` : ""}${agent.requestedModel ? `requested=${agent.requestedModel} · ` : ""}${agent.model}${agent.thinking !== undefined ? `:${agent.thinking}` : ""} · ${money(agent.cost)}`);
         for (const attempt of agent.attempts) {
-            lines.push(`Attempt ${String(attempt.attempt)} · ${attempt.model}${attempt.thinking !== undefined ? `:${attempt.thinking}` : ""} · ${money(attempt.cost)}${attempt.error ? ` · ${attempt.error}` : ""}`, `Prompt: ${attempt.prompt}`);
+            lines.push(`Attempt ${String(attempt.attempt)} · ${attempt.model}${attempt.thinking !== undefined ? `:${attempt.thinking}` : ""} · ${money(attempt.cost)}${attempt.error ? ` · ${attempt.error}` : ""}`, `Prompt: ${attempt.prompt}`, ...(attempt.setup ? [
+                `Hooks: ${attempt.setup.hookNames.join(", ") || "(none)"}`,
+                `Effective: model=${attempt.setup.model.provider}/${attempt.setup.model.model}${attempt.setup.model.thinking ? `:${attempt.setup.model.thinking}` : ""} tools=${attempt.setup.tools.join(",") || "(none)"} cwd=${attempt.setup.cwd}`,
+                ...(attempt.setup.disabledAgentResources ? [
+                    `Disabled skills: ${attempt.setup.disabledAgentResources.skills.join(", ") || "(none)"}`,
+                    `Disabled extensions: ${attempt.setup.disabledAgentResources.extensions.join(", ") || "(none)"}`,
+                    `Unmatched skills: ${attempt.setup.disabledAgentResources.unmatchedSkills.join(", ") || "(none)"}`,
+                    `Unmatched extensions: ${attempt.setup.disabledAgentResources.unmatchedExtensions.join(", ") || "(none)"}`,
+                ] : []),
+            ] : []));
         }
     }
     return lines.filter((line, index) => line || index !== 2);

package/dist/src/workflow-evals.js

@@ -14,7 +14,7 @@ export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "ba
 const EVAL_MODEL_TOKEN = "$EVAL_MODEL";
 const semantic = (description) => [{ id: "intent", description }];
 const JSON_RESULT_TYPES = ["null", "boolean", "number", "integer", "string", "array", "object"];
-const WORKFLOW_CALL_KINDS = ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"];
+const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"];
 const AGENT_OPTION_NAMES = ["role", "model", "thinking", "tools", "retries"];
 const expectationKeys = ["firstSignificantAction", "firstTool", "firstBatchToolSequence", "parentToolSequence", "workflowCallCount", "requiredOperations", "forbiddenOperations", "requiredRoles", "minimumAgentCalls", "requireOutputSchema", "expectedResults", "agentPolicies", "requiredAgentOrder", "requiredAgentStructures", "requiredDataFlow"];
 const caseKeys = ["id", "prompt", "timeoutMs", "maxCost", "expectations", "expectedWorkflowCalls", "semanticCriteria"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": { "type": "git", "url": "git+https://github.com/vekexasia/pi-extensible-workflows.git" },

package/skills/pi-extensible-workflows/SKILL.md

@@ -34,10 +34,11 @@ return agent(
 
 To pass structured input from the main agent, include `args`:
 ```json
-{ "workflow": "namespace.workflowName", "args": { "issue": 42 } }
+{ "workflow": "workflowName", "args": { "issue": 42 } }
 ```
 Inside the workflow, read `args.issue`; omitted `args` is `null`.
-If `workflow_catalog` is available, call it once before creating the first workflow for a task. Use the returned global functions, variables, and registered workflows as needed for the rest of that task. Do not try to reinvent already exposed functions.
+Use `workflow_stop` with the exact run ID to stop an active background run from the current Pi session.
+If `workflow_catalog` is available, call it once before creating the first workflow for a task. Use the returned global functions, variables, registered workflows, and configured model aliases as needed for the rest of that task. Alias targets are catalog metadata, not an availability probe. Do not try to reinvent already exposed functions.
 
 Pass downstream only needed results. Workflow JavaScript has no imports, filesystem, network, process, or timers; delegate such work to agents with the required tools.
 
@@ -46,7 +47,7 @@ Pass downstream only needed results. Workflow JavaScript has no imports, filesys
 ```typescript
 interface AgentOptions {
   label?: string; // optional non-empty display name
-  model?: `${provider}/${model}` | `${provider}/${model}:${thinking}`;
+  model?: string; // configured alias or provider/model[:thinking]
   thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
   role?: string; // one of the available workflow roles
   tools?: string[]; // [] = no tools; omitted uses role or launch tools
@@ -56,7 +57,9 @@ interface AgentOptions {
 }
 ```
 
-Agent calls are unnamed. Direct `agent(...)` calls receive hidden source call-site identity; aliases are unsupported. Calls from one source call site must not race outside `parallel` or `pipeline`, whose structural keys keep replay deterministic.
+Extensions may define additional JSON-compatible agent option keys such as `advisor: true`. Core-owned keys still use the validation and role constraints above; extension options are passed to setup hooks and native setup but are not inherited by child agents.
+
+Agent calls are unnamed. Direct `agent(...)` calls receive hidden source call-site identity; JavaScript aliases for workflow calls are unsupported. Calls from one source call site must not race outside `parallel` or `pipeline`, whose structural keys keep replay deterministic.
 
 ## Shared worktree scope
 
@@ -101,7 +104,8 @@ Registered extension functions receive `withWorktree` in their context, so they
 - Preserve item metadata in workflow code between pipeline stages instead of requiring agents to echo it through `outputSchema`.
 - Repeated work uses a JavaScript loop; each direct `agent(...)` call receives deterministic call-site and occurrence identity.
 - Runs default to background; set tool-call `foreground: true` when asked to wait.
-- Omit `maxAgentLaunches` unless an explicit total launch budget is required.
+- Add `budget` only when the run needs aggregate token, cost, duration, or launch limits; each dimension accepts optional `soft` and `hard` values. Soft crossings request wrap-up, while hard exhaustion blocks further budgeted work.
+- A `budget_exhausted` run is resumable through `workflow_resume`. Omitted patch values stay unchanged, explicit `null` removes a limit, and any relaxation requires an exact human-approved proposal through `workflow_respond`.
 - `parallel()` and `pipeline()` return keyed bare values. Await results before use.
 - Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings stay literal.
 - Use `outputSchema` only when another phase must compare, aggregate, or validate the result. Never add it to a final agent whose prose is returned directly. Keep only fields the consumer needs, and avoid repeating the same evidence in multiple schemas.