@quintinshaw/pi-dynamic-workflows 1.9.1 → 1.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Claude-Code-style dynamic workflows for Pi — fan a task out across 100s of subagents with real model routing, token/cost accounting, resume, git-worktree isolation, an interactive /workflows TUI, and a real /deep-research.",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent.ts

@@ -24,6 +24,22 @@ export interface WorkflowAgentOptions {
   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 function listAvailableModelSpecs(): string[] {
+  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 [];
+  }
+}
+
 /** Real token/cost usage for a single subagent run, read from the SDK session. */
 export interface AgentUsage {
   input: number;

package/src/display.ts

@@ -13,6 +13,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 {

package/src/index.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";
@@ -58,12 +58,23 @@ export type {
 } 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,

package/src/run-persistence.ts

@@ -18,6 +18,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 {

package/src/task-panel.ts

@@ -1,17 +1,15 @@
 /**
  * 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 type { ExtensionAPI, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
-import { parseKey } from "@earendil-works/pi-tui";
 import type { ManagedRun, WorkflowManager } from "./workflow-manager.js";
 import type { WorkflowStorage } from "./workflow-saved.js";
-import { openWorkflowNavigator } from "./workflow-ui.js";
 
 const RUN_EVENTS = ["agentStart", "agentEnd", "phase", "log", "complete", "error", "stopped", "paused", "resumed"];
 
@@ -26,31 +24,50 @@ function deliverText(run: ManagedRun): string {
     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: ExtensionAPI, manager: WorkflowManager): void {
   if ((manager as unknown as { __deliveryInstalled?: boolean }).__deliveryInstalled) return;
   (manager as unknown as { __deliveryInstalled?: boolean }).__deliveryInstalled = true;
 
+  const deliver = (content: string) => {
+    void pi.sendMessage(
+      { customType: "workflow-result", content, display: true },
+      { triggerTurn: true, deliverAs: "followUp" },
+    );
+  };
+
   manager.on("complete", ({ runId }: { runId: string }) => {
     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 }: { runId: string; error?: { message?: string } }) => {
-    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: WorkflowManager, theme: Theme, focused: boolean): string[] {
+function renderPanel(manager: WorkflowManager, theme: Theme): string[] {
   const active = manager.listRuns().filter((r) => r.status === "running" || r.status === "paused");
   if (!active.length) return [];
   const rows = active.map((r) => {
@@ -61,36 +78,30 @@ function renderPanel(manager: WorkflowManager, theme: Theme, focused: boolean):
     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: ExtensionAPI,
+  _pi: ExtensionAPI,
   manager: WorkflowManager,
   ui: ExtensionUIContext,
-  opts: TaskPanelOptions = {},
+  _opts: TaskPanelOptions = {},
 ): void {
   ui.setWidget(
     "workflow-tasks",
     (tui: TUI, theme: Theme) => {
       const onEvent = () => tui.requestRender();
       for (const ev of RUN_EVENTS) manager.on(ev, onEvent);
-      const comp: Component & { focused?: boolean; dispose?(): void } = {
-        focused: false,
-        render: () => renderPanel(manager, theme, comp.focused ?? false),
-        handleInput: (data: string) => {
-          const key = parseKey(data);
-          if (key === "enter" || key === "return" || key === "right") {
-            void openWorkflowNavigator(pi, manager, ui, opts);
-          }
-        },
+      // 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: Component & { dispose?(): void } = {
+        render: () => renderPanel(manager, theme),
         invalidate: () => {},
         dispose: () => {
           for (const ev of RUN_EVENTS) manager.off(ev, onEvent);

package/src/workflow-editor.ts

@@ -0,0 +1,252 @@
+/**
+ * "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";
+
+// A trigger is `workflow`/`workflows` (substring, case-insensitive) that is NOT
+// immediately preceded by `/` — so a slash command like `/workflows` or `/workflow`
+// is left alone (not colored, not armed).
+/** Matches a trigger anywhere in the text. */
+const TRIGGER = /(?<!\/)workflows?/i;
+/** Global variant for finding every occurrence to colorize. */
+const TRIGGER_G = /(?<!\/)workflows?/gi;
+/** True when the text immediately before the cursor ends with a trigger word. */
+const TRIGGER_AT_END = /(?<!\/)workflows?$/i;
+
+/** 256-color ring cycling through the spectrum — shifted by a tick to "flow". */
+export const RAINBOW = [
+  196, 160, 202, 166, 208, 172, 214, 178, 220, 184, 226, 190, 118, 82, 46, 47, 48, 49, 50, 51, 45, 39, 33, 27, 21, 57,
+  93, 129, 165, 201, 198, 197,
+];
+
+export function hasTrigger(text: string): boolean {
+  return TRIGGER.test(text);
+}
+
+export function endsWithTrigger(textBeforeCursor: string): boolean {
+  return TRIGGER_AT_END.test(textBeforeCursor);
+}
+
+/** 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 function tokenizeAnsi(line: string): AnsiToken[] {
+  const tokens: AnsiToken[] = [];
+  let i = 0;
+  while (i < line.length) {
+    if (line[i] === "\x1b") {
+      let j = i + 1;
+      const next = line[j];
+      if (next === "[") {
+        // CSI: ends at a final byte in 0x40–0x7e.
+        j++;
+        while (j < line.length && !(line[j] >= "@" && line[j] <= "~")) j++;
+        j++;
+      } else if (next === "]" || next === "_" || next === "P" || next === "^") {
+        // String sequence: ends at BEL (\x07) or ST (\x1b\\).
+        j++;
+        while (j < line.length && line[j] !== "\x07" && !(line[j] === "\x1b" && line[j + 1] === "\\")) j++;
+        if (line[j] === "\x07") j++;
+        else if (line[j] === "\x1b") j += 2;
+      } else {
+        j++; // lone ESC + one byte
+      }
+      tokens.push({ esc: line.slice(i, j) });
+      i = j;
+    } else {
+      tokens.push({ ch: line[i] });
+      i++;
+    }
+  }
+  return tokens;
+}
+
+/**
+ * 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 function colorizeWorkflow(line: string, tick: number, palette: number[] = RAINBOW): string {
+  const tokens = tokenizeAnsi(line);
+  const visible = tokens
+    .filter((t) => t.ch !== undefined)
+    .map((t) => t.ch)
+    .join("");
+  if (!TRIGGER.test(visible)) return line;
+
+  const ranges: Array<[number, number]> = [];
+  TRIGGER_G.lastIndex = 0;
+  for (let m = TRIGGER_G.exec(visible); m; m = TRIGGER_G.exec(visible)) {
+    ranges.push([m.index, m.index + m[0].length]);
+  }
+  const inRange = (idx: number) => ranges.some(([s, e]) => idx >= s && idx < e);
+
+  let out = "";
+  let vi = 0;
+  for (const t of tokens) {
+    if (t.esc !== undefined) {
+      out += t.esc;
+      continue;
+    }
+    if (inRange(vi)) {
+      const color = palette[(vi + tick) % palette.length];
+      // Reset only the foreground (39) afterwards so a surrounding inverse-video
+      // (the cursor) is preserved.
+      out += `\x1b[38;5;${color}m${t.ch}\x1b[39m`;
+    } else {
+      out += t.ch ?? "";
+    }
+    vi++;
+  }
+  return out;
+}
+
+/** Backspace arrives as DEL (0x7f) or BS (0x08) depending on the terminal. */
+function isBackspace(data: string): boolean {
+  return data === "\x7f" || data === "\b";
+}
+
+/**
+ * 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 class WorkflowEditor extends CustomEditor {
+  private tick = 0;
+  private timer?: ReturnType<typeof setInterval>;
+  /** Toggled off by Backspace-after-word; re-armed when a fresh trigger appears. */
+  private disabled = false;
+  private wasTriggered = false;
+
+  constructor(
+    tui: TUI,
+    theme: EditorTheme,
+    keybindings: ConstructorParameters<typeof CustomEditor>[2],
+    private readonly modeState: WorkflowModeState,
+  ) {
+    super(tui, theme, keybindings);
+  }
+
+  /** Highlighted/armed: a trigger is present and the user hasn't toggled it off. */
+  isActive(): boolean {
+    return !this.disabled && hasTrigger(this.getText());
+  }
+
+  override handleInput(data: string): void {
+    // First Backspace right after a trigger word disarms (non-destructive).
+    if (isBackspace(data) && this.isActive() && this.cursorAfterTrigger()) {
+      this.disabled = true;
+      this.syncState();
+      this.tui.requestRender();
+      return;
+    }
+    const before = this.getText();
+    super.handleInput(data);
+    const after = this.getText();
+    if (after !== before) {
+      const now = hasTrigger(after);
+      // A freshly typed trigger re-arms a previously disabled box.
+      if (now && !this.wasTriggered) this.disabled = false;
+      this.wasTriggered = now;
+    }
+    this.syncState();
+  }
+
+  override render(width: number): string[] {
+    const lines = super.render(width);
+    // Keep the shared state current even for non-keystroke changes (history
+    // recall, programmatic setText) so the submit hook reads the right value.
+    this.syncState();
+    this.reconcileAnimation();
+    if (!this.isActive() || lines.length === 0) return lines;
+    // First and last lines are the editor's horizontal borders; only the text
+    // lines in between are colorized.
+    return lines.map((ln, i) => (i === 0 || i === lines.length - 1 ? ln : colorizeWorkflow(ln, this.tick)));
+  }
+
+  /** Absolute text before the cursor, used to detect "right after the word". */
+  private cursorAfterTrigger(): boolean {
+    const lines = this.getLines();
+    const { line, col } = this.getCursor();
+    const before = lines.slice(0, line).join("\n") + (line > 0 ? "\n" : "") + (lines[line] ?? "").slice(0, col);
+    return endsWithTrigger(before);
+  }
+
+  private syncState(): void {
+    this.modeState.active = this.isActive();
+  }
+
+  private reconcileAnimation(): void {
+    const shouldRun = this.isActive() && this.focused;
+    if (shouldRun && !this.timer) {
+      this.timer = setInterval(() => {
+        this.tick = (this.tick + 1) % (RAINBOW.length * 6);
+        this.tui.requestRender();
+      }, 90);
+      // Don't keep the process alive for the animation.
+      (this.timer as { unref?: () => void }).unref?.();
+    } else if (!shouldRun && this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+}
+
+/** The directive appended to a submitted message when workflows mode is armed. */
+export function buildForcedWorkflowPrompt(text: string): string {
+  return [
+    text,
+    "",
+    "[workflows mode] The user armed workflows mode for this message. Handle it by",
+    "running the `workflow` tool: decompose the request and orchestrate subagents",
+    "with a workflow script, rather than answering directly.",
+  ].join("\n");
+}
+
+/**
+ * Install the workflows-mode editor and the submit-time forcing hook.
+ * Call once with the UI context (e.g. in `session_start`).
+ */
+export function installWorkflowEditor(pi: ExtensionAPI, ui: ExtensionUIContext): WorkflowModeState {
+  const state: WorkflowModeState = { active: false };
+
+  ui.setEditorComponent((tui, theme, keybindings) => new WorkflowEditor(tui, theme, keybindings, state));
+
+  // When armed at submit time, rewrite the user's message to force a workflow.
+  pi.on("input", (event: { source?: string; text?: string }) => {
+    if (event.source !== "interactive" || !state.active || !event.text) return { action: "continue" } as const;
+    state.active = false; // consume the arm for this submission
+    return { action: "transform", text: buildForcedWorkflowPrompt(event.text) } as const;
+  });
+
+  return state;
+}