pi-workflow-engine 1.0.0 → 1.2.0

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

@@ -4,11 +4,19 @@ import { getSelectListTheme, keyText, VERSION, type ExtensionAPI, type Extension
 import type { AutocompleteItem, SelectItem } from "@earendil-works/pi-tui";
 import type { WorkflowProgressSnapshot } from "./src/progress-types.ts";
 import type { WorkflowRunState } from "./src/workflow-run-record.ts";
-import { WORKFLOW_TOOL_NAME, type LoadedWorkflow, type WorkflowModule, type WorkflowProgressSource, type WorkflowRef } from "./src/types.ts";
+import {
+  WORKFLOW_TOOL_NAME,
+  type LoadedWorkflow,
+  type WorkflowModule,
+  type WorkflowProgressSource,
+  type WorkflowRef,
+  type WorkflowRunMetadata,
+} from "./src/types.ts";
 import { showWorkflowInspector } from "./src/ui/workflow-inspector.ts";
 import { WorkflowPicker } from "./src/ui/workflow-picker.ts";
 import type { PerfSink } from "./src/perf.ts";
-import { ADAPTIVE_WORKFLOW_GUIDANCE, registerDynamax } from "./src/dynamax.ts";
+import type { DiscoverWorkflowsOptions } from "./src/discovery.ts";
+import { registerDynamax, resolveTurnBudget, type DynamaxHandle } 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";
@@ -32,7 +40,7 @@ import {
   WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
 } from "./src/options.ts";
 import { executeWorkflowInvocation, type WorkflowResultEnvelope } from "./src/workflow-execution.ts";
-import { formatWorkflowResultForContext } from "./src/workflow-result-context.ts";
+import { formatWorkflowResultForContext, formatWorkflowRunFileLines, formatWorkflowRunLine } from "./src/workflow-result-context.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";
@@ -40,13 +48,25 @@ import { registerWorkflowRunCommand, WorkflowRunController } from "./src/workflo
 import { completeCurrentArgument, splitArgumentPrefix } from "./src/command-completions.ts";
 import { assertSupportedPiVersion } from "./src/pi-compat.ts";
 import { formatWorkflowInspection, workflowInspectionSnapshot } from "./src/ui/workflow-format.ts";
+import { workflowUsageForPi, type WorkflowUsageSnapshot } from "./src/usage.ts";
+import { unknownErrorMessage } from "./src/unknown-error.ts";
+import { createHostToolBridge } from "./src/host-tools.ts";
+import { appendSectionToForcedPrompt } from "./src/prompt-sections.ts";
+import { WORKFLOWS_SECTION, WorkflowCatalogPrompt } from "./src/workflow-catalog.ts";
+import { registerWorkflowSizeCommand, resolveWorkflowSize, workflowSettingsPaths } from "./src/workflow-settings.ts";
+import { isRecord } from "./src/guards.ts";
+import { INVALID_WORKFLOW_INVOCATION_MESSAGE, normalizeWorkflowToolRequest, workflowToolReach } from "./src/workflow-tool-request.ts";
+import { workflowArgsText } from "./src/workflow-input.ts";
 
 /** Extension root (this file lives in <repo>/.pi/extensions/pi-workflow-engine/index.ts). */
 const EXTENSION_DIR = fileURLToPath(new URL(".", import.meta.url));
+/** The package's authoring skill, named by path so the guideline still resolves when skills are filtered out. */
+const WORKFLOW_AUTHORING_SKILL_PATH = fileURLToPath(new URL("../../../skills/workflow-authoring/SKILL.md", import.meta.url));
 
 type DiscoveryModule = typeof import("./src/discovery.ts");
 type EngineModule = typeof import("./src/engine.ts");
 type InlineWorkflowModule = typeof import("./src/inline-workflow.ts");
+type WorkflowScriptFileModule = typeof import("./src/workflow-script-file.ts");
 
 async function loadDiscovery(): Promise<DiscoveryModule> {
   return await import("./src/discovery.ts");
@@ -60,18 +80,47 @@ async function loadInlineWorkflow(): Promise<InlineWorkflowModule> {
   return await import("./src/inline-workflow.ts");
 }
 
+async function loadWorkflowScriptFile(): Promise<WorkflowScriptFileModule> {
+  return await import("./src/workflow-script-file.ts");
+}
+
 async function createInvocationPerf(options: ResolvedWorkflowRunOptions): Promise<PerfSink | undefined> {
   if (!options.perf) return undefined;
   const { createPerfRecorder } = await import("./src/perf.ts");
   return createPerfRecorder(true);
 }
 
+/** What workflow discovery reads from a session: its cwd, and whether its project's saved scripts may load. */
+export type WorkflowDiscoveryContext = Pick<ExtensionContext, "cwd" | "isProjectTrusted">;
+
+/** Project `.pi/workflows` scripts load only in a project pi trusts, like pi's own project resources. */
+function projectWorkflowDir(ctx: WorkflowDiscoveryContext): string | undefined {
+  return ctx.isProjectTrusted() ? ctx.cwd : undefined;
+}
+
+/** Every workflow a session can run, with the project-trust gate applied in this one place. */
+async function discoverForSession(
+  ctx: WorkflowDiscoveryContext,
+  options: Omit<DiscoverWorkflowsOptions, "projectDir"> = {},
+): Promise<Map<string, LoadedWorkflow>> {
+  const { discoverWorkflows } = await loadDiscovery();
+  return await discoverWorkflows(EXTENSION_DIR, { ...options, projectDir: projectWorkflowDir(ctx) });
+}
+
 /**
- * Resolve an `api.workflow()` reference to a registered workflow module. Throws on an unknown name.
+ * Resolve an `api.workflow()` reference: a registered workflow by name, or an inline-format script file
+ * via `{ scriptPath }` relative to the cwd. Throws on an unknown name, an unreadable scriptPath, or a
+ * compile error.
  */
-export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<LoadedWorkflow> {
-  const { discoverWorkflows } = await loadDiscovery();
-  const workflows = await discoverWorkflows(EXTENSION_DIR, { perf });
+export async function resolveWorkflowRef(ctx: WorkflowDiscoveryContext, ref: WorkflowRef, perf?: PerfSink): Promise<LoadedWorkflow> {
+  if (typeof ref !== "string") {
+    // Inline scripts are untyped, so check the shape the type promises.
+    const scriptPath: unknown = isRecord(ref) ? ref.scriptPath : undefined;
+    if (typeof scriptPath !== "string") throw new Error("workflow() expects a workflow name or { scriptPath }");
+    const { compileWorkflowScriptFile } = await loadWorkflowScriptFile();
+    return await compileWorkflowScriptFile(ctx.cwd, scriptPath);
+  }
+  const workflows = await discoverForSession(ctx, { perf });
   const mod = workflows.get(ref);
   if (!mod) {
     const available = [...workflows.keys()].join(", ") || "(none)";
@@ -86,7 +135,7 @@ const AUTHOR_TEMP_WORKFLOW_DESCRIPTION = "Ask the host agent to author and run a
 
 const WORKFLOW_OPTION_COMPLETIONS = [
   { value: "--inspect", description: "Open the live workflow inspector" },
-  { value: "--refresh", description: "Refresh dynamic workflow discovery" },
+  { value: "--refresh", description: "Reload .ts drop-in workflows" },
   { value: "--perf", description: "Collect workflow performance metrics" },
   { value: "--result-viewer", description: "Open supported result viewers" },
   { value: "--no-result-viewer", description: "Skip supported result viewers" },
@@ -100,11 +149,12 @@ const WORKFLOW_OPTION_COMPLETIONS = [
   { value: "--resume=", description: "Resume from a retained workflow run ID" },
 ] as const;
 
-async function workflowArgumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+/** Completions get no context, so the project's scripts come from the active session's tracked dir. */
+async function workflowArgumentCompletions(argumentPrefix: string, projectDir: string | undefined): Promise<AutocompleteItem[] | null> {
   const parts = splitArgumentPrefix(argumentPrefix);
   if (parts.completed.length === 0) {
     const { discoverWorkflows } = await loadDiscovery();
-    const workflows = await discoverWorkflows(EXTENSION_DIR);
+    const workflows = await discoverWorkflows(EXTENSION_DIR, { projectDir });
     return completeCurrentArgument(
       argumentPrefix,
       [...workflows.values()].map((workflow) => ({
@@ -116,6 +166,21 @@ async function workflowArgumentCompletions(argumentPrefix: string): Promise<Auto
   return completeCurrentArgument(argumentPrefix, WORKFLOW_OPTION_COMPLETIONS);
 }
 
+/**
+ * The active session's trusted project dir, kept for surfaces pi calls without a context. Session
+ * replacement invalidates a context, so only this value is kept.
+ */
+function trackProjectWorkflowDir(pi: ExtensionAPI): () => string | undefined {
+  let projectDir: string | undefined;
+  pi.on("session_start", (_event, ctx) => {
+    projectDir = projectWorkflowDir(ctx);
+  });
+  pi.on("session_shutdown", () => {
+    projectDir = undefined;
+  });
+  return () => projectDir;
+}
+
 /** Registered workflows in discovery order (built-ins first), then the author option. */
 async function selectWorkflowValue(workflows: ReadonlyMap<string, WorkflowModule>, ctx: ExtensionCommandContext): Promise<string | undefined> {
   const workflowItems: SelectItem[] = [...workflows.values()].map((workflow) => ({
@@ -149,6 +214,7 @@ export interface ActiveWorkflowInspection {
   readonly startedAt: number;
   readonly snapshot: () => WorkflowProgressSnapshot;
   readonly state?: () => WorkflowRunState;
+  readonly skipAgent?: (agentId: number) => boolean;
 }
 
 interface SessionWorkflowInspections {
@@ -163,7 +229,9 @@ export async function openWorkflowInspector(ctx: ExtensionContext, inspection: L
     ctx.ui.notify(formatWorkflowInspection(inspection), "info");
     return;
   }
-  await showWorkflowInspector(ctx.ui, () => workflowInspectionSnapshot(inspection), () => ({ state: inspection.state?.() }));
+  // Only a live inspection can skip agents; a finished one is a snapshot.
+  const controls = "skipAgent" in inspection ? { skipAgent: inspection.skipAgent } : undefined;
+  await showWorkflowInspector(ctx.ui, () => workflowInspectionSnapshot(inspection), () => ({ state: inspection.state?.() }), controls);
 }
 
 function workflowInspectionState(pi: ExtensionAPI, ctx: ExtensionContext): SessionWorkflowInspections {
@@ -186,7 +254,7 @@ async function openAvailableWorkflowInspector(pi: ExtensionAPI, ctx: ExtensionCo
 }
 
 function bindActiveWorkflowInspection(name: string, args: string, source: WorkflowProgressSource): ActiveWorkflowInspection {
-  return { name, args, startedAt: Date.now(), snapshot: () => source.snapshot(), state: source.state };
+  return { name, args, startedAt: Date.now(), snapshot: () => source.snapshot(), state: source.state, skipAgent: source.skipAgent };
 }
 
 export function buildTemporaryWorkflowAuthorPrompt(brief: string): string {
@@ -195,52 +263,53 @@ export function buildTemporaryWorkflowAuthorPrompt(brief: string): string {
 User brief:
 ${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 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}
+Use the workflow tool with a script argument, not a saved workflow name, and read the workflow-authoring skill before writing the script.
 Do not edit files unless the user explicitly requested edits.`;
 }
 
-export interface WorkflowToolRequestParams {
-  readonly name?: string;
-  readonly script?: string;
-  readonly resumeFromRunId?: string;
-  readonly background?: boolean;
-}
-
-export type WorkflowToolRequest =
-  | { readonly kind: "named"; readonly name: string }
-  | { readonly kind: "inline"; readonly script: string }
-  | { readonly kind: "error"; readonly error: "invalid_workflow_invocation"; readonly message: string };
-
-export interface WorkflowToolErrorResult {
+export interface WorkflowToolErrorResult<TDetails = WorkflowToolErrorDetails> {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
-  readonly details: { readonly error: "invalid_workflow_invocation" } | { readonly error: "inline_compile_error"; readonly message: string };
+  readonly details: TDetails;
+  /** The model sees a failed call while the renderer still reads `details`. */
+  readonly isError: true;
 }
 
-const INVALID_WORKFLOW_INVOCATION_MESSAGE = "Provide exactly one workflow name or inline workflow script.";
+type WorkflowToolErrorDetails =
+  | { readonly error: "invalid_workflow_invocation" }
+  | { readonly error: "inline_compile_error"; readonly message: string }
+  | { readonly error: "invalid_script_path"; readonly message: string };
 
-export function normalizeWorkflowToolRequest(params: WorkflowToolRequestParams): WorkflowToolRequest {
-  const name = params.name?.trim() ?? "";
-  const script = params.script?.trim() ?? "";
-  const hasName = name.length > 0;
-  const hasScript = script.length > 0;
-  if (hasName === hasScript) return { kind: "error", error: "invalid_workflow_invocation", message: INVALID_WORKFLOW_INVOCATION_MESSAGE };
-  return hasName ? { kind: "named", name } : { kind: "inline", script };
+function workflowToolError<TDetails>(text: string, details: TDetails): WorkflowToolErrorResult<TDetails> {
+  return { content: [{ type: "text", text }], details, isError: true };
 }
 
 export function invalidWorkflowInvocationResult(): WorkflowToolErrorResult {
-  return { content: [{ type: "text", text: INVALID_WORKFLOW_INVOCATION_MESSAGE }], details: { error: "invalid_workflow_invocation" } };
+  return workflowToolError(INVALID_WORKFLOW_INVOCATION_MESSAGE, { error: "invalid_workflow_invocation" });
 }
 
 export function inlineCompileErrorResult(message: string): WorkflowToolErrorResult {
-  return { content: [{ type: "text", text: `Inline workflow did not compile: ${message}` }], details: { error: "inline_compile_error", message } };
+  return workflowToolError(`Inline workflow did not compile: ${message}`, { error: "inline_compile_error", message });
+}
+
+function invalidScriptPathResult(message: string): WorkflowToolErrorResult {
+  return workflowToolError(message, { error: "invalid_script_path", message });
+}
+
+/** Compile the tool's inline `script` or `scriptPath` file, shaping contract failures as tool errors. */
+async function compileInlineToolWorkflow(
+  cwd: string,
+  request: { readonly kind: "inline"; readonly script: string } | { readonly kind: "script-path"; readonly scriptPath: string },
+): Promise<LoadedWorkflow | WorkflowToolErrorResult> {
+  const [inline, scriptFile] = await Promise.all([loadInlineWorkflow(), loadWorkflowScriptFile()]);
+  try {
+    return request.kind === "inline"
+      ? inline.compileInlineWorkflow(request.script)
+      : await scriptFile.compileWorkflowScriptFile(cwd, request.scriptPath);
+  } catch (error) {
+    if (error instanceof scriptFile.WorkflowScriptPathError) return invalidScriptPathResult(error.message);
+    if (error instanceof inline.InlineWorkflowCompileError) return inlineCompileErrorResult(error.message);
+    throw error;
+  }
 }
 
 export type WorkflowPickerSelection =
@@ -285,27 +354,29 @@ export async function sendWorkflowResult(
   await reviewSessions.present(ctx, retained, options);
 }
 
+/** `input` is a slash command's argument string, or a tool call's string or JSON value. */
 async function executeResolvedWorkflow(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   name: string,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   options: ResolvedWorkflowRunOptions,
   perfRecorder?: PerfSink,
 ): Promise<WorkflowResultEnvelope> {
   const { runResolvedWorkflow } = await loadEngine();
   let liveInspection: ActiveWorkflowInspection | undefined;
   const inspections = workflowInspectionState(pi, ctx);
+  const args = workflowArgsText(input);
   return await executeWorkflowInvocation({
     ctx,
     name,
     mod,
-    args,
+    args: input,
     options,
     perfRecorder,
     runResolvedWorkflow,
-    resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
+    resolveWorkflow: (ref) => resolveWorkflowRef(ctx, ref, perfRecorder),
     onProgressSource(source) {
       if (source) {
         liveInspection = bindActiveWorkflowInspection(name, args, source);
@@ -348,10 +419,10 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
   assertSupportedPiVersion(VERSION);
   const reviewSessions = createReviewSessionCoordinator(pi);
   const backgroundWorkflows = new BackgroundWorkflowCoordinator(pi);
+  const sessionProjectDir = trackProjectWorkflowDir(pi);
   const workflowRuns = new WorkflowRunController(backgroundWorkflows, {
-    async resolveWorkflow(name) {
-      const { discoverWorkflows } = await loadDiscovery();
-      return (await discoverWorkflows(EXTENSION_DIR)).get(name);
+    async resolveWorkflow(name, ctx) {
+      return (await discoverForSession(ctx)).get(name);
     },
     async execute(ctx, name, workflow, options) {
       const perfRecorder = await createInvocationPerf(options);
@@ -360,6 +431,15 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
     },
   });
   backgroundWorkflows.onRunSettled((ctx, runId) => workflowRuns.runSettled(ctx, runId));
+  const workflowCatalog = new WorkflowCatalogPrompt({
+    async discover(ctx) {
+      return [...(await discoverForSession(ctx)).values()].map((workflow) => workflow.meta);
+    },
+    size: (ctx) => resolveWorkflowSize(workflowSettingsPaths(ctx.cwd)).size,
+  });
+  // Before Dynamax, so the stable catalog section precedes the per-turn opt-in section.
+  registerWorkflowCatalog(pi, workflowCatalog);
+  registerWorkflowSizeCommand(pi, (ctx) => workflowCatalog.forget(ctx));
   const dynamax = registerDynamax(pi, shortcuts, { openInspector: (ctx) => openAvailableWorkflowInspector(pi, ctx) });
   registerWorkflowModelProfileCommand(pi);
   registerWorkflowRunCommand(pi, workflowRuns);
@@ -420,7 +500,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,
+    getArgumentCompletions: (argumentPrefix) => workflowArgumentCompletions(argumentPrefix, sessionProjectDir()),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const invocation = parseWorkflowInvocation(args);
       if (invocation.optionErrors.length > 0) {
@@ -429,8 +509,7 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       }
       const options = resolveWorkflowRunOptions(invocation.options);
       const perfRecorder = await createInvocationPerf(options);
-      const { discoverWorkflows } = await loadDiscovery();
-      const workflows = await discoverWorkflows(EXTENSION_DIR, { refresh: invocation.refreshDiscovery, perf: perfRecorder });
+      const workflows = await discoverForSession(ctx, { refresh: invocation.refreshDiscovery, perf: perfRecorder });
       const available = [...workflows.keys()].join(", ") || "(none)";
       if (!invocation.name && !ctx.hasUI) {
         ctx.ui.notify(`Usage: /workflow <name> [args]. Available: ${available}`, "warning");
@@ -460,7 +539,22 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
     },
   });
 
-  registerWorkflowTool(pi, reviewSessions, backgroundWorkflows, shortcuts);
+  registerWorkflowTool(pi, reviewSessions, backgroundWorkflows, shortcuts, dynamax);
+}
+
+/** Add the `<workflows>` catalog to every run that can call the workflow tool. */
+function registerWorkflowCatalog(pi: ExtensionAPI, catalog: WorkflowCatalogPrompt): void {
+  pi.on("session_start", (_event, ctx) => catalog.forget(ctx));
+  pi.on("session_shutdown", (_event, ctx) => catalog.forget(ctx));
+  pi.on("before_agent_start", async (event, ctx) => {
+    const options = event.systemPromptOptions;
+    // Subagent sessions withhold the workflow tool, so they skip the catalog as well.
+    if (!options.selectedTools.includes(WORKFLOW_TOOL_NAME)) return undefined;
+    const text = await catalog.section(ctx);
+    if (text === undefined) return undefined;
+    options.sections[WORKFLOWS_SECTION] = text;
+    return appendSectionToForcedPrompt(options, WORKFLOWS_SECTION);
+  });
 }
 
 /** Result footers advertise the configured triage and inspector shortcuts and pi's current expand key, read at render time. */
@@ -478,6 +572,7 @@ function registerWorkflowTool(
   reviewSessions: ReviewSessionCoordinator,
   backgroundWorkflows: BackgroundWorkflowCoordinator,
   shortcuts: DynamaxShortcuts,
+  dynamax: DynamaxHandle,
 ): void {
   pi.registerTool({
     name: WORKFLOW_TOOL_NAME,
@@ -485,27 +580,38 @@ function registerWorkflowTool(
     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), synchronously by default or explicitly in the background.",
     promptSnippet: "Run an existing named workflow or an inline one-off workflow script",
+    // Like codemode itself, an orchestrating tool stays a top-level model action: from a codemode script a
+    // run would lose its tool row, hit the script's output cap, and parallel runs would each get their own
+    // concurrency cap. It also stays declared under `codemode.mode: "only"`, which hides direct tools.
+    exposure: "model-only",
+    reachesTools: workflowToolReach,
     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.",
-      "Use workflow with `name` for existing registered workflows such as code-review, diagnose, refactor-scout, or perf-review.",
-      "Use workflow with `script` for a new one-off inline workflow; the script must start with `export const meta = { ... }` and default-export an async workflow function.",
-      "Inline workflow scripts must use the injected `Type` object for schemas and must not contain imports or dynamic import().",
-      "Inline scripts may compose registered workflows in-process via `api.workflow(\"<name>\", args)` (e.g. `await api.workflow(\"code-review\", \"HEAD~3\")`); it returns the sub-workflow's result and nests one level only.",
-      "Subagents receive no skills by default. In inline workflows, pass `skills: [\"skill-name\"]` per `agent()` call when the user asks for a skill or a stage should use one; grant only the needed skills.",
-      "Always pass a plain string as the first `api.agent()` argument; build prompts with template strings before calling agent().",
+      "Use workflow only when the user opted into workflow orchestration via `dynamax`, sticky `/workflow:dynamax`, an explicit request to run/author a workflow, or a command/skill instruction.",
+      `Before writing or editing an inline workflow script, read the workflow-authoring skill (${WORKFLOW_AUTHORING_SKILL_PATH}); it is the script API and pattern reference.`,
+      "Every workflow tool call must provide exactly one of `name`, `script`, or `scriptPath`.",
+      "Inline workflow scripts must use the injected `Type` global for schemas and must not contain imports or dynamic import().",
+      "Set `profile: \"small\"`, `\"medium\"`, or `\"big\"` on every `api.agent()` call so the user's central model routes apply; use `model`/`thinkingLevel` only for an intentional override.",
       "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,
+      "Host MCP tools reach subagents only in synchronous workflow tool runs, never in background runs.",
       "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({
-      name: Type.Optional(Type.String({ description: "Workflow name, e.g. code-review. Provide exactly one of name or script." })),
-      script: Type.Optional(Type.String({ description: "Inline workflow script. Provide exactly one of script or name." })),
-      args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
+      name: Type.Optional(Type.String({ description: "Workflow name, e.g. code-review. Provide exactly one of name, script, or scriptPath." })),
+      script: Type.Optional(Type.String({ description: "Inline workflow script. Provide exactly one of name, script, or scriptPath." })),
+      scriptPath: Type.Optional(
+        Type.String({
+          description:
+            "Path, relative to the working directory, of a file holding an inline workflow script. To iterate, edit in place the persisted .pi/.workflow-runs/<runId>.script.js a result names and rerun it here with resumeFromRunId, which accepts the edits as with resumeEditedWorkflow; editing any other copy in the repository, or a .pi/workflows script, changes repository state, so shared read-only agents rerun live. Provide exactly one of name, script, or scriptPath.",
+        }),
+      ),
+      args: Type.Optional(
+        Type.Unknown({
+          description:
+            "Arguments for the workflow: a string (e.g. target or focus) or any JSON value. The workflow reads the value as `api.input` and its text (JSON for non-strings) as `api.args`.",
+        }),
+      ),
       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(
@@ -565,21 +671,23 @@ function registerWorkflowTool(
       if (request.kind === "error") return invalidWorkflowInvocationResult();
       const resumeFromRunId = params.resumeFromRunId?.trim();
       if (params.resumeFromRunId !== undefined && resumeFromRunId === "") {
-        return {
-          content: [{ type: "text", text: "resumeFromRunId must be non-empty." }],
-          details: { error: "invalid_resume_from_run_id" },
-        };
+        return workflowToolError("resumeFromRunId must be non-empty.", { error: "invalid_resume_from_run_id" });
       }
       if (params.resumeEditedWorkflow && !resumeFromRunId) {
-        return {
-          content: [{ type: "text", text: "resumeEditedWorkflow requires resumeFromRunId." }],
-          details: { error: "invalid_edited_workflow_resume" },
-        };
+        return workflowToolError("resumeEditedWorkflow requires resumeFromRunId.", { error: "invalid_edited_workflow_resume" });
       }
       if (params.background) {
         const unavailable = backgroundUnavailableResult(ctx.mode);
         if (unavailable) return unavailable;
       }
+      const turnBudget = dynamax.turnBudget(ctx);
+      const budget = resolveTurnBudget(params.budget, turnBudget, { min: WORKFLOW_BUDGET_MIN, max: WORKFLOW_BUDGET_MAX });
+      if (budget.kind === "spent") {
+        return workflowToolError(
+          `The user's +${budget.total} output-token budget for this turn is spent by its earlier workflow runs. Do not start another workflow this turn unless the user raises the budget.`,
+          { error: "turn_budget_spent", total: budget.total },
+        );
+      }
 
       const runOptions = resolveWorkflowRunOptions({
         concurrency: params.concurrency,
@@ -590,10 +698,11 @@ function registerWorkflowTool(
         autoResumeOnUsageLimit: params.autoResumeOnUsageLimit,
         usageLimitMaxAttempts: params.usageLimitMaxAttempts,
         usageLimitMaxDelayMs: params.usageLimitMaxDelayMs,
-        budget: params.budget,
+        budget: budget.budget,
         perf: params.perf,
         resumeFromRunId,
-        resumeEditedWorkflow: params.resumeEditedWorkflow,
+        // Rerunning an edited script file is the point of scriptPath; each call's own replay identity still guards reuse.
+        resumeEditedWorkflow: params.resumeEditedWorkflow === true || request.kind === "script-path",
         signal,
       });
       const perfRecorder = await createInvocationPerf(runOptions);
@@ -601,36 +710,31 @@ function registerWorkflowTool(
       let resultName: string;
 
       if (request.kind === "named") {
-        const { discoverWorkflows } = await loadDiscovery();
-        const workflows = await discoverWorkflows(EXTENSION_DIR, { perf: perfRecorder });
+        const workflows = await discoverForSession(ctx, { perf: perfRecorder });
         const named = workflows.get(request.name);
         if (!named) {
           const available = [...workflows.keys()].join(", ") || "(none)";
-          return {
-            content: [{ type: "text", text: `Unknown workflow "${request.name}". Available: ${available}` }],
-            details: { error: "unknown_workflow", available },
-          };
+          return workflowToolError(`Unknown workflow "${request.name}". Available: ${available}`, { error: "unknown_workflow", available });
         }
         mod = named;
         resultName = request.name;
       } else {
-        const inline = await loadInlineWorkflow();
-        try {
-          mod = inline.compileInlineWorkflow(request.script);
-        } catch (error) {
-          if (error instanceof inline.InlineWorkflowCompileError) return inlineCompileErrorResult(error.message);
-          throw error;
-        }
+        const compiled = await compileInlineToolWorkflow(ctx.cwd, request);
+        if ("isError" in compiled) return compiled;
+        mod = compiled;
         resultName = mod.meta.name;
       }
 
-      const resultArgs = params.args ?? "";
+      // Omitted args match a slash command without arguments; any other value, null included, is kept verbatim.
+      const resultArgs: unknown = params.args === undefined ? "" : params.args;
       if (params.background) {
         return await startBackgroundWorkflowTool({
           coordinator: backgroundWorkflows,
           ctx,
           name: resultName,
           options: runOptions,
+          // Under Dynamax the agent is orchestrating, so its completion starts a turn to act on the result.
+          wakeOnComplete: dynamax.isActive(ctx),
           async execute(backgroundCtx, backgroundOptions) {
             const envelope = await executeResolvedWorkflow(
               pi,
@@ -647,11 +751,49 @@ function registerWorkflowTool(
       }
       // Marks the tool row as running (rendered `● running <name>`) until the envelope replaces it.
       onUpdate?.({ content: [{ type: "text", text: `Running workflow ${resultName}.` }], details: { state: "running", name: resultName } });
-      const envelope = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, runOptions, perfRecorder);
+      // Only this synchronous path may bridge host MCP tools: executeTool ends with the tool call.
+      const hostTools = createHostToolBridge(() => pi.getAllTools(), ctx);
+      // Keep the latest usage: a failed run still reports what its agents spent instead of dropping it with the error.
+      let spent: WorkflowUsageSnapshot | undefined;
+      const onUsageSnapshot = (snapshot: WorkflowUsageSnapshot) => {
+        spent = snapshot;
+        return runOptions.onUsageSnapshot?.(snapshot);
+      };
+      // A failed run still names its run, script and journal, so the host can fix the script and resume.
+      let run: WorkflowRunMetadata | undefined;
+      const onRunMetadata = (metadata: WorkflowRunMetadata) => {
+        run = metadata;
+        return runOptions.onRunMetadata?.(metadata);
+      };
+      let envelope: WorkflowResultEnvelope;
+      try {
+        envelope = await executeResolvedWorkflow(
+          pi,
+          ctx,
+          resultName,
+          mod,
+          resultArgs,
+          { ...runOptions, hostTools, onUsageSnapshot, onRunMetadata },
+          perfRecorder,
+        );
+      } catch (error) {
+        const message = unknownErrorMessage(error);
+        const lines = [`Workflow ${resultName} failed: ${message}`];
+        if (run) lines.push("", formatWorkflowRunLine(run), ...formatWorkflowRunFileLines(run.runId, run.scriptPath !== undefined));
+        return {
+          ...workflowToolError(lines.join("\n"), { error: "workflow_failed", name: resultName, message }),
+          usage: workflowUsageForPi(spent),
+        };
+      } finally {
+        // Only synchronous runs draw the turn pool down; a background run's spend lands after the turn.
+        turnBudget?.spend(spent?.totals.output ?? 0);
+      }
       reviewSessions.remember(ctx, envelope, runOptions);
       return {
         content: [{ type: "text", text: formatWorkflowResultForContext(envelope) }],
         details: envelope,
+        // pi counts tool-result usage toward the session cost; subagent spend was invisible there before.
+        usage: workflowUsageForPi(envelope.usage),
       };
     },
   });

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

@@ -49,16 +49,19 @@ export function dedupeCandidates<T extends IdentifiedAdvisoryCandidate>(candidat
     const key = candidateDedupKey(candidate);
     const previous = seen.get(key);
     if (!previous) seen.set(key, { ...candidate });
-    else {
-      previous.sourceCandidateIds = [...new Set([...previous.sourceCandidateIds, ...candidate.sourceCandidateIds])];
-      previous.locations = uniqueLocations([...previous.locations, ...candidate.locations]);
-      previous.impact = [...new Set([previous.impact, candidate.impact])].join("\n");
-      previous.discoveryEvidence = [...new Set([...(previous.discoveryEvidence ?? []), ...(candidate.discoveryEvidence ?? [])])];
-    }
+    else mergeCandidateInto(previous, candidate);
   }
   return [...seen.values()];
 }
 
+/** Fold a duplicate into the kept candidate, keeping every source id, location, impact, and piece of evidence. */
+export function mergeCandidateInto<T extends IdentifiedAdvisoryCandidate>(kept: T, duplicate: T): void {
+  kept.sourceCandidateIds = [...new Set([...kept.sourceCandidateIds, ...duplicate.sourceCandidateIds])];
+  kept.locations = uniqueLocations([...kept.locations, ...duplicate.locations]);
+  kept.impact = [...new Set([kept.impact, duplicate.impact])].join("\n");
+  kept.discoveryEvidence = [...new Set([...(kept.discoveryEvidence ?? []), ...(duplicate.discoveryEvidence ?? [])])];
+}
+
 export function uniqueLocations(locations: AdvisoryCandidate["locations"]): AdvisoryCandidate["locations"] {
   return [...new Map(locations.map((location) => [JSON.stringify(location), location])).values()];
 }