pi-extensible-workflows 3.1.0 → 3.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 Turn multi-agent tasks into deterministic jobs that fan out in parallel, pause for approval, and resume without rerunning completed work.
 
-[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html) | [Extension authoring](https://vekexasia.github.io/pi-extensible-workflows/extensions.html)
+[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html) | [Extension authoring](https://vekexasia.github.io/pi-extensible-workflows/extensions.html) | [Video overview](https://youtu.be/qAiivspEHmU)
 
 Requires Node.js 22.19 or newer. This is a trusted Pi extension with the same filesystem and process access as Pi.
 
@@ -20,32 +20,24 @@ 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; every registered function is also directly runnable as a top-level workflow.
-
-Inline workflow launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
-
-A workflow can fan out across specialized agents, combine their results, and resume without rerunning completed work.
+The default path is a named inline workflow: write a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns. Inline launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Runs are backgrounded by default; set `foreground: true` when the final value must be returned in the same tool call.
 
 ```js
 const reviews = await parallel("review", {
-  correctness: () =>
-    agent("Review the current changes for correctness issues."),
-  security: () =>
-    agent("Review the current changes for security risks.", {
-      role: "security-specialist",
-    }),
+  correctness: () => agent("Review the current changes for correctness issues."),
+  security: () => agent("Review the current changes for security risks."),
   tests: () => agent("Review the current changes for missing test coverage."),
 });
 
-const summary = await agent(
-  prompt("Deduplicate and prioritize these findings:\n\n{reviews}", {
-    reviews,
-  }),
+return await agent(
+  prompt("Summarize and prioritize these findings:\n\n{reviews}", { reviews }),
 );
-
-return summary;
 ```
 
+**Advanced capabilities:** Use registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` when the task requires them. They remain available without complicating the basic inline path. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
+
+The main Pi agent writes these scripts on the fly for each task; extensions can add reusable functions and variables, and completed workflows can resume without rerunning completed work.
+
 Learn more about roles, workflow contracts, and extension APIs in the documentation:
 
 - [Workflow tool and invocation API](https://vekexasia.github.io/pi-extensible-workflows/developers.html#tool-api)
@@ -53,6 +45,7 @@ Learn more about roles, workflow contracts, and extension APIs in the documentat
 - [Aggregate run budgets](https://vekexasia.github.io/pi-extensible-workflows/developers.html#budgets)
 - [Workflow DSL and worktrees](https://vekexasia.github.io/pi-extensible-workflows/developers.html#dsl)
 - [Extension authoring guide](https://vekexasia.github.io/pi-extensible-workflows/extensions.html)
+- [Copy-paste extension template](https://github.com/vekexasia/pi-extensible-workflows/tree/main/examples/workflow-extension-template)
 - [Run artifacts and lifecycle events](https://vekexasia.github.io/pi-extensible-workflows/developers.html#lifecycle)
 - [Run inspection and recovery](https://vekexasia.github.io/pi-extensible-workflows/developers.html#operations)
 - [Agent patterns and model selection](https://vekexasia.github.io/pi-extensible-workflows/agents.html#patterns)

package/dist/src/execution.js

@@ -1,5 +1,5 @@
 import { fork, spawn } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
@@ -72,6 +72,7 @@ const named = (value, kind) => { if (typeof value !== "string" || !value.trim())
 const path = (...names) => names.map(encodeURIComponent).join("/");
 const inheritedAgentPath = new AsyncLocalStorage();
 const agentOccurrences = new Map();
+const agentInflight = new Set();
 const shellOccurrences = new Map();
 const worktreeOwners = new AsyncLocalStorage();
 const rejectAgent = () => { throw workError("INVALID_METADATA", "Workflow agent calls must use a direct agent(...) call; aliases and indirect calls are unsupported"); };
@@ -92,14 +93,22 @@ const internalAgent = (...values) => {
   const callSite = values.pop();
   if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow agent call-site identity");
   const inherited = inheritedAgentPath.getStore() || [];
-  // ponytail: same-callsite races outside parallel/pipeline lack a stable structural scope and are unsupported.
   const occurrenceKey = JSON.stringify([inherited, callSite]);
+  if (agentInflight.has(occurrenceKey)) throw workError("INVALID_METADATA", "Concurrent agent calls from the same source call site are unsupported; use parallel(...) or pipeline(...)");
+  agentInflight.add(occurrenceKey);
   const occurrence = (agentOccurrences.get(occurrenceKey) || 0) + 1;
   agentOccurrences.set(occurrenceKey, occurrence);
   const options = values.length < 2 || values[1] === undefined ? {} : values[1];
   const worktreeOwner = worktreeOwners.getStore();
   const identity = { structuralPath: [...inherited], callSite, occurrence, ...(worktreeOwner ? { worktreeOwner } : {}) };
-  const result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  let result;
+  try {
+    result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  } catch (error) {
+    agentInflight.delete(occurrenceKey);
+    throw error;
+  }
+  void result.then(() => agentInflight.delete(occurrenceKey), () => agentInflight.delete(occurrenceKey));
   Object.defineProperties(result, {
     toJSON: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before serialization"); } },
     toString: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before interpolation"); } },
@@ -421,7 +430,7 @@ function workflowErrorFromWorker(error) {
 export function runWorkflow(script, args = null, bridge = {}, signal) {
     encoded(args);
     const config = JSON.stringify({ script: instrumentWorkflow(script), args: structuredClone(args), functions: bridge.functions ?? {}, variables: bridge.variables ?? {} });
-    const childDir = mkdtempSync(join(tmpdir(), "pi-wf-"));
+    const childDir = realpathSync(mkdtempSync(join(tmpdir(), "pi-wf-")));
     const childFile = join(childDir, "child.cjs");
     writeFileSync(childFile, childSource);
     const child = fork(childFile, [String(RPC_LIMIT_BYTES), config], {

package/dist/src/host.d.ts

@@ -34,8 +34,8 @@ export declare function formatWorkflowPreview(args: {
     description?: unknown;
 }): string;
 export declare const WORKFLOW_TOOL_LABEL = "Workflow";
-export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow";
-export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline launches require an explicit non-empty name; registered function launches reject name and use workflow as the run name. Runs in the background by default; completion arrives as a follow-up message. Foreground results include the completed run ID. Use workflow_retry with an explicit failed run ID to replay completed structural operations; parentRunId only reuses named worktrees.";
+export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow with a named inline parallel-to-summary path by default";
+export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow. Prefer a named inline script that fans out independent work with parallel(...), awaits the keyed results before interpolating them into one summarizing agent(...), and returns. Inline launches require an explicit non-empty name; registered function launches reject name and use workflow as the run name. Advanced controls include registered functions, outputSchema, budgets, checkpoints, worktrees, retry/resume, CLI export, and pipelines. Use workflow_retry with an explicit failed run ID; parentRunId only reuses named worktrees. Runs are in the background by default; completion arrives as a follow-up message. Set foreground: true when the caller must wait for the final value. Foreground results include the completed run ID. Recovery map: agent(..., { retries }) reruns one agent call in the same run for transient failures; workflow_retry({ runId }) replays a failed run into a child; workflow_resume({ runId, budget? }) continues a budget_exhausted run; parentRunId on a new launch only borrows named worktrees and never replays or resumes.";
 export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     name: Type.TOptional<Type.TString>;
     description: Type.TOptional<Type.TString>;
@@ -64,7 +64,6 @@ export interface WorkflowPhaseView {
     name: string;
     occurrence: number;
     state: WorkflowPhaseState;
-    status: WorkflowPhaseState;
     observed: boolean;
     afterAgent?: number;
     agents: readonly AgentRecord[];
@@ -83,7 +82,48 @@ export declare function buildWorkflowPhaseModel(run: Pick<PersistedRun, "state"
 export interface WorkflowPhaseSelection {
     phaseId?: string | undefined;
     agentId?: string | undefined;
+    nodeId?: string | undefined;
+    expandedNodeIds?: readonly string[] | undefined;
+    treeOnly?: boolean | undefined;
+    detailsOnly?: boolean | undefined;
+    actions?: {
+        title: string;
+        options: readonly string[];
+        index: number;
+    } | undefined;
 }
+export type WorkflowPhaseTreeNodeKind = "phase" | "operation" | "agent";
+export interface WorkflowPhaseTreeNode {
+    id: string;
+    kind: WorkflowPhaseTreeNodeKind;
+    label: string;
+    depth: number;
+    phaseId: string;
+    operationPath: readonly string[];
+    parentId?: string;
+    children: readonly string[];
+    state: WorkflowPhaseState | AgentRecord["state"];
+    agentId?: string;
+    agent?: AgentRecord;
+    phase?: WorkflowPhaseView;
+}
+export interface WorkflowPhaseTree {
+    roots: readonly string[];
+    nodes: readonly WorkflowPhaseTreeNode[];
+    byId: ReadonlyMap<string, WorkflowPhaseTreeNode>;
+}
+export interface WorkflowPhaseTreeSelection {
+    nodeId?: string | undefined;
+}
+export type WorkflowPhaseTreeDirection = "up" | "down" | "left" | "right";
+export declare function buildWorkflowPhaseTree(model: WorkflowPhaseModel): WorkflowPhaseTree;
+export declare function workflowPhaseTreeVisibleNodes(tree: WorkflowPhaseTree, expanded?: ReadonlySet<string>): readonly WorkflowPhaseTreeNode[];
+export declare function workflowPhaseTreeInitialExpanded(tree: WorkflowPhaseTree): ReadonlySet<string>;
+export declare function preserveWorkflowPhaseTreeSelection(tree: WorkflowPhaseTree, selection: WorkflowPhaseTreeSelection): WorkflowPhaseTreeSelection;
+export declare function navigateWorkflowPhaseTree(tree: WorkflowPhaseTree, selectedNodeId: string | undefined, expandedNodeIds: ReadonlySet<string>, direction: WorkflowPhaseTreeDirection): {
+    nodeId?: string;
+    expandedNodeIds: ReadonlySet<string>;
+};
 export declare function preserveWorkflowPhaseSelection(model: WorkflowPhaseModel, selection: WorkflowPhaseSelection): WorkflowPhaseSelection;
 export declare function formatWorkflowProgress(run: PersistedRun, spinner?: string, styles?: WorkflowProgressStyles): string;
 export declare function truncateWorkflowProgress(text: string, width: number): string[];
@@ -94,7 +134,7 @@ export declare function formatNavigatorDashboard(run: PersistedRun, checkpoints:
 export declare function formatNavigatorRun(loaded: {
     run: PersistedRun;
     snapshot: Readonly<LaunchSnapshot>;
-}, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string;
+}, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
 export declare function formatWorkflowPhaseDashboard(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>, width: number, selection?: WorkflowPhaseSelection, styles?: WorkflowProgressStyles): string[];
 export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
 export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory, agentDir?: string): void;