pi-workflow-engine 0.13.0 → 1.1.0

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

@@ -7,16 +7,16 @@ 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, type PerfSink, type PerfSnapshot } from "./perf.ts";
+import { createPerfRecorder, formatPerfSummary, type PerfSink } from "./perf.ts";
 import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.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 { showWorkflowInspector } from "./ui/workflow-inspector.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
 import { runFinalizers } from "./finalizers.ts";
@@ -97,8 +97,10 @@ export async function runResolvedWorkflow(
 ): Promise<unknown> {
   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 progress = new ProgressTracker(ctx, mod.meta.name, runId, (snapshot) => durableProgress?.updateProgress(snapshot), {
+    plannedPhases: mod.meta.phases?.map((phase) => phase.title),
+    display: resolvedOptions.background ? "background" : "live",
+  });
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
   const usage = createWorkflowUsageRecorder((snapshot) => progress.updateUsage(snapshot));
   const budget = createBudget(resolvedOptions.budget, usage);
@@ -122,6 +124,7 @@ export async function runResolvedWorkflow(
     },
   );
   durableProgress = durableRun;
+  const progressSource = { snapshot: () => progress.snapshot(), state: () => durableRun.state };
   const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
@@ -129,11 +132,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 ctx.ui
-        .custom<void>(
-          (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
-          WORKFLOW_VIEWER_OVERLAY_OPTIONS,
-        )
+      void showWorkflowInspector(ctx.ui, progressSource.snapshot, () => ({ state: progressSource.state() }))
         .catch((error: unknown) => {
           try {
             progress.log(`inspector failed: ${unknownErrorMessage(error)}`);
@@ -179,6 +178,8 @@ 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().
@@ -206,69 +207,44 @@ export async function runResolvedWorkflow(
     }),
   );
 
-  if (workflowOutcome.ok && finalizationOutcome.ok) {
+  let outcome: Outcome<unknown> = workflowOutcome;
+  if (!finalizationOutcome.ok) {
+    outcome = workflowOutcome.ok
+      ? finalizationOutcome
+      : { ok: false, error: combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error) };
+  }
+  const pauseError = outcome.ok ? undefined : backgroundPauseError(outcome.error, ctx.signal, resolvedOptions.signal);
+  if (outcome.ok) {
     durableRun.transition({
       state: "completed",
       progress: progress.snapshot(),
       usage: usage.snapshot(),
-      result: workflowOutcome.value,
+      result: outcome.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;
-    }
+  } else if (pauseError instanceof WorkflowProviderUsageLimitError) {
+    durableRun.transition({
+      state: "paused",
+      progress: progress.snapshot(),
+      ...createProviderUsageLimitPauseRecord(pauseError, resolvedOptions, mod.source.kind === "file" && args.length === 0),
+    });
+  } else if (pauseError) {
+    durableRun.transition({
+      state: "paused",
+      progress: progress.snapshot(),
+      message: unknownErrorMessage(pauseError),
+    });
+  } else {
     durableRun.transition({
       state: ctx.signal?.aborted || resolvedOptions.signal?.aborted ? "stopped" : "failed",
       progress: progress.snapshot(),
       usage: usage.snapshot(),
-      error,
+      error: outcome.error,
     });
   }
+  await durableRun.flush().catch(() => undefined);
 
-  if (workflowOutcome.ok) {
-    if (finalizationOutcome.ok) return workflowOutcome.value;
-    throw finalizationOutcome.error;
-  }
-  if (finalizationOutcome.ok) throw workflowOutcome.error;
-  throw combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
+  if (outcome.ok) return outcome.value;
+  throw outcome.error;
 }
 
 function backgroundPauseError(error: unknown, ...signals: Array<AbortSignal | undefined>): unknown {
@@ -315,7 +291,7 @@ async function finalizeWorkflowRun(input: WorkflowFinalizationInput): Promise<vo
           if (!input.options.perf) return;
           const snapshot = input.perf.snapshot();
           await input.options.onPerfSnapshot?.(snapshot);
-          input.progress.log(formatPerfSummary(snapshot));
+          input.progress.log(formatPerfSummary(snapshot.aggregates));
         },
       },
       ...input.unlinkSignals.map((run, index) => ({
@@ -343,13 +319,7 @@ async function finalizeWorkflowRun(input: WorkflowFinalizationInput): Promise<vo
       },
     ],
     {
-      onBestEffortFailure: (failure) => {
-        try {
-          input.progress.log(`${failure.name} failed: ${unknownErrorMessage(failure.error)}`);
-        } catch {
-          // Observer failures must never replace the workflow outcome.
-        }
-      },
+      onBestEffortFailure: (failure) => input.progress.log(`${failure.name} failed: ${unknownErrorMessage(failure.error)}`),
     },
   );
 }
@@ -434,6 +404,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,
@@ -491,24 +462,14 @@ function createWorkflowScope(progress: WorkflowProgress, prefix: string, namespa
 function namespaceProgressEvent(namespace: string, event: WorkflowProgressEvent): WorkflowProgressEvent {
   switch (event.type) {
     case "counter":
-      return { ...event, key: `${namespace}.${event.key}` };
     case "counter_delta":
+    case "summary":
       return { ...event, key: `${namespace}.${event.key}` };
     case "lane_item":
       return { ...event, lane: `${namespace} ▸ ${event.lane}` };
-    case "summary":
-      return { ...event, key: `${namespace}.${event.key}` };
   }
 }
 
-function formatPerfSummary(snapshot: PerfSnapshot): string {
-  const parts = snapshot.aggregates
-    .filter((aggregate) => aggregate.count > 0)
-    .slice(0, 5)
-    .map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
-  return parts.length > 0 ? `perf: ${parts.join(", ")}` : "perf: no samples";
-}
-
 async function notifyLifecycleObserver(
   progress: ProgressTracker,
   name: string,

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

@@ -10,7 +10,6 @@ export interface Finalizer {
 
 export interface FinalizerFailure {
   readonly name: string;
-  readonly criticality: FinalizerCriticality;
   readonly error: unknown;
 }
 
@@ -35,24 +34,18 @@ export class RequiredFinalizerError extends AggregateError {
 export async function runFinalizers(
   finalizers: readonly Finalizer[],
   options: RunFinalizersOptions = {},
-): Promise<readonly FinalizerFailure[]> {
+): Promise<void> {
   const requiredFailures: FinalizerFailure[] = [];
-  const bestEffortFailures: FinalizerFailure[] = [];
 
   for (const finalizer of finalizers) {
     try {
       await finalizer.run();
     } catch (error) {
-      const failure: FinalizerFailure = {
-        name: finalizer.name,
-        criticality: finalizer.criticality,
-        error,
-      };
+      const failure: FinalizerFailure = { name: finalizer.name, error };
       if (finalizer.criticality === "required") {
         requiredFailures.push(failure);
         continue;
       }
-      bestEffortFailures.push(failure);
       try {
         options.onBestEffortFailure?.(failure);
       } catch {
@@ -62,5 +55,4 @@ export async function runFinalizers(
   }
 
   if (requiredFailures.length > 0) throw new RequiredFinalizerError(requiredFailures);
-  return bestEffortFailures;
 }

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

@@ -0,0 +1,55 @@
+import { resolve } from "node:path";
+import { runBoundedProcess, type BoundedProcessResult } from "./process-runner.ts";
+import { isPathWithin } from "./tree-fingerprint.ts";
+
+export interface GitCommandOptions {
+  /** The GitHub CLI shares the runner so pull-request commands get the same bounds. Defaults to `git`. */
+  readonly file?: "git" | "gh";
+  readonly cwd: string;
+  readonly args: readonly string[];
+  /** Names the command in its abort, timeout, output-limit, and exit messages. */
+  readonly label: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+  readonly stdin?: string;
+  /** Overrides merged over `process.env`. */
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export async function runGit(options: GitCommandOptions): Promise<BoundedProcessResult> {
+  const { label, timeoutMs, maxBufferBytes } = options;
+  const env = { ...process.env, ...options.env };
+  // Drop env-level diff overrides so git emits plain patches. Setting them to an empty string
+  // instead makes a plain `git diff` try to run an empty external diff command.
+  delete env.GIT_EXTERNAL_DIFF;
+  delete env.GIT_DIFF_OPTS;
+  return await runBoundedProcess({
+    file: options.file ?? "git",
+    args: options.args,
+    cwd: options.cwd,
+    env,
+    stdin: options.stdin,
+    signal: options.signal,
+    timeoutMs,
+    maxBufferBytes,
+    abortError: `${label} aborted`,
+    timeoutError: `${label} timed out after ${timeoutMs}ms`,
+    maxBufferError: maxBufferBytes === undefined ? undefined : `${label} exceeded ${maxBufferBytes} bytes`,
+    exitError: (stderr, code, signal) => stderr.trim() || `${label} exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
+  });
+}
+
+/** A full SHA-1 or SHA-256 Git object ID. */
+export function isGitObjectId(value: string): boolean {
+  return /^[0-9a-f]{40,64}$/i.test(value);
+}
+
+/** Resolve `git rev-parse --show-toplevel` output to a root that contains `cwd`. */
+export function parseGitTopLevel(output: string, cwd: string): string | undefined {
+  const withoutLf = output.endsWith("\n") ? output.slice(0, -1) : output;
+  const value = withoutLf.endsWith("\r") ? withoutLf.slice(0, -1) : withoutLf;
+  if (value.length === 0 || value.includes("\n") || value.includes("\0")) return undefined;
+  const root = resolve(cwd, value);
+  return isPathWithin(root, cwd) ? root : undefined;
+}

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

@@ -0,0 +1,8 @@
+/** A non-null, non-array object whose fields can be inspected by name. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

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/identity-canonicalization.ts

@@ -2,15 +2,9 @@ export type IdentityCanonicalization =
   | { readonly kind: "verified"; readonly value: string }
   | { readonly kind: "unverifiable"; readonly reason: string };
 
-export interface IdentityCanonicalizationOptions {
-  readonly maxBytes?: number;
-  readonly maxDepth?: number;
-  readonly maxNodes?: number;
-}
-
-const DEFAULT_MAX_BYTES = 1 << 20;
-const DEFAULT_MAX_DEPTH = 64;
-const DEFAULT_MAX_NODES = 16_384;
+const MAX_BYTES = 1 << 20;
+const MAX_DEPTH = 64;
+const MAX_NODES = 16_384;
 
 /**
  * Produce a deterministic, bounded identity for JSON-like data.
@@ -19,13 +13,7 @@ const DEFAULT_MAX_NODES = 16_384;
  * accessors, proxies, or values JSON cannot represent. Those inputs disable
  * replay instead of throwing or being silently collapsed to the same key.
  */
-export function canonicalizeIdentity(
-  value: unknown,
-  options: IdentityCanonicalizationOptions = {},
-): IdentityCanonicalization {
-  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
-  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+export function canonicalizeIdentity(value: unknown): IdentityCanonicalization {
   const active = new WeakSet<object>();
   const chunks: string[] = [];
   let bytes = 0;
@@ -33,14 +21,14 @@ export function canonicalizeIdentity(
 
   const append = (chunk: string): void => {
     bytes += Buffer.byteLength(chunk);
-    if (bytes > maxBytes) throw new IdentityCanonicalizationError(`identity exceeded ${maxBytes} bytes`);
+    if (bytes > MAX_BYTES) throw new IdentityCanonicalizationError(`identity exceeded ${MAX_BYTES} bytes`);
     chunks.push(chunk);
   };
 
   const visit = (current: unknown, depth: number): void => {
     nodes += 1;
-    if (nodes > maxNodes) throw new IdentityCanonicalizationError(`identity exceeded ${maxNodes} values`);
-    if (depth > maxDepth) throw new IdentityCanonicalizationError(`identity exceeded ${maxDepth} levels`);
+    if (nodes > MAX_NODES) throw new IdentityCanonicalizationError(`identity exceeded ${MAX_NODES} values`);
+    if (depth > MAX_DEPTH) throw new IdentityCanonicalizationError(`identity exceeded ${MAX_DEPTH} levels`);
 
     if (current === null) {
       append("n;");