pi-workflow-engine 0.11.0 → 0.12.0

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

@@ -1,14 +1,16 @@
 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 { 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.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 { 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 { ADAPTIVE_WORKFLOW_GUIDANCE, dynamaxSessionKey, registerDynamax } from "./src/dynamax.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 {
@@ -18,20 +20,36 @@ import {
 } from "./src/ui/workflow-result-renderer.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.";
 }
 
@@ -117,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 {
@@ -217,20 +213,20 @@ export function getLastWorkflowInspection(): LastWorkflowInspection | undefined
   return latestWorkflowInspection;
 }
 
-export function getActiveWorkflowInspection(): ActiveWorkflowInspection | undefined {
-  return latestActiveWorkflowInspection;
-}
-
 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,
   );
 }
 
 function workflowInspectionState(pi: ExtensionAPI, ctx: ExtensionContext): SessionWorkflowInspections {
   const sessions = workflowInspections.get(pi) ?? new Map<string, SessionWorkflowInspections>();
-  const key = dynamaxSessionKey(ctx);
+  const key = sessionKey(ctx);
   const state = sessions.get(key) ?? {};
   sessions.set(key, state);
   workflowInspections.set(pi, sessions);
@@ -238,10 +234,6 @@ function workflowInspectionState(pi: ExtensionAPI, ctx: ExtensionContext): Sessi
 }
 
 async function openAvailableWorkflowInspector(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
-  if (!ctx.hasUI) {
-    ctx.ui.notify("Workflow inspector requires the TUI", "warning");
-    return;
-  }
   const state = workflowInspectionState(pi, ctx);
   const inspection = state.active ?? state.last;
   if (!inspection) {
@@ -251,11 +243,6 @@ async function openAvailableWorkflowInspector(pi: ExtensionAPI, ctx: ExtensionCo
   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() };
 }
@@ -283,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);
@@ -304,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;
@@ -332,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);
@@ -367,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 };
 }
 
@@ -395,7 +439,7 @@ ${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.
@@ -408,6 +452,7 @@ export interface WorkflowToolRequestParams {
   readonly name?: string;
   readonly script?: string;
   readonly resumeFromRunId?: string;
+  readonly background?: boolean;
 }
 
 export type WorkflowToolRequest =
@@ -570,10 +615,35 @@ function createReviewSessionCoordinator(pi: ExtensionAPI): ReviewSessionCoordina
 }
 
 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) });
-  pi.on("session_shutdown", (_event, ctx) => {
-    const key = dynamaxSessionKey(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);
   });
@@ -598,11 +668,13 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
   });
 
   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);
@@ -623,6 +695,7 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
   // /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) {
@@ -657,12 +730,20 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
     },
   });
 
-  // 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.",
@@ -676,6 +757,9 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       "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({
@@ -684,6 +768,38 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       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,
@@ -693,15 +809,20 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       ),
       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);
@@ -726,14 +847,31 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
           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 = resolveWorkflowRunOptions({
-        inspect: ctx.hasUI,
+        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);
@@ -765,6 +903,26 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       }
 
       const resultArgs = params.args ?? "";
+      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 {

package/.pi/extensions/pi-workflow-engine/src/advisory-schema.ts

@@ -59,12 +59,8 @@ export const AdvisoryReportWithStatsSchema = Type.Object({
   stats: Type.Optional(Type.Record(Type.String(), Type.Union([Type.String(), Type.Number()]))),
 });
 
-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/.pi/extensions/pi-workflow-engine/src/agent-attempt.ts

@@ -37,8 +37,9 @@ export async function executeAgentAttempt(input: {
   readonly label: string;
   readonly rowId: number;
   readonly tags: AgentRunTags;
+  readonly admitLiveAgent: () => void;
 }): Promise<AgentAttemptResult> {
-  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, tags } = input;
+  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, tags, admitLiveAgent } = input;
   let repositoryBefore: RepositoryResumeContext | undefined;
   let evidence: AgentReplayEvidence | undefined;
   if (isReplayEnabled(replay)) {
@@ -104,6 +105,7 @@ export async function executeAgentAttempt(input: {
     }
 
     assertWorkflowBudgetAvailable(rc.budget);
+    admitLiveAgent();
     const rawResult = await promptAgentSession({
       rc,
       handle,

package/.pi/extensions/pi-workflow-engine/src/agent-limits.ts

@@ -0,0 +1,35 @@
+import { throwIfAborted } from "./cancellation.ts";
+
+export class WorkflowAgentLimitError extends Error {
+  override readonly name = "WorkflowAgentLimitError";
+  readonly code = "WORKFLOW_AGENT_LIMIT_EXCEEDED";
+
+  constructor(readonly maxAgents: number) {
+    super(`Workflow live-agent limit of ${maxAgents} has been reached; no new model request was started.`);
+  }
+}
+
+export class WorkflowAgentTimeoutError extends Error {
+  override readonly name = "WorkflowAgentTimeoutError";
+  readonly code = "WORKFLOW_AGENT_TIMEOUT";
+
+  constructor(
+    readonly label: string,
+    readonly timeoutMs: number,
+  ) {
+    super(`Workflow agent "${label}" exceeded its ${timeoutMs}ms duration limit.`);
+  }
+}
+
+/** Shared run-level admission counter. Cache hits do not call admit(). */
+export class WorkflowAgentLimiter {
+  private admitted = 0;
+
+  constructor(readonly maxAgents: number) {}
+
+  admit(signal: AbortSignal | undefined): void {
+    throwIfAborted(signal);
+    if (this.admitted >= this.maxAgents) throw new WorkflowAgentLimitError(this.maxAgents);
+    this.admitted++;
+  }
+}