pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -1,32 +1,55 @@
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { SelectList, Text, truncateToWidth, type Component, type SelectItem, type SelectListTheme, type TUI } from "@earendil-works/pi-tui";
-import type { WorkflowProgressSnapshot } from "./src/progress.ts";
-import type { WorkflowModule, WorkflowProgressSource, WorkflowRef, WorkflowRunMetadata, WorkflowRunOptions } from "./src/types.ts";
+import { VERSION, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
+import { isAdvisoryReport } from "./src/advisory-schema.ts";
+import type { WorkflowProgressSnapshot } from "./src/progress-types.ts";
+import type { LoadedWorkflow, WorkflowModule, WorkflowProgressSource, WorkflowRef, WorkflowRunMetadata, WorkflowRunOptions } from "./src/types.ts";
 import { WorkflowInspector } from "./src/ui/workflow-inspector.ts";
-import type { PerfSink, PerfSnapshot } from "./src/perf.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./src/ui/workflow-viewer-layout.ts";
+import type { PerfSink } from "./src/perf.ts";
 import type { WorkflowUsageSnapshot } from "./src/usage.ts";
-import { registerDynamax } from "./src/dynamax.ts";
-import { handleReviewViewerAction } from "./src/review/review-actions.ts";
-import { decideReviewResultsPresentation, extensionContextMode, maybeShowReviewResultsViewer } from "./src/review/review-results-flow.ts";
+import { ADAPTIVE_WORKFLOW_GUIDANCE, registerDynamax } from "./src/dynamax.ts";
+import { sessionKey } from "./src/session-identity.ts";
+import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./src/dynamax-shortcuts.ts";
+import { ReviewSessionCoordinator } from "./src/review/review-session-coordinator.ts";
 import {
   formatWorkflowDetailLines,
-  isAdvisoryReport,
   isWorkflowResult,
   renderWorkflowResult,
-  type WorkflowPerfDetails,
-  type WorkflowResultEnvelope,
 } from "./src/ui/workflow-result-renderer.ts";
-import { parseWorkflowBudgetString, WORKFLOW_BUDGET_MAX, WORKFLOW_BUDGET_MIN } from "./src/options.ts";
+import {
+  parseWorkflowBudgetString,
+  parseWorkflowIntegerString,
+  resolveWorkflowRunOptions,
+  type ResolvedWorkflowRunOptions,
+  WORKFLOW_AGENT_TIMEOUT_MAX_MS,
+  WORKFLOW_AGENT_TIMEOUT_MIN_MS,
+  WORKFLOW_AGENT_RETRIES_MAX,
+  WORKFLOW_AGENT_RETRIES_MIN,
+  WORKFLOW_BUDGET_MAX,
+  WORKFLOW_BUDGET_MIN,
+  WORKFLOW_MAX_AGENTS_MAX,
+  WORKFLOW_MAX_AGENTS_MIN,
+  WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+  WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN,
+  WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS,
+  WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+} from "./src/options.ts";
+import { executeWorkflowInvocation, type WorkflowExecution, type WorkflowPerfDetails } from "./src/workflow-execution.ts";
+import { registerWorkflowModelProfileCommand } from "./src/model-profile-command.ts";
+import { BackgroundWorkflowCoordinator } from "./src/background-workflows.ts";
+import { backgroundUnavailableResult, startBackgroundWorkflowTool } from "./src/background-workflow-tool.ts";
+import { registerWorkflowRunCommand, WorkflowRunController } from "./src/workflow-run-controller.ts";
+import { completeCurrentArgument, splitArgumentPrefix } from "./src/command-completions.ts";
+import { assertSupportedPiVersion } from "./src/pi-compat.ts";
+import { formatWorkflowInspection, workflowInspectionSnapshot } from "./src/ui/workflow-format.ts";
 
 /** Extension root (this file lives in <repo>/.pi/extensions/pi-workflow-engine/index.ts). */
 const EXTENSION_DIR = fileURLToPath(new URL(".", import.meta.url));
 
 function summarize(result: unknown): string {
-  if (result && typeof result === "object" && typeof (result as { summary?: unknown }).summary === "string") {
-    return (result as { summary: string }).summary;
-  }
+  if (typeof result === "object" && result !== null && "summary" in result && typeof result.summary === "string") return result.summary;
   return typeof result === "string" ? result : "Workflow finished.";
 }
 
@@ -73,21 +96,6 @@ function formatFindingLocation(location: { readonly file: string; readonly line?
   return `${location.file}${line}${symbol}`;
 }
 
-function workflowEnvelope(
-  name: string,
-  result: unknown,
-  usage?: WorkflowUsageSnapshot,
-  perf?: WorkflowPerfDetails,
-  metadata?: WorkflowRunMetadata,
-): WorkflowResultEnvelope {
-  return { name, result, completedAt: Date.now(), usage, perf, runId: metadata?.runId, resumedFromRunId: metadata?.resumedFromRunId };
-}
-
-function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
-  if (!snapshot?.enabled) return undefined;
-  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
-}
-
 type DiscoveryModule = typeof import("./src/discovery.ts");
 type EngineModule = typeof import("./src/engine.ts");
 type InlineWorkflowModule = typeof import("./src/inline-workflow.ts");
@@ -104,9 +112,8 @@ async function loadInlineWorkflow(): Promise<InlineWorkflowModule> {
   return await import("./src/inline-workflow.ts");
 }
 
-async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSink | undefined> {
-  const enabled = options.perf ?? process.env.PI_WORKFLOW_PERF === "1";
-  if (!enabled) return undefined;
+async function createInvocationPerf(options: ResolvedWorkflowRunOptions): Promise<PerfSink | undefined> {
+  if (!options.perf) return undefined;
   const { createPerfRecorder } = await import("./src/perf.ts");
   return createPerfRecorder(true);
 }
@@ -114,7 +121,7 @@ async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSi
 /**
  * Resolve an `api.workflow()` reference to a registered workflow module. Throws on an unknown name.
  */
-export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<WorkflowModule> {
+export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<LoadedWorkflow> {
   const { discoverWorkflows } = await loadDiscovery();
   const workflows = await discoverWorkflows(EXTENSION_DIR, { perf });
   const mod = workflows.get(ref);
@@ -128,77 +135,55 @@ export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Pro
 const AUTHOR_TEMP_WORKFLOW_VALUE = "__author-temporary-workflow__";
 const AUTHOR_TEMP_WORKFLOW_LABEL = "Author temporary one-shot workflow";
 const AUTHOR_TEMP_WORKFLOW_DESCRIPTION = "Ask the host agent to author and run an inline workflow.";
-const WORKFLOW_PICKER_MAX_VISIBLE = 8;
-const WORKFLOW_PICKER_LAYOUT = { minPrimaryColumnWidth: 18, maxPrimaryColumnWidth: 22 };
-
-class WorkflowPickerComponent implements Component {
-  private readonly list: SelectList;
-
-  constructor(
-    items: SelectItem[],
-    private readonly tui: TUI,
-    private readonly theme: Theme,
-    done: (value: string | undefined) => void,
-  ) {
-    this.list = new SelectList(items, Math.min(WORKFLOW_PICKER_MAX_VISIBLE, items.length), selectListTheme(theme), WORKFLOW_PICKER_LAYOUT);
-    this.list.onSelect = (item) => done(item.value);
-    this.list.onCancel = () => done(undefined);
-    this.list.onSelectionChange = () => this.tui.requestRender();
-  }
-
-  render(width: number): string[] {
-    const safeWidth = Math.max(20, width);
-    const rule = this.theme.fg("borderMuted", "-".repeat(safeWidth));
-    const lines = [
-      rule,
-      this.theme.fg("accent", this.theme.bold("Run workflow")),
-      "",
-      ...this.list.render(safeWidth),
-      "",
-      this.theme.fg("muted", "up/down navigate  enter select  escape cancel"),
-      rule,
-    ];
-    return lines.map((line) => truncateToWidth(line, safeWidth));
-  }
-
-  handleInput(data: string): void {
-    this.list.handleInput(data);
-    this.tui.requestRender();
-  }
 
-  invalidate(): void {
-    this.list.invalidate();
+const WORKFLOW_OPTION_COMPLETIONS = [
+  { value: "--inspect", description: "Open the live workflow inspector" },
+  { value: "--refresh", description: "Refresh dynamic workflow discovery" },
+  { value: "--perf", description: "Collect workflow performance metrics" },
+  { value: "--result-viewer", description: "Open supported result viewers" },
+  { value: "--no-result-viewer", description: "Skip supported result viewers" },
+  { value: "--resume-edited", description: "Allow resume after workflow source edits" },
+  { value: "--concurrency=", description: "Set the global subagent concurrency cap" },
+  { value: "--parallel-limit=", description: "Set the parallel submission limit" },
+  { value: "--max-agents=", description: "Set the maximum admitted live agents" },
+  { value: "--agent-timeout-ms=", description: "Set the timeout for each agent attempt" },
+  { value: "--agent-retries=", description: "Set retries for each agent call" },
+  { value: "--budget=", description: "Set the workflow output-token budget" },
+  { value: "--resume=", description: "Resume from a retained workflow run ID" },
+] as const;
+
+async function workflowArgumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+  const parts = splitArgumentPrefix(argumentPrefix);
+  if (parts.completed.length === 0) {
+    const { discoverWorkflows } = await loadDiscovery();
+    const workflows = await discoverWorkflows(EXTENSION_DIR);
+    return completeCurrentArgument(
+      argumentPrefix,
+      [...workflows.values()].map((workflow) => ({
+        value: workflow.meta.name,
+        description: workflow.meta.description,
+      })),
+    );
   }
-}
-
-function selectListTheme(theme: Theme): SelectListTheme {
-  return {
-    selectedPrefix: (text) => theme.fg("accent", text),
-    selectedText: (text) => theme.fg("accent", text),
-    description: (text) => theme.fg("muted", text),
-    scrollInfo: (text) => theme.fg("muted", text),
-    noMatch: (text) => theme.fg("muted", text),
-  };
-}
-
-function workflowPickerItems(workflows: ReadonlyMap<string, WorkflowModule>): SelectItem[] {
-  return [
-    { value: AUTHOR_TEMP_WORKFLOW_VALUE, label: AUTHOR_TEMP_WORKFLOW_LABEL, description: AUTHOR_TEMP_WORKFLOW_DESCRIPTION },
-    ...[...workflows.values()].map((mod) => ({ value: mod.meta.name, label: mod.meta.name, description: mod.meta.description })),
-  ];
+  return completeCurrentArgument(argumentPrefix, WORKFLOW_OPTION_COMPLETIONS);
 }
 
 async function selectWorkflowValue(workflows: ReadonlyMap<string, WorkflowModule>, ctx: ExtensionCommandContext): Promise<string | undefined> {
-  const items = workflowPickerItems(workflows);
-  if (typeof ctx.ui.custom === "function") {
-    return await ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new WorkflowPickerComponent(items, tui, theme, done));
-  }
-
-  const choice = await ctx.ui.select(
+  const choices = [
+    {
+      value: AUTHOR_TEMP_WORKFLOW_VALUE,
+      display: `${AUTHOR_TEMP_WORKFLOW_LABEL} — ${AUTHOR_TEMP_WORKFLOW_DESCRIPTION}`,
+    },
+    ...[...workflows.values()].map((workflow) => ({
+      value: workflow.meta.name,
+      display: `${workflow.meta.name} — ${workflow.meta.description}`,
+    })),
+  ];
+  const selected = await ctx.ui.select(
     "Run workflow",
-    items.map((item) => item.label),
+    choices.map((choice) => choice.display),
   );
-  return items.find((item) => item.label === choice)?.value ?? choice;
+  return choices.find((choice) => choice.display === selected)?.value;
 }
 
 export interface LastWorkflowInspection {
@@ -215,30 +200,42 @@ export interface ActiveWorkflowInspection {
   readonly snapshot: () => WorkflowProgressSnapshot;
 }
 
-let lastWorkflowInspection: LastWorkflowInspection | undefined;
-let activeWorkflowInspection: ActiveWorkflowInspection | undefined;
-
-export function getLastWorkflowInspection(): LastWorkflowInspection | undefined {
-  return lastWorkflowInspection;
+interface SessionWorkflowInspections {
+  last?: LastWorkflowInspection;
+  active?: ActiveWorkflowInspection;
 }
 
-export function getActiveWorkflowInspection(): ActiveWorkflowInspection | undefined {
-  return activeWorkflowInspection;
+const workflowInspections = new WeakMap<ExtensionAPI, Map<string, SessionWorkflowInspections>>();
+let latestWorkflowInspection: LastWorkflowInspection | undefined;
+let latestActiveWorkflowInspection: ActiveWorkflowInspection | undefined;
+
+export function getLastWorkflowInspection(): LastWorkflowInspection | undefined {
+  return latestWorkflowInspection;
 }
 
 export async function openWorkflowInspector(ctx: ExtensionContext, inspection: LastWorkflowInspection | ActiveWorkflowInspection): Promise<void> {
+  if (!ctx.hasUI || ctx.mode !== "tui") {
+    ctx.ui.notify(formatWorkflowInspection(inspection), "info");
+    return;
+  }
   await ctx.ui.custom<void>(
-    (tui, theme, _keybindings, done) => new WorkflowInspector(snapshotGetter(inspection), tui, theme, () => done(undefined)),
-    { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+    (tui, theme, _keybindings, done) => new WorkflowInspector(() => workflowInspectionSnapshot(inspection), tui, theme, () => done(undefined)),
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
   );
 }
 
-async function openAvailableWorkflowInspector(ctx: ExtensionContext): Promise<void> {
-  if (!ctx.hasUI) {
-    ctx.ui.notify("Workflow inspector requires the TUI", "warning");
-    return;
-  }
-  const inspection = activeWorkflowInspection ?? lastWorkflowInspection;
+function workflowInspectionState(pi: ExtensionAPI, ctx: ExtensionContext): SessionWorkflowInspections {
+  const sessions = workflowInspections.get(pi) ?? new Map<string, SessionWorkflowInspections>();
+  const key = sessionKey(ctx);
+  const state = sessions.get(key) ?? {};
+  sessions.set(key, state);
+  workflowInspections.set(pi, sessions);
+  return state;
+}
+
+async function openAvailableWorkflowInspector(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  const state = workflowInspectionState(pi, ctx);
+  const inspection = state.active ?? state.last;
   if (!inspection) {
     ctx.ui.notify("No workflow inspector is available yet", "warning");
     return;
@@ -246,11 +243,6 @@ async function openAvailableWorkflowInspector(ctx: ExtensionContext): Promise<vo
   await openWorkflowInspector(ctx, inspection);
 }
 
-function snapshotGetter(inspection: LastWorkflowInspection | ActiveWorkflowInspection): () => WorkflowProgressSnapshot {
-  const snapshot = inspection.snapshot;
-  return typeof snapshot === "function" ? snapshot : () => snapshot;
-}
-
 function bindActiveWorkflowInspection(name: string, args: string, source: WorkflowProgressSource): ActiveWorkflowInspection {
   return { name, args, startedAt: Date.now(), snapshot: () => source.snapshot() };
 }
@@ -278,6 +270,10 @@ export function parseWorkflowInvocation(input: string): WorkflowInvocation {
 
 const INVALID_BUDGET_OPTION = "--budget requires a positive integer output-token count";
 const INVALID_RESUME_OPTION = "--resume requires a workflow run id";
+const INVALID_MAX_AGENTS_OPTION = "--max-agents requires an integer";
+const INVALID_AGENT_TIMEOUT_OPTION = "--agent-timeout-ms requires an integer";
+const INVALID_AGENT_RETRIES_OPTION = "--agent-retries requires an integer";
+const INVALID_EDITED_RESUME_OPTION = "--resume-edited requires --resume <run-id>";
 
 function parseWorkflowOptions(input: string): { args: string; options: WorkflowRunOptions; refreshDiscovery?: boolean; optionErrors?: string[] } {
   const tokens = input.split(/\s+/).filter(Boolean);
@@ -299,6 +295,10 @@ function parseWorkflowOptions(input: string): { args: string; options: WorkflowR
       options.perf = true;
       continue;
     }
+    if (token === "--resume-edited") {
+      options.resumeEditedWorkflow = true;
+      continue;
+    }
     if (token === "--result-viewer" || token === "--review-viewer") {
       options.resultViewer = "open";
       continue;
@@ -327,6 +327,54 @@ function parseWorkflowOptions(input: string): { args: string; options: WorkflowR
       if (next !== undefined) i++;
       continue;
     }
+    if (token.startsWith("--max-agents=")) {
+      const parsed = parseWorkflowIntegerString(token.slice("--max-agents=".length));
+      if (parsed === undefined) optionErrors.push(INVALID_MAX_AGENTS_OPTION);
+      else options.maxAgents = parsed;
+      continue;
+    }
+    if (token === "--max-agents") {
+      const next = tokens[i + 1];
+      const parsed = parseWorkflowIntegerString(next);
+      if (parsed === undefined) optionErrors.push(INVALID_MAX_AGENTS_OPTION);
+      else {
+        options.maxAgents = parsed;
+        i++;
+      }
+      continue;
+    }
+    if (token.startsWith("--agent-timeout-ms=")) {
+      const parsed = parseWorkflowIntegerString(token.slice("--agent-timeout-ms=".length));
+      if (parsed === undefined) optionErrors.push(INVALID_AGENT_TIMEOUT_OPTION);
+      else options.agentTimeoutMs = parsed;
+      continue;
+    }
+    if (token === "--agent-timeout-ms") {
+      const next = tokens[i + 1];
+      const parsed = parseWorkflowIntegerString(next);
+      if (parsed === undefined) optionErrors.push(INVALID_AGENT_TIMEOUT_OPTION);
+      else {
+        options.agentTimeoutMs = parsed;
+        i++;
+      }
+      continue;
+    }
+    if (token.startsWith("--agent-retries=")) {
+      const parsed = parseWorkflowIntegerString(token.slice("--agent-retries=".length));
+      if (parsed === undefined) optionErrors.push(INVALID_AGENT_RETRIES_OPTION);
+      else options.agentRetries = parsed;
+      continue;
+    }
+    if (token === "--agent-retries") {
+      const next = tokens[i + 1];
+      const parsed = parseWorkflowIntegerString(next);
+      if (parsed === undefined) optionErrors.push(INVALID_AGENT_RETRIES_OPTION);
+      else {
+        options.agentRetries = parsed;
+        i++;
+      }
+      continue;
+    }
     if (token.startsWith("--budget=")) {
       const parsed = parseBudgetOption(token.slice("--budget=".length));
       if (parsed === undefined) optionErrors.push(INVALID_BUDGET_OPTION);
@@ -362,6 +410,7 @@ function parseWorkflowOptions(input: string): { args: string; options: WorkflowR
     }
     kept.push(token);
   }
+  if (options.resumeEditedWorkflow && !options.resumeFromRunId) optionErrors.push(INVALID_EDITED_RESUME_OPTION);
   return { args: kept.join(" ").trim(), options, refreshDiscovery: refreshDiscovery || undefined, optionErrors: optionErrors.length > 0 ? optionErrors : undefined };
 }
 
@@ -390,11 +439,12 @@ ${brief.trim()}
 Use the workflow tool with a script argument, not a saved workflow name.
 The script must start with export const meta = { ... } and default-export an async workflow function.
 Use the injected Type object for schemas. Do not import anything or use dynamic import().
-Set thinkingLevel explicitly on each agent() call.
+Set profile to "small", "medium", or "big" on each agent() call; use explicit model/thinkingLevel only for an intentional override.
 Always pass a plain string as the first api.agent() argument; build prompts with template strings before calling agent().
 If using \`isolation: "worktree"\`, remember api.agent() returns \`{ result, patch, changed }\`; read \`.result\` for the agent answer and \`.patch\` for the diff.
 When the run is budgeted, guard expensive loops with \`while (api.budget.total && api.budget.remaining() > N) { ... }\`; api.agent() throws once the budget is spent.
 Subagents receive no skills by default. When the brief asks for a skill or a stage clearly benefits from one, pass \`skills: ["skill-name"]\` on that agent call only.
+${ADAPTIVE_WORKFLOW_GUIDANCE}
 Do not edit files unless the user explicitly requested edits.`;
 }
 
@@ -402,6 +452,7 @@ export interface WorkflowToolRequestParams {
   readonly name?: string;
   readonly script?: string;
   readonly resumeFromRunId?: string;
+  readonly background?: boolean;
 }
 
 export type WorkflowToolRequest =
@@ -458,76 +509,152 @@ export async function pickWorkflow(
 
 export async function sendWorkflowResult(
   pi: ExtensionAPI,
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
   name: string,
-  mod: WorkflowModule,
+  mod: LoadedWorkflow,
   args: string,
   options: WorkflowRunOptions,
   perfRecorder?: PerfSink,
+  reviewSessions: ReviewSessionCoordinator = createReviewSessionCoordinator(pi),
+): Promise<void> {
+  await sendResolvedWorkflowResult(
+    pi,
+    ctx,
+    name,
+    mod,
+    args,
+    resolveWorkflowRunOptions(options),
+    perfRecorder,
+    reviewSessions,
+  );
+}
+
+async function sendResolvedWorkflowResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  name: string,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+  perfRecorder: PerfSink | undefined,
+  reviewSessions: ReviewSessionCoordinator,
 ): Promise<void> {
-  const { runWorkflow } = await loadEngine();
-  let perfSnapshot: PerfSnapshot | undefined;
-  let usageSnapshot: WorkflowUsageSnapshot | undefined;
-  let runMetadata: WorkflowRunMetadata | undefined;
+  const execution = await executeResolvedWorkflow(pi, ctx, name, mod, args, options, perfRecorder);
+  reviewSessions.remember(ctx, execution, options);
+  sendWorkflowExecution(pi, execution);
+  await reviewSessions.present(ctx, execution, options);
+}
+
+async function executeResolvedWorkflow(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  name: string,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+  perfRecorder?: PerfSink,
+): Promise<WorkflowExecution> {
+  const { runResolvedWorkflow } = await loadEngine();
   let liveInspection: ActiveWorkflowInspection | undefined;
-  const result = await runWorkflow(ctx, mod, args, {
-    ...options,
-    perf: options.perf ?? perfRecorder !== undefined,
+  const inspections = workflowInspectionState(pi, ctx);
+  return await executeWorkflowInvocation({
+    ctx,
+    name,
+    mod,
+    args,
+    options,
     perfRecorder,
+    runResolvedWorkflow,
     resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
     onProgressSource(source) {
       if (source) {
         liveInspection = bindActiveWorkflowInspection(name, args, source);
-        activeWorkflowInspection = liveInspection;
-      } else if (activeWorkflowInspection === liveInspection) {
-        activeWorkflowInspection = undefined;
+        inspections.active = liveInspection;
+        latestActiveWorkflowInspection = liveInspection;
+      } else if (inspections.active === liveInspection) {
+        inspections.active = undefined;
+        if (latestActiveWorkflowInspection === liveInspection) latestActiveWorkflowInspection = undefined;
         liveInspection = undefined;
       }
-      options.onProgressSource?.(source);
-    },
-    onPerfSnapshot(snapshot) {
-      perfSnapshot = snapshot;
-      options.onPerfSnapshot?.(snapshot);
-    },
-    onUsageSnapshot(snapshot) {
-      usageSnapshot = snapshot;
-      options.onUsageSnapshot?.(snapshot);
-    },
-    onRunMetadata(metadata) {
-      runMetadata = metadata;
-      options.onRunMetadata?.(metadata);
     },
     onProgressSnapshot(snapshot) {
-      lastWorkflowInspection = { name, args, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
-      options.onProgressSnapshot?.(snapshot);
+      const completed = { name, args, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
+      inspections.last = completed;
+      latestWorkflowInspection = completed;
     },
   });
-  const perf = compactPerfSnapshot(perfSnapshot);
-  const reviewDecision = decideReviewResultsPresentation({
-    workflowName: name,
-    result,
-    mode: extensionContextMode(ctx),
-    hasUI: ctx.hasUI,
-    resultViewer: options.resultViewer,
-    invocationKind: "command",
-  });
-  const reviewAction = await maybeShowReviewResultsViewer(ctx, reviewDecision);
-  if (reviewDecision.kind !== "send") {
-    await handleReviewViewerAction(pi, ctx, reviewAction, reviewDecision.issues, reviewDecision.report.reviewContext);
-  }
+}
+
+function sendWorkflowExecution(pi: ExtensionAPI, execution: WorkflowExecution): void {
+  const { name } = execution.envelope;
   pi.sendMessage(
     {
       customType: "workflow-result",
-      content: formatMessageContent(name, result, usageSnapshot, perf, runMetadata),
+      content: formatMessageContent(
+        name,
+        execution.envelope.result,
+        execution.envelope.usage,
+        execution.envelope.perf,
+        execution.metadata,
+      ),
       display: true,
-      details: workflowEnvelope(name, result, usageSnapshot, perf, runMetadata),
+      details: execution.envelope,
     },
     { triggerTurn: false },
   );
 }
 
-export default function workflowEngine(pi: ExtensionAPI): void {
-  registerDynamax(pi, undefined, { openInspector: openAvailableWorkflowInspector });
+function createReviewSessionCoordinator(pi: ExtensionAPI): ReviewSessionCoordinator {
+  return new ReviewSessionCoordinator(pi, {
+    async runFollowUp(ctx, workflow, options) {
+      const perfRecorder = await createInvocationPerf(options);
+      return await executeResolvedWorkflow(pi, ctx, workflow.meta.name, workflow, "", options, perfRecorder);
+    },
+    publish: (execution) => sendWorkflowExecution(pi, execution),
+  });
+}
+
+export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShortcuts = resolveDynamaxShortcuts()): void {
+  assertSupportedPiVersion(VERSION);
+  const reviewSessions = createReviewSessionCoordinator(pi);
+  const backgroundWorkflows = new BackgroundWorkflowCoordinator(pi);
+  const workflowRuns = new WorkflowRunController(backgroundWorkflows, {
+    async resolveWorkflow(name) {
+      const { discoverWorkflows } = await loadDiscovery();
+      return (await discoverWorkflows(EXTENSION_DIR)).get(name);
+    },
+    async execute(ctx, name, workflow, options) {
+      const perfRecorder = await createInvocationPerf(options);
+      const execution = await executeResolvedWorkflow(pi, ctx, name, workflow, "", options, perfRecorder);
+      reviewSessions.remember(ctx, execution, options);
+    },
+  });
+  backgroundWorkflows.onRunSettled((ctx, runId) => workflowRuns.runSettled(ctx, runId));
+  registerDynamax(pi, shortcuts, { openInspector: (ctx) => openAvailableWorkflowInspector(pi, ctx) });
+  registerWorkflowModelProfileCommand(pi);
+  registerWorkflowRunCommand(pi, workflowRuns);
+  pi.on("session_start", async (_event, ctx) => {
+    await backgroundWorkflows.sessionStarted(ctx);
+    await workflowRuns.sessionStarted(ctx);
+  });
+  pi.on("agent_settled", async (_event, ctx) => {
+    await backgroundWorkflows.agentSettled(ctx);
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    workflowRuns.sessionShutdown(ctx);
+    await backgroundWorkflows.sessionShutdown(ctx);
+    const key = sessionKey(ctx);
+    workflowInspections.get(pi)?.delete(key);
+    reviewSessions.dispose(ctx);
+  });
+  if (shortcuts.results) {
+    pi.registerShortcut(shortcuts.results, {
+      description: "Open last code-review results",
+      handler: async (ctx) => {
+        await reviewSessions.reopen(ctx);
+      },
+    });
+  }
 
   pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
     const details = message.details;
@@ -541,27 +668,42 @@ export default function workflowEngine(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("workflow:inspector", {
-    description: "Open the current or last workflow inspector",
+    description: "Open the current, last, or a retained run inspector",
+    getArgumentCompletions: (argumentPrefix) => workflowRuns.inspectorArgumentCompletions(argumentPrefix),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const trimmed = args.trim();
       if (trimmed && trimmed !== "last") {
-        ctx.ui.notify("Usage: /workflow:inspector [last]", "warning");
+        if (await workflowRuns.inspectStoredRun(ctx, trimmed)) return;
+        ctx.ui.notify(`Workflow run ${trimmed} was not found.`, "warning");
+        return;
+      }
+      await openAvailableWorkflowInspector(pi, ctx);
+    },
+  });
+
+  pi.registerCommand("workflow:results", {
+    description: "Reopen the last code-review findings viewer",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      if (args.trim()) {
+        ctx.ui.notify("Usage: /workflow:results", "warning");
         return;
       }
-      await openAvailableWorkflowInspector(ctx);
+      await reviewSessions.reopen(ctx);
     },
   });
 
   // /workflow <name> [args] — user-invoked.
   pi.registerCommand("workflow", {
     description: "Run a multi-agent workflow: /workflow <name> [args]",
+    getArgumentCompletions: workflowArgumentCompletions,
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const direct = parseWorkflowInvocation(args);
       if (direct.optionErrors?.length) {
         ctx.ui.notify(`Invalid workflow option: ${direct.optionErrors.join("; ")}`, "warning");
         return;
       }
-      const perfRecorder = await createInvocationPerf(direct.options);
+      const directOptions = resolveWorkflowRunOptions(direct.options);
+      const perfRecorder = await createInvocationPerf(directOptions);
       const { discoverWorkflows } = await loadDiscovery();
       const workflows = await discoverWorkflows(EXTENSION_DIR, { refresh: direct.refreshDiscovery, perf: perfRecorder });
       const available = [...workflows.keys()].join(", ") || "(none)";
@@ -583,16 +725,25 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         return;
       }
 
-      await sendWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, invocation.options, perfRecorder);
+      const effectiveOptions = invocation === direct ? directOptions : resolveWorkflowRunOptions(invocation.options);
+      await sendResolvedWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, effectiveOptions, perfRecorder, reviewSessions);
     },
   });
 
-  // workflow tool — lets the host agent fan out mid-conversation.
+  registerWorkflowTool(pi, reviewSessions, backgroundWorkflows);
+}
+
+/** Register the host-facing workflow tool independently from command and lifecycle surfaces. */
+function registerWorkflowTool(
+  pi: ExtensionAPI,
+  reviewSessions: ReviewSessionCoordinator,
+  backgroundWorkflows: BackgroundWorkflowCoordinator,
+): void {
   pi.registerTool({
     name: "workflow",
     label: "Workflow",
     description:
-      "ONLY call workflow when the user opted into multi-agent orchestration via the literal token `dynamax`, sticky `/workflow:dynamax on`, an explicit request to run or author a workflow, or a command/skill instruction. Runs either a registered named workflow or an inline one-off workflow script (fan-out → verify → synthesize) and returns its structured result.",
+      "ONLY call workflow when the user opted into multi-agent orchestration via the literal token `dynamax`, sticky `/workflow:dynamax on`, an explicit request to run or author a workflow, or a command/skill instruction. Runs either a registered named workflow or an inline one-off workflow script (fan-out → verify → synthesize), synchronously by default or explicitly in the background.",
     promptSnippet: "Run an existing named workflow or an inline one-off workflow script",
     promptGuidelines: [
       "Use workflow only when the user opted into workflow orchestration via `dynamax`, `/workflow:dynamax on`, an explicit request to run/author a workflow, or a command/skill instruction.",
@@ -605,6 +756,10 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       "When using `isolation: \"worktree\"`, `api.agent()` returns `{ result, patch, changed }`; use `.result` for the answer and `.patch` for the isolated diff.",
       "If an inline subagent needs grep/find/code-search helpers, use `tools: [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]` plus `toolHints: [\"search\"]` so installed tools such as ast-grep, mgrep, ffgrep, or fffind are discovered dynamically.",
       "`api.budget` exposes `{ total, spent(), remaining() }` (output tokens). When the run is budgeted, scale fleets from `budget.total` and guard loops with `while (budget.total && budget.remaining() > N) { await api.agent(...) }`; `api.agent()` throws once the ceiling is reached.",
+      ADAPTIVE_WORKFLOW_GUIDANCE,
+      "Set background: true only when the user explicitly wants the workflow to continue after this tool call; the tool returns a durable run ID and completion is delivered later.",
+      "Set autoResumeOnUsageLimit: true only for an explicitly backgrounded workflow when the user wants bounded automatic continuation after a recognized provider usage window.",
+      "Set resumeEditedWorkflow: true only with resumeFromRunId when the user explicitly accepts reusing behaviorally identical calls after workflow source edits.",
       "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
     ],
     parameters: Type.Object({
@@ -613,6 +768,38 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
       concurrency: Type.Optional(Type.Number({ description: "Optional per-run agent concurrency cap" })),
       parallelSubmissionLimit: Type.Optional(Type.Number({ description: "Optional limit for eagerly submitted parallel thunks" })),
+      maxAgents: Type.Optional(
+        Type.Integer({
+          description: `Maximum live model calls started across this run; replay hits are excluded; clamped to ${WORKFLOW_MAX_AGENTS_MIN}-${WORKFLOW_MAX_AGENTS_MAX}`,
+        }),
+      ),
+      agentTimeoutMs: Type.Optional(
+        Type.Integer({
+          description: `Maximum live duration per agent in milliseconds; clamped to ${WORKFLOW_AGENT_TIMEOUT_MIN_MS}-${WORKFLOW_AGENT_TIMEOUT_MAX_MS}`,
+        }),
+      ),
+      agentRetries: Type.Optional(
+        Type.Integer({
+          description: `Retries per agent for classified transient provider failures; clamped to ${WORKFLOW_AGENT_RETRIES_MIN}-${WORKFLOW_AGENT_RETRIES_MAX}`,
+        }),
+      ),
+      autoResumeOnUsageLimit: Type.Optional(
+        Type.Boolean({ description: "For a background run, opt into bounded automatic resume after a recognized provider usage limit" }),
+      ),
+      usageLimitMaxAttempts: Type.Optional(
+        Type.Integer({
+          minimum: WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN,
+          maximum: WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+          description: "Maximum total run attempts in one automatic provider-limit resume chain",
+        }),
+      ),
+      usageLimitMaxDelayMs: Type.Optional(
+        Type.Integer({
+          minimum: WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+          maximum: WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS,
+          description: "Maximum delay accepted from a provider reset hint before automatic resume",
+        }),
+      ),
       budget: Type.Optional(
         Type.Integer({
           minimum: WORKFLOW_BUDGET_MIN,
@@ -622,15 +809,20 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       ),
       perf: Type.Optional(Type.Boolean({ description: "Include workflow performance timing aggregates in the result details" })),
       resumeFromRunId: Type.Optional(Type.String({ minLength: 1, description: "Workflow run id to resume from by replaying matching completed agent results" })),
+      resumeEditedWorkflow: Type.Optional(
+        Type.Boolean({ description: "With resumeFromRunId, ignore only workflow-source fingerprint changes while retaining all other replay checks" }),
+      ),
+      background: Type.Optional(Type.Boolean({ description: "Return a durable run ID immediately and deliver completion to this conversation later" })),
     }),
     renderCall(args, theme) {
       const suffix = args.args ? ` ${theme.fg("dim", args.args)}` : "";
+      const background = args.background ? ` ${theme.fg("dim", "(background)")}` : "";
       if (args.name?.trim()) {
-        return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name.trim())}${suffix}`, 0, 0);
+        return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name.trim())}${background}${suffix}`, 0, 0);
       }
       const preview = compactInlinePreview(args.script);
       const previewSuffix = preview ? ` ${theme.fg("dim", preview)}` : "";
-      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", "inline")}${suffix}${previewSuffix}`, 0, 0);
+      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", "inline")}${background}${suffix}${previewSuffix}`, 0, 0);
     },
     renderResult(result, { expanded, isPartial }, theme) {
       if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
@@ -655,18 +847,35 @@ export default function workflowEngine(pi: ExtensionAPI): void {
           details: { error: "invalid_resume_from_run_id" },
         };
       }
+      if (params.resumeEditedWorkflow && !resumeFromRunId) {
+        return {
+          content: [{ type: "text", text: "resumeEditedWorkflow requires resumeFromRunId." }],
+          details: { error: "invalid_edited_workflow_resume" },
+        };
+      }
+      if (params.background) {
+        const unavailable = backgroundUnavailableResult(ctx.mode);
+        if (unavailable) return unavailable;
+      }
 
-      const runOptions: WorkflowRunOptions = {
-        inspect: ctx.hasUI,
+      const runOptions = resolveWorkflowRunOptions({
+        inspect: ctx.hasUI && ctx.mode === "tui",
         concurrency: params.concurrency,
         parallelSubmissionLimit: params.parallelSubmissionLimit,
+        maxAgents: params.maxAgents,
+        agentTimeoutMs: params.agentTimeoutMs,
+        agentRetries: params.agentRetries,
+        autoResumeOnUsageLimit: params.autoResumeOnUsageLimit,
+        usageLimitMaxAttempts: params.usageLimitMaxAttempts,
+        usageLimitMaxDelayMs: params.usageLimitMaxDelayMs,
         budget: params.budget,
         perf: params.perf,
         resumeFromRunId,
+        resumeEditedWorkflow: params.resumeEditedWorkflow,
         signal,
-      };
+      });
       const perfRecorder = await createInvocationPerf(runOptions);
-      let mod: WorkflowModule;
+      let mod: LoadedWorkflow;
       let resultName: string;
 
       if (request.kind === "named") {
@@ -693,45 +902,41 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         resultName = mod.meta.name;
       }
 
-      const { runWorkflow } = await loadEngine();
-      let perfSnapshot: PerfSnapshot | undefined;
-      let usageSnapshot: WorkflowUsageSnapshot | undefined;
-      let runMetadata: WorkflowRunMetadata | undefined;
-      let liveInspection: ActiveWorkflowInspection | undefined;
       const resultArgs = params.args ?? "";
-      const result = await runWorkflow(ctx, mod, resultArgs, {
-        ...runOptions,
-        perf: runOptions.perf ?? perfRecorder !== undefined,
-        perfRecorder,
-        resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
-        onProgressSource(source) {
-          if (source) {
-            liveInspection = bindActiveWorkflowInspection(resultName, resultArgs, source);
-            activeWorkflowInspection = liveInspection;
-          } else if (activeWorkflowInspection === liveInspection) {
-            activeWorkflowInspection = undefined;
-            liveInspection = undefined;
-          }
-        },
-        onPerfSnapshot: (snapshot) => {
-          perfSnapshot = snapshot;
-        },
-        onUsageSnapshot: (snapshot) => {
-          usageSnapshot = snapshot;
-        },
-        onRunMetadata: (metadata) => {
-          runMetadata = metadata;
-        },
-        onProgressSnapshot: (snapshot) => {
-          // Record the run so /workflow:inspector can reopen it — tool-invoked (dynamax) runs were
-          // previously uninspectable, unlike the /workflow command path.
-          lastWorkflowInspection = { name: resultName, args: resultArgs, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
-        },
-      });
-      const perf = compactPerfSnapshot(perfSnapshot);
+      if (params.background) {
+        return await startBackgroundWorkflowTool({
+          coordinator: backgroundWorkflows,
+          ctx,
+          name: resultName,
+          options: runOptions,
+          async execute(backgroundCtx, backgroundOptions) {
+            const execution = await executeResolvedWorkflow(
+              pi,
+              backgroundCtx,
+              resultName,
+              mod,
+              resultArgs,
+              backgroundOptions,
+              perfRecorder,
+            );
+            reviewSessions.remember(ctx, execution, backgroundOptions);
+          },
+        });
+      }
+      const execution = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, runOptions, perfRecorder);
+      reviewSessions.remember(ctx, execution, runOptions);
       return {
-        content: [{ type: "text", text: formatMessageContent(resultName, result, usageSnapshot, perf, runMetadata) }],
-        details: workflowEnvelope(resultName, result, usageSnapshot, perf, runMetadata),
+        content: [{
+          type: "text",
+          text: formatMessageContent(
+            resultName,
+            execution.envelope.result,
+            execution.envelope.usage,
+            execution.envelope.perf,
+            execution.metadata,
+          ),
+        }],
+        details: execution.envelope,
       };
     },
   });