pi-workflow-engine 0.10.3 → 0.12.0

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

@@ -1,31 +1,18 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
-import { agentDetailParts, agentLabelColor, formatCount, formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
+import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
+import { agentDetailParts, agentLabelColor, formatCount, formatDuration, statusIcon } from "./workflow-format.ts";
 
-const MAX_WIDGET_LINES = 12;
-const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-export interface WorkflowWidget {
-  nextFrame(): void;
-  render(width: number, theme: Theme): string[];
-  invalidate(): void;
-}
-
-export function createWorkflowWidget(snapshotProvider: () => WorkflowProgressSnapshot): WorkflowWidget {
-  return new LiveWorkflowWidget(snapshotProvider);
-}
+const MAX_WIDGET_LINES = 10;
 
 export function renderWorkflowWidgetLines(
   snapshot: WorkflowProgressSnapshot,
-  frame: number,
-  width: number,
   theme: Theme,
 ): string[] {
-  const safeWidth = Math.max(1, width);
   const counts = countAgents(snapshot.phases);
   const active = counts.running + counts.queued;
   const elapsed = formatDuration((snapshot.doneAt ?? Date.now()) - snapshot.startedAt);
-  const spinner = active > 0 ? theme.fg("accent", SPINNER[frame % SPINNER.length]) : theme.fg("success", "✓");
+  const activity = active > 0 ? theme.fg("accent", "●") : theme.fg("success", "✓");
 
   const headingParts = [`${counts.done}/${counts.total} done`, elapsed];
   if (counts.running > 0) headingParts.unshift(`${counts.running} running`);
@@ -33,10 +20,7 @@ export function renderWorkflowWidgetLines(
   if (counts.failed > 0) headingParts.unshift(theme.fg("error", `${counts.failed} failed`));
 
   const lines: string[] = [
-    truncateDisplay(
-      `${spinner} ${theme.bold(snapshot.title)} ${theme.fg("dim", "·")} ${theme.fg("muted", snapshot.currentPhase)} ${theme.fg("dim", "·")} ${headingParts.join(` ${theme.fg("dim", "·")} `)}`,
-      safeWidth,
-    ),
+    `${activity} ${theme.bold(snapshot.title)} ${theme.fg("dim", "·")} ${theme.fg("muted", snapshot.currentPhase)} ${theme.fg("dim", "·")} ${headingParts.join(` ${theme.fg("dim", "·")} `)}`,
   ];
 
   const footer = footerLine(snapshot, theme);
@@ -46,53 +30,13 @@ export function renderWorkflowWidgetLines(
   const visibleBodyLinesToRender = reserveHiddenLine ? body.lines.slice(0, Math.max(0, bodyBudget - 1)) : body.lines;
   const hidden = body.hidden + (body.lines.length - visibleBodyLinesToRender.length);
 
-  for (const line of visibleBodyLinesToRender) lines.push(truncateDisplay(line, safeWidth));
+  lines.push(...visibleBodyLinesToRender);
   if (hidden > 0 && lines.length < MAX_WIDGET_LINES) {
-    lines.push(truncateDisplay(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden} more`)}`, safeWidth));
+    lines.push(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden} more`)}`);
   }
-  if (footer && lines.length < MAX_WIDGET_LINES) lines.push(truncateDisplay(footer, safeWidth));
-
-  return lines.slice(0, MAX_WIDGET_LINES).map((line) => truncateDisplay(line, safeWidth));
-}
-
-class LiveWorkflowWidget implements WorkflowWidget {
-  private frame = 0;
-  private cachedWidth: number | undefined;
-  private cachedFrame: number | undefined;
-  private cachedDoneAt: number | undefined;
-  private cachedLines: string[] | undefined;
-
-  constructor(private readonly snapshotProvider: () => WorkflowProgressSnapshot) {}
+  if (footer && lines.length < MAX_WIDGET_LINES) lines.push(footer);
 
-  nextFrame(): void {
-    this.frame = (this.frame + 1) % SPINNER.length;
-    this.invalidate();
-  }
-
-  render(width: number, theme: Theme): string[] {
-    const snapshot = this.snapshotProvider();
-    if (
-      this.cachedLines &&
-      this.cachedWidth === width &&
-      this.cachedFrame === this.frame &&
-      this.cachedDoneAt === snapshot.doneAt
-    ) {
-      return this.cachedLines;
-    }
-
-    this.cachedLines = renderWorkflowWidgetLines(snapshot, this.frame, width, theme);
-    this.cachedWidth = width;
-    this.cachedFrame = this.frame;
-    this.cachedDoneAt = snapshot.doneAt;
-    return this.cachedLines;
-  }
-
-  invalidate(): void {
-    this.cachedWidth = undefined;
-    this.cachedFrame = undefined;
-    this.cachedDoneAt = undefined;
-    this.cachedLines = undefined;
-  }
+  return lines.slice(0, MAX_WIDGET_LINES);
 }
 
 interface AgentCounts {
@@ -173,9 +117,10 @@ function agentLine(agent: AgentRowSnapshot, theme: Theme): string {
 }
 
 function footerLine(snapshot: WorkflowProgressSnapshot, theme: Theme): string | undefined {
+  const usage = formatWorkflowUsageLine(snapshot.usage);
   const counters = snapshot.counters.slice(0, 4).map((counter) => `${counter.label} ${formatCount(counter.value)}`);
   const latestLog = snapshot.logs[snapshot.logs.length - 1];
-  const parts = counters.length > 0 ? counters : [];
+  const parts = usage ? [usage, ...counters] : counters;
   if (latestLog) parts.push(latestLog);
   if (parts.length === 0) return undefined;
   return `${theme.fg("dim", "└─")} ${theme.fg("dim", parts.join(" · "))}`;

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

@@ -0,0 +1,8 @@
+/** Read an unknown thrown value without allowing hostile coercion to mask the original failure. */
+export function unknownErrorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

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

@@ -6,12 +6,22 @@ export interface WorkflowUsageCost {
   readonly total: number;
 }
 
+export type WorkflowUsageCoverage = "none" | "partial" | "complete";
+
+export interface WorkflowUsageComponentCoverage {
+  readonly input: WorkflowUsageCoverage;
+  readonly output: WorkflowUsageCoverage;
+  readonly cacheRead: WorkflowUsageCoverage;
+  readonly cacheWrite: WorkflowUsageCoverage;
+}
+
 export interface WorkflowUsageTotals {
   readonly input: number;
   readonly output: number;
   readonly cacheRead: number;
   readonly cacheWrite: number;
   readonly totalTokens: number;
+  readonly coverage: WorkflowUsageComponentCoverage;
   readonly cost: WorkflowUsageCost;
 }
 
@@ -36,7 +46,21 @@ export interface WorkflowUsageSink {
 }
 
 const ZERO_COST: WorkflowUsageCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
-const ZERO_TOTALS: WorkflowUsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: ZERO_COST };
+const ZERO_COVERAGE: WorkflowUsageComponentCoverage = {
+  input: "none",
+  output: "none",
+  cacheRead: "none",
+  cacheWrite: "none",
+};
+const ZERO_TOTALS: WorkflowUsageTotals = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  coverage: ZERO_COVERAGE,
+  cost: ZERO_COST,
+};
 
 interface AssistantUsageMessage {
   readonly provider?: string;
@@ -47,6 +71,8 @@ interface AssistantUsageMessage {
 export class WorkflowUsageRecorder implements WorkflowUsageSink {
   private readonly agents: WorkflowAgentUsage[] = [];
 
+  constructor(private readonly onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void) {}
+
   recordAgentSession(input: { label: string; phase?: string; messages: readonly unknown[] }): void {
     const assistantMessages = input.messages.flatMap((message) => {
       const parsed = parseAssistantUsageMessage(message);
@@ -64,6 +90,7 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
       assistantMessages: assistantMessages.length,
       usage,
     });
+    this.onSnapshot?.(this.snapshot());
   }
 
   snapshot(): WorkflowUsageSnapshot {
@@ -79,8 +106,8 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
   }
 }
 
-export function createWorkflowUsageRecorder(): WorkflowUsageSink {
-  return new WorkflowUsageRecorder();
+export function createWorkflowUsageRecorder(onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void): WorkflowUsageSink {
+  return new WorkflowUsageRecorder(onSnapshot);
 }
 
 export function emptyWorkflowUsageTotals(): WorkflowUsageTotals {
@@ -96,19 +123,45 @@ export function isWorkflowUsageSnapshot(value: unknown): value is WorkflowUsageS
 
 export function hasWorkflowUsage(snapshot: unknown): snapshot is WorkflowUsageSnapshot {
   if (!isWorkflowUsageSnapshot(snapshot)) return false;
-  return snapshot.assistantMessages > 0 || snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
+  return snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
 }
 
 export function formatWorkflowUsageLine(snapshot: unknown): string | undefined {
   if (!hasWorkflowUsage(snapshot)) return undefined;
-  const parts = [`↑${formatUsageCount(snapshot.totals.input)}`, `↓${formatUsageCount(snapshot.totals.output)}`];
-  if (snapshot.totals.cacheRead > 0) parts.push(`R${formatUsageCount(snapshot.totals.cacheRead)}`);
-  if (snapshot.totals.cacheWrite > 0) parts.push(`W${formatUsageCount(snapshot.totals.cacheWrite)}`);
+  const parts = formatWorkflowUsageComponents(snapshot.totals);
   parts.push(`cost $${snapshot.totals.cost.total.toFixed(3)}`);
   parts.push(`agents ${snapshot.agents.length}`);
   return `Usage: ${parts.join(" · ")}`;
 }
 
+function formatWorkflowUsageComponents(totals: WorkflowUsageTotals): string[] {
+  const parts: string[] = [];
+  const completeCacheBreakdown =
+    totals.coverage.cacheRead === "complete" && totals.coverage.cacheWrite === "complete";
+  appendUsageComponent(parts, completeCacheBreakdown ? "fresh" : "input", totals.input, totals.coverage.input);
+  appendUsageComponent(parts, "cache read", totals.cacheRead, totals.coverage.cacheRead);
+  appendUsageComponent(parts, "cache write", totals.cacheWrite, totals.coverage.cacheWrite);
+  appendUsageComponent(parts, "output", totals.output, totals.coverage.output);
+
+  const knownComponents = totals.input + totals.output + totals.cacheRead + totals.cacheWrite;
+  if (parts.length === 0 && totals.totalTokens > 0) parts.push(`tokens ${formatUsageCount(totals.totalTokens)}`);
+  else if (!hasCompleteCoverage(totals.coverage) && totals.totalTokens !== knownComponents) {
+    parts.push(`total ${formatUsageCount(totals.totalTokens)}`);
+  }
+  return parts;
+}
+
+function appendUsageComponent(
+  parts: string[],
+  label: string,
+  value: number,
+  coverage: WorkflowUsageCoverage,
+): void {
+  if (value <= 0 || coverage === "none") return;
+  const count = formatUsageCount(value);
+  parts.push(`${label} ${coverage === "partial" ? `≥${count}` : count}`);
+}
+
 function isWorkflowAgentUsage(value: unknown): value is WorkflowAgentUsage {
   if (!isRecord(value)) return false;
   if (typeof value.label !== "string") return false;
@@ -126,9 +179,20 @@ function isWorkflowUsageTotals(value: unknown): value is WorkflowUsageTotals {
   if (finiteNumber(value.cacheRead) === undefined) return false;
   if (finiteNumber(value.cacheWrite) === undefined) return false;
   if (finiteNumber(value.totalTokens) === undefined) return false;
+  if (!isWorkflowUsageCoverage(value.coverage)) return false;
   return isWorkflowUsageCost(value.cost);
 }
 
+function isWorkflowUsageCoverage(value: unknown): value is WorkflowUsageComponentCoverage {
+  if (!isRecord(value)) return false;
+  return (
+    isCoverageValue(value.input) &&
+    isCoverageValue(value.output) &&
+    isCoverageValue(value.cacheRead) &&
+    isCoverageValue(value.cacheWrite)
+  );
+}
+
 function isWorkflowUsageCost(value: unknown): value is WorkflowUsageCost {
   if (!isRecord(value)) return false;
   return (
@@ -158,14 +222,26 @@ function parseUsageTotals(value: unknown): WorkflowUsageTotals | undefined {
   const output = finiteNumber(value.output);
   const cacheRead = finiteNumber(value.cacheRead);
   const cacheWrite = finiteNumber(value.cacheWrite);
+  const reportedTotal = finiteNumber(value.totalTokens);
   const cost = parseUsageCost(value.cost);
-  if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || !cost) return undefined;
+  if (!cost) return undefined;
+  if (input === undefined && output === undefined && cacheRead === undefined && cacheWrite === undefined && reportedTotal === undefined) {
+    return undefined;
+  }
+  const coverage: WorkflowUsageComponentCoverage = {
+    input: input === undefined ? "none" : "complete",
+    output: output === undefined ? "none" : "complete",
+    cacheRead: cacheRead === undefined ? "none" : "complete",
+    cacheWrite: cacheWrite === undefined ? "none" : "complete",
+  };
+  const componentTotal = (input ?? 0) + (output ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
   return {
-    input,
-    output,
-    cacheRead,
-    cacheWrite,
-    totalTokens: input + output + cacheRead + cacheWrite,
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    totalTokens: hasCompleteCoverage(coverage) ? componentTotal : (reportedTotal ?? componentTotal),
+    coverage,
     cost,
   };
 }
@@ -177,12 +253,20 @@ function parseUsageCost(value: unknown): WorkflowUsageCost | undefined {
   const cacheRead = finiteNumber(value.cacheRead);
   const cacheWrite = finiteNumber(value.cacheWrite);
   const total = finiteNumber(value.total);
-  if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || total === undefined) return undefined;
-  return { input, output, cacheRead, cacheWrite, total };
+  if (total === undefined) return undefined;
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    total,
+  };
 }
 
 function sumTotals(values: readonly WorkflowUsageTotals[]): WorkflowUsageTotals {
-  return values.reduce((sum, value) => addTotals(sum, value), emptyWorkflowUsageTotals());
+  const [first, ...rest] = values;
+  if (!first) return emptyWorkflowUsageTotals();
+  return rest.reduce(addTotals, cloneTotals(first));
 }
 
 function addTotals(left: WorkflowUsageTotals, right: WorkflowUsageTotals): WorkflowUsageTotals {
@@ -192,6 +276,12 @@ function addTotals(left: WorkflowUsageTotals, right: WorkflowUsageTotals): Workf
     cacheRead: left.cacheRead + right.cacheRead,
     cacheWrite: left.cacheWrite + right.cacheWrite,
     totalTokens: left.totalTokens + right.totalTokens,
+    coverage: {
+      input: combineCoverage(left.coverage.input, right.coverage.input),
+      output: combineCoverage(left.coverage.output, right.coverage.output),
+      cacheRead: combineCoverage(left.coverage.cacheRead, right.coverage.cacheRead),
+      cacheWrite: combineCoverage(left.coverage.cacheWrite, right.coverage.cacheWrite),
+    },
     cost: {
       input: left.cost.input + right.cost.input,
       output: left.cost.output + right.cost.output,
@@ -209,10 +299,28 @@ function cloneTotals(value: WorkflowUsageTotals): WorkflowUsageTotals {
     cacheRead: value.cacheRead,
     cacheWrite: value.cacheWrite,
     totalTokens: value.totalTokens,
+    coverage: { ...value.coverage },
     cost: { ...value.cost },
   };
 }
 
+function combineCoverage(left: WorkflowUsageCoverage, right: WorkflowUsageCoverage): WorkflowUsageCoverage {
+  return left === right ? left : "partial";
+}
+
+function hasCompleteCoverage(coverage: WorkflowUsageComponentCoverage): boolean {
+  return (
+    coverage.input === "complete" &&
+    coverage.output === "complete" &&
+    coverage.cacheRead === "complete" &&
+    coverage.cacheWrite === "complete"
+  );
+}
+
+function isCoverageValue(value: unknown): value is WorkflowUsageCoverage {
+  return value === "none" || value === "partial" || value === "complete";
+}
+
 function formatUsageCount(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;

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

@@ -1,6 +1,6 @@
 import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type AdvisoryFinding, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
 import { compactResults } from "./concurrency.ts";
-import type { AgentOptions, WorkflowApi, WorkflowProgressEvent } from "./types.ts";
+import type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
 
 export interface AdvisoryLens {
   label: string;
@@ -27,6 +27,26 @@ export const DEFAULT_ADVISORY_TOOLS: NonNullable<AgentOptions["tools"]> = ["read
 /** Dynamically include installed grep/find/search-like extension tools. */
 export const DEFAULT_ADVISORY_TOOL_HINTS: NonNullable<AgentOptions["toolHints"]> = ["search"];
 
+export function emptyAdvisoryReport<Stats extends WorkflowRunStats>(
+  summary: string,
+  nextSteps: string[],
+  stats: Stats,
+): AdvisoryReport & { stats: Stats } {
+  return { summary, findings: [], nextSteps, stats };
+}
+
+export function publishVerifiedKeptProgress(
+  api: Pick<WorkflowApi, "progress" | "log">,
+  verified: number,
+  kept: number,
+): void {
+  api.progress({ type: "counter", key: "verified", label: "verified", value: verified });
+  api.progress({ type: "counter", key: "kept", label: "kept", value: kept });
+  api.progress({ type: "summary", key: "verified", value: verified });
+  api.progress({ type: "summary", key: "kept", value: kept });
+  api.log(`${verified} verified → ${kept} kept`);
+}
+
 export type AdvisorySchedulingMode = "pipeline" | "finder-barrier";
 
 export interface LensVerificationPipelineOptions<Lens extends AdvisoryLens, Verified extends AdvisoryVerified> {
@@ -85,7 +105,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       label: `find:${lens.label}`,
       tools,
       toolHints,
-      thinkingLevel: "low",
+      profile: "small",
       schema: AdvisoryCandidatesSchema,
     });
     const candidates = (found?.candidates ?? []).slice(0, perLens);
@@ -122,7 +142,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       label: `verify:${location.file.split("/").pop() ?? location.file}`,
       tools,
       toolHints,
-      thinkingLevel: "low",
+      profile: "small",
       schema: AdvisoryVerdictSchema,
     });
     if (!judged) return null;

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

@@ -0,0 +1,121 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedWorkflowRunOptions } from "./options.ts";
+import type { PerfAggregate, PerfSink, PerfSnapshot } from "./perf.ts";
+import type { WorkflowProgressSnapshot } from "./progress-types.ts";
+import type {
+  LoadedWorkflow,
+  WorkflowProgressSource,
+  WorkflowRef,
+  WorkflowRunMetadata,
+} from "./types.ts";
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+export interface WorkflowPerfDetails {
+  readonly enabled: boolean;
+  readonly startedAt: number;
+  readonly aggregates: readonly PerfAggregate[];
+}
+
+export interface WorkflowResultEnvelope {
+  readonly name: string;
+  readonly result: unknown;
+  readonly completedAt: number;
+  readonly usage?: WorkflowUsageSnapshot;
+  readonly perf?: WorkflowPerfDetails;
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export type ResolvedWorkflowRunner = (
+  ctx: ExtensionContext,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+) => Promise<unknown>;
+
+export interface WorkflowExecutionInput {
+  readonly ctx: ExtensionContext;
+  readonly name: string;
+  readonly mod: LoadedWorkflow;
+  readonly args: string;
+  readonly options: ResolvedWorkflowRunOptions;
+  readonly perfRecorder?: PerfSink;
+  readonly runResolvedWorkflow: ResolvedWorkflowRunner;
+  readonly resolveWorkflow: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
+  readonly onProgressSource?: (source: WorkflowProgressSource | undefined) => void | Promise<void>;
+  readonly onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
+}
+
+export interface WorkflowExecution {
+  readonly metadata?: WorkflowRunMetadata;
+  readonly envelope: WorkflowResultEnvelope;
+}
+
+/** Shared command/tool execution path. The engine remains lazy-loaded by the caller. */
+export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+  let perfSnapshot: PerfSnapshot | undefined;
+  let usageSnapshot: WorkflowUsageSnapshot | undefined;
+  let runMetadata: WorkflowRunMetadata | undefined;
+  const { options } = input;
+  const runOptions: ResolvedWorkflowRunOptions = {
+    ...options,
+    perfRecorder: input.perfRecorder,
+    resolveWorkflow: input.resolveWorkflow,
+    onProgressSource(source) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSource?.(source),
+        () => options.onProgressSource?.(source),
+      );
+    },
+    onPerfSnapshot(snapshot) {
+      perfSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onPerfSnapshot?.(snapshot));
+    },
+    onUsageSnapshot(snapshot) {
+      usageSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onUsageSnapshot?.(snapshot));
+    },
+    onRunMetadata(metadata) {
+      runMetadata = metadata;
+      return notifyLifecycleObservers(() => options.onRunMetadata?.(metadata));
+    },
+    onProgressSnapshot(snapshot) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSnapshot?.(snapshot),
+        () => options.onProgressSnapshot?.(snapshot),
+      );
+    },
+  };
+  const result = await input.runResolvedWorkflow(input.ctx, input.mod, input.args, runOptions);
+  const perf = compactPerfSnapshot(perfSnapshot);
+  return {
+    metadata: runMetadata,
+    envelope: {
+      name: input.name,
+      result,
+      completedAt: Date.now(),
+      usage: usageSnapshot,
+      perf,
+      runId: runMetadata?.runId,
+      resumedFromRunId: runMetadata?.resumedFromRunId,
+    },
+  };
+}
+
+function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
+  if (!snapshot?.enabled) return undefined;
+  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
+}
+
+async function notifyLifecycleObservers(...observers: ReadonlyArray<() => void | Promise<void>>): Promise<void> {
+  const failures: unknown[] = [];
+  for (const observer of observers) {
+    try {
+      await observer();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, "Workflow lifecycle observers failed");
+}

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

@@ -1,4 +1,10 @@
-import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+import type {
+  LoadedWorkflow,
+  WorkflowMeta,
+  WorkflowModule,
+  WorkflowSourceIdentity,
+} from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
 
 type WorkflowMetaCandidate = {
   readonly name?: unknown;
@@ -30,6 +36,18 @@ export function parseWorkflowModule(value: unknown): { module: WorkflowModule }
   return { module: { meta: parsedMeta.meta, default: candidate.default } };
 }
 
+/** Attach engine-owned source provenance after an authored module has been validated. */
+export function loadWorkflow(
+  module: WorkflowModule,
+  source: WorkflowSourceIdentity,
+  isolatedWorktreeBaseline?: WorktreeBaseline,
+): LoadedWorkflow {
+  const loaded = { meta: module.meta, default: module.default, source };
+  return isolatedWorktreeBaseline === undefined
+    ? loaded
+    : { ...loaded, isolatedWorktreeBaseline };
+}
+
 function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
   if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
 

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

@@ -0,0 +1,72 @@
+import type { WorkflowBackgroundOrigin } from "./types.ts";
+import type { WorkflowRunRecord } from "./workflow-run-record.ts";
+
+const MAX_BACKGROUND_TEXT = 2_048;
+
+export type WorkflowRunDelivery =
+  | { readonly state: "pending" }
+  | { readonly state: "delivered"; readonly deliveredAt: number }
+  | { readonly state: "unavailable"; readonly attemptedAt: number; readonly message: string };
+
+export interface PersistedWorkflowBackground {
+  readonly origin: WorkflowBackgroundOrigin;
+  readonly delivery: WorkflowRunDelivery;
+}
+
+export function createPersistedWorkflowBackground(
+  origin: WorkflowBackgroundOrigin | undefined,
+): PersistedWorkflowBackground | undefined {
+  if (!origin) return undefined;
+  return {
+    origin: {
+      sessionId: boundedText(origin.sessionId),
+      requestedAt: origin.requestedAt,
+    },
+    delivery: { state: "pending" },
+  };
+}
+
+export function updateWorkflowRunDelivery(
+  record: WorkflowRunRecord,
+  delivery: WorkflowRunDelivery,
+  at = Date.now(),
+): WorkflowRunRecord {
+  if (!record.background) throw new Error(`Workflow run ${record.runId} is not a background run.`);
+  return {
+    ...record,
+    updatedAt: at,
+    background: {
+      origin: record.background.origin,
+      delivery: delivery.state === "unavailable"
+        ? { ...delivery, message: boundedText(delivery.message) }
+        : delivery,
+    },
+  };
+}
+
+export function isPersistedWorkflowBackground(value: unknown): value is PersistedWorkflowBackground {
+  if (!isRecord(value) || !isRecord(value.origin) || !isRecord(value.delivery)) return false;
+  if (typeof value.origin.sessionId !== "string" || !isFiniteNumber(value.origin.requestedAt)) return false;
+  switch (value.delivery.state) {
+    case "pending":
+      return true;
+    case "delivered":
+      return isFiniteNumber(value.delivery.deliveredAt);
+    case "unavailable":
+      return isFiniteNumber(value.delivery.attemptedAt) && typeof value.delivery.message === "string";
+    default:
+      return false;
+  }
+}
+
+function boundedText(value: string): string {
+  return value.length <= MAX_BACKGROUND_TEXT ? value : `${value.slice(0, MAX_BACKGROUND_TEXT - 1)}…`;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}