pi-extensible-workflows 3.3.0 → 3.4.1

package/dist/src/registry.js

@@ -29,6 +29,7 @@ export class WorkflowRegistry {
     #extensions = new Set();
     #globals = new Map();
     #hooks = new Map();
+    #agentAttemptActions = new Map();
     #roleDirectories = new Map();
     #modelAliases = new Map();
     #frozen = false;
@@ -39,18 +40,19 @@ export class WorkflowRegistry {
             fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
         if (object(extension) && Object.prototype.hasOwnProperty.call(extension, "workflows"))
             fail("INVALID_METADATA", "Separate registered workflow definitions were removed; register a function with input and output schemas instead");
-        if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "modelAliases", "agentSetupHooks", "roleDirectories"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim())
+        if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "modelAliases", "agentSetupHooks", "agentAttemptActions", "roleDirectories"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim())
             fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
         const functions = extension.functions ?? {};
         const variables = extension.variables ?? {};
         const modelAliases = extension.modelAliases ?? {};
         const agentSetupHooks = extension.agentSetupHooks ?? {};
+        const agentAttemptActions = extension.agentAttemptActions ?? {};
         const roleDirectoryValues = extension.roleDirectories === undefined ? [] : extension.roleDirectories;
         if (!Array.isArray(roleDirectoryValues))
             fail("INVALID_METADATA", "Workflow extension roleDirectories must be an array");
         const roleDirectories = [...new Set(Array.from(roleDirectoryValues, (value) => normalizeRoleDirectory(value)))];
-        if (!object(functions) || !object(variables) || !object(modelAliases) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentSetupHooks).length === 0 && roleDirectories.length === 0))
-            fail("INVALID_METADATA", "Workflow extensions require functions, variables, model aliases, agent setup hooks, or role directories");
+        if (!object(functions) || !object(variables) || !object(modelAliases) || !object(agentSetupHooks) || !object(agentAttemptActions) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentSetupHooks).length === 0 && Object.keys(agentAttemptActions).length === 0 && roleDirectories.length === 0))
+            fail("INVALID_METADATA", "Workflow extensions require functions, variables, model aliases, agent setup hooks, agent attempt actions, or role directories");
         const names = [...Object.keys(functions), ...Object.keys(variables)];
         if (new Set(names).size !== names.length)
             fail("GLOBAL_COLLISION", "Global name collision inside extension");
@@ -89,7 +91,13 @@ export class WorkflowRegistry {
             if (this.#hooks.has(name))
                 fail("DUPLICATE_NAME", `Agent setup hook already registered: ${name}`);
         }
-        const stored = deepFreeze({ ...extension, functions, variables, modelAliases, agentSetupHooks, ...(roleDirectories.length ? { roleDirectories } : {}) });
+        for (const [name, action] of Object.entries(agentAttemptActions)) {
+            if (!IDENTIFIER.test(name) || !object(action) || Object.keys(action).some((key) => !["label", "visible", "run"].includes(key)) || typeof action.label !== "string" || !action.label.trim() || typeof action.visible !== "function" || typeof action.run !== "function")
+                fail("INVALID_METADATA", `Invalid agent attempt action: ${name}`);
+            if (this.#agentAttemptActions.has(name))
+                fail("DUPLICATE_NAME", `Agent attempt action already registered: ${name}`);
+        }
+        const stored = deepFreeze({ ...extension, functions, variables, modelAliases, agentSetupHooks, agentAttemptActions, ...(roleDirectories.length ? { roleDirectories } : {}) });
         this.#extensions.add(stored);
         for (const directory of roleDirectories)
             if (!this.#roleDirectories.has(directory))
@@ -100,6 +108,8 @@ export class WorkflowRegistry {
             this.#modelAliases.set(name, { name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, resolve: alias.resolve });
         for (const [name, hook] of Object.entries(agentSetupHooks))
             this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
+        for (const [name, action] of Object.entries(agentAttemptActions))
+            this.#agentAttemptActions.set(name, action);
     }
     function(name) {
         if (!IDENTIFIER.test(name))
@@ -197,6 +207,7 @@ export class WorkflowRegistry {
     agentSetupHooks() {
         return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
     }
+    agentAttemptActions() { return Object.freeze(Object.fromEntries(this.#agentAttemptActions.entries())); }
     roleDirectories() {
         return [...this.#roleDirectories.keys()];
     }
@@ -250,6 +261,7 @@ function createWorkflowRegistryApi(registry) {
         roleDirectories: () => registry.roleDirectories(),
         roleDirectoryRegistrations: () => registry.roleDirectoryRegistrations(),
         agentSetupHooks: () => registry.agentSetupHooks(),
+        agentAttemptActions: () => registry.agentAttemptActions(),
     };
 }
 function workflowRegistryHost() {

package/dist/src/session-inspector.js

@@ -115,6 +115,13 @@ function readTranscript(path) {
         return undefined;
     }
 }
+function attemptTranscriptPath(attempt) {
+    const session = attempt.session;
+    if (!session || session.transport !== "local" || typeof session.locator !== "object" || session.locator === null || Array.isArray(session.locator))
+        return undefined;
+    const path = session.locator.sessionFile;
+    return typeof path === "string" && path ? path : undefined;
+}
 function resultRunId(result) {
     if (!result)
         return undefined;
@@ -161,33 +168,18 @@ async function agentReport(agent) {
     const fallbackThinking = agent.model.thinking;
     const attempts = [];
     for (const attempt of agent.attemptDetails ?? []) {
-        const log = readTranscript(attempt.sessionFile);
+        const setup = attempt.setup;
+        const path = attemptTranscriptPath(attempt);
+        const log = path ? readTranscript(path) : undefined;
         if (log) {
-            const model = log.model ?? fallbackModel;
+            const model = log.model ?? `${setup.model.provider}/${setup.model.model}`;
             const cost = log.cost;
-            attempts.push({
-                attempt: attempt.attempt,
-                prompt: log.prompt ?? "(transcript unavailable)",
-                model,
-                ...(log.thinking !== undefined ? { thinking: log.thinking } : {}),
-                cost,
-                models: log.models.length ? log.models : [{ model, cost }],
-                ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
-                ...(attempt.setup ? { setup: attempt.setup } : {}),
-            });
+            attempts.push({ attempt: attempt.attempt, prompt: log.prompt ?? "(transcript unavailable)", model, ...(log.thinking !== undefined ? { thinking: log.thinking } : {}), cost, models: log.models.length ? log.models : [{ model, cost }], ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}), setup });
             continue;
         }
+        const model = `${setup.model.provider}/${setup.model.model}`;
         const cost = attempt.accounting.cost;
-        attempts.push({
-            attempt: attempt.attempt,
-            prompt: "(transcript unavailable)",
-            model: fallbackModel,
-            ...(fallbackThinking !== undefined ? { thinking: fallbackThinking } : {}),
-            cost,
-            models: [{ model: fallbackModel, cost }],
-            ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}),
-            ...(attempt.setup ? { setup: attempt.setup } : {}),
-        });
+        attempts.push({ attempt: attempt.attempt, prompt: "(transcript unavailable)", model, ...(setup.model.thinking !== undefined ? { thinking: setup.model.thinking } : {}), cost, models: [{ model, cost }], ...(attempt.error ? { error: `${attempt.error.code}: ${attempt.error.message}` } : {}), setup });
     }
     if (!attempts.length) {
         const cost = agent.accounting?.cost ?? 0;

package/dist/src/types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSessionEvent, CreateAgentSessionOptions, InlineExtension, SessionStats, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CreateAgentSessionOptions, InlineExtension, ToolDefinition } from "@earendil-works/pi-coding-agent";
 export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export declare const AGENT_STATES: readonly ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
 export declare const WORKFLOW_CALL_KINDS: readonly ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
@@ -193,10 +193,10 @@ export interface AgentResourcePolicy {
     global: AgentResourceExclusions;
     project: AgentResourceExclusions;
     effective: AgentResourceExclusions;
-    unmatchedSkills: string[];
-    unmatchedExtensions: string[];
-    excludedSkills?: string[];
-    excludedExtensions?: string[];
+    unmatchedSkills: readonly string[];
+    unmatchedExtensions: readonly string[];
+    excludedSkills?: readonly string[];
+    excludedExtensions?: readonly string[];
 }
 export interface AgentActivity {
     kind: "reasoning" | "tool" | "text";
@@ -224,22 +224,17 @@ export interface AgentSetupSummary {
         unmatchedExtensions: readonly string[];
     };
 }
+export interface AgentAttemptError {
+    code: string;
+    message: string;
+}
 export interface AgentAttemptSummary {
     attempt: number;
-    sessionId: string;
-    sessionFile: string;
-    error?: {
-        code: string;
-        message: string;
-    };
-    accounting: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: number;
-    };
-    setup?: AgentSetupSummary;
+    transport: string;
+    session?: WorkflowAgentSessionReference;
+    setup: AgentSetupSummary;
+    error?: AgentAttemptError;
+    accounting: AgentAccounting;
 }
 export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase {
     owner: string;
@@ -252,6 +247,8 @@ export interface WorkflowWorktreeReference {
     readonly branch: string;
 }
 export interface AgentRecord {
+    systemPrompt?: string;
+    prompt?: string;
     id: string;
     name: string;
     label?: string;
@@ -311,6 +308,7 @@ export interface RunRecord {
     cwd: string;
     sessionId: string;
     state: RunState;
+    agentSessions: readonly WorkflowAgentSessionReference[];
     parentRunId?: string;
     retry?: WorkflowRetryProvenance;
     phase?: string;
@@ -413,47 +411,65 @@ export interface WorkflowVariable {
     schema: JsonSchema;
     resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue;
 }
-type NativeAgentMessage = {
-    role: string;
-    content?: unknown;
-    stopReason?: string;
-    errorMessage?: string;
-    usage?: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: {
-            total: number;
-        };
-    };
-};
-type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
-export interface NativeSession {
+export interface WorkflowAgentSessionReference {
+    readonly transport: string;
     readonly sessionId: string;
-    readonly sessionFile: string | undefined;
-    readonly messages: readonly NativeAgentMessage[];
-    getSessionStats(): NativeSessionStats;
-    readonly systemPrompt?: string;
-    readonly model?: {
-        provider: string;
-        model?: string;
-        id?: string;
+    readonly locator?: JsonValue;
+}
+export interface WorkflowAgentSessionStats {
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly total: number;
     };
-    readonly agent?: {
-        state: {
-            tools: readonly {
-                name: string;
-            }[];
+    readonly cost: number;
+}
+export interface WorkflowAgentMessage {
+    readonly role: string;
+    readonly content?: unknown;
+    readonly stopReason?: string;
+    readonly errorMessage?: string;
+    readonly usage?: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly cost: {
+            readonly total: number;
         };
     };
-    getLeafId?: () => string | null;
-    getToolDefinitions?: () => unknown;
-    subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
-    prompt(text: string): Promise<void>;
-    steer?(text: string): Promise<void>;
-    abort?(): Promise<void>;
-    dispose(): void;
+}
+export interface WorkflowAgentSessionState {
+    readonly model: ModelSpec;
+    readonly thinking?: ModelSpec["thinking"];
+    readonly tools: readonly string[];
+    readonly systemPrompt?: string;
+}
+export interface WorkflowAgentSessionEvent {
+    readonly type: string;
+    readonly state?: Readonly<WorkflowAgentSessionState>;
+    readonly message?: WorkflowAgentMessage;
+    readonly assistantMessageEvent?: {
+        readonly type: string;
+    };
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly isError?: boolean;
+}
+export interface WorkflowAgentTurnResult {
+    readonly assistant?: WorkflowAgentMessage;
+}
+export interface WorkflowAgentSession {
+    readonly reference: WorkflowAgentSessionReference;
+    getState(): Readonly<WorkflowAgentSessionState>;
+    getSessionStats(): WorkflowAgentSessionStats;
+    subscribe(listener: (event: WorkflowAgentSessionEvent) => void): () => void;
+    prompt(text: string): Promise<WorkflowAgentTurnResult>;
+    steer(text: string): Promise<void>;
+    abort(): Promise<void>;
+    dispose(): Promise<void>;
 }
 type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
 type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
@@ -472,12 +488,37 @@ export interface SessionInput {
     resourcePolicy?: AgentResourcePolicy;
     options?: AgentOptions;
 }
-export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
+export interface PreparedAgentSession {
+    readonly cwd: string;
+    readonly model: ModelSpec;
+    readonly tools: readonly string[];
+    readonly sessionLabel: string;
+    readonly agentDir?: string;
+    readonly customTools?: readonly ToolDefinition[];
+    readonly resultTool?: ToolDefinition;
+    readonly options?: Readonly<Record<string, JsonValue>>;
+    readonly systemPrompt?: string;
+    readonly systemPromptAppend?: string;
+    readonly extensionFactories?: readonly InlineExtension[];
+    readonly additionalSkillPaths?: readonly string[];
+    readonly resourcePolicy?: Readonly<AgentResourcePolicy>;
+}
+export interface AgentTransportContext {
+    readonly run: Readonly<WorkflowRunContext>;
+    readonly identity: Readonly<AgentIdentity>;
+    readonly attempt: number;
+    readonly signal: AbortSignal;
+}
+export interface AgentTransport {
+    readonly id: string;
+    createSession(prepared: Readonly<PreparedAgentSession>, context: Readonly<AgentTransportContext>): Promise<WorkflowAgentSession>;
+}
 export interface AgentSetup {
     prompt: string;
     options: AgentOptions;
     sessionInput: SessionInput;
-    createSession: SessionFactory;
+    prepared: Readonly<PreparedAgentSession>;
+    transport: AgentTransport;
 }
 export interface AgentSetupContext {
     readonly run: Readonly<WorkflowRunContext>;
@@ -503,11 +544,32 @@ export interface WorkflowRoleDirectoryRegistration {
     path: string;
     extension: WorkflowExtensionMetadata;
 }
+export interface AgentAttemptActionUi {
+    notify(message: string, level?: "info" | "warning" | "error"): void;
+    confirm(title: string, message: string): Promise<boolean>;
+    select(title: string, options: readonly string[]): Promise<string | undefined>;
+    input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+export interface AgentAttemptActionContext {
+    readonly run: Readonly<RunRecord>;
+    readonly agent: Readonly<AgentRecord>;
+    readonly attempt: Readonly<AgentAttemptSummary>;
+    readonly session?: WorkflowAgentSessionReference;
+    readonly liveSession?: WorkflowAgentSession;
+    readonly signal: AbortSignal;
+    readonly ui: Readonly<AgentAttemptActionUi>;
+}
+export interface AgentAttemptAction {
+    readonly label: string;
+    visible(context: Readonly<AgentAttemptActionContext>): boolean;
+    run(context: Readonly<AgentAttemptActionContext>): void | Promise<void>;
+}
 export interface WorkflowExtension extends WorkflowExtensionMetadata {
     functions?: Readonly<Record<string, WorkflowFunction>>;
     variables?: Readonly<Record<string, WorkflowVariable>>;
     modelAliases?: Readonly<Record<string, WorkflowModelAlias>>;
     agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
+    agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>>;
     roleDirectories?: readonly (string | URL)[];
 }
 export interface WorkflowJournal {
@@ -524,8 +586,8 @@ export interface WorkflowFailureAgent {
     role?: string;
     structuralPath: readonly string[];
     attempt: number;
-    sessionId?: string;
-    sessionFile?: string;
+    transport?: string;
+    session?: WorkflowAgentSessionReference;
 }
 export interface WorkflowSiblingAgent {
     id: string;
@@ -687,6 +749,7 @@ export interface WorkflowValidationParameters {
     name?: string;
     description?: string;
     script?: string;
+    scriptPath?: string;
     workflow?: string;
     args?: unknown;
 }

package/dist/src/validation.js

@@ -825,10 +825,25 @@ export function validateWorkflowLaunchWithRegistry(params, context, registry) {
         fail("INVALID_METADATA", "maxAgentLaunches has been removed; use budget.agentLaunches");
     if (params.script !== undefined && params.workflow !== undefined)
         fail("INVALID_METADATA", "Provide either script or workflow, not both");
+    if (params.scriptPath !== undefined && (typeof params.scriptPath !== "string" || !params.scriptPath.trim()))
+        fail("INVALID_METADATA", "scriptPath must be a non-empty path");
+    if ((params.script !== undefined || params.workflow !== undefined) && params.scriptPath !== undefined)
+        fail("INVALID_METADATA", "Provide either script, scriptPath, or workflow, not more than one");
+    const scriptPath = typeof params.scriptPath === "string" ? params.scriptPath.trim() : undefined;
+    let fileScript;
+    if (scriptPath !== undefined) {
+        try {
+            fileScript = readFileSync(resolve(context.cwd, scriptPath), "utf8");
+        }
+        catch (error) {
+            fail("INVALID_SYNTAX", `Cannot read workflow script file ${scriptPath}: ${errorText(error)}`);
+        }
+    }
     const functionName = typeof params.workflow === "string" ? params.workflow : undefined;
-    if (functionName !== undefined && params.name !== undefined)
-        fail("INVALID_METADATA", "Registered function launches do not accept name; workflow is the run name");
-    const workflowName = functionName ?? (typeof params.name === "string" ? params.name.trim() : "");
+    const explicitName = params.name === undefined ? undefined : typeof params.name === "string" ? params.name.trim() : "";
+    if (params.name !== undefined && !explicitName)
+        fail("INVALID_METADATA", "Workflow name must be non-empty when provided");
+    const workflowName = explicitName ?? functionName ?? "";
     if (functionName === undefined && !workflowName)
         fail("INVALID_METADATA", "Inline workflow launches require a non-empty name");
     const fn = functionName === undefined ? undefined : registry?.function(functionName);
@@ -837,9 +852,9 @@ export function validateWorkflowLaunchWithRegistry(params, context, registry) {
     const args = params.args === undefined ? null : params.args;
     if (functionName !== undefined && fn && (!object(args) || !jsonValue(args) || !Value.Check(fn.input, args)))
         fail("RESULT_INVALID", `Invalid input for ${functionName}`);
-    const script = functionName !== undefined && fn ? functionLaunchScript(functionName) : typeof params.script === "string" && params.script.trim() ? params.script : "";
+    const script = functionName !== undefined && fn ? functionLaunchScript(functionName) : typeof params.script === "string" && params.script.trim() ? params.script : fileScript ?? "";
     if (!script)
-        fail("INVALID_SYNTAX", "Provide script or registered function");
+        fail("INVALID_SYNTAX", "Provide script, scriptPath, or registered function");
     const metadata = validateWorkflowMetadata({ name: workflowName, ...(typeof params.description === "string" ? { description: params.description } : fn?.description ? { description: fn.description } : {}) });
     const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false, registry && typeof registry.roleDirectoryRegistrations === "function" ? registry.roleDirectoryRegistrations() : registry && typeof registry.roleDirectories === "function" ? registry.roleDirectories() : undefined);
     const projectAgentDefinitions = context.projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(context.cwd, ".pi"))) : {};

package/dist/src/workflow-artifacts.d.ts

@@ -9,5 +9,6 @@ export type WorkflowTui = {
     requestRender(force?: boolean): void;
 };
 export declare function workflowScriptArtifact(script: string): WorkflowArtifact;
+export declare function workflowPromptArtifact(prompt: string): WorkflowArtifact;
 export declare function workflowResultArtifact(value: JsonValue): WorkflowArtifact;
 export declare function openWorkflowArtifact(tui: WorkflowTui, command: string, artifact: WorkflowArtifact): Promise<number | null>;

package/dist/src/workflow-artifacts.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 export function workflowScriptArtifact(script) { return { extension: ".js", content: script }; }
+export function workflowPromptArtifact(prompt) { return { extension: ".md", content: prompt }; }
 export function workflowResultArtifact(value) { return typeof value === "string" ? { extension: ".md", content: value } : { extension: ".json", content: `${JSON.stringify(value, null, 2)}\n` }; }
 async function spawnWorkflowEditor(command, path) {
     const [editor, ...editorArgs] = command.split(" ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -33,7 +33,7 @@
     "inspect": "node dist/src/cli.js inspect",
     "lint": "eslint .",
     "test": "npm run build && TEST_FILES='dist/test/*.test.js' npm run test:run",
-    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test --test-concurrency=1 $TEST_FILES",
+    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test --test-concurrency=1 --test-reporter=dot $TEST_FILES",
     "acceptance": "npm run build && TEST_FILES='dist/test/runtime-acceptance.test.js' npm run test:run",
     "docs:check": "node scripts/check-docs.mjs",
     "check": "npm run lint && npm test && npm run docs:check",

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

@@ -27,15 +27,23 @@ Await `parallel(...)` or `pipeline(...)` results before interpolation. Runs are
 ## Runtime and safety rules
 
 
-Inline launches require a non-empty `name`. Registered function launches must omit `name`; they use `workflow` as the run name:
 
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId, foreground? })` replays a failed run into a child; `workflow_resume({ runId, budget?, foreground? })` continues a `budget_exhausted` run; recovery inherits the source snapshot's foreground/background launch mode, while legacy snapshots without `launchMode` recover in background; set `foreground: true` or `false` to override it; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
-For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground launches and foreground recovery retain their terminal value and completed `runId`, while background launches and recovery return `runId` immediately and deliver completion or failure as a follow-up. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
-Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
+
+A reviewed JavaScript file on disk can use `scriptPath` instead of `script`.
+
+Recovery map:
+  - `agent(..., { retries })` reruns one agent call in the same run for transient failures;
+  - `workflow_retry({ runId, foreground? })` replays a failed run into a child;
+  - `workflow_resume({ runId, budget?, foreground? })` continues a `budget_exhausted` run;
+  - recovery inherits the source snapshot's foreground/background launch mode, while legacy snapshots without `launchMode` recover in background; set `foreground: true` or `false` to override it;
+  - `parentRunId` on a new launch only borrows named worktrees and never replays or resumes.
+
+For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId, foreground: <prevValue> })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
+`workflow_stop` requires the exact run ID; foreground launches and foreground recovery retain their terminal value and completed `runId`, while background launches and recovery return `runId` immediately and deliver completion or failure as a follow-up. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
+Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task. Make sure to call workflow_catalog more than once if you need to inspect details about a global function.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.