pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/ui/dynamax-editor-decoration.ts

@@ -0,0 +1,220 @@
+import { sliceByColumn, visibleWidth, type EditorComponent } from "@earendil-works/pi-tui";
+
+export type DynamaxEffect = "shine" | "static" | "off";
+
+export interface DynamaxAnimationScheduler {
+  now(): number;
+  schedule(callback: () => void, delayMs: number): () => void;
+}
+
+export interface DynamaxEditorDecoration {
+  readonly editor: EditorComponent;
+  dispose(): void;
+}
+
+interface DynamaxEditorDecorationOptions {
+  effect: Exclude<DynamaxEffect, "off">;
+  scheduler?: DynamaxAnimationScheduler;
+  isActive?: () => boolean;
+}
+
+const DYNAMAX_RENDER_PATTERN = /(^|[^A-Za-z0-9_])(dynamax)(?=[^A-Za-z0-9_]|$)/gi;
+const DYNAMAX_COLORS = [
+  [233, 137, 115],
+  [228, 186, 103],
+  [141, 192, 122],
+  [102, 194, 179],
+  [121, 157, 207],
+  [157, 134, 195],
+  [206, 130, 172],
+] as const;
+const RESET_FOREGROUND = "\x1b[39m";
+const DYNAMAX_EFFECT_ENV = "PI_DYNAMAX_EFFECT";
+export const DYNAMAX_ANIMATION_FRAME_MS = 135;
+const DYNAMAX_SHINE_FRAME_COUNT = DYNAMAX_COLORS.length;
+const DEFAULT_DYNAMAX_ANIMATION_SCHEDULER: DynamaxAnimationScheduler = {
+  now: () => performance.now(),
+  schedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return () => clearTimeout(timer);
+  },
+};
+
+export function resolveDynamaxEffect(env: NodeJS.ProcessEnv = process.env): DynamaxEffect {
+  const configured = env[DYNAMAX_EFFECT_ENV]?.trim().toLowerCase();
+  if (configured === "shine" || configured === "static" || configured === "off") return configured;
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return "off";
+  return "shine";
+}
+
+export function highlightDynamaxTokens(line: string, shinePosition?: number): string {
+  const { visibleText, rawPositions } = mapVisibleCharacters(line);
+  const insertions = new Map<number, string>();
+  for (const match of visibleText.matchAll(DYNAMAX_RENDER_PATTERN)) {
+    const token = match[2]!;
+    const visibleStart = match.index! + match[1]!.length;
+    for (let index = 0; index < token.length; index++) {
+      const rawPosition = rawPositions[visibleStart + index]!;
+      const color = DYNAMAX_COLORS[index % DYNAMAX_COLORS.length]!;
+      const shine = shinePosition === undefined ? (index === 0 ? 0.45 : 0) : shineFactor(index, shinePosition);
+      insertions.set(rawPosition, foregroundColor(color, shine));
+    }
+    const restorePosition = rawPositions[visibleStart + token.length] ?? line.length;
+    insertions.set(restorePosition, foregroundRestoreAt(line, restorePosition));
+  }
+  if (insertions.size === 0) return line;
+
+  let highlighted = "";
+  for (let rawPosition = 0; rawPosition <= line.length; rawPosition++) {
+    highlighted += insertions.get(rawPosition) ?? "";
+    if (rawPosition < line.length) highlighted += line[rawPosition];
+  }
+  return highlighted;
+}
+
+export function decorateDynamaxEditor(
+  editor: EditorComponent,
+  requestRender: () => void,
+  options: DynamaxEditorDecorationOptions,
+): DynamaxEditorDecoration {
+  const { effect } = options;
+  const originalRender = editor.render;
+  const scheduler = options.scheduler ?? DEFAULT_DYNAMAX_ANIMATION_SCHEDULER;
+  const isActive = options.isActive ?? (() => true);
+  let disposed = false;
+  let cancelScheduled: (() => void) | undefined;
+  let lastSignature: string | undefined;
+  let animationStartedAt: number | undefined;
+
+  const cancelAnimation = (): void => {
+    cancelScheduled?.();
+    cancelScheduled = undefined;
+    animationStartedAt = undefined;
+  };
+  const scheduleRender = (delayMs: number): void => {
+    if (cancelScheduled || disposed || !isActive()) return;
+    cancelScheduled = scheduler.schedule(() => {
+      cancelScheduled = undefined;
+      if (disposed || !isActive()) return;
+      requestRender();
+    }, Math.max(0, delayMs));
+  };
+
+  const decoratedRender = (width: number): string[] => {
+    const lines = originalRender.call(editor, width);
+    const signature = visibleDynamaxSignature(lines);
+    if (signature !== lastSignature) {
+      cancelAnimation();
+      lastSignature = signature;
+      if (signature && effect === "shine" && isActive()) animationStartedAt = scheduler.now();
+    }
+
+    let shinePosition: number | undefined;
+    if (animationStartedAt !== undefined && signature && effect === "shine" && isActive()) {
+      const now = scheduler.now();
+      const elapsed = Math.max(0, now - animationStartedAt);
+      const frame = Math.floor(elapsed / DYNAMAX_ANIMATION_FRAME_MS);
+      if (frame < DYNAMAX_SHINE_FRAME_COUNT) {
+        shinePosition = frame;
+        const nextFrameAt = animationStartedAt + (frame + 1) * DYNAMAX_ANIMATION_FRAME_MS;
+        scheduleRender(nextFrameAt - now);
+      } else {
+        cancelAnimation();
+      }
+    } else if (!signature || effect !== "shine" || !isActive()) {
+      cancelAnimation();
+    }
+
+    return lines.map((line) => highlightDynamaxTokens(line, shinePosition));
+  };
+
+  editor.render = decoratedRender;
+  return {
+    editor,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cancelAnimation();
+      if (editor.render === decoratedRender) editor.render = originalRender;
+    },
+  };
+}
+
+function shineFactor(index: number, shinePosition: number): number {
+  const distance = Math.abs(index - shinePosition);
+  if (distance === 0) return 0.7;
+  if (distance === 1) return 0.3;
+  return 0;
+}
+
+function foregroundColor(color: readonly [number, number, number], shine: number): string {
+  const red = Math.round(color[0] + (255 - color[0]) * shine);
+  const green = Math.round(color[1] + (255 - color[1]) * shine);
+  const blue = Math.round(color[2] + (255 - color[2]) * shine);
+  return `\x1b[38;2;${red};${green};${blue}m`;
+}
+
+function mapVisibleCharacters(line: string): { visibleText: string; rawPositions: number[] } {
+  let visibleText = "";
+  const rawPositions: number[] = [];
+  let rawPosition = 0;
+  while (rawPosition < line.length) {
+    const controlLength = terminalControlSequenceLength(line, rawPosition);
+    if (controlLength > 0) {
+      rawPosition += controlLength;
+      continue;
+    }
+    visibleText += line[rawPosition];
+    rawPositions.push(rawPosition);
+    rawPosition += 1;
+  }
+  return { visibleText, rawPositions };
+}
+
+function terminalControlSequenceLength(line: string, position: number): number {
+  if (line[position] !== "\x1b") return 0;
+  const introducer = line[position + 1];
+  if (introducer === "[") {
+    for (let index = position + 2; index < line.length; index++) {
+      const code = line.charCodeAt(index);
+      if (code >= 0x40 && code <= 0x7e) return index - position + 1;
+    }
+    return line.length - position;
+  }
+  if (introducer === "]" || introducer === "_") {
+    for (let index = position + 2; index < line.length; index++) {
+      if (line[index] === "\x07") return index - position + 1;
+      if (line[index] === "\x1b" && line[index + 1] === "\\") return index - position + 2;
+    }
+    return line.length - position;
+  }
+  return Math.min(2, line.length - position);
+}
+
+function foregroundRestoreAt(line: string, rawPosition: number): string {
+  const column = visibleWidth(line.slice(0, rawPosition));
+  // The extra cell makes Pi emit the active SGR prefix even when the token ends the line.
+  const sliced = sliceByColumn(`${line} `, column, 1);
+  let controls = "";
+  let position = 0;
+  while (position < sliced.length) {
+    const controlLength = terminalControlSequenceLength(sliced, position);
+    if (controlLength === 0) break;
+    const sequence = sliced.slice(position, position + controlLength);
+    if (sequence.startsWith("\x1b[") && sequence.endsWith("m")) controls += sequence;
+    position += controlLength;
+  }
+  return `${RESET_FOREGROUND}${controls}`;
+}
+
+function visibleDynamaxSignature(lines: string[]): string {
+  const matches: string[] = [];
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const { visibleText } = mapVisibleCharacters(lines[lineIndex]!);
+    for (const match of visibleText.matchAll(DYNAMAX_RENDER_PATTERN)) {
+      const visibleStart = match.index! + match[1]!.length;
+      matches.push(`${lineIndex}:${visibleStart}:${match[2]!}`);
+    }
+  }
+  return matches.join("|");
+}

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

@@ -1,7 +1,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import type { AgentRowSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
-import type { WorkflowLaneItemStatus } from "../types.ts";
+import type { AgentRowSnapshot, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "../progress-types.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
 
 export type WorkflowDisplayStatus = WorkflowLaneItemStatus | "queued" | "done" | "failed";
 export type WorkflowThemeColor = Parameters<Theme["fg"]>[0];
@@ -49,10 +49,6 @@ export function statusIcon(status: WorkflowDisplayStatus, theme: Theme): string
   }
 }
 
-export function badge(label: string, color: WorkflowThemeColor, theme: Theme): string {
-  return theme.fg(color, `[${label}]`);
-}
-
 export function truncateDisplay(text: string, width: number): string {
   if (width <= 0) return "";
   return truncateToWidth(text, width);
@@ -97,6 +93,30 @@ export interface WorkflowStatusSource {
   readonly counters: readonly { readonly key: string; readonly label: string; readonly value: number }[];
 }
 
+interface WorkflowInspectionSource {
+  readonly name: string;
+  readonly snapshot: WorkflowProgressSnapshot | (() => WorkflowProgressSnapshot);
+}
+
+export function workflowInspectionSnapshot(inspection: WorkflowInspectionSource): WorkflowProgressSnapshot {
+  return typeof inspection.snapshot === "function" ? inspection.snapshot() : inspection.snapshot;
+}
+
+export function formatWorkflowInspection(inspection: WorkflowInspectionSource): string {
+  const snapshot = workflowInspectionSnapshot(inspection);
+  const counts = countSnapshotAgents(snapshot);
+  const lines = [
+    `Workflow inspector: ${inspection.name}`,
+    `Run: ${snapshot.runId}`,
+    `Phase: ${snapshot.currentPhase}`,
+    `Agents: ${counts.running} running, ${counts.queued} queued, ${counts.done} done, ${counts.failed} failed`,
+  ];
+  const usage = formatWorkflowUsageLine(snapshot.usage);
+  if (usage) lines.push(usage);
+  if (snapshot.logs.length > 0) lines.push("Recent log:", ...snapshot.logs.slice(-8).map((entry) => `- ${entry}`));
+  return lines.join("\n");
+}
+
 export function statusText(snapshot: WorkflowProgressSnapshot, theme: Theme): string | undefined {
   const counts = countSnapshotAgents(snapshot);
   return statusTextFromCounts(snapshot, counts, theme);

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

@@ -1,9 +1,16 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, type TUI, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import type { AgentRowSnapshot, WorkflowLaneItemSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
+import type { AgentRowSnapshot, WorkflowLaneItemSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
 import { agentDetailParts, formatCount, formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
+import {
+  centerWorkflowViewerViewport,
+  fitWorkflowViewerRow,
+  fitWorkflowViewerRows,
+  workflowViewerHeight,
+} from "./workflow-viewer-layout.ts";
 
-type Section = "Overview" | "Agents" | "Findings" | "Logs";
+type Section = "Overview" | "Agents" | "Findings" | "Logs" | "Result";
 
 interface InspectorLine {
   text: string;
@@ -11,11 +18,20 @@ interface InspectorLine {
   key?: string;
 }
 
-const SECTIONS: readonly Section[] = ["Overview", "Agents", "Findings", "Logs"];
+const BASE_SECTIONS: readonly Section[] = ["Overview", "Agents", "Findings", "Logs"];
+const RESULT_SECTIONS: readonly Section[] = [...BASE_SECTIONS, "Result"];
+const MAX_RESULT_SOURCE_LINES = 200;
+const MAX_RESULT_RENDERED_LINES = 400;
+
+export interface WorkflowInspectorOutcome {
+  readonly label: string;
+  readonly text: string;
+}
 
 export class WorkflowInspector {
   private sectionIndex = 0;
-  private readonly selected: Record<Section, number> = { Overview: 0, Agents: 0, Findings: 0, Logs: 0 };
+  private contentWidth = 80;
+  private readonly selected: Record<Section, number> = { Overview: 0, Agents: 0, Findings: 0, Logs: 0, Result: 0 };
   private readonly expanded = new Set<string>();
 
   constructor(
@@ -23,6 +39,7 @@ export class WorkflowInspector {
     private readonly tui: Pick<TUI, "requestRender" | "terminal">,
     private readonly theme: Theme,
     private readonly close: () => void,
+    private readonly outcome?: WorkflowInspectorOutcome,
   ) {}
 
   handleInput(data: string): void {
@@ -32,7 +49,7 @@ export class WorkflowInspector {
     }
 
     if (matchesKey(data, "tab")) {
-      this.sectionIndex = (this.sectionIndex + 1) % SECTIONS.length;
+      this.sectionIndex = (this.sectionIndex + 1) % this.sections().length;
       this.requestRender();
       return;
     }
@@ -60,47 +77,52 @@ export class WorkflowInspector {
   }
 
   render(width: number): string[] {
-    const w = Math.max(24, width);
+    const w = Math.max(4, width);
     const inner = Math.max(1, w - 4);
+    this.contentWidth = inner;
     const th = this.theme;
     const snapshot = this.snapshotProvider();
-    const body = this.sectionLines(this.currentSection(), snapshot, inner);
-    const maxBody = Math.max(6, Math.floor(this.tui.terminal.rows * 0.8) - 6);
-    const selectedLine = this.selectedLineIndex(body);
-    const maxStart = Math.max(0, body.length - maxBody);
-    const start = Math.min(maxStart, Math.max(0, selectedLine - Math.floor(maxBody / 2)));
-    const visible = body.slice(start, start + maxBody);
-    const lines: string[] = [];
-
-    lines.push(th.fg("border", `╭${"─".repeat(w - 2)}╮`));
-    lines.push(this.row(` ${th.fg("accent", th.bold("Workflow Inspector"))} ${th.fg("dim", snapshot.title)}`, inner));
-    lines.push(this.row(` ${this.tabs()}`, inner));
-    lines.push(this.row(th.fg("dim", "─".repeat(inner)), inner));
-
-    for (const line of visible) lines.push(this.row(line.text, inner));
-    while (visible.length < maxBody) {
-      visible.push({ text: "" });
-      lines.push(this.row("", inner));
+    const section = this.currentSection();
+    let body = this.sectionLines(section, snapshot, inner);
+    const selectableCount = body.filter((line) => line.selectable).length;
+    const clampedSelection = Math.min(Math.max(0, selectableCount - 1), this.selected[section]);
+    if (clampedSelection !== this.selected[section]) {
+      this.selected[section] = clampedSelection;
+      body = this.sectionLines(section, snapshot, inner);
     }
-
-    lines.push(this.row(th.fg("dim", "─".repeat(inner)), inner));
-    const pct = body.length <= maxBody ? "100%" : `${Math.round(((start + visible.length) / body.length) * 100)}%`;
-    const selected = this.selected[this.currentSection()] + 1;
-    const count = Math.max(1, this.itemCount(this.currentSection()));
-    lines.push(
-      this.row(
+    const innerHeight = Math.max(1, workflowViewerHeight(this.tui.terminal.rows) - 2);
+    const maxBody = Math.max(1, innerHeight - 5);
+    const viewport = centerWorkflowViewerViewport(body, maxBody, this.selectedLineIndex(body));
+    const pct = `${viewport.percentage}%`;
+    const selected = this.selected[section] + 1;
+    const count = Math.max(1, selectableCount);
+    const content = fitWorkflowViewerRows(viewport.visible.map((line) => line.text), maxBody);
+    const interior = fitWorkflowViewerRows(
+      [
+        ` ${th.fg("accent", th.bold("Workflow Inspector"))} ${th.fg("dim", snapshot.title)}`,
+        ` ${this.tabs()}`,
+        th.fg("dim", "─".repeat(inner)),
+        ...content,
+        th.fg("dim", "─".repeat(inner)),
         `${th.fg("dim", `${body.length} lines · ${pct} · ${selected}/${count}`)} ${th.fg("dim", "· tab sections · ↑↓ select · enter expand/collapse · q/esc close")}`,
-        inner,
-      ),
+      ],
+      innerHeight,
     );
-    lines.push(th.fg("border", `╰${"─".repeat(w - 2)}╯`));
-    return lines.map((line) => truncateDisplay(line, w));
+    return [
+      th.fg("border", `╭${"─".repeat(Math.max(0, w - 2))}╮`),
+      ...interior.map((line) => this.row(line, inner)),
+      th.fg("border", `╰${"─".repeat(Math.max(0, w - 2))}╯`),
+    ].map((line) => truncateDisplay(line, w));
   }
 
   invalidate(): void {}
 
   private currentSection(): Section {
-    return SECTIONS[this.sectionIndex] ?? "Overview";
+    return this.sections()[this.sectionIndex] ?? "Overview";
+  }
+
+  private sections(): readonly Section[] {
+    return this.outcome ? RESULT_SECTIONS : BASE_SECTIONS;
   }
 
   private requestRender(): void {
@@ -108,24 +130,23 @@ export class WorkflowInspector {
   }
 
   private tabs(): string {
-    return SECTIONS.map((section, index) => {
-      const label = index === this.sectionIndex ? this.theme.fg("accent", this.theme.bold(section)) : this.theme.fg("muted", section);
-      return label;
+    return this.sections().map((section, index) => {
+      return index === this.sectionIndex ? this.theme.fg("accent", this.theme.bold(section)) : this.theme.fg("muted", section);
     }).join(this.theme.fg("dim", "  |  "));
   }
 
   private row(content: string, innerWidth: number): string {
-    const padded = padRight(truncateDisplay(content, innerWidth), innerWidth);
-    return this.theme.fg("border", "│") + " " + padded + " " + this.theme.fg("border", "│");
+    const fitted = fitWorkflowViewerRow(content, innerWidth);
+    return this.theme.fg("border", "│") + " " + fitted + " " + this.theme.fg("border", "│");
   }
 
   private itemCount(section: Section): number {
-    return this.sectionLines(section, this.snapshotProvider(), 80).filter((line) => line.selectable).length;
+    return this.sectionLines(section, this.snapshotProvider(), this.contentWidth).filter((line) => line.selectable).length;
   }
 
   private selectedKey(section: Section): string | undefined {
     let index = -1;
-    for (const line of this.sectionLines(section, this.snapshotProvider(), 80)) {
+    for (const line of this.sectionLines(section, this.snapshotProvider(), this.contentWidth)) {
       if (!line.selectable) continue;
       index++;
       if (index === this.selected[section]) return line.key;
@@ -153,6 +174,8 @@ export class WorkflowInspector {
         return this.findingLines(snapshot, width);
       case "Logs":
         return this.logLines(snapshot);
+      case "Result":
+        return this.resultLines(width);
     }
   }
 
@@ -162,6 +185,8 @@ export class WorkflowInspector {
       { text: `${this.theme.fg("muted", "Phase")} ${this.theme.fg("accent", snapshot.currentPhase)}`, selectable: true, key: "overview:phase" },
       { text: `${this.theme.fg("muted", "Elapsed")} ${elapsed}`, selectable: true, key: "overview:elapsed" },
     ];
+    const usage = formatWorkflowUsageLine(snapshot.usage);
+    if (usage) lines.push({ text: usage, selectable: true, key: "overview:usage" });
     if (snapshot.counters.length > 0) {
       lines.push({ text: this.theme.fg("dim", "Counters") });
       for (const counter of snapshot.counters) {
@@ -260,9 +285,26 @@ export class WorkflowInspector {
       return { text, selectable: true, key };
     });
   }
-}
 
-function padRight(text: string, width: number): string {
-  const visible = visibleWidth(text);
-  return text + " ".repeat(Math.max(0, width - visible));
+  private resultLines(width: number): InspectorLine[] {
+    if (!this.outcome) return [{ text: this.theme.fg("dim", "No retained outcome is available for this run.") }];
+    const source = this.outcome.text.split("\n");
+    const lines: InspectorLine[] = [{ text: this.theme.fg("dim", this.outcome.label) }];
+    const shown = source.slice(0, MAX_RESULT_SOURCE_LINES);
+    for (const sourceLine of shown) {
+      const wrapped = wrapTextWithAnsi(sourceLine || " ", Math.max(10, width - 2));
+      for (const line of wrapped) {
+        if (lines.length >= MAX_RESULT_RENDERED_LINES) break;
+        const index = lines.length;
+        const selected = this.currentSection() === "Result" && this.selected.Result === index - 1;
+        const text = selected ? this.theme.bg("selectedBg", line) : line;
+        lines.push({ text, selectable: true, key: `result:${index}` });
+      }
+      if (lines.length >= MAX_RESULT_RENDERED_LINES) break;
+    }
+    if (shown.length < source.length || lines.length >= MAX_RESULT_RENDERED_LINES) {
+      lines.push({ text: this.theme.fg("dim", "… retained result truncated for display") });
+    }
+    return lines;
+  }
 }

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -1,68 +1,18 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Text } from "@earendil-works/pi-tui";
-import type { AdvisoryFinding, AdvisoryLocation, AdvisoryReport } from "../advisory-schema.ts";
-import type { PerfAggregate } from "../perf.ts";
+import { isAdvisoryReport, type AdvisoryReportWithStats } from "../advisory-schema.ts";
 import { renderIssueDetails, renderIssuesTable } from "../review/review-format.ts";
-import { toReviewIssues, type ReviewContext } from "../review/review-issues.ts";
+import { toReviewIssues } from "../review/review-issues.ts";
 import { formatCount } from "./workflow-format.ts";
-import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "../usage.ts";
-
-export interface WorkflowPerfDetails {
-  readonly enabled: boolean;
-  readonly startedAt: number;
-  readonly aggregates: readonly PerfAggregate[];
-}
-
-export interface WorkflowResultEnvelope {
-  name: string;
-  result: unknown;
-  completedAt: number;
-  usage?: WorkflowUsageSnapshot;
-  perf?: WorkflowPerfDetails;
-  runId?: string;
-  resumedFromRunId?: string;
-}
-
-export interface AdvisoryWorkflowResult extends AdvisoryReport {
-  stats?: Record<string, string | number>;
-  reviewContext?: ReviewContext;
-}
+import { formatWorkflowUsageLine } from "../usage.ts";
+import type { WorkflowPerfDetails, WorkflowResultEnvelope } from "../workflow-execution.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 
 export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
   if (!isRecord(value)) return false;
   return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
 }
 
-function isAdvisoryLocation(value: unknown): value is AdvisoryLocation {
-  if (!isRecord(value)) return false;
-  if (typeof value.file !== "string") return false;
-  if (value.line !== undefined && typeof value.line !== "number") return false;
-  if (value.symbol !== undefined && typeof value.symbol !== "string") return false;
-  return true;
-}
-
-function isAdvisoryFinding(value: unknown): value is AdvisoryFinding {
-  if (!isRecord(value)) return false;
-  if (typeof value.summary !== "string") return false;
-  if (typeof value.category !== "string") return false;
-  if (!isSeverity(value.severity)) return false;
-  if (!isConfidence(value.confidence)) return false;
-  if (!Array.isArray(value.locations) || !value.locations.every(isAdvisoryLocation)) return false;
-  if (!Array.isArray(value.evidence) || !value.evidence.every((entry) => typeof entry === "string")) return false;
-  if (typeof value.impact !== "string") return false;
-  if (typeof value.recommendation !== "string") return false;
-  return true;
-}
-
-export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResult {
-  if (!isRecord(value)) return false;
-  if (typeof value.summary !== "string" || !Array.isArray(value.findings)) return false;
-  if (!value.findings.every(isAdvisoryFinding)) return false;
-  if (!Array.isArray(value.nextSteps) || !value.nextSteps.every((entry) => typeof entry === "string")) return false;
-  if (value.stats !== undefined && !isStats(value.stats)) return false;
-  return true;
-}
-
 export interface WorkflowRunDisplayMetadata {
   readonly runId?: string;
   readonly resumedFromRunId?: string;
@@ -105,7 +55,7 @@ export function renderWorkflowResultText(
 
 function renderAdvisoryResult(
   name: string,
-  result: AdvisoryWorkflowResult,
+  result: AdvisoryReportWithStats,
   expanded: boolean,
   theme: Theme,
   usage?: unknown,
@@ -209,23 +159,10 @@ function safeJson(value: unknown): string {
   try {
     return JSON.stringify(value, null, 2) ?? String(value);
   } catch (error) {
-    return error instanceof Error ? error.message : String(error);
+    return unknownErrorMessage(error);
   }
 }
 
-function isSeverity(value: unknown): value is AdvisoryFinding["severity"] {
-  return value === "low" || value === "medium" || value === "high";
-}
-
-function isConfidence(value: unknown): value is AdvisoryFinding["confidence"] {
-  return value === "low" || value === "medium" || value === "high";
-}
-
-function isStats(value: unknown): value is Record<string, string | number> {
-  if (!isRecord(value)) return false;
-  return Object.values(value).every((entry) => typeof entry === "string" || typeof entry === "number");
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-viewer-layout.ts

@@ -0,0 +1,51 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+const VIEWPORT_HEIGHT_RATIO = 0.8;
+const VIEWPORT_MARGIN_ROWS = 2;
+
+export const WORKFLOW_VIEWER_OVERLAY_OPTIONS = {
+  overlay: true,
+  overlayOptions: {
+    anchor: "center",
+    width: "80%",
+    minWidth: 40,
+    maxHeight: "80%",
+    margin: 1,
+  },
+} as const;
+
+export function workflowViewerHeight(terminalRows: number): number {
+  const rows = Math.max(1, terminalRows);
+  const availableRows = Math.max(1, rows - VIEWPORT_MARGIN_ROWS);
+  const proportionalRows = Math.floor(rows * VIEWPORT_HEIGHT_RATIO);
+  return Math.min(availableRows, Math.max(3, proportionalRows));
+}
+
+export function fitWorkflowViewerRow(text: string, width: number): string {
+  return truncateToWidth(text, Math.max(0, width), "...", true);
+}
+
+export function fitWorkflowViewerRows(lines: readonly string[], height: number): string[] {
+  const visible = lines.slice(0, Math.max(0, height));
+  return [...visible, ...Array.from({ length: Math.max(0, height - visible.length) }, () => "")];
+}
+
+interface WorkflowViewerViewport<T> {
+  readonly visible: readonly T[];
+  readonly percentage: number;
+}
+
+export function centerWorkflowViewerViewport<T>(
+  rows: readonly T[],
+  height: number,
+  selectedIndex: number,
+): WorkflowViewerViewport<T> {
+  const visibleHeight = Math.max(0, Math.floor(height));
+  const clampedSelection = Math.min(Math.max(0, rows.length - 1), Math.max(0, selectedIndex));
+  const maxStart = Math.max(0, rows.length - visibleHeight);
+  const start = Math.min(maxStart, Math.max(0, clampedSelection - Math.floor(visibleHeight / 2)));
+  const visible = rows.slice(start, start + visibleHeight);
+  const end = Math.min(rows.length, start + visible.length);
+  const percentage = rows.length <= visibleHeight ? 100 : Math.round((end / rows.length) * 100);
+  return { visible, percentage };
+}