pi-extensible-workflows 1.0.1 → 3.0.0

package/dist/src/workflow-evals.js

@@ -707,6 +707,7 @@ export async function replayWorkflowScript(script, args = null, signal) {
                 active -= 1;
             }
         },
+        worktree: async () => ({ path: "/worktrees/eval", branch: "eval-branch" }),
         phase: (name) => { phases.push(name); },
         log: (message) => { logs.push(message); },
     }, signal);
@@ -860,7 +861,7 @@ function semanticJudgePrompt(evalCase, calls, cwd, home) {
         return [];
     } }));
     const roleText = [...usedRoles].map((role) => `${role}: ${roles[role]?.description ?? "no description"}`).join("\n") || "none";
-    const docs = "agent(prompt, options) delegates; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
+    const docs = "agent(prompt, options) delegates; shell(command, options) runs a deterministic host command and returns exitCode/stdout/stderr; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
     return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow script(s):\n${calls.map((call, index) => `--- ${String(index)} ---\n${call.script ?? "<missing>"}`).join("\n")}`;
 }
 async function runSemanticJudge(input, calls, cwd, home, sessionDir, maxCost) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "1.0.1",
+  "version": "3.0.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -31,8 +31,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/src/cli.js",
     "inspect": "node dist/src/cli.js inspect",
     "lint": "eslint .",
-    "test": "npm run build && node --test 'dist/test/*.test.js'",
-    "acceptance": "npm run build && node --test dist/test/runtime-acceptance.test.js",
+    "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",
+    "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",
     "evals": "npm run build && node dist/src/workflow-evals.js",

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

@@ -4,87 +4,81 @@ 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.
 
-Use `workflow` exclusively for genuinely multi-agent orchestration. For one agent, use ordinary tools or `Agent` directly. Do not wrap a single agent in a workflow; define distinct responsibilities and keep the result flow explicit.
-
-## Pattern
-
+## Example
 ```js
-const reportSchema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    findings: { type: "array", items: { type: "string" } },
-  },
-  required: ["summary", "findings"],
-  additionalProperties: false,
-};
+const reportSchema = { type: "object", properties: { summary: { type: "string" }, findings: { type: "array", items: { type: "string" } } }, required: ["summary", "findings"], additionalProperties: false };
+
 
 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 }),
 });
 
-// Add a downstream agent only when synthesis or independent review is a real phase.
 return agent(
   prompt("Review these reports:\n\n{reports}", { reports }),
   { role: "reviewer", outputSchema: reportSchema },
 );
 ```
 
-To pass structured input from the main agent, include `args`:
+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`; omitted `args` is `null`.
-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.
+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.
+Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task. 
 
-Pass downstream only needed results. Workflow JavaScript has no imports, filesystem, network, process, or timers; delegate such work to agents with the required tools.
+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`.
 
-## `agent()` options
+Example use of `shell`:
 
-```typescript
-interface AgentOptions {
-  label?: string; // optional non-empty display name
-  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
-  outputSchema?: JsonSchema;
-  retries?: number; // non-negative; use for safe, repeatable work
-  timeoutMs?: number | null; // positive milliseconds; null means unlimited
+```js
+// ... other code
+const testRes = await shell("yarn test", { env: { CI: "1" } });
+if (testRes.exitCode === 0) {
+   // success path
+   return {...}
 }
 ```
 
-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.
+Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
-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.
+## `agent()` options
+```typescript
+export interface AgentOptions {
+  label?: string; model?: string; role?: string; tools?: string[];
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; 
+  outputSchema?: JsonSchema; 
+  retries?: number; 
+  timeoutMs?: number | null;
+  [key: string]: JsonValue;
+}
+```
 
-## Shared worktree scope
+Extensions may add JSON-compatible agent options such as `advisor: true`; core keys retain validation and role constraints. Extension options go to setup hooks/native setup and are not inherited by child agents.
 
-Use `withWorktree(callback)` or `withWorktree(name, callback)` when top-level agents should collaborate in one worktree:
+Agent calls are unnamed. Direct calls receive hidden source call-site identity; aliases are unsupported, and calls from one source site must not race outside `parallel` or `pipeline`, whose structural keys make replay deterministic.
 
+## Passing agent results
+Use independent `agent(prompt, options)` calls and pass each completed result explicitly to the next prompt. This keeps workflow execution deterministic and makes replay state local to each call:
 ```js
-const results = await withWorktree("implementation", async () => parallel("implementation", {
-  api: () => agent("Implement the API"),
-  tests: () => agent("Add integration tests"),
-}));
+const findings = await agent("Inspect the implementation.");
+const fix = await agent(prompt("Propose the smallest fix from these findings:\n\n{findings}", { findings }));
+return { findings, fix };
 ```
 
-The callback result is returned unchanged and the worktree is created only when the first enclosed agent launches. Concurrent agents share mutable files, so give them non-conflicting work or coordinate explicitly.
-
-`parallel()` tasks may call any workflow function, not only `agent()`:
-
+## Worktrees
+Use `withWorktree(name, callback)` for top-level agents that collaborate in one explicitly named worktree scope:
 ```js
-const results = await parallel("checks", {
-  security: () => reviewRepository({ focus: "security" }),
-  release: () => reviewRepository({ focus: "release readiness" }),
+const result = await withWorktree("issue", async ({ path, branch }) => {
+  const report = await agent("Implement the issue");
+  return { path, branch, report };
 });
 ```
+Entering the scope materializes its worktree before the callback. The callback receives a frozen reference containing only the real string `path` and `branch`; callbacks may ignore the argument, and their bare return value is preserved. Concurrent agents share mutable files, so assign non-conflicting work or coordinate explicitly.
 
-Use separate named scopes when each parallel branch needs its own worktree:
-
+Branches may call any workflow function, not only `agent()`. Use separate named scopes when parallel branches need isolated worktrees:
 ```js
 const results = await parallel("implementation", {
   api: () => withWorktree("api", () => agent("Implement the API")),
@@ -92,26 +86,17 @@ const results = await parallel("implementation", {
 });
 ```
 
-Registered extension functions receive `withWorktree` in their context, so they may create a shared scope internally. They can compose other registered functions without importing their source:
-```ts
-const report = await context.invoke("reviewRepository", { focus: "security" });
-```
-Their public inputs and outputs must remain JSON; callbacks cannot cross the extension-function boundary.
+Registered extension functions receive `withWorktree` in context and can compose other registered functions with `context.invoke("reviewRepository", { focus: "security" })`. Their public inputs and outputs remain JSON; callbacks cannot cross the extension boundary.
 
 ## Rules
-
-- Do not create a workflow for one agent. Phases must have distinct work.
-- Use `log(messageString)` in the script to surface brief status messages to the operator.
-- A role owns its execution policy. When `role` is present, do not also set `model`, `thinking`, or `tools`; only task-specific options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
-- Use `parallel()` for independent tasks with different flows. Use `pipeline()` when each keyed item passes through the same ordered stages; do not duplicate identical stage chains inside `parallel()` branches.
-- Call shapes are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; object keys are stable task, item, and stage names.
-- 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.
+- Use `log(messageString)` for brief operator status.
+- A role owns execution policy: with `role`, do not set `model`, `thinking`, or `tools`; only task options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
+- Use `parallel()` for independent tasks with different flows and `pipeline()` when every keyed item follows the same ordered stages; do not duplicate identical chains in `parallel()`. Signatures are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; keys are stable task, item, and stage names.
+- Preserve item metadata in workflow code between pipeline stages instead of making agents echo it through `outputSchema`.
+- Use a JavaScript loop for repeated work; each direct `agent(...)` call gets deterministic call-site and occurrence identity.
 - Runs default to background; set tool-call `foreground: true` when asked to wait.
-- Add `budget` only when the run needs aggregate limits. The only valid dimension names are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches` (never `cost`, `duration`, `launches`, or other shorthand). Each dimension is `{ soft?: number, hard?: number }`; `soft` must be less than `hard`.
-- 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.
-- With `outputSchema`, agents must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an additional retry is justified and the work is idempotent.
-- Do not add "persona" specs to the prompt for agents. Just define the task.
+- Add `budget` only for aggregate limits. Do not invent limits, omit if user do not ask explicitly. Valid dimensions are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches`; each is `{ soft?: number, hard?: number }` with `soft < hard`.
+- `budget_exhausted` runs resume through `workflow_resume`: omitted patch values stay unchanged, `null` removes a limit, and tightening resumes directly. Relaxation stores the exact proposal and returns `{ state: "awaiting_approval", proposalId }`; `workflow_respond` must answer that ID. Rejection leaves the run exhausted; approval applies the budget and cold-resumes it. `workflow_retry` is only for persisted `failed` runs and inherits cumulative usage; replay itself consumes no budget.
+- `parallel()` and `pipeline()` return keyed bare values; await them before use. Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings remain literal.
+- Use `outputSchema` only when another phase compares, aggregates, or validates a result, never for final prose. Keep only consumer-needed fields and avoid repeated evidence. Agents with it must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an extra retry is justified and work is idempotent.
+- Do not add persona specifications to agent prompts; define the task directly.