pi-workflow-engine 0.9.0 → 0.10.0

package/README.md

@@ -8,7 +8,7 @@ Use `dynamax` when a task needs several independent passes: review from differen
 
 The package ships no bundled runtime dependencies. It uses the pi SDK and pi's bundled core packages, so installing it does not pull in a second agent stack.
 
-The built-in workflows are advisory. They inspect, verify, and report; they do not edit files.
+The built-in workflows are advisory by default. They inspect, verify, and report; they do not edit files. Workflow authors can opt individual subagents into disposable git worktrees when they want reviewable patches instead of direct edits.
 
 ## Install
 
@@ -134,9 +134,13 @@ Useful flags:
 /workflow code-review --result-viewer
 /workflow code-review --no-result-viewer
 /workflow code-review --concurrency=4
+/workflow code-review --budget=50000
+/workflow code-review --resume <run-id>
 /workflow code-review --refresh
 ```
 
+Every workflow result includes a run id. If a long run is interrupted, rerun the same workflow with `--resume <run-id>` to replay matching completed `agent()` calls from the journal and run only the first changed or missing call onward. Resume is deterministic-prefix based: keep prompts and agent options stable if you want cache hits.
+
 The code-review workflow can open an interactive findings viewer. Select findings and hand them back to the parent agent for minimal fixes, or ask it to raise GitHub PR comments when `gh` is authenticated and PR context is available.
 
 For the full command guide, see [USAGE.md](USAGE.md).
@@ -202,10 +206,15 @@ Inline workflows are passed to the `workflow` tool as a script string. They are
 - Each `agent()` runs an in-process pi `AgentSession` with `SessionManager.inMemory()`.
 - Workflow results aggregate the finalized assistant usage from those subagent sessions before disposal and show token/cost totals separately from pi's host-session footer accounting.
 - Structured output uses a terminating tool whose `parameters` is your schema. pi validates the call; the engine captures the args. There is no JSON scraping.
+- A schema agent that finishes without calling `final_answer` is re-prompted once before returning `null`.
+- Runs write completed `agent()` results to `.pi/.workflow-runs/<run-id>.jsonl`; `--resume <run-id>` replays the longest unchanged prefix and writes a fresh journal for the resumed run.
+- `agent(..., { isolation: "worktree" })` runs in a disposable git worktree and returns `{ result, patch, changed }`; the user working tree is not mutated.
 - A single run-level semaphore caps concurrent agents, so nested `parallel`, `pipeline`, and `workflow()` calls stay bounded.
+- `parallel()` and `pipeline()` are fail-soft: recoverable branch failures, including budget backstops, become `null` slots while survivors continue. A genuine run abort still rejects.
 - Built-in workflows stay statically imported so they share pi's bundled `typebox` identity.
 - Set `thinkingLevel` per fan-out agent. Otherwise many subagents can inherit an expensive global reasoning level.
 - Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; clear prompt text like `include skill name` also works when `skills` is omitted.
+- `tools` is a strict allowlist for subagents. Use `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools such as `ast-grep`, `mgrep`, `ffgrep`, or `fffind` without hard-coding a specific extension.
 - Set `model` per agent only when needed: bare ids are Anthropic shorthand, and `provider/id` targets other providers.
   Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
 

package/USAGE.md

@@ -18,7 +18,7 @@ From inside a repo:
 /workflow perf-review "workflow startup latency"
 ```
 
-The built-in workflows are advisory. They inspect, verify, and report; they do **not** edit files.
+The built-in workflows are advisory by default. They inspect, verify, and report; they do **not** edit files. Saved or inline workflows can opt individual agents into disposable git worktrees when they need reviewable patches.
 
 Useful flags:
 
@@ -28,6 +28,8 @@ Useful flags:
 /workflow code-review --result-viewer    # explicitly open the findings viewer
 /workflow code-review --review-viewer    # alias for --result-viewer
 /workflow code-review --concurrency=4    # cap concurrent subagents
+/workflow code-review --budget=50000     # output-token ceiling for subagents
+/workflow code-review --resume <run-id>  # replay matching completed agent calls
 /workflow code-review --refresh          # rediscover newly added workflow files
 ```
 
@@ -104,12 +106,25 @@ During a run, pi shows live phases and subagent status. Use `--inspect` if you w
 
 Code-review findings are rendered as a formatted result message by default. pi no longer asks whether to open the findings viewer. Use `--result-viewer` or `--review-viewer` when you want to inspect findings interactively, press `enter` to expand/collapse the nicely formatted finding text, and use `1`-`9` to jump directly to a visible finding.
 
+### Resume a run
+
+Every workflow result includes a run id. Resume with:
+
+```text
+/workflow code-review --resume <run-id> HEAD~3
+```
+
+The `workflow` tool exposes the same feature as `resumeFromRunId`. Resume replays completed `agent()` results from `.pi/.workflow-runs/<run-id>.jsonl` while the agent call index and prompt/options hash still match. After the first missing or changed call, the rest of the run executes live and writes a new journal under the new run id. Cached results do not add usage or budget spend for the resumed run.
+
+Resume only caches completed `agent()` calls. It does not snapshot arbitrary workflow local variables or in-flight tool work. Keep prompts and agent options deterministic across reruns if you want cache hits.
+
 ## Author a saved workflow
 
 Saved workflows are TypeScript modules with `meta` plus a default async function:
 
 ```ts
 import { Type } from "typebox";
+import { compactResults } from "../src/concurrency.ts";
 import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -120,13 +135,17 @@ export const meta: WorkflowMeta = {
 const Finding = Type.Object({
   summary: Type.String(),
 });
+const SEARCH_TOOLS = ["read", "bash", "grep", "find", "ls"];
+const SEARCH_TOOL_HINTS = ["search"] as const;
 
 export default async function run({ agent, parallel, phase, args }: WorkflowApi) {
   phase("Find");
-  const findings = await parallel([
-    () => agent(`Find correctness issues: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
-    () => agent(`Find edge cases: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
-  ]);
+  const findings = compactResults(
+    await parallel([
+      () => agent(`Find correctness issues: ${args}`, { schema: Finding, tools: SEARCH_TOOLS, toolHints: SEARCH_TOOL_HINTS, thinkingLevel: "low" }),
+      () => agent(`Find edge cases: ${args}`, { schema: Finding, tools: SEARCH_TOOLS, toolHints: SEARCH_TOOL_HINTS, thinkingLevel: "low" }),
+    ]),
+  );
 
   phase("Synthesize");
   return agent(`Summarize: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
@@ -138,18 +157,39 @@ Core primitives:
 | Primitive | What it does |
 | --- | --- |
 | `agent(prompt, opts)` | Runs one isolated subagent. With `schema`, returns validated structured data. |
-| `parallel(thunks)` | Runs thunks concurrently and waits for all. |
-| `pipeline(items, ...stages)` | Runs each item through stages independently. |
+| `parallel(thunks)` | Runs thunks concurrently and waits for all; recoverable failures become `null` slots. |
+| `pipeline(items, ...stages)` | Runs each item through stages independently; a failed item becomes `null`. |
 | `phase(title)` / `log(message)` | Updates workflow progress UI. |
 | `progress(event)` | Emits counters, summaries, and lane items. |
 | `workflow(ref, args?)` | Runs another workflow inline as a sub-step and returns its result. |
 
 Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
 
+`tools` is a strict allowlist. If you set `tools: ["read", "bash"]`, extension tools such as `ast-grep`, `mgrep`, `fffind`, or `ffgrep` are hidden from that subagent. Add `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools while keeping the concrete base allowlist portable. The built-in advisory workflows use `tools: ["read", "bash", "grep", "find", "ls"]` plus `toolHints: ["search"]`.
+
 Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; if `tools` is also restricted, the engine automatically keeps `read` available so the subagent can load the selected `SKILL.md`. When `skills` is omitted, clear prompt text such as `/skill:name`, `include skill name`, or `use the name skill` is also treated as an opt-in. Pass `skills: []` to suppress that inference.
 
 Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
 
+### Mutating agents in worktrees
+
+Use `isolation: "worktree"` only for agents that should edit files. The agent runs in a detached git worktree, the engine captures its net patch, then the worktree is removed. The user's working tree is not changed.
+
+```ts
+const edit = await agent("Rename this helper and update its call sites.", {
+  tools: ["read", "bash", "edit", "grep", "find", "ls"],
+  isolation: "worktree",
+  thinkingLevel: "medium",
+});
+
+if (edit.changed) {
+  return { summary: "Patch ready for review.", patch: edit.patch };
+}
+return { summary: edit.result };
+```
+
+Isolated agents require the workflow `cwd` to be inside a git work tree. Outside git, the agent fails fast rather than silently mutating the shared directory. The return value is `{ result, patch, changed }`, where `result` is the normal text or structured `agent()` result and `patch` is a `git diff HEAD` patch. Worktree setup costs disk and git process time, so keep it opt-in for mutating/parallel-edit stages.
+
 ### Compose workflows
 
 `workflow(ref, args?)` runs a registered workflow by name as a sub-step, returning its result. The child shares the parent run's concurrency cap, abort signal, and perf timing, and its phases nest under `<name> ▸ <phase>` in the live UI.
@@ -161,7 +201,7 @@ export default async function run({ workflow }: WorkflowApi) {
 }
 ```
 
-Nesting is one level only: calling `workflow()` from inside a sub-workflow rejects. Resolution throws on an unknown name — wrap the call in `try/catch` if a missing sub-workflow should be non-fatal (note `parallel()` rejects the whole batch on the first error, so catch inside each thunk for per-branch resilience).
+Nesting is one level only: calling `workflow()` from inside a sub-workflow rejects. Resolution throws on an unknown name. Inside `parallel()` or `pipeline()`, recoverable branch errors become `null` results, so filter nulls before synthesis; a genuine run abort still rejects.
 
 ### Where workflows live
 
@@ -218,6 +258,7 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 | --- | --- |
 | `--concurrency=N` / `PI_WORKFLOW_CONCURRENCY=N` | Cap concurrent subagents. Default is `min(8, max(2, CPU count))`. |
 | `--parallel-limit=N` / `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` | Limit eager `parallel()` submission. |
+| `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling for completed subagents. `agent()` throws `WorkflowBudgetExceededError` before starting another agent once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. |
 | `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. Usage/cost totals are reported separately from perf. |
 | `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
 
@@ -226,4 +267,5 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 - **Unknown workflow**: confirm the extension is loaded with `pi list`; use `--refresh` for new drop-ins.
 - **Inline compile error**: check the inline rules above.
 - **Slow run**: lower fan-out, set `thinkingLevel`, or reduce `--concurrency`.
+- **Budget exhausted**: narrow the target, raise `--budget`, reduce fan-out/concurrency, or guard custom loops with `api.budget.remaining()`.
 - **Duplicate command/tool warnings while developing**: avoid loading both the global package and the working copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [
@@ -49,14 +49,14 @@
     "prepublishOnly": "tsgo --noEmit && bun run test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
+    "@earendil-works/pi-agent-core": "0.79.10",
+    "@earendil-works/pi-ai": "0.79.10",
+    "@earendil-works/pi-coding-agent": "0.79.10",
+    "@earendil-works/pi-tui": "0.79.10",
+    "typebox": "1.3.0"
   },
   "devDependencies": {
-    "@types/node": "^22",
-    "@typescript/native-preview": "^7.0.0-dev.20260615.1"
+    "@types/node": "^22.20.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260623.1"
   }
 }