pi-workflow-engine 0.10.2 → 0.11.0

package/USAGE.md

@@ -27,6 +27,7 @@ Useful flags:
 /workflow:inspector                      # open the current or last workflow inspector
 /workflow code-review --result-viewer    # explicitly open the findings viewer
 /workflow code-review --review-viewer    # alias for --result-viewer
+/workflow:results                        # reopen the latest code-review findings without rerunning
 /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
@@ -42,7 +43,7 @@ Useful flags:
 | `diagnose` | Investigates a bug, failing command, or regression. |
 | `perf-review` | Reviews a slow path or performance concern. |
 
-`code-review` auto-detects a diff when you do not pass args. If there is an open GitHub PR for the current branch, it uses that PR diff; otherwise it falls back to branch-vs-main/master or `HEAD~1`.
+`code-review` auto-detects a diff when you do not pass args. If there is an open GitHub PR for the current branch, it uses the cumulative PR diff; otherwise it falls back to branch-vs-main/master or `HEAD~1`. Per-commit `gh pr diff --patch` input is rejected because it can surface superseded code. If diff capture fails, the review fails instead of returning an empty report or "no findings."
 
 ## Use Dynamax for custom workflows
 
@@ -68,26 +69,65 @@ Sticky mode and inspector shortcut:
 /workflow:dynamax status
 ```
 
-The workflow inspector is also registered as a first-class shortcut shown by `/hotkeys`; the default is `ctrl+shift+m`. `ctrl+o` is intentionally not used because pi already uses it for tool-output expansion and tree filtering.
+The workflow inspector and code-review results viewer are also registered as first-class shortcuts shown by `/hotkeys`. The defaults are `ctrl+shift+m` for the inspector and `ctrl+shift+r` for the latest review results. `ctrl+o` is intentionally not used because pi already uses it for tool-output expansion and tree filtering.
 
 When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives the workflow permission reminder, stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. Sticky mode, one-shot pending mode, and active Dynamax workflow runs show compact TUI status with `/workflow:dynamax on|off` and the inspector shortcut; off mode clears that status line.
 
 When the host agent calls the `workflow` tool from a TUI session, pi opens the live workflow inspector for that run. The compact workflow widget still shows the latest moving status above the editor, but the inspector is the richer view for phases, agents, findings, and logs.
 
-Configure the inspector shortcut by creating `~/.pi/agent/extensions/pi-workflow-engine.json`:
+Configure either shortcut by creating `~/.pi/agent/extensions/pi-workflow-engine.json`:
 
 ```json
 {
   "shortcuts": {
-    "inspector": "ctrl+shift+x"
+    "inspector": "ctrl+shift+x",
+    "results": "ctrl+shift+y"
   }
 }
 ```
 
-Set `"inspector": null` to disable the shortcut while keeping `/workflow:dynamax` and `/workflow:inspector` available.
+Set either shortcut to `null` to disable it while keeping `/workflow:inspector` and `/workflow:results` available.
 
 With Dynamax enabled, the host agent usually calls the `workflow` tool with `script`: a one-off inline workflow tailored to your prompt. It can still call a saved workflow by `name` when one already fits.
 
+### Adaptive multi-pass authoring
+
+A single fan-out is still the default when it can answer the question. When the first pass may reveal gaps, conflicts, weak claims, or missing evidence, an inline workflow can inspect those intermediate results and commission only the follow-up work the LLM says is needed:
+
+```ts
+const firstPass = (await api.parallel(initialTasks)).filter((result) => result !== null);
+
+const MAX_FOLLOW_UPS = 4;
+const GapAnalysis = Type.Object({
+  items: Type.Array(
+    Type.Object({ question: Type.String(), reason: Type.String() }),
+    { maxItems: MAX_FOLLOW_UPS },
+  ),
+});
+const gaps = await api.agent(
+  `Identify only material gaps that require another agent:\n${JSON.stringify(firstPass)}`,
+  { schema: GapAnalysis, thinkingLevel: "low" },
+);
+
+const followUpItems = gaps?.items.slice(0, MAX_FOLLOW_UPS) ?? [];
+const followUps = followUpItems.length
+  ? (await api.parallel(
+      followUpItems.map((item) => () =>
+        api.agent(`Resolve this gap and cite evidence: ${JSON.stringify(item)}`, {
+          thinkingLevel: "low",
+        }),
+      ),
+    )).filter((result) => result !== null)
+  : [];
+
+return api.agent(
+  `Synthesize the first pass and any follow-ups:\n${JSON.stringify({ firstPass, followUps })}`,
+  { thinkingLevel: "medium" },
+);
+```
+
+The structured gap-analysis result lets ordinary TypeScript decide whether a second pass exists. Put a hard `maxItems` bound on LLM-authored task lists and defensively slice before fan-out. Prefer conditionals and bounded loops over new iteration, quorum, graph, reduction, or retry primitives, and do not generate follow-up agents when the first pass is already sufficient.
+
 ## Workflow results
 
 Workflow results are rendered in pi with:
@@ -104,7 +144,11 @@ These workflow usage totals are separate from `--perf`, which is internal timing
 
 During a run, pi shows live phases and subagent status. Use `--inspect` if you want a larger live view while the workflow is active, then `/workflow:inspector` if you want to bring the last completed inspector back up afterward.
 
-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.
+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. The viewer is centred, scales to the terminal, and shows the visible finding/detail ranges while scrolling. `/workflow:results` or `ctrl+shift+r` reopens the most recent validated code-review report in the current pi session without rerunning the workflow; selections reset when it reopens.
+
+The Fix action revalidates the exact reviewed PR/ref/index/working-tree snapshot, then runs each selected finding through its own worktree-isolated agent and returns the finding ID, validation summary, patch, and changed status. Failed attempts do not discard successful previews, no patch is applied to your active tree automatically, and a moved or unverifiable review target is rejected rather than patched against the wrong code. The original review and all Fix previews retained in that pi session share one output-token budget. Reopening the viewer does not reset it, finalized preview usage is always deducted, and only one preview can run at a time.
+
+Inline GitHub comments are available only for findings captured from a verified PR target. Before posting, the engine revalidates the reviewed snapshot and requires the current PR head to match; identical comments on that head are skipped.
 
 ### Resume a run
 
@@ -114,9 +158,24 @@ Every workflow result includes a run id. Resume with:
 /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.
+The `workflow` tool exposes the same feature as `resumeFromRunId`. Replay is explicit for agents that share the workflow directory and automatic for isolated patch-producing agents:
 
-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.
+| Agent call | Default during resume | Override |
+| --- | --- | --- |
+| Shared workspace | Runs live | `resume: "read-only"` opts into repository-wide Git-visible replay; `resumeInputs` adds ignored paths under the workflow cwd |
+| `isolation: "worktree"` | Replays when identity matches | `resume: "off"` forces a live run |
+
+Use `resume: "read-only"` only when the shared agent is advisory. In Git repositories the engine resolves the repository root and binds replay to HEAD, staged and unstaged tracked changes, index modes, and bounded non-ignored untracked contents across that whole worktree, even when pi starts in a subdirectory. Add ignored or generated files under the workflow cwd with cwd-relative `resumeInputs`; explicitly named ignored paths are fingerprinted directly and cannot escape that cwd. The complete identity is checked before accepting a hit, after execution, and again after cleanup. A changed surface turns a hit into a live run and prevents unsafe recording. Tracked symlinks, submodules, and unsupported index states fail closed. Use `resume: "off"` when the call may inspect undeclared ignored files, external paths, services, environment, or clock state.
+
+Journals use replay contract v2. A hit requires the same prompt/options and execution identity: repository-wide Git-visible state plus explicitly declared ignored inputs, workflow source provenance, coding-agent runtime version, effective system prompt/provider/model/thinking level, ordered selected skill contents, and ordered executable tool definitions plus source fingerprints. Unverifiable, cyclic, oversized, symlinked, submodule-backed, or mutable identity surfaces fail closed and run live. A tool-free structured agent uses a capability identity instead of hashing a workspace it cannot observe; an isolated agent binds replay to both the commit and tree objects of its exact prepared worktree baseline, including deterministic normalized snapshots for repositories with no commits. Each resumed run writes a fresh journal under its new run id, and cached results do not add usage or budget spend.
+
+Cached values are revalidated before use: text must still be text, structured output must satisfy the current typebox schema, and an isolated patch must have consistent metadata and pass `git apply --check --binary` against its fresh baseline worktree. A malformed or stale value runs live.
+
+Invalidations appear in progress output with a concise reason. Legacy v1 journals and early v2 entries without effective-session identity are parsed for compatibility but always miss. Git repositories with no commits and non-Git directories remain supported. Git control data and engine-owned workflow journals cannot be declared as inputs; if a Git-visible or explicit surface exceeds safety bounds, that call runs live.
+
+Statically loaded built-ins fingerprint and revalidate their bounded extension source tree so imported helper changes invalidate replay, while inline workflows use the compiler-provided script fingerprint. Dynamically discovered and programmatic modules are intentionally non-replayable because their transitive runtime imports or captured closures cannot be bound to an immutable source snapshot.
+
+Resume only caches completed `agent()` calls. It does not snapshot arbitrary workflow local variables, in-flight tool work, environment or clock state, external services, or generated inputs outside the captured repository/workflow/skill/tool surfaces. Use `resume: "off"` for calls that depend on those values, and keep prompts and options deterministic when you want cache hits.
 
 ## Author a saved workflow
 
@@ -142,13 +201,29 @@ export default async function run({ agent, parallel, phase, args }: WorkflowApi)
   phase("Find");
   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" }),
+      () => agent(`Find correctness issues: ${args}`, {
+        schema: Finding,
+        tools: SEARCH_TOOLS,
+        toolHints: SEARCH_TOOL_HINTS,
+        thinkingLevel: "low",
+        resume: "read-only",
+      }),
+      () => agent(`Find edge cases: ${args}`, {
+        schema: Finding,
+        tools: SEARCH_TOOLS,
+        toolHints: SEARCH_TOOL_HINTS,
+        thinkingLevel: "low",
+        resume: "read-only",
+      }),
     ]),
   );
 
   phase("Synthesize");
-  return agent(`Summarize: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
+  return agent(`Summarize: ${JSON.stringify(findings)}`, {
+    thinkingLevel: "medium",
+    tools: [],
+    resume: "read-only",
+  });
 }
 ```
 
@@ -158,11 +233,14 @@ Core primitives:
 | --- | --- |
 | `agent(prompt, opts)` | Runs one isolated subagent. With `schema`, returns validated structured data. |
 | `parallel(thunks)` | Runs thunks concurrently and waits for all; recoverable failures become `null` slots. |
+| `parallel(thunks, { settled: true })` | Retains each success or recoverable failure as a serialisable discriminated result. |
 | `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. |
 
+Use settled mode when the workflow must distinguish a successful `null` from a failed branch. It preserves input order and returns `{ ok: true, value }` or `{ ok: false, error: { name?, message } }` for every thunk. Genuine workflow cancellation still rejects the whole `parallel()` call and cancels siblings.
+
 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"]`.
@@ -188,7 +266,9 @@ if (edit.changed) {
 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.
+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 results are replayable by default; add `resume: "off"` when their inputs are not fully captured. Worktree setup costs disk and git process time, so keep it opt-in for mutating/parallel-edit stages.
+
+Cleanup is a required finalizer. The engine attempts every registered worktree removal, retains failed paths for another cleanup attempt, and fails the workflow with the aggregated cleanup error if any worktree still cannot be removed. Advisory finalizers such as UI snapshots and journal pruning do not replace an otherwise valid workflow result.
 
 ### Compose workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [
@@ -35,7 +35,7 @@
     "image": "https://raw.githubusercontent.com/timbrinded/pi-workflow-engine/master/assets/preview.png"
   },
   "scripts": {
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "bun test --timeout=30000",
     "test:changedlines": "bun test tests/changedlines.test.ts",
     "test:concurrency": "bun test tests/concurrency.test.ts",
@@ -46,17 +46,17 @@
     "bench:discovery": "bun run scripts/bench/discovery.ts",
     "bench:startup": "bun run scripts/bench/startup.ts",
     "bench:ui": "bun run scripts/bench/ui.ts",
-    "prepublishOnly": "tsgo --noEmit && bun run test"
+    "prepublishOnly": "tsc --noEmit && bun run test"
   },
   "peerDependencies": {
-    "@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"
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260623.1"
+    "typescript": "^7.0.2"
   }
 }