pi-workflow-engine 0.1.1 → 0.3.0

package/README.md

@@ -1,10 +1,27 @@
-<p align="center">
-  <img src="assets/preview.png" width="200" alt="pi-workflow-engine — a central agent orchestrating a ring of subagents" />
-</p>
+![agents](assets/preview.png)
 
 # pi-workflow-engine
 
-A customisable multi-agent workflow-orchestration engine for the [pi](https://pi.dev) coding agent — your own version of Claude Code's built-in `/code-review`, built on pi's SDK. Workflows fan out to many subagents, pass validated structured data between stages, and synthesise a result.
+Claude Code style workflows for the [pi](https://pi.dev) coding agent.
+
+This is not just a way to run a prompt. It is a way to turn an agentic procedure into code: scope the task, fork isolated subagents, fan out across review lenses, validate every handoff with schemas, verify candidate findings, and synthesize one ranked result.
+
+The built-in workflows are advisory: they inspect, fan out, verify, and report. They do not edit files. Start with `/workflow code-review`, or use the focused scouts for refactors, diagnosis, and performance.
+
+## Why workflows matter
+
+Claude Code popularised a useful pattern: the best agentic coding work is not a single chat turn. It is a loop of context gathering, delegated action, verification, and synthesis. Its docs describe the [agentic loop](https://code.claude.com/docs/en/glossary#agentic-loop), [skills and commands](https://code.claude.com/docs/en/skills), and [subagents](https://code.claude.com/docs/en/glossary#subagent) as composable building blocks for repeatable engineering work.
+
+`pi-workflow-engine` brings that shape to pi with static TypeScript workflows:
+
+- **Procedures, not prompts**: write the workflow once, then invoke it with `/workflow` or let the host agent call the `workflow` tool.
+- **Isolated subagents**: each `agent()` runs in its own in-memory pi session, so exploratory work does not pollute the main conversation.
+- **Parallel cognition**: run many focused agents at once, with a shared concurrency cap so large workflows stay bounded.
+- **Typed handoffs**: pass structured data between stages using typebox schemas instead of asking the model to emit parseable prose.
+- **Verifier stages**: make verification part of the control flow, not an optional final instruction.
+- **Live progress**: surface phases, agent status, counters, and lane items in the TUI while the run is still moving.
+
+The result is closer to an executable review playbook than a chatbot shortcut.
 
 ## Install
 
@@ -18,118 +35,154 @@ Or from npm:
 pi install npm:pi-workflow-engine
 ```
 
-That's all — pi fetches the package and serves its dependencies from its own bundle, so there's no clone, install, or build step. Restart pi (or run `/reload` in an open session), then confirm it's registered:
+That's all. pi fetches the package and serves its core dependencies from its own bundle, so there is no clone, install, or build step. Restart pi, or run `/reload` in an open session, then confirm it is registered:
 
 ```bash
 pi list
 ```
 
-Scope it to a single repo instead of globally (writes to that repo's `.pi/settings.json`):
+Scope it to a single repo instead of globally. This writes to that repo's `.pi/settings.json`:
 
 ```bash
 pi install git:github.com/timbrinded/pi-workflow-engine -l
 ```
 
-Uninstall with `pi remove git:github.com/timbrinded/pi-workflow-engine`.
+Uninstall with:
+
+```bash
+pi remove git:github.com/timbrinded/pi-workflow-engine
+```
 
 ## Usage
 
 In a pi session, from inside a git repo with changes:
 
-```
-/workflow code-review            # review the current branch
-/workflow code-review HEAD~3     # review a ref range / target / focus area
-/workflow ping                   # quick engine smoke test (one agent)
+```text
+/workflow code-review            # review the current branch or open PR
+/workflow code-review HEAD~3     # review a ref range, target, or focus area
+/workflow refactor-scout src/    # find safe refactor opportunities
+/workflow diagnose "typecheck fails after the schema change"
+/workflow perf-review "workflow startup latency"
+/workflow code-review --inspect  # open the live workflow inspector
+/workflow ping                   # quick engine smoke test
 ```
 
-The host agent can also invoke the `workflow` tool itself mid-conversation (e.g. "run the code-review workflow") and fold the structured result back into its reasoning.
-
-`code-review` returns a verified, ranked report:
-
-```json
-{
-  "summary": "1 confirmed bug: off-by-one loop boundary in sum.js ...",
-  "findings": [
-    {
-      "file": "sum.js",
-      "line": 3,
-      "severity": "bug",
-      "verdict": "CONFIRMED",
-      "summary": "Off-by-one: `i <= arr.length` should be `i < arr.length`; accesses arr[arr.length] (undefined) → NaN."
-    }
-  ]
-}
+The host agent can also invoke the `workflow` tool mid-conversation:
+
+```text
+Run the code-review workflow on this PR and use the result before deciding what to fix.
 ```
 
-## How it works
+The advisory workflows inspect and report only; they do not edit files. They return the same shape: summary, ranked findings, evidence, impact, recommendations, and next steps.
+
+## Built-in workflows
+
+- `code-review`: Reviews the current branch, open PR, ref range, or target. It looks for correctness bugs and cleanup issues, then independently verifies candidates before ranking them.
+- `refactor-scout`: Looks for small, safe refactor opportunities: duplication, complexity, weak types, boundary leaks, dead code, and convention drift.
+- `diagnose`: Investigates a symptom, failing command, or regression. It generates competing root-cause hypotheses, verifies them, and returns the most likely causes with next validation steps.
+- `perf-review`: Reviews a slow path or workload for bottleneck hypotheses, measurement gaps, and safe optimization directions. It avoids claiming certainty when measurement evidence is missing.
+- `ping`: Minimal smoke workflow for checking that the engine can run one structured agent call.
+
+## The code-review workflow
+
+The bundled review workflow is deliberately shaped like a serious review process:
+
+1. **Scope**: detect the open PR or branch diff, list changed files, and read relevant project conventions.
+2. **Find**: fan out across focused review lenses such as logic bugs, error paths, edge cases, simplification, and conventions.
+3. **Gate and dedupe**: bound candidates to changed lines and collapse duplicate findings before spending verifier tokens.
+4. **Verify**: send each survivor to an independent verifier that must confirm, mark plausible, or refute with evidence.
+5. **Synthesize**: produce one ranked report with stats, verdicts, and concrete locations.
 
-A **workflow** is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you five primitives:
+The review lenses live in `workflows/code-review.ts`. That is where your repo's real failure modes belong.
+
+## Authoring workflows
+
+A workflow is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you the primitives:
 
 | Primitive | Behaviour |
 |-----------|-----------|
-| `agent(prompt, { schema })` | Runs a subagent in an isolated session; with a typebox `schema` it returns validated structured data, otherwise the final text. |
-| `parallel(thunks)` | Runs every thunk concurrently and waits for all (a barrier). |
-| `pipeline(items, ...stages)` | Runs each item through all stages independently — no barrier between stages. |
-| `phase(title)` / `log(msg)` | Drive the live progress tree shown in the TUI. |
+| `agent(prompt, { schema })` | Runs a subagent in an isolated session. With a typebox `schema`, returns validated structured data; otherwise returns final text. |
+| `parallel(thunks)` | Runs every thunk concurrently and waits for all results. |
+| `pipeline(items, ...stages)` | Runs each item through all stages independently, with no barrier between stages. |
+| `phase(title)` / `log(msg)` | Drives the live progress tree shown in the TUI and stderr breadcrumbs when headless. |
+| `progress(event)` | Emits structured progress for richer workflow UI surfaces. |
 
 ```ts
 import { Type } from "typebox";
 import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
-export const meta: WorkflowMeta = { name: "my-workflow", description: "..." };
+export const meta: WorkflowMeta = {
+  name: "my-workflow",
+  description: "Find, verify, and summarize something important.",
+};
+
+const FindingSchema = Type.Object({
+  summary: Type.String(),
+  file: Type.String(),
+  line: Type.Optional(Type.Number()),
+});
 
-export default async function run({ agent, parallel, pipeline, phase, log, args }: WorkflowApi) {
+export default async function run({ agent, parallel, phase }: WorkflowApi) {
   phase("Find");
-  const result = await agent("find issues ...", { schema: Type.Object({ /* ... */ }) });
-  return result; // a typed object, validated against the schema
+
+  const findings = await parallel([
+    () => agent("Find correctness bugs in the diff.", { schema: FindingSchema, thinkingLevel: "low" }),
+    () => agent("Find error-handling bugs in the diff.", { schema: FindingSchema, thinkingLevel: "low" }),
+  ]);
+
+  phase("Synthesize");
+  return agent(`Summarize these findings: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
 }
 ```
 
 Under the hood:
 
-- **Each `agent()` is an in-process pi `AgentSession`** (`createAgentSession` + `SessionManager.inMemory()`), inheriting the host's model unless you set one.
-- **Structured output is a terminating tool**: the engine registers one tool whose `parameters` *is* your schema; pi validates the call and the engine captures the args — no parsing.
-- **A single global semaphore caps concurrent agents**, so `parallel`/`pipeline` nest freely while the cap holds inside every `agent()` call.
-- **Surfaces**: a `/workflow <name> [args]` command, plus a `workflow` tool the host agent can call.
+- **Each `agent()` is an in-process pi `AgentSession`** using `createAgentSession` and `SessionManager.inMemory()`.
+- **Structured output is a terminating tool**. The engine registers one tool whose `parameters` is your schema; pi validates the call and the engine captures the args. There is no JSON scraping.
+- **A single global semaphore caps concurrent agents**, so `parallel` and `pipeline` can nest freely while every `agent()` call still respects the run cap.
+- **Two surfaces are registered**: `/workflow <name> [args]` for direct use, and a `workflow` tool for host-agent delegation.
 
 ## Local development
 
-Only needed if you want to **add or customise workflows, or contribute** — using the bundled workflows requires none of this.
+Only needed if you want to add workflows, customise workflows, or contribute. Using the bundled workflows requires none of this.
 
 ```bash
 git clone https://github.com/timbrinded/pi-workflow-engine
 cd pi-workflow-engine
-bun install            # dev deps for typechecking only; pi serves bundled copies at runtime
-bun run typecheck      # tsc --noEmit
-bun scripts/smoke.ts   # no-LLM check: module graph loads + workflow discovery resolves
+bun install
+bun run typecheck
+bun scripts/smoke.ts
 ```
 
-Load your working copy into a session without installing it (ephemeral — overrides nothing):
+Load your working copy into a session without installing it. This is ephemeral and overrides nothing:
 
 ```bash
 pi -e ./src/index.ts -p "/workflow ping"
 ```
 
-**Add a workflow:** drop a `.ts` in `workflows/`, import it in `src/workflows.ts`, and add it to `BUILTIN_WORKFLOWS`. Statically-imported workflows share pi's bundled `typebox`, which guarantees schema validation. (Files in `workflows/` and `~/.pi/agent/workflows/` are also discovered dynamically at runtime, best-effort.)
+Add a workflow by creating `workflows/<name>.ts`, importing it in `src/workflows.ts`, and adding it to `BUILTIN_WORKFLOWS`. Statically imported workflows share pi's bundled `typebox`, which guarantees schema validation. Files in `workflows/` and `~/.pi/agent/workflows/` are also discovered dynamically at runtime on a best-effort basis.
 
-**Customise the review:** edit the `ANGLES` array in `workflows/code-review.ts` — the lenses are where your codebase's real failure modes and conventions belong. Tune `model` / `thinkingLevel` / `tools` per `agent()` call, and `DEFAULT_CONCURRENCY` in `src/engine.ts`.
+Tune the built-in review workflow by editing the `ANGLES` array in `workflows/code-review.ts`. Tune `model`, `thinkingLevel`, and `tools` per `agent()` call, and tune `DEFAULT_CONCURRENCY` in `src/engine.ts`.
 
 ### Layout
 
-```
+```text
 src/
-  index.ts         extension entry (registers the command + tool)
+  index.ts         extension entry; registers the command and tool
   types.ts         WorkflowApi / WorkflowModule contracts
-  agent-runner.ts  the createAgentSession + terminating-tool schema bridge
+  agent-runner.ts  createAgentSession + terminating-tool schema bridge
   concurrency.ts   Semaphore, parallel(), pipeline()
-  engine.ts        runWorkflow() — binds the primitives to a run
+  engine.ts        runWorkflow(); binds primitives to one run
   progress.ts      live phase/agent tree via ctx.ui.setWidget
   discovery.ts     static registry + best-effort drop-in loading
 workflows/
-  code-review.ts   the example: scope → find → verify → synthesize
-  ping.ts          minimal smoke workflow
+  code-review.ts     scope -> find -> verify -> synthesize
+  refactor-scout.ts  advisory refactor opportunities
+  diagnose.ts        advisory bug diagnosis
+  perf-review.ts     advisory performance investigation
+  ping.ts            minimal smoke workflow
 ```
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": ["pi-package"],
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test:ui": "bun scripts/test-workflow-ui.ts",
     "prepublishOnly": "tsc --noEmit"
   },
   "peerDependencies": {

package/src/advisory-schema.ts

@@ -0,0 +1,64 @@
+import { Type, type Static } from "typebox";
+
+export const AdvisorySeveritySchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Impact level of an advisory finding.",
+});
+
+export const AdvisoryConfidenceSchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Confidence that the finding is actionable.",
+});
+
+export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")], {
+  description: "Verifier judgment for a candidate finding.",
+});
+
+export const AdvisoryLocationSchema = Type.Object({
+  file: Type.String({ description: "Repository-relative file path." }),
+  line: Type.Optional(Type.Number({ description: "Relevant 1-based line number when known." })),
+  symbol: Type.Optional(Type.String({ description: "Relevant function, class, type, or other symbol when known." })),
+});
+
+export const AdvisoryCandidateSchema = Type.Object({
+  summary: Type.String({ description: "One-line candidate finding or hypothesis." }),
+  category: Type.String({ description: "Workflow-specific category such as bug, duplication, root-cause, or io." }),
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  impact: Type.String({ description: "Concrete consequence if this candidate is real." }),
+  recommendation: Type.Optional(Type.String({ description: "Optional first-step recommendation before synthesis." })),
+});
+
+export const AdvisoryCandidatesSchema = Type.Object({
+  candidates: Type.Array(AdvisoryCandidateSchema, { description: "Candidate advisory findings or hypotheses." }),
+});
+
+export const AdvisoryVerdictSchema = Type.Object({
+  verdict: AdvisoryVerifierVerdictSchema,
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
+  confidence: Type.Optional(AdvisoryConfidenceSchema),
+});
+
+export const AdvisoryFindingSchema = Type.Object({
+  summary: Type.String({ description: "One-line final finding." }),
+  category: Type.String({ description: "Workflow-specific category for grouping and display." }),
+  severity: AdvisorySeveritySchema,
+  confidence: AdvisoryConfidenceSchema,
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence." })),
+  impact: Type.String({ description: "Concrete user, runtime, maintenance, or performance impact." }),
+  recommendation: Type.String({ description: "Advisory next action; not an automatic edit." }),
+});
+
+export const AdvisoryReportSchema = Type.Object({
+  summary: Type.String({ description: "Short overall advisory summary." }),
+  findings: Type.Array(AdvisoryFindingSchema, { description: "Verified and ranked advisory findings." }),
+  nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
+});
+
+export type AdvisorySeverity = Static<typeof AdvisorySeveritySchema>;
+export type AdvisoryConfidence = Static<typeof AdvisoryConfidenceSchema>;
+export type AdvisoryVerifierVerdict = Static<typeof AdvisoryVerifierVerdictSchema>;
+export type AdvisoryLocation = Static<typeof AdvisoryLocationSchema>;
+export type AdvisoryCandidate = Static<typeof AdvisoryCandidateSchema>;
+export type AdvisoryCandidates = Static<typeof AdvisoryCandidatesSchema>;
+export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
+export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
+export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;

package/src/agent-runner.ts

@@ -49,11 +49,13 @@ function lastAssistantText(state: AgentState): string {
 export async function runAgent(rc: RunContext, prompt: string, opts: AgentOptions = {}): Promise<unknown> {
   const label = opts.label ?? "agent";
 
-  // Acquire a global concurrency slot before spawning the session.
+  // Track queued agents before acquiring a global concurrency slot.
+  const rowId = rc.progress.agentQueued(opts.phase, label);
   return rc.semaphore.run(async () => {
-    rc.progress.agentStart(opts.phase, label);
+    rc.progress.agentStart(opts.phase, label, rowId);
 
     let captured: unknown = null;
+    let failed = false;
     const customTools: ToolDefinition[] = opts.schema
       ? [
           defineTool({
@@ -92,7 +94,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
 
     const unsubscribe = session.subscribe((event) => {
       if (event.type === "tool_execution_start" && event.toolName !== FINAL_TOOL) {
-        rc.progress.agentTool(label, event.toolName);
+        rc.progress.agentTool(label, event.toolName, rowId);
       }
     });
 
@@ -107,12 +109,14 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
       }
       return lastAssistantText(session.state);
     } catch (error) {
+      failed = true;
+      rc.progress.agentFailed(label, error, rowId);
       rc.progress.log(`${label} failed: ${error instanceof Error ? error.message : String(error)}`);
       throw error;
     } finally {
       unsubscribe();
       session.dispose();
-      rc.progress.agentDone(label);
+      if (!failed) rc.progress.agentDone(label, rowId);
     }
   });
 }

package/src/engine.ts

@@ -3,7 +3,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { parallel, pipeline, Semaphore } from "./concurrency.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
-import type { AgentOptions, WorkflowApi, WorkflowModule } from "./types.ts";
+import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 
 /** Default global cap on concurrent agents per run. */
 const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
@@ -12,8 +13,22 @@ const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
  */
-export async function runWorkflow(ctx: ExtensionContext, mod: WorkflowModule, args: string): Promise<unknown> {
+export async function runWorkflow(
+  ctx: ExtensionContext,
+  mod: WorkflowModule,
+  args: string,
+  options: WorkflowRunOptions = {},
+): Promise<unknown> {
   const progress = new ProgressTracker(ctx, mod.meta.name);
+  if (options.inspect && ctx.hasUI) {
+    void ctx.ui
+      .custom<void>(
+        (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
+        { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+      )
+      .catch((error: unknown) => progress.log(`inspector failed: ${error instanceof Error ? error.message : String(error)}`));
+  }
+
   const rc: RunContext = {
     cwd: ctx.cwd,
     hostModel: ctx.model,
@@ -31,6 +46,7 @@ export async function runWorkflow(ctx: ExtensionContext, mod: WorkflowModule, ar
     pipeline,
     phase: (title) => progress.phase(title),
     log: (message) => progress.log(message),
+    progress: (event) => progress.event(event),
     args,
     cwd: ctx.cwd,
     signal: ctx.signal,

package/src/index.ts

@@ -1,8 +1,11 @@
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { discoverWorkflows } from "./discovery.ts";
 import { runWorkflow } from "./engine.ts";
+import type { WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import { isWorkflowResult, renderWorkflowResult, type WorkflowResultEnvelope } from "./ui/workflow-result-renderer.ts";
 
 /** Repo root (this file lives in <repo>/src/index.ts). */
 const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
@@ -18,34 +21,84 @@ function formatReport(name: string, result: unknown): string {
   return [`## Workflow: ${name}`, "", "```json", JSON.stringify(result, null, 2), "```"].join("\n");
 }
 
+function workflowEnvelope(name: string, result: unknown): WorkflowResultEnvelope {
+  return { name, result, completedAt: Date.now() };
+}
+
+interface WorkflowInvocation {
+  name: string;
+  args: string;
+  options: WorkflowRunOptions;
+}
+
+function parseWorkflowInvocation(input: string): WorkflowInvocation {
+  const trimmed = input.trim();
+  const space = trimmed.indexOf(" ");
+  const name = space === -1 ? trimmed : trimmed.slice(0, space);
+  const rest = space === -1 ? "" : trimmed.slice(space + 1).trim();
+  const inspect = /(?:^|\s)--inspect(?:\s|$)/.test(rest);
+  const cleanedArgs = rest.replace(/(?:^|\s)--inspect(?=\s|$)/g, " ").trim();
+  return { name, args: cleanedArgs, options: inspect ? { inspect: true } : {} };
+}
+
+async function pickWorkflow(
+  workflows: ReadonlyMap<string, WorkflowModule>,
+  ctx: ExtensionCommandContext,
+): Promise<WorkflowInvocation | undefined> {
+  const choices = [...workflows.values()].map((mod) => `${mod.meta.name} — ${mod.meta.description}`);
+  const choice = await ctx.ui.select("Run workflow", choices);
+  if (!choice) return undefined;
+
+  const separator = choice.indexOf(" — ");
+  const name = separator === -1 ? choice : choice.slice(0, separator);
+  const args = name === "code-review" ? (await ctx.ui.input("Code-review target/instructions", "Blank = auto-detect diff"))?.trim() ?? "" : "";
+  const inspect = await ctx.ui.confirm("Open inspector?", "Open a live workflow inspector while this workflow runs?");
+  return { name, args, options: { inspect } };
+}
+
+async function sendWorkflowResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  name: string,
+  mod: WorkflowModule,
+  args: string,
+  options: WorkflowRunOptions,
+): Promise<void> {
+  const result = await runWorkflow(ctx, mod, args, options);
+  pi.sendMessage(
+    { customType: "workflow-result", content: formatReport(name, result), display: true, details: workflowEnvelope(name, result) },
+    { triggerTurn: false },
+  );
+}
+
 export default function workflowEngine(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
+    const details = message.details;
+    if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+    return renderWorkflowResult("workflow", details ?? message.content, expanded, theme);
+  });
+
   // /workflow <name> [args] — user-invoked.
   pi.registerCommand("workflow", {
     description: "Run a multi-agent workflow: /workflow <name> [args]",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
-      const trimmed = args.trim();
-      const space = trimmed.indexOf(" ");
-      const name = space === -1 ? trimmed : trimmed.slice(0, space);
-      const rest = space === -1 ? "" : trimmed.slice(space + 1).trim();
-
       const workflows = await discoverWorkflows(REPO_DIR);
       const available = [...workflows.keys()].join(", ") || "(none)";
+      const direct = parseWorkflowInvocation(args);
+      const invocation = direct.name ? direct : ctx.hasUI ? await pickWorkflow(workflows, ctx) : undefined;
 
-      if (!name) {
+      if (!invocation) {
         ctx.ui.notify(`Usage: /workflow <name> [args]. Available: ${available}`, "warning");
         return;
       }
-      const mod = workflows.get(name);
+
+      const mod = workflows.get(invocation.name);
       if (!mod) {
-        ctx.ui.notify(`Unknown workflow "${name}". Available: ${available}`, "error");
+        ctx.ui.notify(`Unknown workflow "${invocation.name}". Available: ${available}`, "error");
         return;
       }
 
-      const result = await runWorkflow(ctx, mod, rest);
-      pi.sendMessage(
-        { customType: "workflow-result", content: formatReport(name, result), display: true, details: result },
-        { triggerTurn: false },
-      );
+      await sendWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, invocation.options);
     },
   });
 
@@ -59,6 +112,18 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       name: Type.String({ description: "Workflow name, e.g. code-review" }),
       args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
     }),
+    renderCall(args, theme) {
+      const suffix = args.args ? ` ${theme.fg("dim", args.args)}` : "";
+      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name)}${suffix}`, 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
+      const details = result.details;
+      if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+      const first = result.content[0];
+      const text = first?.type === "text" ? first.text : "Workflow finished.";
+      return new Text(theme.fg("muted", text), 0, 0);
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const workflows = await discoverWorkflows(REPO_DIR);
       const mod = workflows.get(params.name);
@@ -70,7 +135,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         };
       }
       const result = await runWorkflow(ctx, mod, params.args ?? "");
-      return { content: [{ type: "text", text: summarize(result) }], details: result };
+      return { content: [{ type: "text", text: summarize(result) }], details: workflowEnvelope(params.name, result) };
     },
   });
 }