@quintinshaw/pi-dynamic-workflows 1.9.0 → 1.9.2

package/README.md

@@ -1,12 +1,36 @@
 # pi-dynamic-workflows
 
-> Claude-Code-style dynamic workflows for [Pi](https://github.com/earendil-works/pi).
+[![npm](https://img.shields.io/npm/v/@quintinshaw/pi-dynamic-workflows?color=cb3837&logo=npm)](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows)
+[![license](https://img.shields.io/badge/license-MIT-blue)](#license)
+[![for Pi](https://img.shields.io/badge/for-Pi-7c3aed)](https://github.com/earendil-works/pi)
+[![tests](https://img.shields.io/badge/tests-43%20passing-success)](#development)
 
-A Pi extension that adds a `workflow` tool. Instead of one assistant doing everything sequentially, the model writes a small JavaScript script that fans out the work across many isolated subagents, then synthesizes the results.
+> **Claude-Code-style dynamic workflows for [Pi](https://github.com/earendil-works/pi).** One assistant turn fans out into dozens of isolated subagents, cross-checks itself, and hands you a synthesized result.
 
-Great for codebase audits, multi-perspective review, large refactors, and fan-out research. Inspired by Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code).
+Instead of one model grinding through a task step by step, Pi writes a small JavaScript **orchestration script** that spawns many subagents in parallel, holds the intermediate results in script variables (not the chat context), and returns only the answer. You get the structure of a pipeline with the flexibility of plain code.
 
-Fork of [Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows), updated for `@earendil-works/*` packages with a subagent settings-inheritance fix.
+Perfect for **codebase-wide audits, multi-perspective review, large refactors, and cross-checked research** — anything where one context window isn't enough.
+
+Inspired by Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code).
+
+---
+
+## ✨ Highlights
+
+- 🚀 **Fan-out orchestration** — `agent()`, `parallel()`, `pipeline()`, `phase()` in a sandboxed script. Up to 16 concurrent / 1000 total subagents.
+- 🧭 **Interactive `/workflows` TUI** — drill through runs → phases → agents → agent detail with the keyboard, just like Claude Code. Pause, stop, and save runs without leaving the view.
+- 📊 **Real token & cost accounting** — read straight from each subagent's session (input / output / cost), not estimated. Your `budget` gates on the real total.
+- 🧠 **Real per-agent / per-phase model routing** — send the cheap work to a small model and the hard synthesis to a big one, resolved against your authenticated models.
+- ⏯️ **Resume** — interrupted runs replay completed agents from a journal (no re-run, no tokens) and only run what's left or what you changed.
+- 🌲 **Git worktree isolation** — `isolation: "worktree"` gives an agent its own branch so parallel agents can edit the same files without clobbering each other.
+- 🔭 **Bundled `/deep-research`** — fans out **real** web searches, fetches sources, keeps only multi-source-supported claims, and writes a cited report. Plus `/adversarial-review` for skeptic-vetted findings.
+- 🧩 **Saved & nested workflows** — turn any run into a `/<name>` slash command; compose saved workflows from inside other scripts.
+- 🪟 **Non-blocking by default + live task panel** — workflows run in the background: the turn ends immediately so you can keep chatting or start other tasks, a "Workflows running" panel tracks them under your input, and when one finishes its result is delivered back and the conversation **auto-continues** (queued politely after whatever you're doing, never interrupting).
+- 🌈 **Workflows mode in the input box** — type `workflow`/`workflows` and the word turns into a flowing rainbow, arming a forced workflow for that message. One Backspace right after the word disarms it (turns plain white) without deleting it.
+
+> **This is a heavily extended fork.** The [upstream project](https://github.com/Michaelliv/pi-dynamic-workflows) shipped the core script runtime; here, every advertised capability is actually **implemented, real-tested against the Pi SDK, and shipped** — see the [comparison](#whats-different-from-upstream) below.
+
+---
 
 ## Install
 
@@ -14,7 +38,7 @@ Fork of [Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynam
 pi install @quintinshaw/pi-dynamic-workflows
 ```
 
-Then `/reload` in Pi. The extension registers a `workflow` tool and activates it on session start.
+Then `/reload` in Pi. The extension registers the `workflow` tool and the `/workflows`, `/deep-research`, and `/adversarial-review` commands.
 
 <details>
 <summary>From source (for development)</summary>
@@ -25,55 +49,72 @@ pi install /path/to/pi-dynamic-workflows
 ```
 </details>
 
-## Usage
+## 30-second demo
 
-Ask Pi for a workflow in plain language:
+Just ask for a workflow in plain language:
 
 ```text
-Run a workflow to inspect this repository and summarize the main modules.
+Run a workflow to audit every route under src/routes/ for missing auth checks.
 ```
 
-The model writes a workflow script and calls the `workflow` tool. Live progress streams inline:
+Pi writes the script and runs it in the background — your turn ends right away, and a compact progress view streams in the "Workflows running" task panel while you keep working:
 
 ```text
-◆ Workflow: inspect_project (3/3 done · 12,480 tokens)
+◆ Workflow: auth_audit (5/5 done · 48,210 tokens · $0.0131)
   ✓ Scan 1/1
-    #1 ✓ repo inventory
-  ✓ Analyze 2/2
-    #2 ✓ source modules
-    #3 ✓ final summary
+    #1 ✓ enumerate routes
+  ✓ Review 3/3
+    #2 ✓ routes/users.ts
+    #3 ✓ routes/admin.ts
+    #4 ✓ routes/billing.ts
+  ✓ Verify 1/1
+    #5 ✓ adversarial recheck
 ```
 
-Press `Esc` to cancel a running run; active subagents are aborted and surfaced as skipped.
+When it finishes, the result is delivered back into the conversation and the turn auto-continues — queued after whatever you're doing so it never interrupts. (Need the result inline in the same turn instead? The model can pass `background: false` to block.)
 
-### Background runs & `/workflows`
+## What's different from upstream
 
-Ask for a background workflow (the model passes `background: true`) and it runs without blocking your session. Manage it with the `/workflows` command:
+This fork turns the original's roadmap into working, tested features:
 
-```text
-/workflows                 # open the interactive navigator (plain list in print mode)
-/workflows list            # force the plain-text list
-/workflows status <id>     # watch a running run live (status bar), prints result when done
-/workflows stop <id>       # abort a running run
-/workflows pause <id>      # pause a running run
-/workflows resume <id>     # resume an interrupted run (replays cached results)
-/workflows rm <id>         # remove a run from the list
-```
+| Capability | Upstream | This fork |
+| --- | :---: | :---: |
+| Core `agent`/`parallel`/`pipeline` runtime | ✅ | ✅ |
+| Structured (JSON-Schema) subagent output | ✅ | ✅ |
+| **Token & cost accounting** | estimate | ✅ real, from the SDK session |
+| **Per-agent / per-phase model routing** | prose-only* | ✅ actually switches models |
+| **`/workflows` command + interactive TUI** | — | ✅ full keyboard navigator |
+| **Resume an interrupted run** | — | ✅ journaled, replays the prefix |
+| **Git worktree isolation** | — | ✅ real worktrees, auto-cleanup |
+| **`/deep-research` with real web access** | — | ✅ live search + cross-checking |
+| **Saved workflows as `/<name>`** | — | ✅ |
+| **Nested `workflow()`** | — | ✅ shares the global caps |
+| **Non-blocking background runs + live task panel + auto-continue delivery** | — | ✅ |
+| Test suite | minimal | ✅ 43 tests + real Pi end-to-end |
 
-### Bundled workflows
+<sub>*Upstream injected the requested model as a text line in the prompt; it never changed the subagent's actual model.</sub>
+
+## Commands
 
 ```text
-/deep-research <question>      # web-researched, source-cross-checked report
-/adversarial-review <task>     # findings cross-checked by skeptical reviewers
+/workflows                 # open the interactive navigator (plain list in print mode)
+/workflows status <id>     # watch a running run live; prints the result when it finishes
+/workflows save <name>     # save the latest run's script as a reusable /<name> command
+/workflows pause|resume|stop|rm <id>
+
+/deep-research <question>  # web-researched, source-cross-checked report
+/adversarial-review <task> # findings cross-checked by skeptical reviewers
 ```
 
-`/deep-research` fans out web searches across several angles, fetches the top sources with real `web_search` / `web_fetch` tools, keeps only claims supported by multiple sources, and writes a cited report.
+In the **interactive navigator**: `↑/↓` (or `j/k`) select · `enter`/`→` open · `esc`/`←` back · `j/k` scroll detail · `p` pause · `x` stop · `r` restart (re-runs the whole workflow as a fresh background run) · `s` save · `q` quit. The agents list and each agent's detail show **which model it ran on**.
 
-Save any run as a reusable command: `/workflows save <name>` writes the most recent run's script to `.pi/workflows/saved/<name>.json`, and it immediately becomes `/<name>` (arguments parsed as `key=value` + positionals into `args`).
+### Workflows mode (input box)
 
-## Workflow script shape
+As you type, the words `workflow`/`workflows` light up as a **flowing rainbow** — a signal that submitting this message will deliberately run a workflow (the message is rewritten to ask Pi to orchestrate subagents rather than answer directly). Changed your mind? Press **Backspace** once right after the word: it turns plain white (disarmed) without being deleted. Type a fresh trigger word to re-arm. Slash commands like `/workflows` are left alone (never highlighted). Everything else about the editor — history, autocomplete, paste, multiline — is unchanged.
 
-A workflow is plain JavaScript. The first statement must export literal metadata:
+## Writing a workflow
+
+A workflow is plain JavaScript whose first statement exports literal metadata:
 
 ```js
 export const meta = {
@@ -102,7 +143,7 @@ return { inventory, summary }
 | `workflow(name, args)` | Run a saved workflow inline and return its result (one level deep; shares the global caps). |
 | `log(message)` | Append a workflow-level log line. |
 | `args` | Optional JSON value passed via the tool's `args` parameter. |
-| `budget` | `{ total, spent(), remaining() }` token-budget tracker. |
+| `budget` | `{ total, spent(), remaining() }` token-budget tracker (real tokens). |
 | `cwd`, `process.cwd()` | Working directory for subagents. |
 
 ### Agent options
@@ -111,16 +152,18 @@ return { inventory, summary }
 | --- | --- | --- |
 | `label` | string | Human-readable label for progress display |
 | `phase` | string | Override the current phase for this agent |
-| `schema` | object | JSON Schema for structured output |
+| `schema` | object | JSON Schema → the subagent returns a validated object |
 | `model` | string | Run this agent on a specific model — `provider/modelId` or a bare `modelId` |
 | `isolation` | `"worktree"` | Run this agent in its own throwaway git worktree (parallel edits without conflict) |
 | `timeoutMs` | number | Override the default 5-minute agent timeout |
 
-Models can also be set per phase via `meta.phases[].model`. Precedence is `opts.model` > phase model > session default; an unknown model logs a warning and falls back to the default.
+Models can also be set per phase via `meta.phases[].model`. Precedence: `opts.model` > phase model > session default; an unknown model logs a warning and falls back. The model each agent ran on is recorded and shown in the `/workflows` navigator.
+
+**Model routing is decided by the assistant, not hardcoded.** When it writes a workflow, Pi is given the routing policy and the list of your currently authenticated models, and picks each agent's `model` accordingly: a lighter same-family model (one tier below your main model — e.g. Claude→Haiku, GPT→a mini) for exploration/search/gathering agents, and your main model for analysis/judgment/decision agents. If you name a specific model, that wins.
 
 ### Structured output
 
-Pass a JSON Schema via `opts.schema` and the subagent returns a validated object:
+Pass a JSON Schema and the subagent returns a validated object instead of prose:
 
 ```js
 const finding = await agent('Find security-sensitive files.', {
@@ -136,51 +179,38 @@ const finding = await agent('Find security-sensitive files.', {
 })
 ```
 
-Backed by a Pi `structured_output` tool with `terminate: true`, so the subagent ends on that call.
+Backed by a Pi `structured_output` tool with `terminate: true`, so the subagent ends on that call — no wasted follow-up turn.
 
-### Determinism rules
+### Determinism
 
-Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`, `new Date()`, `Math.random()`, `require`/`import`/`fs`/network, and (inside `meta`) spreads, computed keys, template interpolation, and function calls. This keeps `meta` parseable and runs reproducible.
-
-## What works today
-
-- **Core runtime** — `agent` / `parallel` / `pipeline` / `phase` / `log` / `budget` in a sandboxed script
-- **Structured output** — JSON-Schema-validated subagent results
-- **Real token & cost accounting** — read from each subagent's SDK session (input / output / total / cost), with a character estimate only as fallback when a provider reports no usage; `budget` gates on the real total
-- **Real per-agent / per-phase model routing** — `opts.model` and `meta.phases[].model` actually select the model (resolved against your authed model registry), with graceful fallback
-- **`/workflows` interactive navigator** — `/workflows` opens a focused TUI you drill through with the keyboard (runs → phases → agents → agent detail): `↑/↓` (or `j/k`) select, `enter`/`→` open, `esc`/`←` back, `j/k` scroll detail, `p` pause/resume, `x` stop, `s` save, `q` quit. In print/RPC mode it falls back to plain text
-- **Live task panel + background delivery** — while a `background: true` run is going, a "Workflows running" panel sits below the input (focus it and press `enter` to open the navigator); when the run finishes, its result is delivered back into the conversation so your paused task continues
-- **Bundled `/deep-research` & `/adversarial-review`** — `/deep-research` runs real web searches (via built-in `web_search` / `web_fetch` tools), extracts claims, cross-checks them across sources, and reports only what survived; `/adversarial-review` investigates a task then has independent skeptics try to refute each finding, keeping only those that clear an agreement threshold
-- **Saved workflows as `/<name>`** — save a run's script with `/workflows save <name>` and it becomes a reusable slash command; arguments are parsed (`key=value` and positionals) and passed through as `args`
-- **Nested `workflow()`** — call `await workflow('saved-name', args)` inside a script to run a saved workflow inline; nesting is one level deep and shares the parent's concurrency limiter, agent counter, and token budget so the global caps hold
-- **Resume** — each agent result is journaled by a deterministic call index; resuming replays the unchanged prefix from cache (no re-run, no tokens) and runs only new or edited calls live
-- **Worktree isolation** — `isolation: "worktree"` runs an agent in its own git worktree on a throwaway branch, so parallel agents can edit the same files without conflict; the worktree is torn down after (results are not auto-merged), and it falls back to a logged no-op outside a git repo
-- **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
-- **Live progress + token/cost display**, `Esc` to abort
-- **Log persistence** to `.pi/workflows/runs/`
+Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`, `new Date()`, `Math.random()`, `require`/`import`/`fs`/network, and (inside `meta`) spreads, computed keys, template interpolation, and function calls. This keeps `meta` parseable and runs **reproducible** — which is what makes resume reliable.
 
 ## How it works
 
 ```text
 user prompt
-  → Pi model writes a workflow script
-  → workflow tool parses + runs it in a vm sandbox
-  → script calls agent() / parallel() / pipeline()
+  → Pi writes a workflow script
+  → the workflow tool parses + runs it in a vm sandbox
+  → the script calls agent() / parallel() / pipeline()
   → each agent() spawns a fresh in-memory Pi subagent session
-  → snapshots stream back as compact progress
-  → final structured result returns to the parent assistant
+  → results are journaled; snapshots stream back as compact progress
+  → the final structured result returns to the parent assistant
 ```
 
-Subagents run in fresh in-memory Pi sessions with the standard coding tools (read, bash, edit, write, grep, find, ls), so they work exactly like a normal Pi turn.
+Subagents run in fresh in-memory Pi sessions with the standard coding tools (read, bash, edit, write, grep, find, ls), so they work exactly like a normal Pi turn — and inherit your provider/model settings.
 
 ## Development
 
 ```bash
 npm install
-npm test     # biome check + tsc + unit tests
+npm test     # biome check + tsc + 43 unit tests
 ```
 
-Parser unit tests live in `tests/workflow-parser.test.ts`.
+Tests live in `tests/`. Each feature is also verified end-to-end against a real Pi subagent session before release.
+
+## Credits
+
+Fork of [Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows), rebuilt on `@earendil-works/*` packages with the advertised feature set implemented and a subagent settings-inheritance fix. Inspired by [Claude Code dynamic workflows](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code).
 
 ## License
 

package/dist/agent.d.ts

@@ -9,6 +9,12 @@ export interface WorkflowAgentOptions {
     /** Extra system guidance prepended to every subagent task. */
     instructions?: string;
 }
+/**
+ * List the user's currently available models (those with auth configured) as
+ * `provider/modelId` specs. Used to tell the workflow author which models it may
+ * route agents to. Best-effort: returns [] if the registry can't be built.
+ */
+export declare function listAvailableModelSpecs(): string[];
 /** Real token/cost usage for a single subagent run, read from the SDK session. */
 export interface AgentUsage {
     input: number;

package/dist/agent.js

@@ -1,6 +1,22 @@
 import { join } from "node:path";
 import { AuthStorage, createAgentSession, createCodingTools, getAgentDir, ModelRegistry, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { createStructuredOutputTool } from "./structured-output.js";
+/**
+ * List the user's currently available models (those with auth configured) as
+ * `provider/modelId` specs. Used to tell the workflow author which models it may
+ * route agents to. Best-effort: returns [] if the registry can't be built.
+ */
+export function listAvailableModelSpecs() {
+    try {
+        const dir = getAgentDir();
+        const auth = AuthStorage.create(join(dir, "auth.json"));
+        const registry = ModelRegistry.create(auth, join(dir, "models.json"));
+        return registry.getAvailable().map((m) => `${m.provider}/${m.id}`);
+    }
+    catch {
+        return [];
+    }
+}
 export class WorkflowAgent {
     cwd;
     baseTools;

package/dist/display.d.ts

@@ -11,6 +11,8 @@ export interface WorkflowAgentSnapshot {
     error?: string;
     /** Tokens used by this agent. */
     tokens?: number;
+    /** The model this agent ran on (provider/id), when known. */
+    model?: string;
 }
 export interface WorkflowSnapshot {
     name: string;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { AdversarialReviewConfig } from "./adversarial-review.js";
 export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
 export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
-export { WorkflowAgent } from "./agent.js";
+export { listAvailableModelSpecs, WorkflowAgent } from "./agent.js";
 export type { AutoWorkflowConfig } from "./auto-workflow.js";
 export { shouldUseWorkflow, suggestWorkflowScript } from "./auto-workflow.js";
 export { registerBuiltinWorkflows } from "./builtin-commands.js";
@@ -25,12 +25,13 @@ export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-t
 export type { AgentOptions, JournalEntry, SharedRuntime, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
+export { buildForcedWorkflowPrompt, colorizeWorkflow, endsWithTrigger, hasTrigger, installWorkflowEditor, RAINBOW, tokenizeAnsi, WorkflowEditor, type WorkflowModeState, } from "./workflow-editor.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
-export { createWorkflowTool } from "./workflow-tool.js";
+export { backgroundStartedText, createWorkflowTool } from "./workflow-tool.js";
 export { keyToAction, type NavAction, NavigatorModel, NavigatorState, openWorkflowNavigator, renderNavigator, type ViewKind, } from "./workflow-ui.js";
 export type { Worktree } from "./worktree.js";
 export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
-export { WorkflowAgent } from "./agent.js";
+export { listAvailableModelSpecs, WorkflowAgent } from "./agent.js";
 export { shouldUseWorkflow, suggestWorkflowScript } from "./auto-workflow.js";
 export { registerBuiltinWorkflows } from "./builtin-commands.js";
 export * from "./config.js";
@@ -15,8 +15,9 @@ export { installResultDelivery, installTaskPanel } from "./task-panel.js";
 export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
+export { buildForcedWorkflowPrompt, colorizeWorkflow, endsWithTrigger, hasTrigger, installWorkflowEditor, RAINBOW, tokenizeAnsi, WorkflowEditor, } from "./workflow-editor.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
-export { createWorkflowTool } from "./workflow-tool.js";
+export { backgroundStartedText, createWorkflowTool } from "./workflow-tool.js";
 export { keyToAction, NavigatorModel, NavigatorState, openWorkflowNavigator, renderNavigator, } from "./workflow-ui.js";
 export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/run-persistence.d.ts

@@ -12,6 +12,8 @@ export interface PersistedAgentState {
     error?: string;
     startedAt?: string;
     endedAt?: string;
+    /** The model this agent ran on (provider/id), when known. */
+    model?: string;
 }
 export interface PersistedRunState {
     runId: string;

package/dist/task-panel.d.ts

@@ -1,7 +1,7 @@
 /**
  * Background-run UX, mirroring Claude Code:
  *  - A live task panel below the input lists in-progress runs while you keep working.
- *    Focus it (↓) and press enter to open the full navigator.
+ *    It is informational; run /workflows to open the full navigator.
  *  - When a background run finishes, its result is delivered back into the
  *    conversation so the paused task continues with the outcome.
  */
@@ -13,12 +13,21 @@ export interface TaskPanelOptions {
     cwd?: string;
 }
 /**
- * Deliver a background run's result into the conversation when it completes or
- * fails. Set up once per extension; idempotent via an internal guard.
+ * When a background run finishes (or fails), deliver its result back into the
+ * conversation AND continue the turn so the assistant can act on it — without
+ * blocking the user meanwhile:
+ *
+ *  - `triggerTurn: true` starts a fresh turn when the agent is idle, feeding the
+ *    result to the model so the paused conversation continues.
+ *  - `deliverAs: "followUp"` means that if the user is busy in another turn, the
+ *    result is queued and picked up after that turn finishes — never interrupting.
+ *
+ * Set up once per extension; idempotent via an internal guard.
  */
 export declare function installResultDelivery(pi: ExtensionAPI, manager: WorkflowManager): void;
 /**
  * Install the live "workflows running" panel below the editor. Re-rendered on
- * every manager event; focus + enter opens the navigator.
+ * every manager event. Informational only — the user opens the navigator with
+ * /workflows. (`_pi`/`_opts` are kept for signature stability.)
  */
-export declare function installTaskPanel(pi: ExtensionAPI, manager: WorkflowManager, ui: ExtensionUIContext, opts?: TaskPanelOptions): void;
+export declare function installTaskPanel(_pi: ExtensionAPI, manager: WorkflowManager, ui: ExtensionUIContext, _opts?: TaskPanelOptions): void;

package/dist/task-panel.js

@@ -1,42 +1,56 @@
 /**
  * Background-run UX, mirroring Claude Code:
  *  - A live task panel below the input lists in-progress runs while you keep working.
- *    Focus it (↓) and press enter to open the full navigator.
+ *    It is informational; run /workflows to open the full navigator.
  *  - When a background run finishes, its result is delivered back into the
  *    conversation so the paused task continues with the outcome.
  */
-import { parseKey } from "@earendil-works/pi-tui";
-import { openWorkflowNavigator } from "./workflow-ui.js";
 const RUN_EVENTS = ["agentStart", "agentEnd", "phase", "log", "complete", "error", "stopped", "paused", "resumed"];
 function deliverText(run) {
     const r = run.result?.result;
     const body = r && typeof r.report === "string" && r.report.trim() ? r.report : JSON.stringify(run.result?.result, null, 2);
     const tokens = run.result?.tokenUsage ? ` · ${run.result.tokenUsage.total.toLocaleString()} tokens` : "";
     const agents = run.result?.agentCount ?? run.snapshot.agentCount;
-    return `✓ Workflow "${run.snapshot.name}" finished (${agents} agents${tokens}).\n\n${body}`;
+    return [
+        `✓ Background workflow "${run.snapshot.name}" finished (${agents} agents${tokens}).`,
+        "Continue helping the user based on this result.",
+        "",
+        body,
+    ].join("\n");
 }
 /**
- * Deliver a background run's result into the conversation when it completes or
- * fails. Set up once per extension; idempotent via an internal guard.
+ * When a background run finishes (or fails), deliver its result back into the
+ * conversation AND continue the turn so the assistant can act on it — without
+ * blocking the user meanwhile:
+ *
+ *  - `triggerTurn: true` starts a fresh turn when the agent is idle, feeding the
+ *    result to the model so the paused conversation continues.
+ *  - `deliverAs: "followUp"` means that if the user is busy in another turn, the
+ *    result is queued and picked up after that turn finishes — never interrupting.
+ *
+ * Set up once per extension; idempotent via an internal guard.
  */
 export function installResultDelivery(pi, manager) {
     if (manager.__deliveryInstalled)
         return;
     manager.__deliveryInstalled = true;
+    const deliver = (content) => {
+        void pi.sendMessage({ customType: "workflow-result", content, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+    };
     manager.on("complete", ({ runId }) => {
         const run = manager.getRun(runId);
-        if (run)
-            void pi.sendMessage({ customType: "workflow-result", content: deliverText(run), display: true });
+        // Only background/resumed runs are delivered: a foreground (sync) run already
+        // returns its result inline as the tool result, so re-delivering would dup it.
+        if (run?.background)
+            deliver(deliverText(run));
     });
     manager.on("error", ({ runId, error }) => {
-        void pi.sendMessage({
-            customType: "workflow-result",
-            content: `✗ Workflow ${runId} failed: ${error?.message ?? "unknown error"}`,
-            display: true,
-        });
+        if (!manager.getRun(runId)?.background)
+            return;
+        deliver(`✗ Background workflow ${runId} failed: ${error?.message ?? "unknown error"}`);
     });
 }
-function renderPanel(manager, theme, focused) {
+function renderPanel(manager, theme) {
     const active = manager.listRuns().filter((r) => r.status === "running" || r.status === "paused");
     if (!active.length)
         return [];
@@ -48,29 +62,23 @@ function renderPanel(manager, theme, focused) {
         const phase = live?.snapshot.currentPhase ? ` · ${live.snapshot.currentPhase}` : "";
         return `  ${icon} ${r.workflowName}  ${done}/${agents.length} agents${phase}`;
     });
-    const hint = focused
-        ? theme.fg("accent", "  enter: open · esc: back")
-        : theme.fg("dim", "  ↓ then enter, or /workflows, to open");
+    const hint = theme.fg("dim", "  run /workflows to open");
     return [theme.bold(`Workflows running (${active.length}):`), ...rows, hint];
 }
 /**
  * Install the live "workflows running" panel below the editor. Re-rendered on
- * every manager event; focus + enter opens the navigator.
+ * every manager event. Informational only — the user opens the navigator with
+ * /workflows. (`_pi`/`_opts` are kept for signature stability.)
  */
-export function installTaskPanel(pi, manager, ui, opts = {}) {
+export function installTaskPanel(_pi, manager, ui, _opts = {}) {
     ui.setWidget("workflow-tasks", (tui, theme) => {
         const onEvent = () => tui.requestRender();
         for (const ev of RUN_EVENTS)
             manager.on(ev, onEvent);
+        // Purely informational: it lists running runs and re-renders on events. To
+        // open the navigator, the user runs /workflows (the panel takes no input).
         const comp = {
-            focused: false,
-            render: () => renderPanel(manager, theme, comp.focused ?? false),
-            handleInput: (data) => {
-                const key = parseKey(data);
-                if (key === "enter" || key === "return" || key === "right") {
-                    void openWorkflowNavigator(pi, manager, ui, opts);
-                }
-            },
+            render: () => renderPanel(manager, theme),
             invalidate: () => { },
             dispose: () => {
                 for (const ev of RUN_EVENTS)

package/dist/workflow-editor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * "Workflows mode" input affordance, à la a smart input box:
+ *
+ *  - While the editor text contains the word `workflow`/`workflows`, those letters
+ *    render as a flowing rainbow, signalling that submitting will engage a workflow.
+ *  - Pressing Backspace immediately after such a word toggles the highlight OFF
+ *    (the word stays, but turns plain white) — a non-destructive "don't run a
+ *    workflow after all". Re-typing a fresh trigger word turns it back on.
+ *  - When the highlight is ON at submit time, the user's message is transformed to
+ *    instruct Pi to actually run the workflow tool.
+ *
+ * Implementation: we replace the core editor with a thin subclass of the exported
+ * `CustomEditor` (which itself extends pi-tui's `Editor`), overriding only
+ * `render()` (to colorize) and `handleInput()` (for the Backspace toggle). All
+ * other editor behavior — history, autocomplete, paste, undo, multiline — is
+ * inherited untouched.
+ */
+import { CustomEditor, type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+/** 256-color ring cycling through the spectrum — shifted by a tick to "flow". */
+export declare const RAINBOW: number[];
+export declare function hasTrigger(text: string): boolean;
+export declare function endsWithTrigger(textBeforeCursor: string): boolean;
+/** Shared, mutable view of whether "workflows mode" is currently armed. */
+export interface WorkflowModeState {
+    active: boolean;
+}
+interface AnsiToken {
+    esc?: string;
+    ch?: string;
+}
+/**
+ * Split a rendered line into ANSI-escape tokens (passed through verbatim) and
+ * single visible-character tokens. Handles CSI sequences (`\x1b[…m`, e.g. the
+ * cursor's inverse-video) and APC/OSC string sequences (e.g. the zero-width
+ * `CURSOR_MARKER` = `\x1b_pi:c\x07`) so colorization never corrupts them.
+ */
+export declare function tokenizeAnsi(line: string): AnsiToken[];
+/**
+ * Colorize every `workflow`/`workflows` occurrence in a rendered line with a
+ * flowing rainbow, leaving all ANSI escapes (cursor, markers) intact. Returns the
+ * line unchanged when it contains no trigger.
+ */
+export declare function colorizeWorkflow(line: string, tick: number, palette?: number[]): string;
+/**
+ * Editor that paints the trigger words and owns the on/off toggle. Reads/writes
+ * `state.active` so the extension's `input` handler can decide whether to force a
+ * workflow at submit time.
+ */
+export declare class WorkflowEditor extends CustomEditor {
+    private readonly modeState;
+    private tick;
+    private timer?;
+    /** Toggled off by Backspace-after-word; re-armed when a fresh trigger appears. */
+    private disabled;
+    private wasTriggered;
+    constructor(tui: TUI, theme: EditorTheme, keybindings: ConstructorParameters<typeof CustomEditor>[2], modeState: WorkflowModeState);
+    /** Highlighted/armed: a trigger is present and the user hasn't toggled it off. */
+    isActive(): boolean;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    /** Absolute text before the cursor, used to detect "right after the word". */
+    private cursorAfterTrigger;
+    private syncState;
+    private reconcileAnimation;
+}
+/** The directive appended to a submitted message when workflows mode is armed. */
+export declare function buildForcedWorkflowPrompt(text: string): string;
+/**
+ * Install the workflows-mode editor and the submit-time forcing hook.
+ * Call once with the UI context (e.g. in `session_start`).
+ */
+export declare function installWorkflowEditor(pi: ExtensionAPI, ui: ExtensionUIContext): WorkflowModeState;
+export {};