pi-workflow-engine 0.12.0 → 1.0.0

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

@@ -1,10 +1,11 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { CustomEditor, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { EditorComponent, KeyId } from "@earendil-works/pi-tui";
+import { CustomEditor, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import type { EditorComponent } from "@earendil-works/pi-tui";
 import { completeCurrentArgument } from "./command-completions.ts";
-import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./dynamax-shortcuts.ts";
+import type { DynamaxShortcuts } from "./dynamax-shortcuts.ts";
 import { sessionKey } from "./session-identity.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
+import { dot, GLYPH } from "./ui/kit.ts";
+import { setWorkflowInspectorShortcut } from "./ui/workflow-widget.ts";
 import {
   decorateDynamaxEditor,
   resolveDynamaxEffect,
@@ -21,17 +22,21 @@ export interface DynamaxState {
 
 export interface DynamaxRuntime {
   state: DynamaxState;
-  runningWorkflow?: string;
 }
 
 export type DynamaxRuntimeStore = Map<string, DynamaxRuntime>;
 
 export interface DynamaxRegistrationOptions {
-  openInspector?: (ctx: ExtensionContext) => Promise<void> | void;
+  openInspector: (ctx: ExtensionContext) => Promise<void> | void;
   effect?: DynamaxEffect;
   animationScheduler?: DynamaxAnimationScheduler;
 }
 
+export interface DynamaxHandle {
+  /** Opt the next agent run in. The `input` hook ignores prompts this extension sends (pi tags them `source: "extension"`). */
+  markOneShot(ctx: ExtensionContext): void;
+}
+
 export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
 export const DYNAMAX_STATUS_KEY = "dynamax";
 
@@ -78,8 +83,6 @@ Inline workflow rules:
 ${ADAPTIVE_WORKFLOW_GUIDANCE}
 `;
 
-const DYNAMAX_CONTEXT_CUSTOM_TYPE = "workflow-dynamax-reminder";
-
 export function createDynamaxState(): DynamaxState {
   return { sticky: false, oneShotPending: false, turnActive: false };
 }
@@ -126,16 +129,15 @@ export function describeDynamaxState(state: DynamaxState): string {
   return `sticky ${sticky}; one-shot ${oneShot}${turn}`;
 }
 
-export function dynamaxWidgetLine(state: DynamaxState, shortcut: KeyId | null, runningWorkflow?: string): string {
-  const modes = [
-    runningWorkflow ? `running ${runningWorkflow}` : undefined,
-    state.sticky ? "sticky on" : undefined,
-    !state.sticky && state.turnActive ? "active this turn" : undefined,
-    state.oneShotPending ? "one-shot pending" : undefined,
-  ].filter((value): value is string => value !== undefined);
-  const mode = modes.join(" + ") || "off";
-  const inspectorHint = shortcut ? `${shortcut} inspector` : "/workflow:inspector";
-  return `dynamax: ${mode} | /workflow:dynamax on|off | ${inspectorHint}`;
+/**
+ * Footer status: `◆ dynamax` while sticky, `◆ dynamax · next prompt` while a one-shot waits for its
+ * prompt, `◆ dynamax · this turn` while that turn runs. A running workflow names itself in its own
+ * status (`◆ repo-scan · Scan 2/3 · 4s`), so this one only states the mode.
+ */
+export function dynamaxStatusText(state: DynamaxState, theme: Theme): string {
+  const mode = state.sticky ? undefined : state.oneShotPending ? "next prompt" : state.turnActive ? "this turn" : undefined;
+  const label = `${theme.fg("accent", GLYPH.workflow)} ${theme.fg("accent", "dynamax")}`;
+  return mode ? `${label}${dot(theme)}${theme.fg("muted", mode)}` : label;
 }
 
 export function appendDynamaxSystemReminder(systemPrompt: string, state: DynamaxState): string {
@@ -145,24 +147,16 @@ export function appendDynamaxSystemReminder(systemPrompt: string, state: Dynamax
   return `${systemPrompt}\n\n${DYNAMAX_REMINDER.trim()}`;
 }
 
-export function appendDynamaxContextReminder(messages: AgentMessage[], state: DynamaxState): AgentMessage[] {
-  if (!state.sticky) return messages;
-  return [...messages, createDynamaxContextMessage()];
-}
-
-export function registerDynamax(
-  pi: ExtensionAPI,
-  shortcuts: DynamaxShortcuts = resolveDynamaxShortcuts(),
-  options: DynamaxRegistrationOptions = {},
-): void {
+export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, options: DynamaxRegistrationOptions): DynamaxHandle {
   const runtimes: DynamaxRuntimeStore = new Map();
   const effect = options.effect ?? resolveDynamaxEffect();
+  setWorkflowInspectorShortcut(shortcuts.inspector);
   let editorInstallation: DynamaxEditorInstallation | undefined;
-  const openInspector =
-    options.openInspector ??
-    ((ctx: ExtensionContext): void => {
-      ctx.ui.notify("No workflow inspector is available yet", "warning");
-    });
+  const markOneShot = (ctx: ExtensionContext): void => {
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    markDynamaxOneShot(runtime.state);
+    updateDynamaxSurfaces(ctx, runtime);
+  };
   const installEditor = (ctx: ExtensionContext): void => {
     if (ctx.mode !== "tui" || effect === "off") return;
     const previousFactory = ctx.ui.getEditorComponent();
@@ -229,7 +223,7 @@ export function registerDynamax(
 
   pi.on("session_start", (_event, ctx) => {
     installEditor(ctx);
-    updateDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx), shortcuts);
+    updateDynamaxSurfaces(ctx, getDynamaxRuntime(runtimes, ctx));
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
@@ -238,12 +232,7 @@ export function registerDynamax(
   });
 
   pi.on("input", (event, ctx) => {
-    if (event.source === "extension") return { action: "continue" };
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    if (hasDynamaxToken(event.text)) {
-      markDynamaxOneShot(runtime.state);
-      updateDynamaxSurfaces(ctx, runtime, shortcuts);
-    }
+    if (event.source !== "extension" && hasDynamaxToken(event.text)) markOneShot(ctx);
     return { action: "continue" };
   });
 
@@ -251,45 +240,21 @@ export function registerDynamax(
     const runtime = getDynamaxRuntime(runtimes, ctx);
     const systemPrompt = appendDynamaxSystemReminder(event.systemPrompt, runtime.state);
     if (systemPrompt === event.systemPrompt) return undefined;
-    updateDynamaxSurfaces(ctx, runtime, shortcuts);
+    updateDynamaxSurfaces(ctx, runtime);
     return { systemPrompt };
   });
 
   pi.on("agent_end", (_event, ctx) => {
     const runtime = getDynamaxRuntime(runtimes, ctx);
-    runtime.runningWorkflow = undefined;
     if (!runtime.state.sticky) runtime.state.turnActive = false;
-    updateDynamaxSurfaces(ctx, runtime, shortcuts);
-  });
-
-  pi.on("tool_execution_start", (event, ctx) => {
-    if (event.toolName !== "workflow") return undefined;
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    runtime.runningWorkflow = workflowLabel(event.args);
-    updateDynamaxSurfaces(ctx, runtime, shortcuts);
-    return undefined;
-  });
-
-  pi.on("tool_execution_end", (event, ctx) => {
-    if (event.toolName !== "workflow") return undefined;
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    runtime.runningWorkflow = undefined;
-    updateDynamaxSurfaces(ctx, runtime, shortcuts);
-    return undefined;
-  });
-
-  pi.on("context", (event, ctx) => {
-    const runtime = getDynamaxRuntime(runtimes, ctx);
-    const messages = appendDynamaxContextReminder(event.messages, runtime.state);
-    if (messages === event.messages) return undefined;
-    return { messages };
+    updateDynamaxSurfaces(ctx, runtime);
   });
 
   if (shortcuts.inspector) {
     pi.registerShortcut(shortcuts.inspector, {
       description: "Open workflow inspector",
       handler: async (ctx) => {
-        await openInspector(ctx);
+        await options.openInspector(ctx);
       },
     });
   }
@@ -306,13 +271,13 @@ export function registerDynamax(
       }
       if (action === "on") {
         enableDynamaxSticky(runtime.state);
-        updateDynamaxSurfaces(ctx, runtime, shortcuts);
+        updateDynamaxSurfaces(ctx, runtime);
         ctx.ui.notify("Dynamax workflow orchestration is on for this session", "info");
         return;
       }
       if (action === "off") {
         clearDynamax(runtime.state);
-        updateDynamaxSurfaces(ctx, runtime, shortcuts);
+        updateDynamaxSurfaces(ctx, runtime);
         ctx.ui.notify("Dynamax workflow orchestration is off", "info");
         return;
       }
@@ -323,44 +288,20 @@ export function registerDynamax(
       ctx.ui.notify("Usage: /workflow:dynamax [on|off|status]", "warning");
     },
   });
+
+  return { markOneShot };
 }
 
-export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime, shortcuts: DynamaxShortcuts): void {
+export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime): void {
   if (!ctx.hasUI) return;
-  if (!isDynamaxActive(runtime.state) && !runtime.runningWorkflow) {
+  if (!isDynamaxActive(runtime.state)) {
     clearDynamaxSurfaces(ctx);
     return;
   }
-
-  const status = dynamaxWidgetLine(runtime.state, shortcuts.inspector, runtime.runningWorkflow);
-  ctx.ui.setStatus(DYNAMAX_STATUS_KEY, status);
+  ctx.ui.setStatus(DYNAMAX_STATUS_KEY, dynamaxStatusText(runtime.state, ctx.ui.theme));
 }
 
 export function clearDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">): void {
   if (!ctx.hasUI) return;
   ctx.ui.setStatus(DYNAMAX_STATUS_KEY, undefined);
 }
-
-function workflowLabel(args: unknown): string {
-  if (!isRecord(args)) return "workflow";
-  const name = args.name;
-  if (typeof name === "string" && name.trim()) return name.trim();
-  const script = args.script;
-  if (typeof script === "string" && script.trim()) return "inline workflow";
-  return "workflow";
-}
-
-function createDynamaxContextMessage(): AgentMessage {
-  return {
-    role: "custom",
-    customType: DYNAMAX_CONTEXT_CUSTOM_TYPE,
-    content: DYNAMAX_REMINDER.trim(),
-    display: false,
-    details: { dynamax: true, sticky: true },
-    timestamp: Date.now(),
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}

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

@@ -8,15 +8,14 @@ import { abortReason, isWorkflowPauseError, linkAbortSignal, throwIfAborted } fr
 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 { 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 +96,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 +123,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 +131,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)}`);
@@ -206,69 +204,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 +288,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 +316,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)}`),
     },
   );
 }
@@ -491,24 +458,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/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;");