@signalridge/pi-workflows 1.8.0 → 1.10.0

package/src/ui-inspection.ts

@@ -0,0 +1,206 @@
+import type {
+  WorkflowInspection,
+  WorkflowInspectionCall,
+  WorkflowInspectionEvent,
+  WorkflowInspectionPhase,
+  WorkflowInspectionTask,
+} from "./inspection.js";
+import type { ScriptRun } from "./journal.js";
+import { sanitizeDisplayText } from "./safe-text.js";
+import { expandedText, statusMark } from "./ui-presentation.js";
+
+/** Only the UI's consumed projection fields, checked at the adapter boundary. */
+export interface WorkflowPresentationSnapshot {
+  readonly runId: string;
+  readonly executionId: string;
+  readonly executionGeneration?: number;
+  readonly revision?: number;
+  readonly currentPhase?: string;
+  readonly currentPhaseKey?: string;
+  readonly observationSource: WorkflowInspection["observationSource"];
+  readonly restored: boolean;
+  readonly truncated: boolean;
+  readonly logicalCalls: number;
+  readonly replayedCalls: number;
+  readonly physicalDispatches: number;
+  readonly phases: readonly PresentationPhase[];
+  readonly calls: readonly PresentationCall[];
+  readonly tasks: readonly WorkflowInspectionTask[];
+  readonly events: readonly WorkflowInspectionEvent[];
+}
+
+export type PresentationPhase = WorkflowInspectionPhase;
+export type PresentationCall = WorkflowInspectionCall;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 1024;
+}
+function optionalText(value: unknown): value is string | undefined {
+  return value === undefined || text(value);
+}
+function count(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function optionalCount(value: unknown): value is number | undefined {
+  return value === undefined || count(value);
+}
+function status(value: unknown): boolean {
+  return (
+    typeof value === "string" &&
+    ["unknown", "pending", "queued", "running", "completed", "failed", "stopped", "interrupted"].includes(value)
+  );
+}
+function phase(value: unknown): value is PresentationPhase {
+  return (
+    record(value) &&
+    text(value.id) &&
+    text(value.frameId) &&
+    text(value.title) &&
+    optionalText(value.detail) &&
+    optionalText(value.phaseKey) &&
+    typeof value.declared === "boolean" &&
+    typeof value.entered === "boolean"
+  );
+}
+function call(value: unknown): value is PresentationCall {
+  return (
+    record(value) &&
+    text(value.id) &&
+    text(value.frameId) &&
+    Number.isInteger(value.index) &&
+    count(value.index) &&
+    (value.kind === "agent" || value.kind === "workflow" || value.kind === "checkpoint" || value.kind === "unknown") &&
+    status(value.status) &&
+    typeof value.observed === "boolean" &&
+    typeof value.journalOnly === "boolean" &&
+    [
+      "label",
+      "phase",
+      "phaseKey",
+      "agentType",
+      "tier",
+      "graphId",
+      "taskKey",
+      "taskId",
+      "agentId",
+      "attemptId",
+      "resultPreview",
+      "errorPreview",
+    ].every((key) => optionalText(value[key])) &&
+    ["tokenCount", "compactionCount", "physicalDispatches", "replayedAgentCount"].every((key) =>
+      optionalCount(value[key]),
+    ) &&
+    (value.physicalStatus === undefined || status(value.physicalStatus)) &&
+    (value.replayed === undefined || typeof value.replayed === "boolean")
+  );
+}
+function task(value: unknown): value is WorkflowInspectionTask {
+  return (
+    record(value) &&
+    ["id", "frameId", "graphId", "taskId"].every((key) => text(value[key])) &&
+    optionalText(value.description) &&
+    optionalText(value.phase) &&
+    optionalText(value.errorPreview) &&
+    count(value.attempt) &&
+    (status(value.status) || value.status === "skipped")
+  );
+}
+function event(value: unknown): value is WorkflowInspectionEvent {
+  return (
+    record(value) &&
+    text(value.id) &&
+    text(value.frameId) &&
+    typeof value.type === "string" &&
+    ["phase", "task", "workflow", "quality", "control-attempt", "log"].includes(value.type) &&
+    ["stage", "title", "graphId", "taskKey", "helperId", "helper", "outcome", "message"].every((key) =>
+      optionalText(value[key]),
+    ) &&
+    optionalCount(value.attempt) &&
+    (value.accepted === undefined || typeof value.accepted === "boolean")
+  );
+}
+function array<T extends { readonly id: string }>(
+  value: unknown,
+  maximum: number,
+  validate: (item: unknown) => item is T,
+): value is T[] {
+  if (!Array.isArray(value) || value.length > maximum || !value.every(validate)) return false;
+  const items: readonly T[] = value;
+  return items.every((item) => item.id.length > 0) && new Set(items.map((item) => item.id)).size === items.length;
+}
+
+/** Never interpret unknown adapter data as control authority or mutate its strings. */
+export function parsePresentation(value: unknown, runId: string): WorkflowPresentationSnapshot | undefined {
+  if (
+    !record(value) ||
+    value.runId !== runId ||
+    !text(value.executionId) ||
+    !optionalCount(value.executionGeneration) ||
+    !optionalCount(value.revision) ||
+    !optionalText(value.currentPhase) ||
+    !optionalText(value.currentPhaseKey) ||
+    (value.observationSource !== "execution" && value.observationSource !== "journal-only") ||
+    typeof value.restored !== "boolean" ||
+    typeof value.truncated !== "boolean" ||
+    !count(value.logicalCalls) ||
+    !count(value.replayedCalls) ||
+    !count(value.physicalDispatches) ||
+    !array(value.phases, 256, phase) ||
+    !array(value.calls, 2048, call) ||
+    !array(value.tasks, 256, task) ||
+    !array(value.events, 128, event)
+  )
+    return undefined;
+  return {
+    runId,
+    executionId: value.executionId,
+    executionGeneration: value.executionGeneration,
+    revision: value.revision,
+    currentPhase: value.currentPhase,
+    currentPhaseKey: value.currentPhaseKey,
+    observationSource: value.observationSource,
+    restored: value.restored,
+    truncated: value.truncated,
+    logicalCalls: value.logicalCalls,
+    replayedCalls: value.replayedCalls,
+    physicalDispatches: value.physicalDispatches,
+    phases: value.phases,
+    calls: value.calls,
+    tasks: value.tasks,
+    events: value.events,
+  };
+}
+
+export function inspectionCallLabel(call: WorkflowInspectionCall): string {
+  return (
+    `${statusMark(call.status)} Call ${call.index} · ${sanitizeDisplayText(call.label ?? call.kind, 160)} · ${call.status}` +
+    `${call.phase ? ` · phase ${sanitizeDisplayText(call.phase, 120)}` : ""}` +
+    `${call.tier ? ` · tier ${sanitizeDisplayText(call.tier, 80)}` : ""}` +
+    ` · compactions ${call.compactionCount ?? 0}` +
+    `${call.replayed ? " · replayed" : ""}` +
+    `${call.journalOnly ? " · journal-only" : ""}` +
+    `${call.errorPreview ? ` · error: ${sanitizeDisplayText(call.errorPreview, 120)}` : call.resultPreview ? ` · result: ${sanitizeDisplayText(call.resultPreview, 120)}` : ""}`
+  );
+}
+
+export function inspectionCallDetail(call: WorkflowInspectionCall, run: ScriptRun): string {
+  return [
+    inspectionCallLabel(call),
+    `Frame: ${sanitizeDisplayText(call.frameId, 200)}${call.frameId === run.runId ? " (root)" : " (nested)"}`,
+    ...(call.agentType ? [`Agent type: ${sanitizeDisplayText(call.agentType, 200)}`] : []),
+    ...(call.agentId ? [`Agent: ${sanitizeDisplayText(call.agentId, 128)}`] : []),
+    ...(call.tokenCount === undefined ? [] : [`Tokens: ${call.tokenCount}`]),
+    ...(call.physicalStatus
+      ? [`Physical status: ${call.physicalStatus} · dispatches ${call.physicalDispatches ?? 0}`]
+      : []),
+    ...(call.taskId ? [`Task: ${sanitizeDisplayText(call.taskId, 200)}`] : []),
+    call.observed
+      ? "Live callback facts (stored preview, not a conversation)."
+      : "Journal-only call; historical label/phase is unknown.",
+    ...(call.errorPreview ? [`Error: ${expandedText(call.errorPreview)}`] : []),
+    ...(call.resultPreview ? [expandedText(call.resultPreview)] : []),
+  ].join("\n");
+}

package/src/ui-presentation.ts

@@ -0,0 +1,196 @@
+import type { WorkflowEngine } from "./engine.js";
+import type { ScriptRun } from "./journal.js";
+import { sanitizeDisplayText, sanitizeTerminalText } from "./safe-text.js";
+
+export type RunStatus = ScriptRun["status"];
+export type WorkflowAction = "refresh" | "pause" | "resume" | "stop" | "back";
+export interface WorkflowActionItem {
+  value: WorkflowAction;
+  label: string;
+}
+
+export function isTerminal(status: RunStatus): boolean {
+  return status === "completed" || status === "failed" || status === "stopped";
+}
+
+/** ASCII marks occupy exactly one cell, including on ambiguous-width terminals. */
+export function statusMark(status: string): string {
+  if (status === "completed") return "+";
+  if (status === "failed") return "!";
+  if (status === "stopped" || status === "stopping") return "x";
+  if (status === "paused" || status === "pausing" || status === "interrupted") return "=";
+  if (status === "pending" || status === "queued") return ".";
+  if (status === "skipped") return "-";
+  return status === "running" ? ">" : "?";
+}
+
+export function elapsed(run: ScriptRun): string {
+  const ms = (isTerminal(run.status) ? run.updatedAt : Date.now()) - run.startedAt;
+  const seconds = Number.isFinite(ms) ? Math.floor(Math.max(0, ms) / 1_000) : 0;
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+
+export function callIndexes(run: ScriptRun): string[] {
+  return [...new Set([...Object.keys(run.callStatus), ...Object.keys(run.callResults)])]
+    .filter((id) => /^(?:0|[1-9]\d*)$/u.test(id))
+    .sort((a, b) => Number(a) - Number(b));
+}
+
+export function tokenCount(run: ScriptRun): number | undefined {
+  const values = Object.values(run.callResults)
+    .map((result) => result.tokenCount)
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  return values.length ? values.reduce((total, value) => total + value, 0) : undefined;
+}
+
+export function resultText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2) ?? "(no stored result)";
+  } catch {
+    return "(result cannot be displayed as JSON)";
+  }
+}
+
+/** Expanded views retain line breaks, but encode controls before any theme styling. */
+export function expandedText(value: string): string {
+  const limit = 16_000;
+  const copy = value.slice(0, limit);
+  return (
+    copy
+      .split("\n")
+      .map((line) => sanitizeTerminalText(line))
+      .join("\n") + (copy.length < value.length ? "\n[Display limited to 16000 characters]" : "")
+  );
+}
+
+export function formatWorkflowRunLabel(run: ScriptRun): string {
+  const phases = run.meta.phases?.length ? ` · phases ${run.meta.phases.length}` : "";
+  return `${sanitizeDisplayText(run.meta.name, 200)} · ${run.status}${phases} · ${callIndexes(run).length} calls · ${elapsed(run)}`;
+}
+
+export function runSummary(run: ScriptRun): string {
+  const statuses = Object.values(run.callStatus);
+  const running = statuses.filter((status) => status === "running").length;
+  const completed = statuses.filter((status) => status === "completed").length;
+  const failed = statuses.filter((status) => status === "failed").length;
+  const tokens = tokenCount(run);
+  return `${statusMark(run.status)} ${run.status} · ${elapsed(run)} · ${tokens ?? "?"} tokens · ${callIndexes(run).length} calls (${running} live / ${completed} done / ${failed} failed)`;
+}
+
+export function callLabel(run: ScriptRun, id: string): string {
+  const result = run.callResults[id];
+  const status = run.callStatus[id] ?? result?.status ?? "unknown";
+  const tier = run.callTiers?.[id]?.tier ?? result?.tier;
+  const compactions = run.compactions[id] ?? result?.compactionCount ?? 0;
+  const preview = result?.error
+    ? `error: ${sanitizeDisplayText(result.error, 120)}`
+    : result?.result !== undefined
+      ? `result: ${sanitizeDisplayText(resultText(result.result), 120)}`
+      : "";
+  return `${statusMark(status)} Call ${id} · ${status}${tier ? ` · tier ${sanitizeDisplayText(tier, 80)}` : ""} · compactions ${compactions}${preview ? ` · ${preview}` : ""}`;
+}
+
+export function callDetail(run: ScriptRun, id: string): string {
+  const result = run.callResults[id];
+  const agentId = run.agentIds[id] ?? result?.agentId;
+  return [
+    callLabel(run, id),
+    ...(agentId ? [`Agent: ${sanitizeDisplayText(agentId, 128)}`] : []),
+    ...(result?.tokenCount === undefined ? [] : [`Tokens: ${result.tokenCount}`]),
+    "Stored call result preview (not a live conversation):",
+    ...(result?.error ? [`Error: ${expandedText(result.error)}`] : []),
+    result?.result === undefined ? "No stored result yet." : expandedText(resultText(result.result)),
+  ].join("\n");
+}
+
+export function formatWorkflowDetail(engine: WorkflowEngine, runId: string): string {
+  const state = engine.getState(runId);
+  if (!state) return "Workflow run is no longer available.";
+  const run = state.run;
+  return [
+    `${sanitizeDisplayText(run.meta.name, 200)} [${run.status}]`,
+    `run: ${sanitizeDisplayText(run.runId, 128)}`,
+    `elapsed: ${elapsed(run)}`,
+    runSummary(run),
+    ...(run.meta.phases ?? []).map(
+      (phase) => `Phase (declared, progress unknown): ${sanitizeDisplayText(phase.title, 200)}`,
+    ),
+    ...callIndexes(run).map((id) => callDetail(run, id)),
+    "Final script result:",
+    run.finalResult === undefined ? "No stored final result yet." : expandedText(resultText(run.finalResult)),
+    ...(run.error ? [`Error: ${expandedText(run.error)}`] : []),
+  ].join("\n");
+}
+
+/** State-only availability; callers must additionally fence nonResumable/terminalIntent. */
+export function workflowActionsFor(status: RunStatus): readonly WorkflowActionItem[] {
+  const back: WorkflowActionItem = { value: "back", label: "Back" };
+  const stop: WorkflowActionItem = { value: "stop", label: "Stop (non-resumable)" };
+  switch (status) {
+    case "pending":
+    case "pausing":
+      return [stop, back];
+    case "running":
+      return [{ value: "pause", label: "Pause" }, stop, back];
+    case "paused":
+    case "interrupted":
+      return [{ value: "resume", label: "Resume" }, stop, back];
+    case "stopping":
+    case "completed":
+    case "failed":
+    case "stopped":
+      return [back];
+  }
+}
+
+export function actionsForRun(run: ScriptRun): readonly WorkflowActionItem[] {
+  return workflowActionsFor(run.status).filter(
+    (item) => item.value !== "resume" || (!run.nonResumable && !run.terminalIntent),
+  );
+}
+
+export function liveWidgetLines(
+  runs: readonly ScriptRun[],
+  mode: "compact" | "detailed" = "compact",
+  maxAgentsShown = 6,
+  maxRows = 12,
+): string[] {
+  const active = runs.filter((run) => !isTerminal(run.status));
+  if (!active.length) return [];
+  const max = Number.isFinite(maxAgentsShown) ? Math.max(1, Math.min(32, Math.floor(maxAgentsShown))) : 6;
+  const rows = Number.isFinite(maxRows) ? Math.max(1, Math.min(32, Math.floor(maxRows))) : 12;
+  const lines = [`Workflows · ${active.length} active · /workflows`];
+  if (rows === 1) return lines;
+  let shown = Math.min(max, active.length, rows - 1);
+  // When runs are hidden, reserve a dedicated overflow row before call details.
+  if (active.length > shown && shown + 2 > rows) shown = Math.max(0, shown - 1);
+  const visible = active.slice(0, shown);
+  const hiddenRuns = active.length - visible.length;
+  for (const [index, run] of visible.entries()) {
+    const runLine = lines.length;
+    lines.push(
+      `  ${statusMark(run.status)} ${run.status} · ${elapsed(run)} · ${callIndexes(run).length} calls · ${sanitizeDisplayText(run.meta.name, 80)}`,
+    );
+    if (mode !== "detailed") continue;
+    const calls = callIndexes(run);
+    const live = calls.filter((id) => run.callStatus[id] === "running");
+    const liveIds = new Set(live);
+    const prioritized = [...live, ...calls.filter((id) => !liveIds.has(id))];
+    const reserved = visible.length - index - 1 + (hiddenRuns > 0 ? 1 : 0);
+    const callRows = Math.max(0, Math.min(max, rows - lines.length - reserved));
+    const shownCalls = prioritized.slice(0, callRows);
+    for (const id of shownCalls) lines.push(`    ${id}: ${run.callStatus[id] ?? run.callResults[id]?.status}`);
+    const hiddenCalls = calls.length - shownCalls.length;
+    if (hiddenCalls > 0) {
+      const last = shownCalls.length ? lines.length - 1 : runLine;
+      lines[last] += ` · ${hiddenCalls} more calls`;
+    }
+  }
+  if (hiddenRuns > 0) lines.push(`  ${hiddenRuns} more workflows · /workflows`);
+  return lines;
+}
+
+export function snapshotRunLine(run: ScriptRun): string {
+  return formatWorkflowRunLabel(run);
+}