pi-workflow-engine 0.11.0 → 0.13.0

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

@@ -1,7 +1,17 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { KeyId } from "@earendil-works/pi-tui";
+import { CustomEditor, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { EditorComponent, KeyId } from "@earendil-works/pi-tui";
+import { completeCurrentArgument } from "./command-completions.ts";
 import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./dynamax-shortcuts.ts";
+import { sessionKey } from "./session-identity.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  decorateDynamaxEditor,
+  resolveDynamaxEffect,
+  type DynamaxAnimationScheduler,
+  type DynamaxEditorDecoration,
+  type DynamaxEffect,
+} from "./ui/dynamax-editor-decoration.ts";
 
 export interface DynamaxState {
   sticky: boolean;
@@ -15,13 +25,34 @@ export interface DynamaxRuntime {
 }
 
 export type DynamaxRuntimeStore = Map<string, DynamaxRuntime>;
+
 export interface DynamaxRegistrationOptions {
   openInspector?: (ctx: ExtensionContext) => Promise<void> | void;
+  effect?: DynamaxEffect;
+  animationScheduler?: DynamaxAnimationScheduler;
 }
 
 export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
 export const DYNAMAX_STATUS_KEY = "dynamax";
-export const DYNAMAX_WIDGET_KEY = "workflow-dynamax";
+
+type EditorFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>>;
+
+interface DynamaxEditorInstallation {
+  factory: EditorFactory;
+  previousFactory: EditorFactory | undefined;
+  decorations: Set<DynamaxEditorDecoration>;
+}
+
+function disposeDynamaxDecorations(decorations: Set<DynamaxEditorDecoration>): void {
+  for (const decoration of decorations) decoration.dispose();
+  decorations.clear();
+}
+
+const DYNAMAX_ACTION_COMPLETIONS = [
+  { value: "on", description: "Keep Dynamax enabled for this session" },
+  { value: "off", description: "Disable sticky and pending Dynamax modes" },
+  { value: "status", description: "Show the current Dynamax state" },
+] as const;
 
 export const ADAPTIVE_WORKFLOW_GUIDANCE = `
 Adaptive multi-pass workflows are optional. Use a simple single-pass fan-out when it is sufficient. When the first pass may expose gaps, conflicts, weak claims, or missing evidence:
@@ -40,7 +71,7 @@ The user has opted into dynamax multi-agent orchestration. The workflow tool is
 Inline workflow rules:
 - Use the injected Type object for schemas, for example Type.Object({ ok: Type.Boolean() }); do not import typebox.
 - Do not use import statements or dynamic import() in inline workflow scripts.
-- Set thinkingLevel explicitly on each agent() call so fan-out remains bounded.
+- Set profile to "small", "medium", or "big" on each agent() call so routing remains explicit; use model/thinkingLevel only for an intentional override.
 - Subagents receive no skills by default. Add \`skills: ["skill-name"]\` per agent only when that stage should load that skill; grant the smallest useful set.
 - Provide exactly one of workflow.name or workflow.script.
 
@@ -57,12 +88,8 @@ export function createDynamaxRuntime(): DynamaxRuntime {
   return { state: createDynamaxState() };
 }
 
-export function dynamaxSessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
-  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
-}
-
 export function getDynamaxRuntime(store: DynamaxRuntimeStore, ctx: Pick<ExtensionContext, "sessionManager">): DynamaxRuntime {
-  const key = dynamaxSessionKey(ctx);
+  const key = sessionKey(ctx);
   const existing = store.get(key);
   if (existing) return existing;
   const runtime = createDynamaxRuntime();
@@ -78,12 +105,8 @@ export function markDynamaxOneShot(state: DynamaxState): void {
   state.oneShotPending = true;
 }
 
-export function setDynamaxSticky(state: DynamaxState, sticky: boolean): void {
-  state.sticky = sticky;
-  if (!sticky) {
-    state.oneShotPending = false;
-    state.turnActive = false;
-  }
+export function enableDynamaxSticky(state: DynamaxState): void {
+  state.sticky = true;
 }
 
 export function clearDynamax(state: DynamaxState): void {
@@ -92,12 +115,6 @@ export function clearDynamax(state: DynamaxState): void {
   state.turnActive = false;
 }
 
-export function consumeDynamaxOneShot(state: DynamaxState): boolean {
-  const pending = state.oneShotPending;
-  state.oneShotPending = false;
-  return pending;
-}
-
 export function isDynamaxActive(state: DynamaxState): boolean {
   return state.sticky || state.oneShotPending || state.turnActive;
 }
@@ -139,23 +156,84 @@ export function registerDynamax(
   options: DynamaxRegistrationOptions = {},
 ): void {
   const runtimes: DynamaxRuntimeStore = new Map();
+  const effect = options.effect ?? resolveDynamaxEffect();
+  let editorInstallation: DynamaxEditorInstallation | undefined;
   const openInspector =
     options.openInspector ??
     ((ctx: ExtensionContext): void => {
       ctx.ui.notify("No workflow inspector is available yet", "warning");
     });
-  const refreshIfVisible = (ctx: ExtensionContext): void => {
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (isDynamaxActive(runtime.state) || runtime.runningWorkflow) {
-      updateDynamaxSurfaces(ctx, runtime, shortcuts);
+  const installEditor = (ctx: ExtensionContext): void => {
+    if (ctx.mode !== "tui" || effect === "off") return;
+    const previousFactory = ctx.ui.getEditorComponent();
+    if (editorInstallation && editorInstallation.factory === previousFactory) return;
+
+    const decorations = new Set<DynamaxEditorDecoration>();
+    const installation: DynamaxEditorInstallation = {
+      previousFactory,
+      decorations,
+      factory: (tui, theme, keybindings) => {
+        const decorate = (editor: EditorComponent): EditorComponent => {
+          const decoration = decorateDynamaxEditor(editor, () => tui.requestRender(), {
+            effect,
+            scheduler: options.animationScheduler,
+            isActive: () => editorInstallation === installation && ctx.ui.getEditorComponent() === installation.factory,
+          });
+          decorations.add(decoration);
+          return decoration.editor;
+        };
+        if (!previousFactory) return decorate(new CustomEditor(tui, theme, keybindings));
+
+        let editor: EditorComponent;
+        try {
+          editor = previousFactory(tui, theme, keybindings);
+        } catch (error) {
+          ctx.ui.notify(
+            `Dynamax could not compose the existing custom editor (${unknownErrorMessage(error)}); using pi's stock-compatible CustomEditor so highlighting stays enabled`,
+            "warning",
+          );
+          installation.previousFactory = undefined;
+          return decorate(new CustomEditor(tui, theme, keybindings));
+        }
+
+        try {
+          return decorate(editor);
+        } catch (error) {
+          ctx.ui.notify(
+            `Dynamax could not decorate the existing custom editor (${unknownErrorMessage(error)}); using pi's stock-compatible CustomEditor so highlighting stays enabled`,
+            "warning",
+          );
+          return decorate(new CustomEditor(tui, theme, keybindings));
+        }
+      },
+    };
+
+    try {
+      ctx.ui.setEditorComponent(installation.factory);
+    } catch (error) {
+      disposeDynamaxDecorations(decorations);
+      ctx.ui.notify(`Dynamax highlighting could not be installed: ${unknownErrorMessage(error)}`, "error");
+      throw error;
+    }
+    editorInstallation = installation;
+  };
+  const uninstallEditor = (ctx: ExtensionContext): void => {
+    const installation = editorInstallation;
+    if (!installation) return;
+    editorInstallation = undefined;
+    disposeDynamaxDecorations(installation.decorations);
+    if (ctx.mode === "tui" && ctx.ui.getEditorComponent() === installation.factory) {
+      ctx.ui.setEditorComponent(installation.previousFactory);
     }
   };
 
   pi.on("session_start", (_event, ctx) => {
+    installEditor(ctx);
     updateDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx), shortcuts);
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
+    uninstallEditor(ctx);
     clearDynamaxSurfaces(ctx);
   });
 
@@ -177,26 +255,6 @@ export function registerDynamax(
     return { systemPrompt };
   });
 
-  pi.on("agent_start", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_start", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_update", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("message_end", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
-  pi.on("turn_end", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
   pi.on("agent_end", (_event, ctx) => {
     const runtime = getDynamaxRuntime(runtimes, ctx);
     runtime.runningWorkflow = undefined;
@@ -205,23 +263,17 @@ export function registerDynamax(
   });
 
   pi.on("tool_execution_start", (event, ctx) => {
+    if (event.toolName !== "workflow") return undefined;
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (event.toolName === "workflow") {
-      runtime.runningWorkflow = workflowLabel(event.args);
-    }
+    runtime.runningWorkflow = workflowLabel(event.args);
     updateDynamaxSurfaces(ctx, runtime, shortcuts);
     return undefined;
   });
 
-  pi.on("tool_execution_update", (_event, ctx) => {
-    refreshIfVisible(ctx);
-  });
-
   pi.on("tool_execution_end", (event, ctx) => {
+    if (event.toolName !== "workflow") return undefined;
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (event.toolName === "workflow") {
-      runtime.runningWorkflow = undefined;
-    }
+    runtime.runningWorkflow = undefined;
     updateDynamaxSurfaces(ctx, runtime, shortcuts);
     return undefined;
   });
@@ -244,6 +296,7 @@ export function registerDynamax(
 
   pi.registerCommand("workflow:dynamax", {
     description: "Toggle Dynamax workflow orchestration: /workflow:dynamax [on|off|status]",
+    getArgumentCompletions: (argumentPrefix) => completeCurrentArgument(argumentPrefix, DYNAMAX_ACTION_COMPLETIONS),
     handler: async (args, ctx) => {
       const runtime = getDynamaxRuntime(runtimes, ctx);
       const action = args.trim().toLowerCase();
@@ -252,7 +305,7 @@ export function registerDynamax(
         return;
       }
       if (action === "on") {
-        setDynamaxSticky(runtime.state, true);
+        enableDynamaxSticky(runtime.state);
         updateDynamaxSurfaces(ctx, runtime, shortcuts);
         ctx.ui.notify("Dynamax workflow orchestration is on for this session", "info");
         return;
@@ -274,8 +327,6 @@ export function registerDynamax(
 
 export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime, shortcuts: DynamaxShortcuts): void {
   if (!ctx.hasUI) return;
-  ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
-  ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
   if (!isDynamaxActive(runtime.state) && !runtime.runningWorkflow) {
     clearDynamaxSurfaces(ctx);
     return;
@@ -287,9 +338,7 @@ export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui"
 
 export function clearDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">): void {
   if (!ctx.hasUI) return;
-  ctx.ui.setWidget(DYNAMAX_WIDGET_KEY, undefined);
   ctx.ui.setStatus(DYNAMAX_STATUS_KEY, undefined);
-  ctx.ui.setStatus(DYNAMAX_WIDGET_KEY, undefined);
 }
 
 function workflowLabel(args: unknown): string {

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

@@ -1,14 +1,22 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
 import { bindParallel, bindPipeline, Semaphore } from "./concurrency.ts";
-import { linkAbortSignal, throwIfAborted } from "./cancellation.ts";
+import { WorkflowAgentLimiter } from "./agent-limits.ts";
+import { defaultAgentRetryScheduler, type AgentRetryScheduler } from "./agent-retry.ts";
+import { resolveWorkflowModelProfiles, type ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
+import { abortReason, isWorkflowPauseError, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
 import { createBudget } from "./budget.ts";
 import { runAgent, type AgentExecutionOptions, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSink, type PerfSnapshot } from "./perf.ts";
 import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.ts";
-import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
-import type { AgentOptions, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
+import {
+  resolveWorkflowRunOptions,
+  type ResolvedWorkflowRunOptions,
+} from "./options.ts";
+import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./ui/workflow-viewer-layout.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
 import { runFinalizers } from "./finalizers.ts";
@@ -17,6 +25,17 @@ import {
   captureWorkflowResumeContext,
   type AgentResumeBaseContext,
 } from "./resume-context.ts";
+import {
+  DurableWorkflowRun,
+  ProjectWorkflowRunStore,
+  workflowRunRecordPath,
+  type WorkflowRunStore,
+} from "./workflow-run-store.ts";
+import { createWorkflowRunRecord } from "./workflow-run-record.ts";
+import {
+  createProviderUsageLimitPauseRecord,
+  WorkflowProviderUsageLimitError,
+} from "./provider-usage-limit.ts";
 
 /** The workflow-facing slice of the progress tracker (satisfied by `ProgressTracker`). */
 export interface WorkflowProgress {
@@ -50,6 +69,8 @@ type Outcome<T> =
 
 export interface WorkflowEngineDependencies {
   readonly worktrees?: WorktreeRegistry;
+  readonly retryScheduler?: AgentRetryScheduler;
+  readonly modelProfiles?: ResolvedWorkflowModelProfiles;
 }
 
 /**
@@ -74,25 +95,44 @@ export async function runResolvedWorkflow(
   resolvedOptions: ResolvedWorkflowRunOptions,
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
-  const progress = new ProgressTracker(ctx, mod.meta.name);
+  const runId = resolvedOptions.runId ?? createWorkflowRunId();
+  let durableProgress: DurableWorkflowRun | undefined;
+  const progress = new ProgressTracker(ctx, mod.meta.name, runId, (snapshot) => durableProgress?.updateProgress(snapshot));
   const progressSource = { snapshot: () => progress.snapshot() };
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
-  const usage = createWorkflowUsageRecorder();
+  const usage = createWorkflowUsageRecorder((snapshot) => progress.updateUsage(snapshot));
   const budget = createBudget(resolvedOptions.budget, usage);
-  const runId = resolvedOptions.runId ?? createWorkflowRunId();
   const journalPath = workflowJournalPath(ctx.cwd, runId);
   const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
+  const runStore = new ProjectWorkflowRunStore(ctx.cwd);
+  let persistenceFailureReported = false;
+  const durableRun = new DurableWorkflowRun(
+    runStore,
+    createWorkflowRunRecord({
+      runId,
+      workflow: mod,
+      options: resolvedOptions,
+      progress: progress.snapshot(),
+      argumentsPresent: args.length > 0,
+    }),
+    (error) => {
+      if (persistenceFailureReported) return;
+      persistenceFailureReported = true;
+      process.stderr.write(`[${mod.meta.name}] run persistence failed: ${unknownErrorMessage(error)}\n`);
+    },
+  );
+  durableProgress = durableRun;
   const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
   const workflowOutcome = await captureOutcome(async () => {
     await notifyLifecycleObserver(progress, "progress source callback", () => resolvedOptions.onProgressSource?.(progressSource));
-    if (resolvedOptions.inspect && ctx.hasUI) {
+    if (resolvedOptions.inspect && ctx.hasUI && ctx.mode === "tui") {
       void ctx.ui
         .custom<void>(
           (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
-          { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+          WORKFLOW_VIEWER_OVERLAY_OPTIONS,
         )
         .catch((error: unknown) => {
           try {
@@ -104,15 +144,34 @@ export async function runResolvedWorkflow(
     }
 
     const journal = await createWorkflowJournal({ resumePath, writePath: journalPath });
+    durableRun.transition({ state: "running", progress: progress.snapshot() });
+    await durableRun.flush().catch(() => undefined);
     await notifyLifecycleObserver(progress, "run metadata callback", () =>
-      resolvedOptions.onRunMetadata?.({ runId, resumedFromRunId: resolvedOptions.resumeFromRunId, journalPath }),
+      resolvedOptions.onRunMetadata?.({
+        runId,
+        resumedFromRunId: resolvedOptions.resumeFromRunId,
+        journalPath,
+        recordPath: workflowRunRecordPath(ctx.cwd, runId),
+      }),
     );
     progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
+    const modelProfiles = dependencies.modelProfiles ?? resolveWorkflowModelProfiles({
+      cwd: ctx.cwd,
+      modelRegistry: ctx.modelRegistry,
+      hostModel: ctx.model,
+    });
     const rc: WorkflowRunContext = {
       cwd: ctx.cwd,
       hostModel: ctx.model,
       modelRegistry: ctx.modelRegistry,
       semaphore: new Semaphore(resolvedOptions.concurrency),
+      agentLimiter: new WorkflowAgentLimiter(resolvedOptions.maxAgents),
+      agentTimeoutMs: resolvedOptions.agentTimeoutMs,
+      agentRetries: resolvedOptions.agentRetries,
+      pauseOnProviderUsageLimit: resolvedOptions.background !== undefined,
+      resumeEditedWorkflow: resolvedOptions.resumeEditedWorkflow,
+      retryScheduler: dependencies.retryScheduler ?? defaultAgentRetryScheduler,
+      modelProfiles,
       progress,
       signal: runAbortController.signal,
       perf,
@@ -141,11 +200,69 @@ export async function runResolvedWorkflow(
       perf,
       usage,
       progress,
+      runStore,
       worktrees,
       unlinkSignals: [unlinkContextAbortSignal, unlinkOptionAbortSignal],
     }),
   );
 
+  if (workflowOutcome.ok && finalizationOutcome.ok) {
+    durableRun.transition({
+      state: "completed",
+      progress: progress.snapshot(),
+      usage: usage.snapshot(),
+      result: workflowOutcome.value,
+    });
+  } else if (!workflowOutcome.ok) {
+    const error = finalizationOutcome.ok
+      ? workflowOutcome.error
+      : combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
+    persistTerminalWorkflowError(error);
+  } else if (!finalizationOutcome.ok) {
+    persistTerminalWorkflowError(finalizationOutcome.error);
+  }
+  await durableRun.flush().catch(() => undefined);
+
+  function persistTerminalWorkflowError(error: unknown): void {
+    const pauseError = backgroundPauseError(error, ctx.signal, resolvedOptions.signal);
+    if (pauseError) {
+      if (pauseError instanceof WorkflowProviderUsageLimitError) {
+        if (resolvedOptions.background === undefined) {
+          durableRun.transition({
+            state: "failed",
+            progress: progress.snapshot(),
+            usage: usage.snapshot(),
+            error: pauseError,
+          });
+          return;
+        }
+        const providerPause = createProviderUsageLimitPauseRecord(
+          pauseError,
+          resolvedOptions,
+          mod.source.kind === "file" && args.length === 0,
+        );
+        durableRun.transition({
+          state: "paused",
+          progress: progress.snapshot(),
+          ...providerPause,
+        });
+        return;
+      }
+      durableRun.transition({
+        state: "paused",
+        progress: progress.snapshot(),
+        message: unknownErrorMessage(pauseError),
+      });
+      return;
+    }
+    durableRun.transition({
+      state: ctx.signal?.aborted || resolvedOptions.signal?.aborted ? "stopped" : "failed",
+      progress: progress.snapshot(),
+      usage: usage.snapshot(),
+      error,
+    });
+  }
+
   if (workflowOutcome.ok) {
     if (finalizationOutcome.ok) return workflowOutcome.value;
     throw finalizationOutcome.error;
@@ -154,6 +271,16 @@ export async function runResolvedWorkflow(
   throw combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
 }
 
+function backgroundPauseError(error: unknown, ...signals: Array<AbortSignal | undefined>): unknown {
+  if (isWorkflowPauseError(error)) return error;
+  for (const signal of signals) {
+    if (!signal?.aborted) continue;
+    const reason = abortReason(signal);
+    if (isWorkflowPauseError(reason)) return reason;
+  }
+  return undefined;
+}
+
 async function captureOutcome<T>(operation: () => Promise<T>): Promise<Outcome<T>> {
   try {
     return { ok: true, value: await operation() };
@@ -168,6 +295,7 @@ interface WorkflowFinalizationInput {
   readonly perf: PerfSink;
   readonly usage: WorkflowUsageSink;
   readonly progress: ProgressTracker;
+  readonly runStore: WorkflowRunStore;
   readonly worktrees: WorktreeRegistry;
   readonly unlinkSignals: readonly (() => void)[];
 }
@@ -201,6 +329,7 @@ async function finalizeWorkflowRun(input: WorkflowFinalizationInput): Promise<vo
         run: () => input.worktrees.removeAll(),
       },
       { name: "journal pruning", criticality: "best-effort", run: () => pruneWorkflowJournals(input.cwd) },
+      { name: "run record pruning", criticality: "best-effort", run: () => input.runStore.prune() },
       { name: "progress completion", criticality: "best-effort", run: () => input.progress.done() },
       {
         name: "progress snapshot callback",
@@ -232,6 +361,30 @@ function combinedWorkflowError(workflowError: unknown, finalizationError: unknow
   );
 }
 
+function createWorkflowAgent(
+  rc: WorkflowRunContext,
+  scope: WorkflowScope,
+  mod: LoadedWorkflow,
+  resumeContext: AgentResumeBaseContext,
+): WorkflowApi["agent"] {
+  function agent<S extends TSchema>(
+    prompt: string,
+    opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
+  ): Promise<IsolatedAgentResult<Static<S>>>;
+  function agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
+  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 executionOptions: AgentExecutionOptions =
+      scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
+        ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
+        : scopedOptions;
+    return runAgent(rc, prompt, executionOptions, resumeContext);
+  }
+  return agent;
+}
+
 /**
  * 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,
@@ -250,14 +403,7 @@ export async function runWorkflowWithContext(
     workflow: await captureWorkflowResumeContext(mod, rc.signal),
   };
 
-  const agent = ((prompt: string, agentOpts?: AgentOptions) => {
-    const scopedOptions = scope.agentOptions(agentOpts);
-    const executionOptions: AgentExecutionOptions =
-      scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
-        ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
-        : scopedOptions;
-    return runAgent(rc, prompt, executionOptions, resumeContext);
-  }) as WorkflowApi["agent"];
+  const agent = createWorkflowAgent(rc, scope, mod, resumeContext);
 
   const workflow: WorkflowApi["workflow"] =
     depth >= 1
@@ -305,7 +451,9 @@ export async function runWorkflowWithContext(
   };
 
   throwIfAborted(rc.signal);
-  return await mod.default(api);
+  const result = await mod.default(api);
+  throwIfAborted(rc.signal);
+  return result;
 }
 
 interface WorkflowScope {

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

@@ -0,0 +1,4 @@
+/** Identify a missing filesystem path reported by Node's filesystem APIs. */
+export function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

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

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { createHash } from "node:crypto";
 import type { LoadedWorkflow, WorkflowApi } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import { parseWorkflowMeta } from "./workflow-module.ts";
 
 /**
@@ -138,8 +139,7 @@ function compileExecutor(defaultExpression: string): InlineWorkflowExecutor {
   try {
     return new AsyncFunction("api", "Type", `"use strict";\nconst workflow = ${defaultExpression};\nreturn await workflow(api);`);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${message}`);
+    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${unknownErrorMessage(error)}`);
   }
 }
 

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

@@ -9,6 +9,7 @@ import {
   isAgentResumeContext,
   resumeContextMismatchReason,
   type AgentResumeContext,
+  type ResumeContextComparisonOptions,
 } from "./resume-context.ts";
 
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
@@ -47,7 +48,7 @@ export type AgentJournalKeyCapture =
   | { readonly kind: "unverifiable"; readonly reason: string };
 
 export interface WorkflowJournal {
-  lookup(key: string, identity: AgentResumeContext): JournalLookup;
+  lookup(key: string, identity: AgentResumeContext, options?: ResumeContextComparisonOptions): JournalLookup;
   record(key: string, result: unknown, identity: AgentResumeContext): Promise<JournalRecordResult>;
 }
 
@@ -60,7 +61,7 @@ export function createWorkflowRunId(): string {
 }
 
 export function workflowJournalPath(cwd: string, runId: string): string {
-  return join(cwd, WORKFLOW_RUNS_DIR, `${validateRunId(runId)}.jsonl`);
+  return join(cwd, WORKFLOW_RUNS_DIR, `${validateWorkflowRunId(runId)}.jsonl`);
 }
 
 export function agentJournalKey(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
@@ -110,9 +111,11 @@ function captureAgentCallHash(
         thinkingLevel: opts.thinkingLevel,
         tools: opts.tools,
         toolHints: opts.toolHints,
+        requireToolHints: opts.requireToolHints === true ? true : undefined,
         skills: opts.skills,
         schema: opts.schema,
         isolation: opts.isolation,
+        candidatePatch: opts.candidatePatch ? { baselineOid: opts.candidatePatch.baselineOid, hash: createHash("sha256").update(opts.candidatePatch.patch).digest("hex") } : undefined,
         worktreeBaseline: worktreeBaseline
           ? {
               ref: worktreeBaseline.ref,
@@ -170,6 +173,8 @@ 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 appendFile(options.writePath, "", "utf8");
   return createMemoryBackedJournal(priorEntries, options.writePath);
 }
 
@@ -182,7 +187,7 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
   }
 
   return {
-    lookup(key, identity) {
+    lookup(key, identity, options) {
       const entries = priorByKey.get(key);
       if (!entries || entries.length === 0) return { hit: false };
 
@@ -197,10 +202,12 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
             : "journal entry predates replay contract v2",
         };
       }
-      const matches = current.filter((entry) => resumeContextMismatchReason(entry.identity, identity) === undefined);
+      const matches = current.filter(
+        (entry) => resumeContextMismatchReason(entry.identity, identity, options) === undefined,
+      );
       if (matches.length === 1) return { hit: true, value: matches[0]!.result };
       if (matches.length > 1) return { hit: false, reason: "multiple cached entries match this agent call" };
-      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity) };
+      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity, options) };
     },
     async record(key, result, identity) {
       const entry: JournalEntryV2 = { version: 2, key, result, identity };
@@ -248,7 +255,7 @@ export async function pruneWorkflowJournals(cwd: string, keep = WORKFLOW_JOURNAL
   await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
 }
 
-function validateRunId(runId: string): string {
+export function validateWorkflowRunId(runId: string): string {
   const trimmed = runId.trim();
   if (!/^[A-Za-z0-9_.-]+$/.test(trimmed)) {
     throw new Error("Workflow run id must contain only letters, numbers, dots, underscores, or hyphens.");