@quintinshaw/pi-dynamic-workflows 1.9.0 → 1.9.2

package/dist/workflow-editor.js

@@ -0,0 +1,228 @@
+/**
+ * "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 } from "@earendil-works/pi-coding-agent";
+// 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) {
+    return TRIGGER.test(text);
+}
+export function endsWithTrigger(textBeforeCursor) {
+    return TRIGGER_AT_END.test(textBeforeCursor);
+}
+/**
+ * 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) {
+    const tokens = [];
+    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, tick, palette = RAINBOW) {
+    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 = [];
+    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) => 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) {
+    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 {
+    modeState;
+    tick = 0;
+    timer;
+    /** Toggled off by Backspace-after-word; re-armed when a fresh trigger appears. */
+    disabled = false;
+    wasTriggered = false;
+    constructor(tui, theme, keybindings, modeState) {
+        super(tui, theme, keybindings);
+        this.modeState = modeState;
+    }
+    /** Highlighted/armed: a trigger is present and the user hasn't toggled it off. */
+    isActive() {
+        return !this.disabled && hasTrigger(this.getText());
+    }
+    handleInput(data) {
+        // 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();
+    }
+    render(width) {
+        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". */
+    cursorAfterTrigger() {
+        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);
+    }
+    syncState() {
+        this.modeState.active = this.isActive();
+    }
+    reconcileAnimation() {
+        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.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) {
+    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, ui) {
+    const state = { 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) => {
+        if (event.source !== "interactive" || !state.active || !event.text)
+            return { action: "continue" };
+        state.active = false; // consume the arm for this submission
+        return { action: "transform", text: buildForcedWorkflowPrompt(event.text) };
+    });
+    return state;
+}

package/dist/workflow-manager.d.ts

@@ -2,7 +2,8 @@
  * Workflow manager for background execution, pause/resume, and run management.
  */
 import { EventEmitter } from "node:events";
-import type { WorkflowSnapshot } from "./display.js";
+import type { WorkflowAgent } from "./agent.js";
+import { type WorkflowSnapshot } from "./display.js";
 import { WorkflowError } from "./errors.js";
 import { type PersistedRunState, type RunPersistence, type RunStatus } from "./run-persistence.js";
 import { type JournalEntry, type WorkflowRunResult } from "./workflow.js";
@@ -19,12 +20,36 @@ export interface ManagedRun {
     args?: unknown;
     /** Accumulated agent results for resume (deterministic call index -> result). */
     journal: JournalEntry[];
+    /**
+     * True when the run was started in the background (or resumed) and the caller is
+     * not awaiting its result inline. Only background runs deliver their result back
+     * into the conversation; a foreground sync run already returns it as the tool
+     * result, so re-delivering would duplicate it.
+     */
+    background: boolean;
+}
+/** Per-execution options shared by sync, background, and resume runs. */
+export interface ExecOptions {
+    /** Replay these journaled agent results for the unchanged prefix (resume). */
+    resumeJournal?: Map<number, JournalEntry>;
+    /** Cap on total agents for this run. */
+    maxAgents?: number;
+    /** Per-agent timeout in milliseconds. */
+    agentTimeoutMs?: number;
+    /** Host signal (e.g. tool/Esc) that should abort this run when fired. */
+    externalSignal?: AbortSignal;
+    /** Called with the live snapshot on every progress event. */
+    onProgress?: (snapshot: WorkflowSnapshot) => void;
 }
 export interface WorkflowManagerOptions {
     cwd?: string;
     concurrency?: number;
     /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
     loadSavedWorkflow?: (name: string) => string | undefined;
+    /** Inject a custom agent runner (tests); defaults to a real subagent session. */
+    agent?: Pick<WorkflowAgent, "run">;
+    /** The session's main model (provider/id), for auto-tiering explore agents. */
+    mainModel?: string;
 }
 export declare class WorkflowManager extends EventEmitter {
     private runs;
@@ -32,7 +57,12 @@ export declare class WorkflowManager extends EventEmitter {
     private cwd;
     private concurrency;
     private loadSavedWorkflow?;
+    private agent?;
+    /** The session's main model (provider/id), for auto-tiering explore agents. */
+    private mainModel?;
     constructor(options?: WorkflowManagerOptions);
+    /** Set the session's main model (provider/id). Used to auto-tier explore agents. */
+    setMainModel(spec: string | undefined): void;
     /**
      * Start a workflow in the background.
      * Returns immediately with a run ID; the workflow executes asynchronously.
@@ -42,9 +72,14 @@ export declare class WorkflowManager extends EventEmitter {
         promise: Promise<WorkflowRunResult>;
     };
     /**
-     * Execute a workflow synchronously (blocking).
+     * Execute a workflow synchronously (blocking) while still tracking it like a
+     * background run, so the `/workflows` navigator and the live task panel see it.
+     * `onProgress` fires on every progress event with the current snapshot, letting
+     * a caller (e.g. the workflow tool) drive its own inline display.
      */
-    runSync(script: string, args?: unknown): Promise<WorkflowRunResult>;
+    runSync(script: string, args?: unknown, exec?: ExecOptions): Promise<WorkflowRunResult>;
+    /** Build a fresh managed run with an empty snapshot. */
+    private createManaged;
     private executeRun;
     private persistRun;
     /**

package/dist/workflow-manager.js

@@ -2,6 +2,7 @@
  * Workflow manager for background execution, pause/resume, and run management.
  */
 import { EventEmitter } from "node:events";
+import { preview } from "./display.js";
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
 import { createRunPersistence, generateRunId, } from "./run-persistence.js";
 import { parseWorkflowScript, runWorkflow } from "./workflow.js";
@@ -11,13 +12,22 @@ export class WorkflowManager extends EventEmitter {
     cwd;
     concurrency;
     loadSavedWorkflow;
+    agent;
+    /** The session's main model (provider/id), for auto-tiering explore agents. */
+    mainModel;
     constructor(options = {}) {
         super();
         this.cwd = options.cwd ?? process.cwd();
         this.concurrency = options.concurrency ?? 8;
         this.loadSavedWorkflow = options.loadSavedWorkflow;
+        this.agent = options.agent;
+        this.mainModel = options.mainModel;
         this.persistence = createRunPersistence(this.cwd);
     }
+    /** Set the session's main model (provider/id). Used to auto-tier explore agents. */
+    setMainModel(spec) {
+        this.mainModel = spec;
+    }
     /**
      * Start a workflow in the background.
      * Returns immediately with a run ID; the workflow executes asynchronously.
@@ -45,6 +55,7 @@ export class WorkflowManager extends EventEmitter {
             script,
             args,
             journal: [],
+            background: true,
         };
         this.runs.set(runId, managed);
         // Persist initial state
@@ -65,14 +76,24 @@ export class WorkflowManager extends EventEmitter {
         return { runId, promise };
     }
     /**
-     * Execute a workflow synchronously (blocking).
+     * Execute a workflow synchronously (blocking) while still tracking it like a
+     * background run, so the `/workflows` navigator and the live task panel see it.
+     * `onProgress` fires on every progress event with the current snapshot, letting
+     * a caller (e.g. the workflow tool) drive its own inline display.
      */
-    async runSync(script, args) {
-        const runId = generateRunId();
-        const controller = new AbortController();
+    async runSync(script, args, exec = {}) {
+        const managed = this.createManaged(script, args);
+        this.runs.set(managed.runId, managed);
+        // Persist the initial state immediately so listRuns()/the task panel can see
+        // the run the moment it starts, not only after the first agent journals.
+        this.persistRun(managed);
+        return this.executeRun(managed, script, args, exec);
+    }
+    /** Build a fresh managed run with an empty snapshot. */
+    createManaged(script, args) {
         const parsed = parseWorkflowScript(script);
-        const managed = {
-            runId,
+        return {
+            runId: generateRunId(),
             status: "running",
             snapshot: {
                 name: parsed.meta.name,
@@ -85,22 +106,34 @@ export class WorkflowManager extends EventEmitter {
                 doneCount: 0,
                 errorCount: 0,
             },
-            controller,
+            controller: new AbortController(),
             startedAt: new Date(),
             script,
             args,
             journal: [],
+            background: false,
         };
-        this.runs.set(runId, managed);
-        return this.executeRun(managed, script, args);
     }
-    async executeRun(managed, script, args, resumeJournal) {
+    async executeRun(managed, script, args, exec = {}) {
+        const { resumeJournal, maxAgents, agentTimeoutMs, externalSignal, onProgress } = exec;
+        const progress = () => onProgress?.(managed.snapshot);
+        // Let a host abort (e.g. Esc during a blocking tool call) cancel this run.
+        if (externalSignal) {
+            if (externalSignal.aborted)
+                managed.controller.abort();
+            else
+                externalSignal.addEventListener("abort", () => managed.controller.abort(), { once: true });
+        }
         try {
             const result = await runWorkflow(script, {
                 cwd: this.cwd,
                 args,
+                agent: this.agent,
+                mainModel: this.mainModel,
                 signal: managed.controller.signal,
                 concurrency: this.concurrency,
+                maxAgents,
+                agentTimeoutMs,
                 loadSavedWorkflow: this.loadSavedWorkflow,
                 resumeJournal,
                 resumeFromRunId: resumeJournal ? managed.runId : undefined,
@@ -113,6 +146,7 @@ export class WorkflowManager extends EventEmitter {
                 onLog: (message) => {
                     managed.snapshot.logs.push(message);
                     this.emit("log", { runId: managed.runId, message });
+                    progress();
                 },
                 onPhase: (title) => {
                     managed.snapshot.currentPhase = title;
@@ -120,6 +154,7 @@ export class WorkflowManager extends EventEmitter {
                         managed.snapshot.phases.push(title);
                     }
                     this.emit("phase", { runId: managed.runId, title });
+                    progress();
                 },
                 onAgentStart: (event) => {
                     managed.snapshot.agents.push({
@@ -128,8 +163,10 @@ export class WorkflowManager extends EventEmitter {
                         phase: event.phase,
                         prompt: event.prompt,
                         status: "running",
+                        model: event.model,
                     });
                     this.emit("agentStart", { runId: managed.runId, ...event });
+                    progress();
                 },
                 onAgentEnd: (event) => {
                     const agent = [...managed.snapshot.agents]
@@ -137,8 +174,18 @@ export class WorkflowManager extends EventEmitter {
                         .find((a) => a.label === event.label && a.status === "running");
                     if (agent) {
                         agent.status = event.result === null ? "error" : "done";
+                        agent.resultPreview = preview(event.result);
+                        agent.tokens = event.tokens;
+                        if (event.model)
+                            agent.model = event.model;
                     }
                     this.emit("agentEnd", { runId: managed.runId, ...event });
+                    progress();
+                },
+                onTokenUsage: (usage) => {
+                    managed.snapshot.tokenUsage = usage;
+                    this.emit("tokenUsage", { runId: managed.runId, usage });
+                    progress();
                 },
             });
             managed.status = "completed";
@@ -184,6 +231,13 @@ export class WorkflowManager extends EventEmitter {
             })),
             logs: managed.snapshot.logs,
             result: managed.result?.result,
+            tokenUsage: managed.snapshot.tokenUsage
+                ? {
+                    input: managed.snapshot.tokenUsage.input,
+                    output: managed.snapshot.tokenUsage.output,
+                    total: managed.snapshot.tokenUsage.total,
+                }
+                : undefined,
             startedAt: managed.startedAt.toISOString(),
             updatedAt: new Date().toISOString(),
             completedAt: managed.status === "completed" ? new Date().toISOString() : undefined,
@@ -233,12 +287,13 @@ export class WorkflowManager extends EventEmitter {
             script: persisted.script,
             args: persisted.args,
             journal: persisted.journal ?? [],
+            background: true,
         };
         this.runs.set(runId, managed);
         const resumeJournal = new Map((persisted.journal ?? []).map((e) => [e.index, e]));
         this.emit("resumed", { runId });
         // Run in the background; executeRun records status/errors on the managed run.
-        void this.executeRun(managed, persisted.script, persisted.args, resumeJournal).catch(() => { });
+        void this.executeRun(managed, persisted.script, persisted.args, { resumeJournal }).catch(() => { });
         return true;
     }
     /**

package/dist/workflow-tool.d.ts

@@ -25,4 +25,11 @@ export interface WorkflowToolOptions {
     storage?: WorkflowStorage;
 }
 export declare function createWorkflowTool(options?: WorkflowToolOptions): ToolDefinition<typeof workflowToolSchema, any>;
+/**
+ * The tool result returned when a workflow starts in the background. It both
+ * informs the model and tells it to reassure the user: the run continues on its
+ * own and the conversation will resume automatically when it finishes, so the
+ * user can just wait here (or go do something else).
+ */
+export declare function backgroundStartedText(name: string, runId: string): string;
 export {};