pi-workflow-engine 1.0.0 → 1.2.0

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

@@ -7,6 +7,7 @@ import { resolveWorkflowModelProfiles, type ResolvedWorkflowModelProfiles } from
 import { abortReason, isWorkflowPauseError, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
 import { createBudget } from "./budget.ts";
 import { runAgent, type AgentExecutionOptions, type RunContext } from "./agent-runner.ts";
+import { runClassifier } from "./classify.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, formatPerfSummary, type PerfSink } from "./perf.ts";
 import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.ts";
@@ -14,11 +15,12 @@ import {
   resolveWorkflowRunOptions,
   type ResolvedWorkflowRunOptions,
 } from "./options.ts";
-import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
+import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowMeta, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { showWorkflowInspector } from "./ui/workflow-inspector.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
 import { runFinalizers } from "./finalizers.ts";
+import { workflowArgsText, workflowInputPresent } from "./workflow-input.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   captureWorkflowResumeContext,
@@ -26,11 +28,14 @@ import {
 } from "./resume-context.ts";
 import {
   DurableWorkflowRun,
+  persistWorkflowRunScript,
   ProjectWorkflowRunStore,
   workflowRunRecordPath,
   type WorkflowRunStore,
 } from "./workflow-run-store.ts";
 import { createWorkflowRunRecord } from "./workflow-run-record.ts";
+import { canRelaunchWorkflowRun } from "./workflow-run-history.ts";
+import { sealWorkflowRunScript } from "./workflow-run-seal.ts";
 import {
   createProviderUsageLimitPauseRecord,
   WorkflowProviderUsageLimitError,
@@ -75,22 +80,23 @@ export interface WorkflowEngineDependencies {
 /**
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
+ * `input` is a slash command's argument string or a tool call's JSON value.
  */
 export async function runWorkflow(
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   options: WorkflowRunOptions = {},
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
-  return await runResolvedWorkflow(ctx, mod, args, resolveWorkflowRunOptions(options), dependencies);
+  return await runResolvedWorkflow(ctx, mod, input, resolveWorkflowRunOptions(options), dependencies);
 }
 
 /** Execute an options-normalized workflow without re-reading environment defaults. */
 export async function runResolvedWorkflow(
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   resolvedOptions: ResolvedWorkflowRunOptions,
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
@@ -106,16 +112,20 @@ export async function runResolvedWorkflow(
   const journalPath = workflowJournalPath(ctx.cwd, runId);
   const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
   const runStore = new ProjectWorkflowRunStore(ctx.cwd);
+  const script = await sealRunScript(ctx.cwd, runId, mod);
   let persistenceFailureReported = false;
+  const initialRecord = createWorkflowRunRecord({
+    runId,
+    workflow: mod,
+    options: resolvedOptions,
+    progress: progress.snapshot(),
+    argumentsPresent: workflowInputPresent(input),
+    scriptPersisted: script.path !== undefined,
+    scriptSeal: script.seal,
+  });
   const durableRun = new DurableWorkflowRun(
     runStore,
-    createWorkflowRunRecord({
-      runId,
-      workflow: mod,
-      options: resolvedOptions,
-      progress: progress.snapshot(),
-      argumentsPresent: args.length > 0,
-    }),
+    initialRecord,
     (error) => {
       if (persistenceFailureReported) return;
       persistenceFailureReported = true;
@@ -123,7 +133,11 @@ export async function runResolvedWorkflow(
     },
   );
   durableProgress = durableRun;
-  const progressSource = { snapshot: () => progress.snapshot(), state: () => durableRun.state };
+  const progressSource = {
+    snapshot: () => progress.snapshot(),
+    state: () => durableRun.state,
+    skipAgent: (agentId: number) => progress.skipAgent(agentId),
+  };
   const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
@@ -131,7 +145,7 @@ export async function runResolvedWorkflow(
   const workflowOutcome = await captureOutcome(async () => {
     await notifyLifecycleObserver(progress, "progress source callback", () => resolvedOptions.onProgressSource?.(progressSource));
     if (resolvedOptions.inspect && ctx.hasUI && ctx.mode === "tui") {
-      void showWorkflowInspector(ctx.ui, progressSource.snapshot, () => ({ state: progressSource.state() }))
+      void showWorkflowInspector(ctx.ui, progressSource.snapshot, () => ({ state: progressSource.state() }), progressSource)
         .catch((error: unknown) => {
           try {
             progress.log(`inspector failed: ${unknownErrorMessage(error)}`);
@@ -150,6 +164,7 @@ export async function runResolvedWorkflow(
         resumedFromRunId: resolvedOptions.resumeFromRunId,
         journalPath,
         recordPath: workflowRunRecordPath(ctx.cwd, runId),
+        ...(script.path === undefined ? {} : { scriptPath: script.path }),
       }),
     );
     progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
@@ -177,11 +192,13 @@ export async function runResolvedWorkflow(
       budget,
       journal,
       worktrees,
+      hostTools: resolvedOptions.hostTools,
+      classifierRoutes: new Map(),
     };
 
     // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
     return perf.time("workflow.total_ms", () =>
-      runWorkflowWithContext(rc, progress, mod, args, {
+      runWorkflowWithContext(rc, progress, mod, input, {
         abortController: runAbortController,
         submissionLimit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
         resolveWorkflow: resolvedOptions.resolveWorkflow,
@@ -222,7 +239,7 @@ export async function runResolvedWorkflow(
     durableRun.transition({
       state: "paused",
       progress: progress.snapshot(),
-      ...createProviderUsageLimitPauseRecord(pauseError, resolvedOptions, mod.source.kind === "file" && args.length === 0),
+      ...createProviderUsageLimitPauseRecord(pauseError, resolvedOptions, canRelaunchWorkflowRun(initialRecord)),
     });
   } else if (pauseError) {
     durableRun.transition({
@@ -244,6 +261,33 @@ export async function runResolvedWorkflow(
   throw outcome.error;
 }
 
+/**
+ * Seal a run whose code came from a script for this install, so a repository cannot ship a run record
+ * whose relaunch runs its own code. An inline run's script is also written beside its record; a saved
+ * script resolves again by name, and the seal pins the content that ran. A failed write or seal only
+ * costs the run its relaunch from `/workflow:runs`.
+ */
+async function sealRunScript(cwd: string, runId: string, mod: LoadedWorkflow): Promise<{ readonly path?: string; readonly seal?: string }> {
+  const { source } = mod;
+  const savedScript = source.kind === "file" && source.selfContained === true;
+  if (!savedScript && (source.kind !== "fingerprint" || mod.inlineScript === undefined)) return {};
+  let path: string | undefined;
+  if (mod.inlineScript !== undefined && source.kind === "fingerprint") {
+    try {
+      path = await persistWorkflowRunScript(cwd, runId, mod.inlineScript);
+    } catch (error) {
+      process.stderr.write(`[${mod.meta.name}] script persistence failed: ${unknownErrorMessage(error)}\n`);
+      return {};
+    }
+  }
+  try {
+    return { path, seal: await sealWorkflowRunScript(runId, source.fingerprint) };
+  } catch (error) {
+    process.stderr.write(`[${mod.meta.name}] script seal failed, so /workflow:runs cannot relaunch this run: ${unknownErrorMessage(error)}\n`);
+    return { path };
+  }
+}
+
 function backgroundPauseError(error: unknown, ...signals: Array<AbortSignal | undefined>): unknown {
   if (isWorkflowPauseError(error)) return error;
   for (const signal of signals) {
@@ -342,7 +386,7 @@ function createWorkflowAgent(
   function agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
   function agent(prompt: string, opts?: AgentOptions): Promise<string>;
   function agent(prompt: string, agentOpts?: AgentOptions): Promise<unknown> {
-    const scopedOptions = scope.agentOptions(agentOpts);
+    const scopedOptions = scope.agentOptions(withPhaseProfile(mod.meta, agentOpts));
     const executionOptions: AgentExecutionOptions =
       scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
         ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
@@ -352,6 +396,17 @@ function createWorkflowAgent(
   return agent;
 }
 
+/**
+ * Routing order is the agent's `model`, then its `profile`, then its declared phase's `profile`, then
+ * the host. Only an explicit `opts.phase` selects a phase profile: the global `phase()` is shared
+ * state that concurrent `parallel`/`pipeline` branches race on.
+ */
+function withPhaseProfile(meta: WorkflowMeta, opts: AgentOptions | undefined): AgentOptions | undefined {
+  if (opts?.phase === undefined || opts.model !== undefined || opts.profile !== undefined) return opts;
+  const profile = meta.phases?.find((phase) => phase.title === opts.phase)?.profile;
+  return profile === undefined ? opts : { ...opts, profile };
+}
+
 /**
  * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
  * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
@@ -361,10 +416,12 @@ export async function runWorkflowWithContext(
   rc: WorkflowRunContext,
   progress: WorkflowProgress,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   opts: WorkflowContextOptions,
 ): Promise<unknown> {
   const depth = opts.depth ?? 0;
+  // Converted before any agent runs, so an argument with no JSON form rejects the call up front.
+  const args = workflowArgsText(input);
   const scope = createWorkflowScope(progress, opts.progressPrefix ?? "", opts.progressNamespace);
   const resumeContext: AgentResumeBaseContext = {
     workflow: await captureWorkflowResumeContext(mod, rc.signal),
@@ -385,7 +442,8 @@ export async function runWorkflowWithContext(
           const childController = new AbortController();
           const unlink = linkAbortSignal(rc.signal, childController);
           try {
-            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childArgs ?? "", {
+            const childInput = childArgs === undefined ? "" : childArgs;
+            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childInput, {
               abortController: childController,
               submissionLimit: opts.submissionLimit,
               resolveWorkflow: opts.resolveWorkflow,
@@ -401,6 +459,7 @@ export async function runWorkflowWithContext(
 
   const api: WorkflowApi = {
     agent,
+    classify: (context, classifyOpts) => runClassifier(rc, context, { ...classifyOpts, phase: scope.agentOptions({ phase: classifyOpts?.phase }).phase }),
     workflow,
     parallel: bindParallel({
       signal: rc.signal,
@@ -412,6 +471,7 @@ export async function runWorkflowWithContext(
     log: scope.log,
     progress: scope.event,
     args,
+    input,
     cwd: rc.cwd,
     budget: rc.budget,
     signal: rc.signal,

package/.pi/extensions/pi-workflow-engine/src/filesystem-error.ts

@@ -2,3 +2,8 @@
 export function isMissingPathError(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+
+/** Identify a path that already exists, as reported for an exclusive (`wx`) create. */
+export function isExistingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}

package/.pi/extensions/pi-workflow-engine/src/host-tools.ts

@@ -0,0 +1,76 @@
+import type { AgentToolCallOutcome } from "@earendil-works/pi-agent-core";
+import { defineTool, type ExtensionToolContext, type ToolDefinition, type ToolInfo } from "@earendil-works/pi-coding-agent";
+
+/** pi names MCP tools `mcp__<server>__<tool>`; its MCP extension also registers these resource tools. */
+const MCP_TOOL_PREFIX = "mcp__";
+const MCP_RESOURCE_TOOLS = new Set(["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+
+/** Mirrors pi's own `isMcpToolName`, which the package does not export. */
+export function isMcpToolName(name: string): boolean {
+  return name.startsWith(MCP_TOOL_PREFIX) || MCP_RESOURCE_TOOLS.has(name);
+}
+
+/** An agent named MCP tools it cannot reach. Raised before prompting so it never runs without them. */
+export class WorkflowHostToolUnavailableError extends Error {
+  readonly code = "WORKFLOW_HOST_TOOL_UNAVAILABLE";
+  readonly tools: readonly string[];
+
+  constructor(tools: readonly string[], bridged: boolean) {
+    super(
+      bridged
+        ? `Host MCP tools not available: ${tools.join(", ")}`
+        : `MCP tools reach subagents only in runs started by the workflow tool; unavailable: ${tools.join(", ")}`,
+    );
+    this.name = "WorkflowHostToolUnavailableError";
+    this.tools = [...tools];
+  }
+}
+
+/**
+ * Host-only tools a subagent can reach through the host session. Subagents are SDK sessions, which
+ * load none of pi's built-in extensions, so they connect no MCP servers of their own; proxies call the
+ * host's tools over its existing connections and through its `tool_call` permission handlers. They act
+ * in the host's context, so a local MCP tool sees the main checkout even for an isolated worktree agent.
+ */
+export interface HostToolBridge {
+  /** Callable host MCP tools, read as each agent starts so servers that connected mid-run are included. */
+  tools(): readonly ToolInfo[];
+  execute(name: string, args: unknown, signal: AbortSignal | undefined): Promise<AgentToolCallOutcome>;
+}
+
+/**
+ * `executeTool` exists only while the host's tool call runs, so only a synchronous `workflow` tool run
+ * gets a bridge; `/workflow` commands and background runs that outlive the call do not.
+ */
+export function createHostToolBridge(
+  registeredTools: () => readonly ToolInfo[],
+  ctx: Pick<ExtensionToolContext, "tools" | "executeTool">,
+): HostToolBridge {
+  return {
+    tools() {
+      const callable = new Set(ctx.tools.map((tool) => tool.name));
+      return registeredTools().filter((tool) => isMcpToolName(tool.name) && callable.has(tool.name));
+    },
+    execute: (name, args, signal) => ctx.executeTool(name, args, { signal }),
+  };
+}
+
+/**
+ * A subagent tool that runs the host tool. It reports no usage: pi already adds nested calls' usage to
+ * the host's `workflow` tool result.
+ */
+export function hostToolProxy(tool: ToolInfo, bridge: HostToolBridge): ToolDefinition {
+  return defineTool({
+    name: tool.name,
+    label: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    promptGuidelines: tool.promptGuidelines,
+    namespace: tool.namespace,
+    annotations: tool.annotations,
+    async execute(_toolCallId, params, signal) {
+      const outcome = await bridge.execute(tool.name, params, signal);
+      return { content: outcome.result.content, details: undefined, ...(outcome.isError ? { isError: true } : {}) };
+    },
+  });
+}

package/.pi/extensions/pi-workflow-engine/src/inline-workflow.ts

@@ -36,10 +36,16 @@ export function compileInlineWorkflow(source: string): LoadedWorkflow {
   return {
     meta: parsedMeta.meta,
     default: (api) => executor(api, Type),
-    source: { kind: "fingerprint", fingerprint: createHash("sha256").update(source).digest("hex") },
+    source: { kind: "fingerprint", fingerprint: inlineScriptFingerprint(source) },
+    inlineScript: source,
   };
 }
 
+/** A compiled script can import nothing, so the hash of its source is its whole identity. */
+export function inlineScriptFingerprint(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}
+
 /** The script's pure-literal meta, read without compiling or running anything; undefined when it does not parse. */
 export function readInlineWorkflowMeta(source: string): WorkflowMeta | undefined {
   try {

package/.pi/extensions/pi-workflow-engine/src/journal.ts

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, appendFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentOptions } from "./types.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
 import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+import { isExistingPathError } from "./filesystem-error.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   isAgentResumeContext,
@@ -15,6 +16,9 @@ import {
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
 export const WORKFLOW_JOURNAL_KEEP = 50;
 
+/** Ignores everything in the runs directory, including this file, so user projects never commit run data. */
+const WORKFLOW_RUNS_GITIGNORE = "*\n";
+
 export interface JournalEntryV2 {
   readonly version: 2;
   readonly key: string;
@@ -56,6 +60,20 @@ export class WorkflowJournalLoadError extends Error {
   override readonly name = "WorkflowJournalLoadError";
 }
 
+/**
+ * Create the directory that holds run files, with a `.gitignore` that ignores all of them: records,
+ * journals, and scripts can carry prompts and results, and user projects do not list this directory in
+ * their own ignore files. An existing `.gitignore` is never overwritten.
+ */
+export async function ensureWorkflowRunsDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(join(dir, ".gitignore"), WORKFLOW_RUNS_GITIGNORE, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (!isExistingPathError(error)) throw error;
+  }
+}
+
 export function createWorkflowRunId(): string {
   return randomUUID();
 }
@@ -161,7 +179,7 @@ export async function createWorkflowJournal(options: {
   readonly writePath: string;
 }): Promise<WorkflowJournal> {
   const priorEntries = options.resumePath ? await loadJournalEntries(options.resumePath, { required: true }) : [];
-  await mkdir(dirname(options.writePath), { recursive: true });
+  await ensureWorkflowRunsDir(dirname(options.writePath));
   await appendFile(options.writePath, "", "utf8");
   return createMemoryBackedJournal(priorEntries, options.writePath);
 }
@@ -201,10 +219,10 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
       const entry: JournalEntryV2 = { version: 2, key, result, identity };
       if (writePath) {
         try {
-          await mkdir(dirname(writePath), { recursive: true });
+          await ensureWorkflowRunsDir(dirname(writePath));
           await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
         } catch (error) {
-      return { ok: false, error: unknownErrorMessage(error) };
+          return { ok: false, error: unknownErrorMessage(error) };
         }
       }
       return { ok: true };

package/.pi/extensions/pi-workflow-engine/src/model-profiles.ts

@@ -1,12 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { isMissingPathError } from "./filesystem-error.ts";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { configFilePaths, readJsonConfigFile, writeJsonConfigFile, type ConfigFilePaths } from "./config-file.ts";
 import { isRecord } from "./guards.ts";
-import { unknownErrorMessage } from "./unknown-error.ts";
 
 export const WORKFLOW_MODEL_PROFILE_NAMES = ["small", "medium", "big"] as const;
 export type WorkflowModelProfileName = (typeof WORKFLOW_MODEL_PROFILE_NAMES)[number];
@@ -20,10 +16,7 @@ export interface WorkflowModelProfileFile {
   readonly profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>>;
 }
 
-export interface WorkflowModelProfilePaths {
-  readonly user: string;
-  readonly project: string;
-}
+export type WorkflowModelProfilePaths = ConfigFilePaths;
 
 interface ResolvedWorkflowModelProfileBase {
   readonly name: WorkflowModelProfileName;
@@ -52,15 +45,10 @@ const HOST_FALLBACK_THINKING: Record<WorkflowModelProfileName, ThinkingLevel> =
   big: "high",
 };
 const CONFIG_FILE_NAME = "workflow-models.json";
+const CONFIG_LABEL = "workflow model profiles";
 
-export function workflowModelProfilePaths(
-  cwd: string,
-  agentDir: string = getAgentDir(),
-): WorkflowModelProfilePaths {
-  return {
-    user: join(agentDir, CONFIG_FILE_NAME),
-    project: join(cwd, ".pi", CONFIG_FILE_NAME),
-  };
+export function workflowModelProfilePaths(cwd: string, agentDir?: string): WorkflowModelProfilePaths {
+  return configFilePaths(CONFIG_FILE_NAME, cwd, agentDir);
 }
 
 export function resolveWorkflowModelProfiles(input: {
@@ -123,22 +111,8 @@ export function resolveAgentModelProfile(
 }
 
 export function readWorkflowModelProfileFile(configPath: string): WorkflowModelProfileFile {
-  let contents: string;
-  try {
-    contents = readFileSync(configPath, "utf8");
-  } catch (error) {
-    if (isMissingPathError(error)) return { profiles: {} };
-    throw new Error(
-      `Could not read workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix the file permissions or remove the file.`,
-    );
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(contents);
-  } catch (error) {
-    throw new Error(`Invalid JSON in workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix or remove the file.`);
-  }
-  return parseWorkflowModelProfileFile(parsed, configPath);
+  const parsed = readJsonConfigFile(configPath, CONFIG_LABEL);
+  return parsed === undefined ? { profiles: {} } : parseWorkflowModelProfileFile(parsed, configPath);
 }
 
 export function setWorkflowModelProfile(input: {
@@ -239,19 +213,7 @@ function assertOnlyKeys(value: Record<string, unknown>, allowed: readonly string
 }
 
 function writeWorkflowModelProfileFile(configPath: string, config: WorkflowModelProfileFile): void {
-  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    renameSync(temporaryPath, configPath);
-  } catch (error) {
-    try {
-      unlinkSync(temporaryPath);
-    } catch {
-      // Best effort: preserve the original write error.
-    }
-    throw new Error(`Could not write workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}.`);
-  }
+  writeJsonConfigFile(configPath, config, CONFIG_LABEL);
 }
 
 function invalidConfig(configPath: string, reason: string): Error {

package/.pi/extensions/pi-workflow-engine/src/model-ref.ts

@@ -0,0 +1,19 @@
+/** Parse a model ref: a bare id is Anthropic shorthand, otherwise "provider/id". Malformed refs throw. */
+export function parseAgentModelRef(modelRef: string): { readonly provider: string; readonly id: string } {
+  const normalized = modelRef.trim();
+  if (normalized.length === 0) {
+    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
+  }
+  if (normalized !== modelRef) {
+    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
+  }
+
+  const slash = modelRef.indexOf("/");
+  if (slash === -1) return { provider: "anthropic", id: modelRef };
+  const provider = modelRef.slice(0, slash);
+  const id = modelRef.slice(slash + 1);
+  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
+    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
+  }
+  return { provider, id };
+}

package/.pi/extensions/pi-workflow-engine/src/pi-compat.ts

@@ -1,6 +1,6 @@
-const MINIMUM_PI_VERSION = "0.80.10";
+const MINIMUM_PI_VERSION = "1.0.0";
 
-const MINIMUM_PI_CORE = [0, 80, 10] as const;
+const MINIMUM_PI_CORE = [1, 0, 0] as const;
 
 /** Fail during extension registration instead of failing later in a workflow. */
 export function assertSupportedPiVersion(version: string): void {

package/.pi/extensions/pi-workflow-engine/src/progress-types.ts

@@ -1,6 +1,6 @@
 import type { WorkflowUsageSnapshot } from "./usage.ts";
 
-export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+export type AgentRowStatus = "queued" | "running" | "done" | "failed" | "skipped";
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
 export interface AgentRowSnapshot {

package/.pi/extensions/pi-workflow-engine/src/progress.ts

@@ -69,7 +69,9 @@ export class ProgressTracker {
   private readonly lanes = new Map<string, WorkflowLaneItem[]>();
   private readonly laneOverflow = new Map<string, number>();
   private readonly rowsById = new Map<number, AgentRow>();
-  private readonly agentCounts: Record<AgentRowStatus, number> = { queued: 0, running: 0, done: 0, failed: 0 };
+  /** How to abort each running row's agent; never part of a snapshot, so it is never persisted. */
+  private readonly skipHandlers = new Map<number, () => void>();
+  private readonly agentCounts: Record<AgentRowStatus, number> = { queued: 0, running: 0, done: 0, failed: 0, skipped: 0 };
   private readonly startedAt = Date.now();
   private readonly laneItemLimit = laneItemLimitFromEnv();
   private doneAt: number | undefined;
@@ -168,12 +170,13 @@ export class ProgressTracker {
     return id;
   }
 
-  agentStart(id: number): void {
+  agentStart(id: number, skip?: () => void): void {
     const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "running");
       row.startedAt = Date.now();
       row.error = undefined;
+      if (skip) this.skipHandlers.set(id, skip);
     }
     this.publish();
   }
@@ -188,8 +191,9 @@ export class ProgressTracker {
   }
 
   agentDone(id: number): void {
+    this.skipHandlers.delete(id);
     const row = this.rowsById.get(id);
-    if (row && row.status !== "failed") {
+    if (row && row.status !== "failed" && row.status !== "skipped") {
       this.transitionAgentStatus(row, "done");
       row.doneAt = Date.now();
     }
@@ -197,6 +201,7 @@ export class ProgressTracker {
   }
 
   agentFailed(id: number, error: unknown): void {
+    this.skipHandlers.delete(id);
     const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "failed");
@@ -206,6 +211,28 @@ export class ProgressTracker {
     this.publish();
   }
 
+  agentSkipped(id: number): void {
+    this.skipHandlers.delete(id);
+    const row = this.rowsById.get(id);
+    if (row) {
+      this.transitionAgentStatus(row, "skipped");
+      row.doneAt = Date.now();
+    }
+    this.publish();
+  }
+
+  /**
+   * Abort one running agent at the user's request (the inspector's skip key); false when the row is
+   * no longer running. The row turns `skipped` once the agent's session has wound down.
+   */
+  skipAgent(id: number): boolean {
+    const skip = this.skipHandlers.get(id);
+    if (!skip || this.rowsById.get(id)?.status !== "running") return false;
+    this.skipHandlers.delete(id);
+    skip();
+    return true;
+  }
+
   updateUsage(snapshot: WorkflowUsageSnapshot): void {
     this.usageSnapshot = snapshot;
     this.publish();
@@ -238,7 +265,8 @@ export class ProgressTracker {
       running: this.agentCounts.running,
       done: this.agentCounts.done,
       failed: this.agentCounts.failed,
-      total: this.agentCounts.queued + this.agentCounts.running + this.agentCounts.done + this.agentCounts.failed,
+      skipped: this.agentCounts.skipped,
+      total: this.agentCounts.queued + this.agentCounts.running + this.agentCounts.done + this.agentCounts.failed + this.agentCounts.skipped,
     };
   }
 

package/.pi/extensions/pi-workflow-engine/src/prompt-sections.ts

@@ -0,0 +1,15 @@
+import type { BeforeAgentStartEventResult, NormalizedBuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+
+type PromptSectionOptions = Pick<NormalizedBuildSystemPromptOptions, "sections" | "forceSystemPrompt">;
+
+/**
+ * Finish adding the `name` section from a `before_agent_start` handler. Normally the section in
+ * `options.sections` is enough and pi appends it as a patch. An earlier handler that forced the whole
+ * prompt makes pi render no sections, so the section is appended to that text instead; pi hands the
+ * returned prompt to later handlers as their `forceSystemPrompt`, so several sections chain.
+ */
+export function appendSectionToForcedPrompt(options: PromptSectionOptions, name: string): BeforeAgentStartEventResult | undefined {
+  const text = options.sections[name];
+  if (options.forceSystemPrompt === undefined || text === undefined) return undefined;
+  return { systemPrompt: `${options.forceSystemPrompt}\n\n<${name}>\n${text}\n</${name}>` };
+}