pi-workflow-engine 0.12.0 → 1.0.0

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

@@ -0,0 +1,79 @@
+import { formatAdvisoryLocation, isAdvisoryReport, type AdvisoryFinding, type AdvisoryReport } from "./advisory-schema.ts";
+import { isRecord } from "./guards.ts";
+import { toReviewIssues } from "./review/review-issues.ts";
+import { formatPerfSummary } from "./perf.ts";
+import { prettyJson } from "./text.ts";
+import { formatWorkflowUsageLine } from "./usage.ts";
+import { workflowResultSummary, type WorkflowResultEnvelope } from "./workflow-execution.ts";
+
+/** Cap on the result JSON copied into the host agent's context; the run record keeps the full value. */
+const MAX_CONTEXT_RESULT_JSON_CHARS = 20_000;
+
+/** The host model only sees this text, never the envelope `details`, so it carries every result field. */
+export function formatWorkflowResultForContext(envelope: WorkflowResultEnvelope): string {
+  const details = formatWorkflowDetailLines(envelope);
+  return `## Workflow: ${envelope.name}\n\n${formatResultForContext(envelope.result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
+}
+
+/** Run id, usage and perf lines appended for the host model. */
+function formatWorkflowDetailLines(envelope: WorkflowResultEnvelope): string[] {
+  const run = envelope.runId
+    ? envelope.resumedFromRunId ? `Run: ${envelope.runId} (resumed from ${envelope.resumedFromRunId})` : `Run: ${envelope.runId}`
+    : undefined;
+  return [
+    run,
+    formatWorkflowUsageLine(envelope.usage),
+    envelope.perf ? formatPerfSummary(envelope.perf.aggregates) : undefined,
+  ].filter((line): line is string => line !== undefined);
+}
+
+function formatResultForContext(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result);
+  const summary = workflowResultSummary(result);
+  if (summary !== undefined && isRecord(result) && Object.keys(result).length === 1) return summary;
+  const json = formatResultJson(result);
+  if (json === undefined) return summary ?? "Workflow finished.";
+  return summary === undefined ? json : `${summary}\n\n${json}`;
+}
+
+function formatAdvisoryReportForContext(report: AdvisoryReport): string {
+  const lines = [report.summary];
+  const issues = toReviewIssues(report);
+  if (issues.length > 0) {
+    lines.push("", "Findings:");
+    for (const { id, finding } of issues) {
+      lines.push(
+        `\n### ${id}: ${finding.summary}`,
+        `- Severity: ${finding.severity}`,
+        `- Confidence: ${finding.confidence}`,
+        `- Category: ${finding.category}`,
+        `- Location: ${formatFindingLocations(finding)}`,
+        `- Impact: ${finding.impact}`,
+        `- Evidence: ${finding.evidence.length > 0 ? finding.evidence.join("; ") : "(none cited)"}`,
+        `- Recommendation: ${finding.recommendation}`,
+      );
+    }
+  }
+  if (report.gaps && report.gaps.length > 0) {
+    lines.push("", "Coverage gaps:", ...report.gaps.map((gap) => `- ${gap}`));
+  }
+  if (report.nextSteps.length > 0) {
+    lines.push("", "Next steps:", ...report.nextSteps.map((step) => `- ${step}`));
+  }
+  return lines.join("\n");
+}
+
+function formatResultJson(result: unknown): string | undefined {
+  if (result === null || result === undefined) return undefined;
+  const json = prettyJson(result);
+  if (json === undefined) return undefined;
+  if (json.length <= MAX_CONTEXT_RESULT_JSON_CHARS) return `Result:\n\`\`\`json\n${json}\n\`\`\``;
+  return `Result (first ${MAX_CONTEXT_RESULT_JSON_CHARS} of ${json.length} characters; truncated, the run record holds the full value):\n\`\`\`json\n${json.slice(0, MAX_CONTEXT_RESULT_JSON_CHARS)}\n\`\`\``;
+}
+
+/** The review anchor that the findings viewer and PR comments cite comes first, then every other cited location. */
+function formatFindingLocations(finding: AdvisoryFinding): string {
+  const locations = finding.reviewAnchor ? [finding.reviewAnchor, ...finding.locations] : finding.locations;
+  return [...new Set(locations.map(formatAdvisoryLocation))].join(", ");
+}

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

@@ -1,3 +1,5 @@
+import { isFiniteNumber, isRecord } from "./guards.ts";
+import { truncateText } from "./text.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import type { WorkflowRunRecord } from "./workflow-run-record.ts";
 
@@ -19,7 +21,7 @@ export function createPersistedWorkflowBackground(
   if (!origin) return undefined;
   return {
     origin: {
-      sessionId: boundedText(origin.sessionId),
+      sessionId: truncateText(origin.sessionId, MAX_BACKGROUND_TEXT),
       requestedAt: origin.requestedAt,
     },
     delivery: { state: "pending" },
@@ -38,7 +40,7 @@ export function updateWorkflowRunDelivery(
     background: {
       origin: record.background.origin,
       delivery: delivery.state === "unavailable"
-        ? { ...delivery, message: boundedText(delivery.message) }
+        ? { ...delivery, message: truncateText(delivery.message, MAX_BACKGROUND_TEXT) }
         : delivery,
     },
   };
@@ -58,15 +60,3 @@ export function isPersistedWorkflowBackground(value: unknown): value is Persiste
       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);
-}

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

@@ -18,19 +18,21 @@ import {
   isWorkflowRunLifecycleAction,
   parseWorkflowRunsCommand,
   retainedWorkflowRunOutcome,
+  supersedingRuns,
   WORKFLOW_RUN_ACTIONS,
   WORKFLOW_RUN_HISTORY_LIMIT,
+  type WorkflowRunActionContext,
   type WorkflowRunLifecycleAction,
 } from "./workflow-run-history.ts";
-import { transitionWorkflowRun, type WorkflowRunRecord } from "./workflow-run-record.ts";
+import { stopWorkflowRunRecord, type WorkflowRunRecord } from "./workflow-run-record.ts";
 import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
-import { emptyWorkflowUsageTotals } from "./usage.ts";
 import {
   WorkflowUsageLimitScheduler,
   type WorkflowUsageLimitSchedulerClock,
 } from "./workflow-usage-limit-scheduler.ts";
-import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { showWorkflowInspector } from "./ui/workflow-inspector.ts";
+import { WorkflowRunsBrowser, type WorkflowRunsBrowserChoice } from "./ui/workflow-runs-browser.ts";
 import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./ui/workflow-viewer-layout.ts";
 import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
 
@@ -77,8 +79,10 @@ export class WorkflowRunController {
     this.completionContext = { cwd: ctx.cwd, sessionManager: ctx.sessionManager };
     this.usageLimitScheduler.activateSession(ctx);
     try {
-      for (const record of await this.storeForCwd(ctx.cwd).list()) {
-        if (canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
+      const records = await this.storeForCwd(ctx.cwd).list();
+      const resumed = resumedRunIds(records);
+      for (const record of records) {
+        if (!resumed.has(record.runId) && canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
       }
     } catch (error) {
       this.log(`[workflow] provider-limit recovery could not load run history: ${unknownErrorMessage(error)}`);
@@ -101,11 +105,12 @@ export class WorkflowRunController {
       return;
     }
     if (!ctx.hasUI) {
-      const records = await this.listRecent(ctx.cwd);
-      ctx.ui.notify(formatWorkflowRunHistory(records, this.background.activeRunIds(ctx)), "info");
+      const { records, runs } = await this.history(ctx);
+      ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
       return;
     }
-    await this.openRunSelector(ctx);
+    if (ctx.mode === "tui") await this.openRunsBrowser(ctx);
+    else await this.openRunSelector(ctx);
   }
 
   async inspectStoredRun(ctx: ExtensionContext, runId: string): Promise<boolean> {
@@ -115,17 +120,35 @@ export class WorkflowRunController {
     return true;
   }
 
-  private async openRunSelector(ctx: ExtensionCommandContext): Promise<void> {
+  /** The TUI runs overlay; it reopens on the same run after each action until closed. */
+  private async openRunsBrowser(ctx: ExtensionCommandContext): Promise<void> {
+    let initialRunId: string | undefined;
     while (true) {
-      const records = await this.listRecent(ctx.cwd);
-      const active = this.background.activeRunIds(ctx);
+      const { records, runs } = await this.history(ctx);
       if (records.length === 0) {
-        ctx.ui.notify(formatWorkflowRunHistory(records, active), "info");
+        ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
         return;
       }
-      const options = records.map((record) =>
-        formatWorkflowRunSummary(record, active.has(record.runId))
+      const choice = await ctx.ui.custom<WorkflowRunsBrowserChoice | undefined>(
+        (...[tui, theme, , done]) =>
+          new WorkflowRunsBrowser({ records, runs }, tui, theme, done, { initialRunId, refresh: () => this.history(ctx) }),
+        WORKFLOW_VIEWER_OVERLAY_OPTIONS,
       );
+      if (!choice) return;
+      initialRunId = choice.runId;
+      await this.perform(choice.action, choice.runId, ctx);
+    }
+  }
+
+  /** Two native selects (run, then action) for UI hosts that cannot show custom components, such as RPC. */
+  private async openRunSelector(ctx: ExtensionCommandContext): Promise<void> {
+    while (true) {
+      const { records, runs } = await this.history(ctx);
+      if (records.length === 0) {
+        ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
+        return;
+      }
+      const options = records.map((record) => formatWorkflowRunSummary(record, runs));
       const selected = await ctx.ui.select("Workflow Runs", options);
       if (!selected) return;
       const selectedIndex = options.indexOf(selected);
@@ -135,7 +158,7 @@ export class WorkflowRunController {
         ctx.ui.notify("The selected workflow run is no longer available.", "warning");
         continue;
       }
-      const actions = availableWorkflowRunActions(record, active.has(record.runId));
+      const actions = availableWorkflowRunActions(record, runs);
       const selectedAction = await ctx.ui.select(
         `${record.workflow.name} · ${record.runId}`,
         [...actions],
@@ -149,22 +172,10 @@ export class WorkflowRunController {
 
   private async inspect(record: WorkflowRunRecord, ctx: ExtensionContext): Promise<void> {
     if (!ctx.hasUI || ctx.mode !== "tui") {
-      ctx.ui.notify(
-        formatWorkflowRunDetails(record, this.background.activeRunIds(ctx).has(record.runId)),
-        "info",
-      );
+      ctx.ui.notify(formatWorkflowRunDetails(record, (await this.history(ctx)).runs), "info");
       return;
     }
-    await ctx.ui.custom<void>(
-      (tui, theme, _keybindings, done) => new WorkflowInspector(
-        () => record.progress,
-        tui,
-        theme,
-        () => done(undefined),
-        { label: `${record.state.toUpperCase()} outcome`, text: retainedWorkflowRunOutcome(record) },
-      ),
-      WORKFLOW_VIEWER_OVERLAY_OPTIONS,
-    );
+    await showWorkflowInspector(ctx.ui, () => record.progress, { text: retainedWorkflowRunOutcome(record), state: record.state });
   }
 
   private async perform(
@@ -181,12 +192,15 @@ export class WorkflowRunController {
       await this.inspect(record, ctx);
       return;
     }
-    const available = availableWorkflowRunActions(
-      record,
-      this.background.activeRunIds(ctx).has(record.runId),
-    );
-    if (!available.includes(action)) {
-      ctx.ui.notify(`Action ${action} is not available for ${record.state} run ${runId}.`, "warning");
+    const { runs } = await this.history(ctx);
+    if (!availableWorkflowRunActions(record, runs).includes(action)) {
+      const resumedAs = record.state === "paused" && action === "resume" ? runs.resumedAs.get(runId) : undefined;
+      ctx.ui.notify(
+        resumedAs
+          ? `Workflow run ${runId} was already resumed as ${resumedAs}.`
+          : `Action ${action} is not available for ${record.state} run ${runId}.`,
+        "warning",
+      );
       return;
     }
 
@@ -194,17 +208,7 @@ export class WorkflowRunController {
       if (action === "stop") {
         if (record.state === "paused") {
           this.usageLimitScheduler.cancel(runId);
-          const stopped = transitionWorkflowRun(record, {
-            state: "stopped",
-            progress: record.progress,
-            usage: record.usage ?? record.progress.usage ?? {
-              agents: [],
-              totals: emptyWorkflowUsageTotals(),
-              assistantMessages: 0,
-            },
-            error: new Error("Workflow stopped by user."),
-          });
-          await this.storeForCwd(ctx.cwd).save(stopped);
+          await this.storeForCwd(ctx.cwd).save(stopWorkflowRunRecord(record));
           await this.background.durableRunSettled(ctx, runId);
           ctx.ui.notify(`Workflow run ${runId} is now stopped.`, "info");
           return;
@@ -227,10 +231,7 @@ export class WorkflowRunController {
     action: "resume" | "restart",
   ): Promise<string> {
     const unavailable = backgroundUnavailableResult(ctx.mode);
-    if (unavailable) {
-      const first = unavailable.content[0];
-      throw new Error(first?.type === "text" ? first.text : "background workflows are unavailable");
-    }
+    if (unavailable) throw new Error(unavailable.content[0].text);
     const workflow = await this.dependencies.resolveWorkflow(record.workflow.name);
     if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
     if (workflow.source.kind !== "file") {
@@ -243,7 +244,6 @@ export class WorkflowRunController {
       throw new Error("workflow source changed, so journal replay cannot resume safely");
     }
     const options = resolveWorkflowRunOptions({
-      inspect: false,
       perf: record.options.perf,
       concurrency: record.options.concurrency,
       parallelSubmissionLimit: record.options.parallelSubmissionLimit ?? undefined,
@@ -257,7 +257,6 @@ export class WorkflowRunController {
         ? (record.state === "paused" ? record.pause?.attempt : undefined) ?? record.options.usageLimitAttempt
         : 0,
       budget: record.options.budget ?? undefined,
-      resultViewer: "skip",
       resumeFromRunId: action === "resume" ? record.runId : undefined,
     });
     const result = await startBackgroundWorkflowTool({
@@ -268,8 +267,7 @@ export class WorkflowRunController {
       execute: (backgroundCtx, backgroundOptions) =>
         this.dependencies.execute(backgroundCtx, workflow.meta.name, workflow, backgroundOptions),
     });
-    const first = result.content[0];
-    const message = first?.type === "text" ? first.text : `Workflow ${action} started.`;
+    const message = result.content[0].text;
     if (typeof result.details.error === "string") throw new Error(message);
     return message;
   }
@@ -282,6 +280,7 @@ export class WorkflowRunController {
       || !record.pause.autoResume
       || record.pause.attempt !== attempt
       || !canRelaunchWorkflowRun(record)
+      || resumedRunIds(await this.storeForCwd(ctx.cwd).list()).has(runId)
     ) {
       return;
     }
@@ -298,11 +297,17 @@ export class WorkflowRunController {
     return await this.storeForCwd(cwd).load(runId);
   }
 
-  private async listRecent(cwd: string): Promise<WorkflowRunRecord[]> {
-    const records = await this.storeForCwd(cwd).list();
-    return records
-      .sort((left, right) => right.createdAt - left.createdAt)
-      .slice(0, WORKFLOW_RUN_HISTORY_LIMIT);
+  /** The most recent runs and what their actions depend on, from one store listing. */
+  private async history(
+    ctx: WorkflowRunCompletionContext,
+  ): Promise<{ readonly records: WorkflowRunRecord[]; readonly runs: WorkflowRunActionContext }> {
+    const records = await this.storeForCwd(ctx.cwd).list();
+    return {
+      records: [...records]
+        .sort((left, right) => right.createdAt - left.createdAt)
+        .slice(0, WORKFLOW_RUN_HISTORY_LIMIT),
+      runs: { activeRunIds: this.background.activeRunIds(ctx), resumedAs: supersedingRuns(records) },
+    };
   }
 
   async argumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
@@ -314,12 +319,11 @@ export class WorkflowRunController {
     if (parts.completed.length !== 1 || !ctx) return null;
     const action = parts.completed[0];
     if (!action || !isWorkflowRunLifecycleAction(action)) return null;
-    const records = await this.listRecent(ctx.cwd);
-    const active = this.background.activeRunIds(ctx);
+    const { records, runs } = await this.history(ctx);
     return completeCurrentArgument(
       argumentPrefix,
       records
-        .filter((record) => availableWorkflowRunActions(record, active.has(record.runId)).includes(action))
+        .filter((record) => availableWorkflowRunActions(record, runs).includes(action))
         .map((record) => ({
           value: record.runId,
           description: `${record.state} · ${record.workflow.name}`,
@@ -331,7 +335,7 @@ export class WorkflowRunController {
     const ctx = this.completionContext;
     const parts = splitArgumentPrefix(argumentPrefix);
     if (parts.completed.length > 0) return null;
-    const records = ctx ? await this.listRecent(ctx.cwd) : [];
+    const records = ctx ? (await this.history(ctx)).records : [];
     return completeCurrentArgument(argumentPrefix, [
       { value: "last", description: "Inspect the current or most recent in-session workflow" },
       ...records.map((record) => ({
@@ -342,6 +346,16 @@ export class WorkflowRunController {
   }
 }
 
+/**
+ * Runs that any stored run resumed, whatever that resume's outcome. A resumed run keeps its paused
+ * record and pause attempt, so automatic resume treats the pause as spent: re-arming it after a
+ * failed or stopped resume would relaunch it on every session start. Manual resume instead uses
+ * `supersedingRuns`, which frees a run whose every resume failed or was stopped.
+ */
+function resumedRunIds(records: readonly WorkflowRunRecord[]): ReadonlySet<string> {
+  return new Set(records.flatMap((record) => record.options.resumeFromRunId ?? []));
+}
+
 export function registerWorkflowRunCommand(
   pi: Pick<ExtensionAPI, "registerCommand">,
   controller: WorkflowRunController,

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

@@ -1,5 +1,6 @@
+import { truncateText } from "./text.ts";
 import { formatWorkflowUsageLine } from "./usage.ts";
-import type { WorkflowRunRecord, WorkflowRunState } from "./workflow-run-record.ts";
+import type { WorkflowRunRecord } from "./workflow-run-record.ts";
 import { formatDuration } from "./ui/workflow-format.ts";
 
 export const WORKFLOW_RUN_HISTORY_LIMIT = 50;
@@ -43,15 +44,37 @@ export function workflowRunsUsage(): string {
   return `Usage: /workflow:runs [${WORKFLOW_RUN_ACTIONS.map((action) => action.value).join("|")} <run-id>]`;
 }
 
+/** What a run's lifecycle actions depend on beyond its own record. */
+export interface WorkflowRunActionContext {
+  /** Runs this session is executing in the background. */
+  readonly activeRunIds: ReadonlySet<string>;
+  /** Resumed runs, keyed to the run that resumed them; see {@link supersedingRuns}. */
+  readonly resumedAs: ReadonlyMap<string, string>;
+}
+
+/**
+ * Maps each run to a stored run that resumed it and is queued, running, paused or completed, so
+ * resuming it again would replay its journal a second time. A run whose every resume failed or
+ * was stopped is absent, which leaves manual resume as the way back to its journal.
+ */
+export function supersedingRuns(records: readonly WorkflowRunRecord[]): ReadonlyMap<string, string> {
+  const resumedAs = new Map<string, string>();
+  for (const record of records) {
+    const source = record.options.resumeFromRunId;
+    if (source !== undefined && record.state !== "failed" && record.state !== "stopped") resumedAs.set(source, record.runId);
+  }
+  return resumedAs;
+}
+
 export function availableWorkflowRunActions(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
 ): readonly WorkflowRunLifecycleAction[] {
   const actions: WorkflowRunLifecycleAction[] = ["inspect"];
-  if ((record.state === "queued" || record.state === "running") && active) actions.push("stop");
+  if ((record.state === "queued" || record.state === "running") && runs.activeRunIds.has(record.runId)) actions.push("stop");
   if (record.state === "paused") {
     actions.push("stop");
-    if (canRelaunchWorkflowRun(record)) actions.push("resume");
+    if (!runs.resumedAs.has(record.runId) && canRelaunchWorkflowRun(record)) actions.push("resume");
   }
   if (
     (record.state === "completed" || record.state === "failed" || record.state === "stopped")
@@ -70,33 +93,31 @@ export function canRelaunchWorkflowRun(record: WorkflowRunRecord): boolean {
 
 export function formatWorkflowRunHistory(
   records: readonly WorkflowRunRecord[],
-  activeRunIds: ReadonlySet<string> = new Set(),
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   if (records.length === 0) return "No durable workflow runs are available for this project.";
   const lines = ["Recent workflow runs:"];
-  for (const record of records.slice(0, WORKFLOW_RUN_HISTORY_LIMIT)) {
-    lines.push(`- ${formatWorkflowRunSummary(record, activeRunIds.has(record.runId), now)}`);
-  }
-  if (records.length > WORKFLOW_RUN_HISTORY_LIMIT) {
-    lines.push(`… ${records.length - WORKFLOW_RUN_HISTORY_LIMIT} older runs hidden`);
+  for (const record of records) {
+    lines.push(`- ${formatWorkflowRunSummary(record, runs, now)}`);
   }
   return lines.join("\n");
 }
 
 export function formatWorkflowRunSummary(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   const usage = formatWorkflowUsageLine(record.usage);
-  const actions = availableWorkflowRunActions(record, active).filter((action) => action !== "inspect");
-  return `${workflowRunStateLabel(record.state)} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
+  const resumedAs = runs.resumedAs.get(record.runId);
+  const actions = availableWorkflowRunActions(record, runs).filter((action) => action !== "inspect");
+  return `${record.state.toUpperCase()} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
 }
 
 export function formatWorkflowRunDetails(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   const agents = record.progress.phases.flatMap((phase) =>
@@ -107,12 +128,14 @@ export function formatWorkflowRunDetails(
   const lines = [
     `Workflow run ${record.runId}`,
     `Workflow: ${record.workflow.name}`,
-    `State: ${workflowRunStateLabel(record.state)}`,
+    `State: ${record.state.toUpperCase()}`,
     `Age: ${formatDuration(Math.max(0, now - record.createdAt))}`,
     `Duration: ${formatWorkflowRunDuration(record, now)}`,
     `Phase: ${record.progress.currentPhase}`,
-    `Actions: ${availableWorkflowRunActions(record, active).join(", ")}`,
+    `Actions: ${availableWorkflowRunActions(record, runs).join(", ")}`,
   ];
+  const resumedAs = runs.resumedAs.get(record.runId);
+  if (resumedAs) lines.push(`Resumed as: ${resumedAs}`);
   if (usage) lines.push(usage);
   if (record.options.resumeEditedWorkflow) lines.push("Edited-workflow resume: enabled");
   const cachedAgents = record.progress.counters.find((counter) => counter.key === "resume.cached")?.value ?? 0;
@@ -136,11 +159,11 @@ export function formatWorkflowRunDetails(
 
 export function retainedWorkflowRunOutcome(record: WorkflowRunRecord): string {
   if (record.state === "completed") {
-    if (record.result.kind === "unavailable") return boundedOutcome(`Result unavailable: ${record.result.reason}`);
-    return boundedOutcome(JSON.stringify(record.result.value, null, 2));
+    if (record.result.kind === "unavailable") return truncateText(`Result unavailable: ${record.result.reason}`, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
+    return truncateText(JSON.stringify(record.result.value, null, 2), WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
   }
   if (record.state === "failed" || record.state === "stopped" || record.state === "paused") {
-    return boundedOutcome(record.message);
+    return truncateText(record.message, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
   }
   return "Run is still in progress.";
 }
@@ -150,13 +173,3 @@ export function formatWorkflowRunDuration(record: WorkflowRunRecord, now = Date.
   const end = record.endedAt ?? (record.state === "paused" ? record.updatedAt : now);
   return formatDuration(Math.max(0, end - start));
 }
-
-export function workflowRunStateLabel(state: WorkflowRunState): string {
-  return state.toUpperCase();
-}
-
-function boundedOutcome(value: string): string {
-  return value.length <= WORKFLOW_RUN_OUTCOME_TEXT_LIMIT
-    ? value
-    : `${value.slice(0, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT - 1)}…`;
-}

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

@@ -1,4 +1,5 @@
 import { validateWorkflowRunId } from "./journal.ts";
+import { isFiniteNumber, isRecord } from "./guards.ts";
 import {
   type ResolvedWorkflowRunOptions,
   WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
@@ -8,7 +9,8 @@ import {
 } from "./options.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
 import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
-import { isWorkflowUsageSnapshot, type WorkflowUsageSnapshot } from "./usage.ts";
+import { truncateText } from "./text.ts";
+import { emptyWorkflowUsageTotals, isWorkflowUsageSnapshot, type WorkflowUsageSnapshot } from "./usage.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   createPersistedWorkflowBackground,
@@ -112,7 +114,6 @@ export type WorkflowRunRecord = WorkflowRunRecordBase & (
 );
 
 export type WorkflowRunTransition =
-  | { readonly state: "queued"; readonly progress: WorkflowProgressSnapshot; readonly at?: number }
   | { readonly state: "running"; readonly progress: WorkflowProgressSnapshot; readonly at?: number }
   | { readonly state: "paused"; readonly progress: WorkflowProgressSnapshot; readonly message: string; readonly pause?: WorkflowRunPause; readonly at?: number }
   | { readonly state: "completed"; readonly progress: WorkflowProgressSnapshot; readonly usage: WorkflowUsageSnapshot; readonly result: unknown; readonly at?: number }
@@ -177,8 +178,6 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
   };
 
   switch (transition.state) {
-    case "queued":
-      return { ...base, state: "queued", startedAt: record.startedAt };
     case "running":
       return { ...base, state: "running", startedAt: record.startedAt ?? at };
     case "paused":
@@ -211,6 +210,16 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
   }
 }
 
+/** Records a user stop from the retained state, for runs whose engine cannot record it itself. */
+export function stopWorkflowRunRecord(record: WorkflowRunRecord): WorkflowRunRecord {
+  return transitionWorkflowRun(record, {
+    state: "stopped",
+    progress: record.progress,
+    usage: record.usage ?? record.progress.usage ?? { agents: [], totals: emptyWorkflowUsageTotals(), assistantMessages: 0 },
+    error: "Workflow stopped by user.",
+  });
+}
+
 export function captureWorkflowRunResult(value: unknown): WorkflowRunStoredResult {
   try {
     const state = { nodes: 0, bytes: 0, active: new WeakSet<object>() };
@@ -334,7 +343,7 @@ function isAllowedTransition(from: WorkflowRunState, to: WorkflowRunState): bool
     case "running":
       return to === "completed" || to === "failed" || to === "stopped" || to === "paused";
     case "paused":
-      return to === "queued" || to === "running" || to === "failed" || to === "stopped";
+      return to === "running" || to === "failed" || to === "stopped";
     case "completed":
     case "failed":
     case "stopped":
@@ -458,7 +467,7 @@ function compactWorkflowRunPause(pause: WorkflowRunPause): WorkflowRunPause {
 }
 
 function boundedText(value: string): string {
-  return value.length <= MAX_PERSISTED_TEXT ? value : `${value.slice(0, MAX_PERSISTED_TEXT - 1)}…`;
+  return truncateText(value, MAX_PERSISTED_TEXT);
 }
 
 export function isWorkflowRunRecord(value: unknown): value is WorkflowRunRecord {
@@ -617,16 +626,8 @@ function isValidRunId(value: unknown): value is string {
   }
 }
 
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
 function isIntegerInRange(value: unknown, min: number, max: number): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 class WorkflowRunValueError extends Error {}