@quintinshaw/pi-dynamic-workflows 1.1.0 → 1.3.0

package/README.md

@@ -46,6 +46,18 @@ The model writes a workflow script and calls the `workflow` tool. Live progress
 
 Press `Esc` to cancel a running run; active subagents are aborted and surfaced as skipped.
 
+### Background runs & `/workflows`
+
+Ask for a background workflow (the model passes `background: true`) and it runs without blocking your session. Manage it with the `/workflows` command:
+
+```text
+/workflows                 # list runs (default)
+/workflows status <id>     # show a run's progress
+/workflows stop <id>       # abort a running run
+/workflows pause <id>      # pause a running run
+/workflows rm <id>         # remove a run from the list
+```
+
 ## Workflow script shape
 
 A workflow is plain JavaScript. The first statement must export literal metadata:
@@ -86,8 +98,11 @@ 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 |
+| `model` | string | Run this agent on a specific model — `provider/modelId` or a bare `modelId` |
 | `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.
+
 ### Structured output
 
 Pass a JSON Schema via `opts.schema` and the subagent returns a validated object:
@@ -117,6 +132,8 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **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` command** — list, inspect, stop, pause, and remove background runs; runs started with `background: true` are reachable from the command
 - **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/`
@@ -125,8 +142,6 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 
 Tracked toward closer parity with Claude Code dynamic workflows:
 
-- **Real per-agent / per-phase model routing** (`opts.model`, `meta.phases[].model`)
-- **Command surface** — `/workflows` (list / status / stop) and reachable background runs
 - **Resume** — journaled results, replay the unchanged prefix, run the rest live
 - **Worktree isolation** for parallel edits, and **bundled `/deep-research`**
 - **Saved workflows** as `/<name>` slash commands

package/dist/agent.d.ts

@@ -30,6 +30,14 @@ export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefi
      * usage is never lost. `total === 0` means the provider reported no usage.
      */
     onUsage?: (usage: AgentUsage) => void;
+    /**
+     * Model spec for this subagent: either `provider/modelId` (unambiguous) or a
+     * bare `modelId`. When it can't be resolved, the session default is used and
+     * a warning is logged. When omitted, the session default applies.
+     */
+    model?: string;
+    /** Called with the resolved model id once known (for display/telemetry). */
+    onModelResolved?: (modelId: string) => void;
 }
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema ? Static<TSchemaDef> : string;
 export declare class WorkflowAgent {
@@ -37,7 +45,16 @@ export declare class WorkflowAgent {
     private readonly baseTools;
     private readonly sessionOptions;
     private readonly instructions?;
+    /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+    private registry?;
     constructor(options?: WorkflowAgentOptions);
+    private getRegistry;
+    /**
+     * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+     * or a bare `modelId` (prefers auth-configured models, then any known model).
+     * Returns undefined when nothing matches.
+     */
+    private resolveModel;
     run<TSchemaDef extends TSchema | undefined = undefined>(prompt: string, options?: AgentRunOptions<TSchemaDef>): Promise<AgentRunResult<TSchemaDef>>;
     private buildPrompt;
     private lastAssistantText;

package/dist/agent.js

@@ -1,22 +1,60 @@
-import { createAgentSession, createCodingTools, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+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";
 export class WorkflowAgent {
     cwd;
     baseTools;
     sessionOptions;
     instructions;
+    /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+    registry;
     constructor(options = {}) {
         this.cwd = options.cwd ?? process.cwd();
         this.baseTools = options.tools ?? createCodingTools(this.cwd);
         this.sessionOptions = options.session ?? {};
         this.instructions = options.instructions;
     }
+    getRegistry() {
+        if (!this.registry) {
+            const dir = getAgentDir();
+            // Same agentDir/auth files createAgentSession uses by default, so a model
+            // resolved here carries valid credentials.
+            const auth = AuthStorage.create(join(dir, "auth.json"));
+            this.registry = ModelRegistry.create(auth, join(dir, "models.json"));
+        }
+        return this.registry;
+    }
+    /**
+     * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+     * or a bare `modelId` (prefers auth-configured models, then any known model).
+     * Returns undefined when nothing matches.
+     */
+    resolveModel(spec) {
+        const registry = this.getRegistry();
+        const slash = spec.indexOf("/");
+        if (slash > 0) {
+            return registry.find(spec.slice(0, slash), spec.slice(slash + 1));
+        }
+        return registry.getAvailable().find((m) => m.id === spec) ?? registry.getAll().find((m) => m.id === spec);
+    }
     async run(prompt, options = {}) {
         const capture = { called: false, value: undefined };
         const customTools = [...this.baseTools, ...(options.tools ?? [])];
         if (options.schema) {
             customTools.push(createStructuredOutputTool({ schema: options.schema, capture }));
         }
+        // Resolve a requested model spec to a Model object. A given-but-unresolved
+        // spec falls back to the session default (with a warning) rather than failing.
+        let resolvedModel;
+        if (options.model) {
+            resolvedModel = this.resolveModel(options.model);
+            if (resolvedModel) {
+                options.onModelResolved?.(`${resolvedModel.provider}/${resolvedModel.id}`);
+            }
+            else {
+                console.warn(`[workflow] model "${options.model}" not found; using session default`);
+            }
+        }
         const agentDir = getAgentDir();
         const { session } = await createAgentSession({
             cwd: this.cwd,
@@ -29,6 +67,8 @@ export class WorkflowAgent {
             settingsManager: SettingsManager.create(this.cwd, agentDir),
             customTools,
             ...this.sessionOptions,
+            // Per-call model wins over any sessionOptions.model.
+            ...(resolvedModel ? { model: resolvedModel } : {}),
         });
         let removeAbortListener;
         try {

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./str
 export { createStructuredOutputTool } from "./structured-output.js";
 export type { AgentOptions, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { buildModelRoutingInstructions, parseModelRoutingFromMeta, resolveModelF
 export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export { createStructuredOutputTool } from "./structured-output.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowTool } from "./workflow-tool.js";

package/dist/workflow-commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowManager } from "./workflow-manager.js";
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export declare function registerWorkflowCommands(pi: ExtensionAPI, manager: WorkflowManager): void;

package/dist/workflow-commands.js

@@ -0,0 +1,111 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+import { renderWorkflowText } from "./display.js";
+const STATUS_ICON = {
+    pending: "·",
+    running: "◆",
+    paused: "⏸",
+    completed: "✓",
+    failed: "✗",
+    aborted: "⊘",
+};
+const USAGE = "Usage: /workflows [list] | status <id> | stop <id> | pause <id> | resume <id> | rm <id>";
+function summarizeRun(run) {
+    const icon = STATUS_ICON[run.status] ?? "?";
+    const done = run.agents.filter((a) => a.status === "done").length;
+    const total = run.agents.length;
+    const tokens = run.tokenUsage ? ` · ${run.tokenUsage.total.toLocaleString()} tok` : "";
+    return `${icon} ${run.runId}  ${run.workflowName} [${run.status}] ${done}/${total} agents${tokens}`;
+}
+function renderPersistedStatus(run) {
+    const lines = [`${STATUS_ICON[run.status] ?? "?"} ${run.workflowName} (${run.runId}) — ${run.status}`];
+    if (run.currentPhase)
+        lines.push(`  phase: ${run.currentPhase}`);
+    for (const agent of run.agents) {
+        const icon = agent.status === "done" ? "✓" : agent.status === "error" ? "✗" : agent.status === "running" ? "◆" : "·";
+        lines.push(`  ${icon} ${agent.label}`);
+    }
+    if (run.tokenUsage)
+        lines.push(`  tokens: ${run.tokenUsage.total.toLocaleString()}`);
+    if (run.durationMs)
+        lines.push(`  duration: ${(run.durationMs / 1000).toFixed(1)}s`);
+    return lines.join("\n");
+}
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export function registerWorkflowCommands(pi, manager) {
+    try {
+        const taken = (pi.getCommands?.() ?? []).some((c) => c.name === "workflows");
+        if (taken)
+            return;
+    }
+    catch {
+        // getCommands may be unavailable in some hosts; fall through and try to register.
+    }
+    pi.registerCommand("workflows", {
+        description: "List and control background workflow runs",
+        async handler(args, ctx) {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const sub = (parts[0] ?? "list").toLowerCase();
+            const id = parts[1];
+            const print = (text) => pi.sendMessage({ customType: "workflows", content: text, display: true });
+            switch (sub) {
+                case "list": {
+                    const runs = manager.listRuns();
+                    if (!runs.length) {
+                        await print("No workflow runs yet. Start one with a background workflow (background: true).");
+                        return;
+                    }
+                    await print(["Workflow runs:", ...runs.map(summarizeRun), "", USAGE].join("\n"));
+                    return;
+                }
+                case "status": {
+                    if (!id) {
+                        ctx.ui.notify(USAGE, "warning");
+                        return;
+                    }
+                    const live = manager.getSnapshot(id);
+                    if (live) {
+                        await print(renderWorkflowText(live, false));
+                        return;
+                    }
+                    const run = manager.listRuns().find((r) => r.runId === id);
+                    if (!run) {
+                        ctx.ui.notify(`No workflow run "${id}"`, "error");
+                        return;
+                    }
+                    await print(renderPersistedStatus(run));
+                    return;
+                }
+                case "stop": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id} (not running)`, manager.getRun(id) ? "info" : "warning");
+                    return;
+                }
+                case "pause": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id} (not running)`, "info");
+                    return;
+                }
+                case "resume": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    const ok = await manager.resume(id);
+                    ctx.ui.notify(ok ? `Resumed ${id}` : `Resume not available for ${id} yet`, ok ? "info" : "warning");
+                    return;
+                }
+                case "rm": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.deleteRun(id) ? `Removed ${id}` : `No run ${id}`, "info");
+                    return;
+                }
+                default:
+                    ctx.ui.notify(`Unknown subcommand "${sub}". ${USAGE}`, "warning");
+            }
+        },
+    });
+}

package/dist/workflow-tool.d.ts

@@ -1,5 +1,7 @@
 import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { WorkflowManager } from "./workflow-manager.js";
+import { type WorkflowStorage } from "./workflow-saved.js";
 declare const workflowToolSchema: Type.TObject<{
     script: Type.TString;
     args: Type.TOptional<Type.TAny>;
@@ -17,6 +19,10 @@ export type WorkflowToolInput = {
 export interface WorkflowToolOptions {
     cwd?: string;
     concurrency?: number;
+    /** Shared manager so background runs are reachable from the `/workflows` command. */
+    manager?: WorkflowManager;
+    /** Shared saved-workflow storage. */
+    storage?: WorkflowStorage;
 }
 export declare function createWorkflowTool(options?: WorkflowToolOptions): ToolDefinition<typeof workflowToolSchema, any>;
 export {};

package/dist/workflow-tool.js

@@ -27,8 +27,8 @@ const workflowToolSchema = Type.Object({
     })),
 });
 export function createWorkflowTool(options = {}) {
-    const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-    const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+    const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+    const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
     return defineTool({
         name: "workflow",
         label: "Workflow",
@@ -70,8 +70,8 @@ export function createWorkflowTool(options = {}) {
                             text: [
                                 `Workflow "${parsed.meta.name}" started in background.`,
                                 `Run ID: ${runId}`,
-                                `Use /workflow status ${runId} to check progress.`,
-                                `Use /workflow stop ${runId} to cancel.`,
+                                `Use /workflows status ${runId} to check progress.`,
+                                `Use /workflows stop ${runId} to cancel.`,
                             ].join("\n"),
                         },
                     ],

package/dist/workflow.d.ts

@@ -31,6 +31,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
         label: string;
         phase?: string;
         prompt: string;
+        model?: string;
     }) => void;
     onAgentEnd?: (event: {
         label: string;

package/dist/workflow.js

@@ -4,10 +4,13 @@ import { WorkflowAgent } from "./agent.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from "./config.js";
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
+import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
 const DETERMINISM_BLOCKLIST = /\bDate\s*\.\s*now\b|\bMath\s*\.\s*random\b|\bnew\s+Date\s*\(\s*\)/;
 export async function runWorkflow(script, options = {}) {
     const started = Date.now();
     const { meta, body } = parseWorkflowScript(script);
+    // Per-phase model routing from meta.phases[].model (empty when none declared).
+    const routingConfig = parseModelRoutingFromMeta(meta.phases);
     const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
     const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
     const runId = options.runId ?? `run-${started.toString(36)}`;
@@ -62,11 +65,13 @@ export async function runWorkflow(script, options = {}) {
         }
         const assignedPhase = agentOptions.phase ?? state.currentPhase;
         const requestedLabel = agentOptions.label?.trim();
+        // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
+        const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
         return limiter(async () => {
             state.agentCount++;
             const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
             const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
-            options.onAgentStart?.({ label, phase: assignedPhase, prompt });
+            options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
             // Captured from the subagent's real session usage; falls back to an
             // estimate when the provider reports no usage (total === 0).
             let usage;
@@ -89,6 +94,7 @@ export async function runWorkflow(script, options = {}) {
                     schema: agentOptions.schema,
                     signal: options.signal,
                     instructions: buildAgentInstructions(assignedPhase, agentOptions),
+                    model: modelSpec,
                     onUsage: (u) => {
                         usage = u;
                     },
@@ -350,8 +356,7 @@ function buildAgentInstructions(phase, options) {
         lines.push(`Act as workflow subagent type: ${options.agentType}`);
     if (options.isolation)
         lines.push(`Requested isolation: ${options.isolation}`);
-    if (options.model)
-        lines.push(`Requested model: ${options.model}`);
+    // Note: options.model is applied for real via the session, not injected as prose.
     return lines.length ? lines.join("\n") : undefined;
 }
 function estimateTokens(value) {

package/extensions/workflow.ts

@@ -1,9 +1,16 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createWorkflowTool } from "../src/index.js";
+import { createWorkflowStorage, createWorkflowTool, registerWorkflowCommands, WorkflowManager } from "../src/index.js";
 
 export default function extension(pi: ExtensionAPI) {
-  const workflowTool = createWorkflowTool();
+  // Single manager/storage shared by the workflow tool and the /workflows command,
+  // so background runs started by the tool are reachable from the command.
+  const cwd = process.cwd();
+  const manager = new WorkflowManager({ cwd });
+  const storage = createWorkflowStorage(cwd);
+
+  const workflowTool = createWorkflowTool({ cwd, manager, storage });
   pi.registerTool(workflowTool);
+  registerWorkflowCommands(pi, manager);
 
   pi.on("session_start", () => {
     const active = pi.getActiveTools();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent.ts

@@ -1,9 +1,12 @@
-import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import { join } from "node:path";
+import type { AssistantMessage, Model, TextContent } from "@earendil-works/pi-ai";
 import {
+  AuthStorage,
   type CreateAgentSessionOptions,
   createAgentSession,
   createCodingTools,
   getAgentDir,
+  ModelRegistry,
   SessionManager,
   SettingsManager,
   type ToolDefinition,
@@ -43,6 +46,14 @@ export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefi
    * usage is never lost. `total === 0` means the provider reported no usage.
    */
   onUsage?: (usage: AgentUsage) => void;
+  /**
+   * Model spec for this subagent: either `provider/modelId` (unambiguous) or a
+   * bare `modelId`. When it can't be resolved, the session default is used and
+   * a warning is logged. When omitted, the session default applies.
+   */
+  model?: string;
+  /** Called with the resolved model id once known (for display/telemetry). */
+  onModelResolved?: (modelId: string) => void;
 }
 
 export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema
@@ -54,6 +65,8 @@ export class WorkflowAgent {
   private readonly baseTools: ToolDefinition[];
   private readonly sessionOptions: Partial<CreateAgentSessionOptions>;
   private readonly instructions?: string;
+  /** Lazily built once; shares the SDK's agentDir/auth so resolved models are authed. */
+  private registry?: ModelRegistry;
 
   constructor(options: WorkflowAgentOptions = {}) {
     this.cwd = options.cwd ?? process.cwd();
@@ -62,6 +75,31 @@ export class WorkflowAgent {
     this.instructions = options.instructions;
   }
 
+  private getRegistry(): ModelRegistry {
+    if (!this.registry) {
+      const dir = getAgentDir();
+      // Same agentDir/auth files createAgentSession uses by default, so a model
+      // resolved here carries valid credentials.
+      const auth = AuthStorage.create(join(dir, "auth.json"));
+      this.registry = ModelRegistry.create(auth, join(dir, "models.json"));
+    }
+    return this.registry;
+  }
+
+  /**
+   * Resolve a model spec to a Model. Accepts `provider/modelId` (unambiguous)
+   * or a bare `modelId` (prefers auth-configured models, then any known model).
+   * Returns undefined when nothing matches.
+   */
+  private resolveModel(spec: string): Model<any> | undefined {
+    const registry = this.getRegistry();
+    const slash = spec.indexOf("/");
+    if (slash > 0) {
+      return registry.find(spec.slice(0, slash), spec.slice(slash + 1));
+    }
+    return registry.getAvailable().find((m) => m.id === spec) ?? registry.getAll().find((m) => m.id === spec);
+  }
+
   async run<TSchemaDef extends TSchema | undefined = undefined>(
     prompt: string,
     options: AgentRunOptions<TSchemaDef> = {},
@@ -73,6 +111,18 @@ export class WorkflowAgent {
       customTools.push(createStructuredOutputTool({ schema: options.schema, capture }) as unknown as ToolDefinition);
     }
 
+    // Resolve a requested model spec to a Model object. A given-but-unresolved
+    // spec falls back to the session default (with a warning) rather than failing.
+    let resolvedModel: Model<any> | undefined;
+    if (options.model) {
+      resolvedModel = this.resolveModel(options.model);
+      if (resolvedModel) {
+        options.onModelResolved?.(`${resolvedModel.provider}/${resolvedModel.id}`);
+      } else {
+        console.warn(`[workflow] model "${options.model}" not found; using session default`);
+      }
+    }
+
     const agentDir = getAgentDir();
     const { session } = await createAgentSession({
       cwd: this.cwd,
@@ -85,6 +135,8 @@ export class WorkflowAgent {
       settingsManager: SettingsManager.create(this.cwd, agentDir),
       customTools,
       ...this.sessionOptions,
+      // Per-call model wins over any sessionOptions.model.
+      ...(resolvedModel ? { model: resolvedModel } : {}),
     });
 
     let removeAbortListener: (() => void) | undefined;

package/src/index.ts

@@ -47,6 +47,7 @@ export type {
   WorkflowRunResult,
 } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";

package/src/workflow-commands.ts

@@ -0,0 +1,117 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { renderWorkflowText } from "./display.js";
+import type { PersistedRunState } from "./run-persistence.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "·",
+  running: "◆",
+  paused: "⏸",
+  completed: "✓",
+  failed: "✗",
+  aborted: "⊘",
+};
+
+const USAGE = "Usage: /workflows [list] | status <id> | stop <id> | pause <id> | resume <id> | rm <id>";
+
+function summarizeRun(run: PersistedRunState): string {
+  const icon = STATUS_ICON[run.status] ?? "?";
+  const done = run.agents.filter((a) => a.status === "done").length;
+  const total = run.agents.length;
+  const tokens = run.tokenUsage ? ` · ${run.tokenUsage.total.toLocaleString()} tok` : "";
+  return `${icon} ${run.runId}  ${run.workflowName} [${run.status}] ${done}/${total} agents${tokens}`;
+}
+
+function renderPersistedStatus(run: PersistedRunState): string {
+  const lines = [`${STATUS_ICON[run.status] ?? "?"} ${run.workflowName} (${run.runId}) — ${run.status}`];
+  if (run.currentPhase) lines.push(`  phase: ${run.currentPhase}`);
+  for (const agent of run.agents) {
+    const icon =
+      agent.status === "done" ? "✓" : agent.status === "error" ? "✗" : agent.status === "running" ? "◆" : "·";
+    lines.push(`  ${icon} ${agent.label}`);
+  }
+  if (run.tokenUsage) lines.push(`  tokens: ${run.tokenUsage.total.toLocaleString()}`);
+  if (run.durationMs) lines.push(`  duration: ${(run.durationMs / 1000).toFixed(1)}s`);
+  return lines.join("\n");
+}
+
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export function registerWorkflowCommands(pi: ExtensionAPI, manager: WorkflowManager): void {
+  try {
+    const taken = (pi.getCommands?.() ?? []).some((c: { name: string }) => c.name === "workflows");
+    if (taken) return;
+  } catch {
+    // getCommands may be unavailable in some hosts; fall through and try to register.
+  }
+
+  pi.registerCommand("workflows", {
+    description: "List and control background workflow runs",
+    async handler(args: string, ctx: ExtensionCommandContext) {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const sub = (parts[0] ?? "list").toLowerCase();
+      const id = parts[1];
+      const print = (text: string) => pi.sendMessage({ customType: "workflows", content: text, display: true });
+
+      switch (sub) {
+        case "list": {
+          const runs = manager.listRuns();
+          if (!runs.length) {
+            await print("No workflow runs yet. Start one with a background workflow (background: true).");
+            return;
+          }
+          await print(["Workflow runs:", ...runs.map(summarizeRun), "", USAGE].join("\n"));
+          return;
+        }
+        case "status": {
+          if (!id) {
+            ctx.ui.notify(USAGE, "warning");
+            return;
+          }
+          const live = manager.getSnapshot(id);
+          if (live) {
+            await print(renderWorkflowText(live, false));
+            return;
+          }
+          const run = manager.listRuns().find((r) => r.runId === id);
+          if (!run) {
+            ctx.ui.notify(`No workflow run "${id}"`, "error");
+            return;
+          }
+          await print(renderPersistedStatus(run));
+          return;
+        }
+        case "stop": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(
+            manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id} (not running)`,
+            manager.getRun(id) ? "info" : "warning",
+          );
+          return;
+        }
+        case "pause": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id} (not running)`, "info");
+          return;
+        }
+        case "resume": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          const ok = await manager.resume(id);
+          ctx.ui.notify(ok ? `Resumed ${id}` : `Resume not available for ${id} yet`, ok ? "info" : "warning");
+          return;
+        }
+        case "rm": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(manager.deleteRun(id) ? `Removed ${id}` : `No run ${id}`, "info");
+          return;
+        }
+        default:
+          ctx.ui.notify(`Unknown subcommand "${sub}". ${USAGE}`, "warning");
+      }
+    },
+  });
+}

package/src/workflow-tool.ts

@@ -12,7 +12,7 @@ import {
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
 import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
 import { WorkflowManager } from "./workflow-manager.js";
-import { createWorkflowStorage } from "./workflow-saved.js";
+import { createWorkflowStorage, type WorkflowStorage } from "./workflow-saved.js";
 
 const workflowToolSchema = Type.Object({
   script: Type.String({
@@ -54,11 +54,15 @@ export type WorkflowToolInput = {
 export interface WorkflowToolOptions {
   cwd?: string;
   concurrency?: number;
+  /** Shared manager so background runs are reachable from the `/workflows` command. */
+  manager?: WorkflowManager;
+  /** Shared saved-workflow storage. */
+  storage?: WorkflowStorage;
 }
 
 export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
-  const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-  const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+  const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+  const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
 
   return defineTool({
     name: "workflow",
@@ -103,8 +107,8 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
               text: [
                 `Workflow "${parsed.meta.name}" started in background.`,
                 `Run ID: ${runId}`,
-                `Use /workflow status ${runId} to check progress.`,
-                `Use /workflow stop ${runId} to cancel.`,
+                `Use /workflows status ${runId} to check progress.`,
+                `Use /workflows stop ${runId} to cancel.`,
               ].join("\n"),
             },
           ],

package/src/workflow.ts

@@ -7,6 +7,7 @@ import { WorkflowAgent, type WorkflowAgentOptions } from "./agent.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from "./config.js";
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import { createWorkflowLogger } from "./logger.js";
+import { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
 
 export interface WorkflowMetaPhase {
   title: string;
@@ -37,7 +38,7 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   runId?: string;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
-  onAgentStart?: (event: { label: string; phase?: string; prompt: string }) => void;
+  onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
   onAgentEnd?: (event: { label: string; phase?: string; result: unknown; tokens?: number }) => void;
   onTokenUsage?: (usage: { input: number; output: number; total: number; cost: number }) => void;
 }
@@ -93,6 +94,8 @@ export async function runWorkflow<T = unknown>(
 ): Promise<WorkflowRunResult<T>> {
   const started = Date.now();
   const { meta, body } = parseWorkflowScript(script);
+  // Per-phase model routing from meta.phases[].model (empty when none declared).
+  const routingConfig = parseModelRoutingFromMeta(meta.phases);
   const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
   const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
   const runId = options.runId ?? `run-${started.toString(36)}`;
@@ -164,13 +167,15 @@ export async function runWorkflow<T = unknown>(
 
     const assignedPhase = agentOptions.phase ?? state.currentPhase;
     const requestedLabel = agentOptions.label?.trim();
+    // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
+    const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
 
     return limiter(async () => {
       state.agentCount++;
       const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
       const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
 
-      options.onAgentStart?.({ label, phase: assignedPhase, prompt });
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
 
       // Captured from the subagent's real session usage; falls back to an
       // estimate when the provider reports no usage (total === 0).
@@ -197,6 +202,7 @@ export async function runWorkflow<T = unknown>(
             schema: agentOptions.schema,
             signal: options.signal,
             instructions: buildAgentInstructions(assignedPhase, agentOptions),
+            model: modelSpec,
             onUsage: (u: AgentUsage) => {
               usage = u;
             },
@@ -480,7 +486,7 @@ function buildAgentInstructions(phase: string | undefined, options: AgentOptions
   if (phase) lines.push(`Workflow phase: ${phase}`);
   if (options.agentType) lines.push(`Act as workflow subagent type: ${options.agentType}`);
   if (options.isolation) lines.push(`Requested isolation: ${options.isolation}`);
-  if (options.model) lines.push(`Requested model: ${options.model}`);
+  // Note: options.model is applied for real via the session, not injected as prose.
   return lines.length ? lines.join("\n") : undefined;
 }