pi-extensible-workflows 3.1.0 → 3.2.0

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@ export * from "./validation.js";
 export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
+export * from "./workflow-artifacts.js";
 export { default } from "./host.js";
 export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PendingWorkflowDecision, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";

package/dist/src/index.js

@@ -5,6 +5,7 @@ export * from "./validation.js";
 export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
+export * from "./workflow-artifacts.js";
 export { default } from "./host.js";
 export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";

package/dist/src/types.d.ts

@@ -257,6 +257,7 @@ export interface AgentRecord {
     state: AgentState;
     parentId?: string;
     structuralPath?: readonly string[];
+    resultPath?: string;
     parentBreadcrumb?: string;
     worktreeOwner?: string;
     role?: string;

package/dist/src/validation.js

@@ -401,6 +401,39 @@ function workflowCallsWithStructure(program) {
     visit(program, { execution: "sequential", structure: [] });
     return calls.sort((left, right) => left.call.start - right.call.start);
 }
+function memberCall(node, objectName, propertyName) {
+    if (node?.type !== "CallExpression" || node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.object.type !== "Identifier" || node.callee.object.name !== objectName || node.callee.property.type !== "Identifier")
+        return false;
+    return node.callee.property.name === propertyName;
+}
+function mapCallback(node) {
+    if (!memberCall(node, "Promise", "all") && !memberCall(node, "Promise", "allSettled"))
+        return undefined;
+    if (node.type !== "CallExpression")
+        return undefined;
+    const source = node.arguments[0];
+    if (source?.type !== "CallExpression" || source.callee.type !== "MemberExpression" || source.callee.computed || source.callee.property.type !== "Identifier" || !["map", "flatMap"].includes(source.callee.property.name))
+        return undefined;
+    const callback = source.arguments[0];
+    return callback?.type === "ArrowFunctionExpression" || callback?.type === "FunctionExpression" ? callback : undefined;
+}
+function hasUnscopedAgent(node, scoped = false) {
+    const operation = workflowCallKind(node);
+    if (operation === "agent")
+        return !scoped;
+    const nestedScope = scoped || operation === "parallel" || operation === "pipeline";
+    return astChildren(node).some((child) => hasUnscopedAgent(child, nestedScope));
+}
+function validateObviousConcurrentAgentCalls(program) {
+    const visit = (node) => {
+        const callback = mapCallback(node);
+        if (callback && hasUnscopedAgent(callback))
+            fail("INVALID_METADATA", "Promise.all/map agent fan-out cannot prove stable call-site identity; use parallel(...) or pipeline(...)");
+        for (const child of astChildren(node))
+            visit(child);
+    };
+    visit(program);
+}
 function validateDirectPrimitiveReferences(program, name) {
     const visit = (node, parent) => {
         if (node.type === "Identifier" && node.name === name) {
@@ -731,6 +764,7 @@ export function preflight(script, capabilities, schemas = [], metadata = { name:
     for (const [index, schema] of schemas.entries())
         validateSchema(schema, `schema[${String(index)}]`);
     const calls = workflowCalls(program);
+    validateObviousConcurrentAgentCalls(program);
     const phases = calls.filter((call) => call.callee.name === "phase").map((call) => literalString(call.arguments[0])).filter((phase) => phase !== undefined);
     for (const call of calls) {
         const operation = call.callee.name;

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

@@ -0,0 +1,13 @@
+import type { JsonValue } from "./types.js";
+export interface WorkflowArtifact {
+    extension: ".js" | ".json" | ".md";
+    content: string;
+}
+export type WorkflowTui = {
+    stop(): void;
+    start(): void;
+    requestRender(force?: boolean): void;
+};
+export declare function workflowScriptArtifact(script: 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

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+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 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(" ");
+    if (!editor)
+        return null;
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(editor, [...editorArgs, path], { stdio: "inherit", shell: process.platform === "win32" });
+            child.once("error", () => { resolve(null); });
+            child.once("close", (code) => { resolve(code); });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+export async function openWorkflowArtifact(tui, command, artifact) {
+    const directory = await mkdtemp(join(tmpdir(), "pi-workflow-editor-"));
+    const path = join(directory, `artifact${artifact.extension}`);
+    try {
+        await writeFile(path, artifact.content, { encoding: "utf8", mode: 0o600 });
+        tui.stop();
+        try {
+            return await spawnWorkflowEditor(command, path);
+        }
+        finally {
+            tui.start();
+            tui.requestRender(true);
+        }
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}

package/examples/workflow-extension-template/README.md

@@ -0,0 +1,37 @@
+# Workflow extension template
+
+This is a small, copyable extension rather than a generator. It shows the usual
+registration shape with one function and one packaged role. Copy the directory
+into a project, rename the metadata and function, then edit the role body.
+
+
+## Run it
+
+From the repository root after installing dependencies and building the package:
+
+```sh
+node --test examples/workflow-extension-template/extension.test.mjs
+```
+
+For a published package, run the same test from this directory after installing
+`pi-extensible-workflows` in the surrounding project. Copy the directory into a
+trusted Pi extension location; Pi auto-discovers its `index.js` entry point.
+
+
+## Files
+
+- `index.js` registers `greet` and resolves `roles/` from `import.meta.url`.
+  Relative role-directory strings are not accepted by the extension API.
+- `roles/reviewer.md` is a portable packaged role with no provider or tool
+  assumptions.
+- `extension.test.mjs` checks registration, function behavior, role packaging,
+  and the advanced examples.
+
+
+## Optional advanced pieces
+
+The dynamic `template-model` alias and `templateAdvisor` setup hook are
+optional examples. The hook only changes an agent after the call includes
+`{ templateAdvisor: true }`; remove either section if the extension does not
+need it. Both features are trusted host code and should be kept under explicit
+project policy.

package/examples/workflow-extension-template/extension.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { cp, mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
+import { beginWorkflowExtensionLoading, loadingRegistry, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, resetWorkflowRegistry, workflowCatalog } from "pi-extensible-workflows";
+
+test("discovers the copied directory as a trusted Pi extension", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workflow-extension-template-"));
+  try {
+    const destination = join(root, ".pi", "extensions", "workflow-extension-template");
+    await mkdir(join(root, "node_modules"), { recursive: true });
+    const packageEntry = fileURLToPath(import.meta.resolve("pi-extensible-workflows"));
+    const packageRoot = join(dirname(packageEntry), "..", "..");
+    await symlink(packageRoot, join(root, "node_modules", "pi-extensible-workflows"), "dir");
+    await cp(dirname(fileURLToPath(import.meta.url)), destination, { recursive: true });
+    const result = await discoverAndLoadExtensions([], root, join(root, ".pi", "agent"));
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.extensions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+
+  resetWorkflowRegistry();
+  const { default: extension } = await import("./index.js");
+  beginWorkflowExtensionLoading();
+  extension();
+
+  const catalog = workflowCatalog();
+  assert.deepEqual(catalog.functions.map(({ name }) => name), ["greet"]);
+  assert.deepEqual(catalog.modelAliasEntries?.filter(({ name }) => name === "template-model").map(({ name, kind }) => ({ name, kind })), [{ name: "template-model", kind: "dynamic" }]);
+  assert.equal(await registeredWorkflowFunctions().greet.run({ name: "Ada" }, {}), "Hello, Ada!");
+
+  const registration = registeredWorkflowRoleDirectoryRegistrations()[0];
+  assert.ok(registration);
+  assert.match(readFileSync(join(registration.path, "reviewer.md"), "utf8"), /Packaged reviewer role/);
+
+  const resolved = await loadingRegistry().resolveModelAliases({
+    cwd: process.cwd(),
+    projectTrusted: true,
+    rootModel: { provider: "example", model: "root" },
+    knownModels: new Set(["example/root", "example/available"]),
+    availableModels: new Set(["example/available"]),
+    signal: new AbortController().signal,
+  });
+  assert.deepEqual(resolved, { "template-model": "example/available" });
+
+  const hook = loadingRegistry().agentSetupHooks().find(({ name }) => name === "templateAdvisor");
+  assert.ok(hook);
+  const agent = { prompt: "Review this", options: {}, sessionInput: {} };
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.equal(agent.sessionInput.systemPromptAppend, undefined);
+  agent.options.templateAdvisor = true;
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.match(agent.sessionInput.systemPromptAppend, /one concrete risk/);
+});

package/examples/workflow-extension-template/index.js

@@ -0,0 +1,51 @@
+import { registerWorkflowExtension } from "pi-extensible-workflows";
+
+const templateExtension = {
+  version: "1.0.0",
+  headline: "Workflow extension template",
+  description: "A copyable registered function with a packaged role.",
+  functions: {
+    greet: {
+      description: "Return a greeting for one person.",
+      input: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      output: { type: "string" },
+      run(input) {
+        return `Hello, ${String(input.name)}!`;
+      },
+    },
+  },
+  // Packaged resources must be absolute paths or file URLs. This URL stays
+  // correct when the extension is copied or installed elsewhere.
+  roleDirectories: [new URL("./roles/", import.meta.url)],
+  // Optional advanced example: select an available model without naming a
+  // provider-specific model in the extension.
+  modelAliases: {
+    "template-model": {
+      resolve({ availableModels, rootModel }) {
+        const root = `${rootModel.provider}/${rootModel.model}`;
+        return availableModels.has(root) ? root : availableModels.values().next().value ?? root;
+      },
+    },
+  },
+  // Optional advanced example: mutate setup only for explicitly opted-in
+  // agents. Setup hooks are trusted code and should stay narrowly scoped.
+  agentSetupHooks: {
+    templateAdvisor: {
+      setup(agent, context) {
+        if (context.signal.aborted || agent.options.templateAdvisor !== true) return;
+        const suffix = "\n\nAdvisor: call out one concrete risk and one next check.";
+        const existing = agent.sessionInput.systemPromptAppend;
+        agent.sessionInput.systemPromptAppend = existing ? existing + suffix : suffix;
+      },
+    },
+  },
+};
+
+export default function extension() {
+  registerWorkflowExtension(templateExtension);
+}

package/examples/workflow-extension-template/roles/reviewer.md

@@ -0,0 +1,4 @@
+---
+description: Packaged reviewer role
+---
+Review the requested change carefully. Return concrete findings with file names and a next check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -25,6 +25,7 @@
     "src",
     "skills",
     "evals",
+    "examples",
     "test/fixtures"
   ],
   "scripts": {
@@ -32,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_FILES",
+    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test --test-concurrency=1 $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

@@ -5,47 +5,36 @@ description: Use when the task is complex enough to require multiple subagents o
 
 # pi-extensible-workflows
 
-Use `workflow` only for genuinely multi-agent orchestration; one agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
+## Default path
 
-## Example
+Use `workflow` only for genuinely multi-agent orchestration; a single agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
-```js
-const reportSchema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    findings: { type: "array", items: { type: "string" } },
-  },
-  required: ["summary", "findings"],
-  additionalProperties: false,
-};
+For most multi-agent tasks, start with a named inline workflow: provide a non-empty `name` and a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns.
 
+```js
 const reports = await parallel("research", {
-  first: () =>
-    agent("Research the first target.", {
-      role: "scout",
-      outputSchema: reportSchema,
-    }),
-  second: () =>
-    agent("Research the second target.", {
-      role: "scout",
-      outputSchema: reportSchema,
-    }),
+  first: () => agent("Research the first target."),
+  second: () => agent("Research the second target."),
 });
 
-return agent(prompt("Review these reports:\n\n{reports}", { reports }), {
-  role: "reviewer",
-  outputSchema: reportSchema,
-});
+return await agent(
+  prompt("Summarize these reports:\n\n{reports}", { reports }),
+);
 ```
 
+Await `parallel(...)` or `pipeline(...)` results before interpolation. Runs are backgrounded by default; set the tool-call `foreground: true` when the caller must wait for the final value.
+
+## 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 } }
 ```
-
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes but does not replay journal results. 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. Retry versus per-agent `retries` and `workflow_resume` is always explicit; external side effects before failure are not guaranteed exactly once.
+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. 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 results retain their value and completed `runId`, while background launches return `runId` immediately. 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.
 
 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`.
@@ -63,6 +52,10 @@ if (testRes.exitCode === 0) {
 
 Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
+## Advanced capabilities
+
+Registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` remain available for workflows that need them. Treat these as advanced controls rather than requirements for the default inline path.
+
 ## `agent()` options
 
 ```typescript

package/src/execution.ts

@@ -1,5 +1,5 @@
 import { fork, spawn, type ChildProcess } 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";
@@ -78,6 +78,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"); };
@@ -98,14 +99,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"); } },
@@ -386,7 +395,7 @@ function workflowErrorFromWorker(error: WorkerErrorShape): WorkflowError {
 export function runWorkflow(script: string, args: JsonValue = null, bridge: WorkflowBridge = {}, signal?: AbortSignal): WorkflowExecution {
   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: ChildProcess = fork(childFile, [String(RPC_LIMIT_BYTES), config], {