@quintinshaw/pi-dynamic-workflows 1.9.0 → 1.9.2

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;
+}

package/src/workflow-manager.ts

@@ -3,7 +3,8 @@
  */
 
 import { EventEmitter } from "node:events";
-import type { WorkflowSnapshot } from "./display.js";
+import type { WorkflowAgent } from "./agent.js";
+import { preview, type WorkflowSnapshot } from "./display.js";
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
 import {
   createRunPersistence,
@@ -27,6 +28,27 @@ 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 {
@@ -34,6 +56,10 @@ export interface WorkflowManagerOptions {
   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 class WorkflowManager extends EventEmitter {
@@ -42,15 +68,25 @@ export class WorkflowManager extends EventEmitter {
   private cwd: string;
   private concurrency: number;
   private loadSavedWorkflow?: (name: string) => string | undefined;
+  private agent?: Pick<WorkflowAgent, "run">;
+  /** The session's main model (provider/id), for auto-tiering explore agents. */
+  private mainModel?: string;
 
   constructor(options: WorkflowManagerOptions = {}) {
     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: string | undefined): void {
+    this.mainModel = spec;
+  }
+
   /**
    * Start a workflow in the background.
    * Returns immediately with a run ID; the workflow executes asynchronously.
@@ -79,6 +115,7 @@ export class WorkflowManager extends EventEmitter {
       script,
       args,
       journal: [],
+      background: true,
     };
 
     this.runs.set(runId, managed);
@@ -104,15 +141,25 @@ export class WorkflowManager extends EventEmitter {
   }
 
   /**
-   * 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: string, args?: unknown): Promise<WorkflowRunResult> {
-    const runId = generateRunId();
-    const controller = new AbortController();
-    const parsed = parseWorkflowScript(script);
+  async runSync(script: string, args?: unknown, exec: ExecOptions = {}): Promise<WorkflowRunResult> {
+    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);
+  }
 
-    const managed: ManagedRun = {
-      runId,
+  /** Build a fresh managed run with an empty snapshot. */
+  private createManaged(script: string, args?: unknown): ManagedRun {
+    const parsed = parseWorkflowScript(script);
+    return {
+      runId: generateRunId(),
       status: "running",
       snapshot: {
         name: parsed.meta.name,
@@ -125,29 +172,38 @@ 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);
   }
 
   private async executeRun(
     managed: ManagedRun,
     script: string,
     args?: unknown,
-    resumeJournal?: Map<number, JournalEntry>,
+    exec: ExecOptions = {},
   ): Promise<WorkflowRunResult> {
+    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,
@@ -160,6 +216,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;
@@ -167,6 +224,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({
@@ -175,8 +233,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]
@@ -184,8 +244,17 @@ 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();
         },
       });
 
@@ -241,6 +310,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,
@@ -292,13 +368,14 @@ 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] as const));
     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/src/workflow-tool.ts

@@ -1,19 +1,39 @@
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { listAvailableModelSpecs } from "./agent.js";
 import {
   createToolUpdateWorkflowDisplay,
   createWorkflowSnapshot,
-  preview,
   recomputeWorkflowSnapshot,
   renderWorkflowText,
   type WorkflowSnapshot,
 } from "./display.js";
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
-import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
+import { parseWorkflowScript, type WorkflowRunResult } from "./workflow.js";
 import { WorkflowManager } from "./workflow-manager.js";
 import { createWorkflowStorage, type WorkflowStorage } from "./workflow-saved.js";
 
+/**
+ * Per-agent model-routing policy handed to the workflow author (the model). It
+ * states the rule and lists the user's currently available models, then lets the
+ * author choose each agent's model via opts.model — no hardcoded family mapping.
+ */
+function modelRoutingGuideline(): string {
+  const available = listAvailableModelSpecs();
+  const list = available.length
+    ? `The user's currently available models (route only to these) are: ${available.join(", ")}.`
+    : "Use models the user has configured.";
+  return [
+    "For workflow, decide each agent's model yourself via opts.model, following this policy:",
+    "If the user named a specific model, use exactly that.",
+    "Otherwise, for exploration/search/inventory/gathering agents, pick a model one tier BELOW the main model in the SAME family (e.g. Claude→Haiku, ChatGPT/GPT→a mini, DeepSeek→a lighter/flash variant), choosing the closest match from the available list.",
+    "For analysis/synthesis/judgment/decision/verification agents, omit opts.model so the agent runs on the main model.",
+    "Never route to a model that is not in the available list; if no suitable lighter sibling exists, omit opts.model (use the main model).",
+    list,
+  ].join(" ");
+}
+
 const workflowToolSchema = Type.Object({
   script: Type.String({
     description: [
@@ -28,7 +48,8 @@ const workflowToolSchema = Type.Object({
   ),
   background: Type.Optional(
     Type.Boolean({
-      description: "Run the workflow in the background. Default: false. When true, returns immediately with a run ID.",
+      description:
+        "Run the workflow in the background. Default: true — the tool returns immediately with a run ID, the turn ends so the user isn't blocked, and the result is delivered back into the conversation when it finishes. Set to false only when you need the result inline in this same turn (the call will block until the workflow completes).",
     }),
   ),
   maxAgents: Type.Optional(
@@ -62,8 +83,13 @@ export interface WorkflowToolOptions {
 
 export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
   const storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
-  const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-  const loadSavedWorkflow = (name: string) => storage.load(name)?.script;
+  const manager =
+    options.manager ??
+    new WorkflowManager({
+      cwd: options.cwd,
+      concurrency: options.concurrency,
+      loadSavedWorkflow: (name: string) => storage.load(name)?.script,
+    });
 
   return defineTool({
     name: "workflow",
@@ -87,38 +113,35 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
       "For workflow, failed agent(), parallel(), or pipeline() branches return null and log the failure unless the workflow is aborted. Check for nulls before synthesizing conclusions.",
       "For workflow, include a final synthesis/assertion agent when combining multiple subagent results; return a compact JSON-serializable value with ok/verdict plus the important outputs.",
       "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
+      modelRoutingGuideline(),
       "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
-      "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+      "For workflow, runs are background by default: the tool returns immediately with a run ID, the turn ends so the user isn't blocked, and the result is delivered back into the conversation when the run finishes. Pass background: false only when you must use the result inline in this same turn (it will block).",
       "For workflow, you may call `await workflow('saved-name', argsObject)` to run a saved workflow inline and use its result; nesting is one level deep only, and the global 16-concurrent / 1000-total caps hold across the nesting.",
     ],
     parameters: workflowToolSchema,
     prepareArguments(args) {
       return normalizeWorkflowToolArgs(args);
     },
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
       const script = normalizeWorkflowScript(params.script);
       const parsed = parseWorkflowScript(script);
 
-      // Background execution
-      if (params.background) {
+      // Background execution is the default: return immediately so the turn ends
+      // and the user isn't blocked. The result is delivered back into the
+      // conversation when the run finishes (see installResultDelivery). Only an
+      // explicit `background: false` blocks for the result inline.
+      if (params.background ?? true) {
         const { runId } = manager.startInBackground(script, params.args);
         return {
-          content: [
-            {
-              type: "text",
-              text: [
-                `Workflow "${parsed.meta.name}" started in background.`,
-                `Run ID: ${runId}`,
-                `Use /workflows status ${runId} to check progress.`,
-                `Use /workflows stop ${runId} to cancel.`,
-              ].join("\n"),
-            },
-          ],
+          content: [{ type: "text", text: backgroundStartedText(parsed.meta.name, runId) }],
           details: { runId, background: true },
         };
       }
 
-      // Synchronous execution (blocking)
+      // Synchronous execution (blocking) — but routed through the manager so the
+      // run shows up live in the /workflows navigator and the task panel while it
+      // runs, then stays in history afterwards. We still block on the result and
+      // return it inline, so the model gets the full output in the same turn.
       let snapshot: WorkflowSnapshot = createWorkflowSnapshot(parsed.meta);
       const display = createToolUpdateWorkflowDisplay(onUpdate, undefined, {
         key: "workflow",
@@ -128,55 +151,15 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
         showResultPreviews: false,
       });
 
-      const update = () => {
-        snapshot = recomputeWorkflowSnapshot(snapshot);
-        display.update(snapshot);
-      };
-
       let result: WorkflowRunResult;
       try {
-        result = await runWorkflow(script, {
-          cwd: options.cwd ?? ctx.cwd,
-          args: params.args,
-          signal,
-          concurrency: options.concurrency,
+        result = await manager.runSync(script, params.args, {
           maxAgents: params.maxAgents,
           agentTimeoutMs: params.agentTimeoutMs,
-          loadSavedWorkflow,
-          onLog(message) {
-            snapshot.logs.push(message);
-            update();
-          },
-          onPhase(title) {
-            snapshot.currentPhase = title;
-            if (!snapshot.phases.includes(title)) snapshot.phases.push(title);
-            update();
-          },
-          onAgentStart(event) {
-            if (signal?.aborted) throw new Error("Workflow was aborted");
-            snapshot.agents.push({
-              id: snapshot.agents.length + 1,
-              label: event.label,
-              phase: event.phase,
-              prompt: event.prompt,
-              status: "running",
-            });
-            update();
-          },
-          onAgentEnd(event) {
-            const agent = [...snapshot.agents]
-              .reverse()
-              .find((item) => item.label === event.label && item.status === "running");
-            if (agent) {
-              agent.status = event.result === null ? "error" : "done";
-              agent.resultPreview = preview(event.result);
-              agent.tokens = event.tokens;
-            }
-            update();
-          },
-          onTokenUsage(usage) {
-            snapshot.tokenUsage = usage;
-            update();
+          externalSignal: signal,
+          onProgress(live) {
+            snapshot = recomputeWorkflowSnapshot(live);
+            display.update(snapshot);
           },
         });
       } catch (error) {
@@ -245,6 +228,25 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
   });
 }
 
+/**
+ * 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 function backgroundStartedText(name: string, runId: string): string {
+  return [
+    `Workflow "${name}" started in the background.`,
+    `Run ID: ${runId}`,
+    "It keeps running on its own. When it finishes, the result is delivered back",
+    "here and the conversation continues automatically — the user does not need to",
+    "do anything. Tell the user they can simply wait here for it to finish (it will",
+    "resume the conversation by itself), or keep chatting / working on other things",
+    "in the meantime; either way the result will come back to this conversation.",
+    `They can also track or cancel it with /workflows status ${runId} or /workflows stop ${runId}.`,
+  ].join("\n");
+}
+
 function normalizeWorkflowToolArgs(args: unknown): WorkflowToolInput {
   if (!args || typeof args !== "object") throw new Error("workflow requires an object argument with a script string");
   const value = args as Record<string, unknown>;