@agent-compose/sdk 0.6.0 → 0.8.0

package/src/display.ts

@@ -0,0 +1,788 @@
+/**
+ * The display palette (ADR-0040 §7, CLI-first amendment) — the typed marker
+ * contract between `agentc display` and the session executors.
+ *
+ * A native-harness session (Claude Code / codex running in-sandbox, or the
+ * local bridge daemon) has no typed platform tools — its platform surface is
+ * the `agentc` CLI. To keep RENDERING parity with platform sessions, the
+ * model is given an explicit palette of display commands
+ * (`agentc display run|changes|document|plan|image|table|chart|ask …`) whose stdout is a one-line
+ * TYPED MARKER. The executors (server cloud-executor, CLI bridge daemon)
+ * detect these markers in tool results and persist the SAME `MessagePart`
+ * shapes the platform harness's tools produce — so the dashboard renders the
+ * same rich cards (run card, reviewed-changes diff, document tile, plan
+ * checklist) with NO new renderer vocabulary beyond the additive
+ * `display_*` tool names.
+ *
+ * Known agentc invocations are ALSO auto-promoted without an explicit
+ * display call: `agentc run dispatch` → the dispatched-run card (the exact
+ * `dispatch_workflow` part shapes turn.ts persists), `agentc run get` → the
+ * run card, `agentc files read` → the document tile. Claude Code's own
+ * TodoWrite tool additionally forwards as a durable `plan` part (the same
+ * shape the ACP daemon posts), so converged sessions get the plan checklist
+ * for free.
+ *
+ * Everything here is pure and executor-agnostic: the promoter takes the
+ * runtime's tool_use / tool_result events and returns plain part-shaped
+ * objects that are structurally identical to the server's `MessagePart`
+ * union (pinned by tests on both sides). Promotion is strictly a REWRITE of
+ * the pair's shape — it never suppresses data: an unrecognized command,
+ * unparseable arguments, or a missing marker all fall back to the raw pair.
+ */
+
+import { REVISION_SELECTOR_RE } from "./directives.js";
+
+// ── Marker contract ──────────────────────────────────────────────────────────
+
+export const DISPLAY_MARKER_KEY = "acDisplay";
+export const DISPLAY_MARKER_VERSION = "v1";
+
+export type DisplayPlanStatus = "pending" | "in_progress" | "completed";
+export interface DisplayPlanEntry {
+  content: string;
+  status: DisplayPlanStatus;
+}
+
+/** Plan bounds — mirror the server's BridgePartSchema (entries ≤ 64,
+ *  content ≤ 1000) so a marker-built plan part is always postable. */
+export const PLAN_MAX_ENTRIES = 64;
+export const PLAN_ENTRY_MAX_CHARS = 1_000;
+
+export type DisplayTableCell = string | number | boolean | null;
+export interface DisplayTableColumn { key: string; label: string }
+export interface DisplayTableData {
+  columns: DisplayTableColumn[];
+  rows: Array<Record<string, DisplayTableCell>>;
+  truncated: boolean;
+}
+
+export type DisplayChartKind = "bar" | "line";
+export interface DisplayChartPoint { x: string | number; y: number }
+export interface DisplayChartSeries { label: string; points: DisplayChartPoint[] }
+
+export interface DisplayAskOption { id: string; label: string }
+
+export type DisplayMarker =
+  | { kind: "run"; runId: string }
+  | { kind: "changes"; runId: string; factorySlug?: string; endedAt?: string | null }
+  | { kind: "document"; path: string; factorySlug?: string; preview?: string | null }
+  | { kind: "plan"; entries: DisplayPlanEntry[] }
+  | { kind: "image"; path: string; factorySlug?: string }
+  | { kind: "table"; columns: DisplayTableColumn[]; rows: Array<Record<string, DisplayTableCell>>; truncated: boolean }
+  | { kind: "chart"; chartKind: DisplayChartKind; series: DisplayChartSeries[]; xLabel?: string; yLabel?: string }
+  | { kind: "ask"; askId: string; prompt: string; options?: DisplayAskOption[]; freeText: boolean };
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const PLAN_STATUSES: ReadonlySet<string> = new Set(["pending", "in_progress", "completed"]);
+
+/** Clamp raw plan entries to the marker/part bounds; invalid rows drop. */
+export function clampPlanEntries(raw: unknown): DisplayPlanEntry[] {
+  if (!Array.isArray(raw)) return [];
+  const entries: DisplayPlanEntry[] = [];
+  for (const e of raw) {
+    if (typeof e !== "object" || e === null) continue;
+    const { content, status } = e as { content?: unknown; status?: unknown };
+    if (typeof content !== "string" || content.trim().length === 0) continue;
+    if (typeof status !== "string" || !PLAN_STATUSES.has(status)) continue;
+    entries.push({ content: content.slice(0, PLAN_ENTRY_MAX_CHARS), status: status as DisplayPlanStatus });
+    if (entries.length >= PLAN_MAX_ENTRIES) break;
+  }
+  return entries;
+}
+
+// ── Table / chart / ask clamps ───────────────────────────────────────────────
+// Shared by the CLI (before it serializes the marker) and the marker parser
+// (so a hand-forged oversized marker can never bloat a persisted part) —
+// the `clampPlanEntries` pattern.
+
+/** Table bounds — mirror the pinned `display_table` output shape. */
+export const TABLE_MAX_COLUMNS = 12;
+export const TABLE_MAX_ROWS = 100;
+export const TABLE_CELL_MAX_CHARS = 200;
+
+/** Drive-path bound for image markers (mirrors the directive path cap). */
+const IMAGE_PATH_MAX_CHARS = 512;
+
+function clampCellString(s: string): string {
+  return s.length > TABLE_CELL_MAX_CHARS ? `${s.slice(0, TABLE_CELL_MAX_CHARS - 1)}…` : s;
+}
+
+function clampCell(value: unknown): DisplayTableCell {
+  if (typeof value === "string") return clampCellString(value);
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "boolean") return value;
+  return null;
+}
+
+/**
+ * Clamp raw table input to the marker/part bounds. Accepts an array of flat
+ * objects (columns inferred from the key union, first-seen order) or a
+ * `{ columns, rows }` object. Null when nothing tabular survives — the CLI
+ * hard-errors, the parser treats the marker as not-a-marker.
+ */
+export function clampTableData(raw: unknown): DisplayTableData | null {
+  let rawColumns: unknown;
+  let rawRows: unknown;
+  if (Array.isArray(raw)) {
+    rawRows = raw;
+  } else if (typeof raw === "object" && raw !== null) {
+    rawColumns = (raw as { columns?: unknown }).columns;
+    rawRows = (raw as { rows?: unknown }).rows;
+  } else {
+    return null;
+  }
+  if (!Array.isArray(rawRows)) return null;
+
+  // Columns: explicit `{ key, label }` list, or the key union of the rows
+  // in first-seen order. `sourceKey` (unclamped) reads the raw rows; the
+  // clamped `key` is what the part carries and what rows are re-keyed to.
+  let truncated = false;
+  const columns: Array<{ sourceKey: string; key: string; label: string }> = [];
+  const seenKeys = new Set<string>();
+  const pushColumn = (key: string, label: string): void => {
+    if (seenKeys.has(key)) return;
+    seenKeys.add(key);
+    if (columns.length >= TABLE_MAX_COLUMNS) { truncated = true; return; }
+    columns.push({ sourceKey: key, key: clampCellString(key), label: clampCellString(label) });
+  };
+
+  if (rawColumns !== undefined) {
+    if (!Array.isArray(rawColumns)) return null;
+    for (const c of rawColumns) {
+      if (typeof c !== "object" || c === null) continue;
+      const { key, label } = c as { key?: unknown; label?: unknown };
+      if (typeof key !== "string" || key.length === 0) continue;
+      pushColumn(key, typeof label === "string" && label.length > 0 ? label : key);
+    }
+  } else {
+    for (const row of rawRows) {
+      if (typeof row !== "object" || row === null || Array.isArray(row)) continue;
+      for (const key of Object.keys(row)) pushColumn(key, key);
+    }
+  }
+  if (columns.length === 0) return null;
+
+  const rows: Array<Record<string, DisplayTableCell>> = [];
+  for (const rawRow of rawRows) {
+    if (typeof rawRow !== "object" || rawRow === null || Array.isArray(rawRow)) continue;
+    if (rows.length >= TABLE_MAX_ROWS) { truncated = true; break; }
+    const row: Record<string, DisplayTableCell> = {};
+    for (const c of columns) row[c.key] = clampCell((rawRow as Record<string, unknown>)[c.sourceKey]);
+    rows.push(row);
+  }
+  if (rows.length === 0) return null;
+  return { columns: columns.map(({ key, label }) => ({ key, label })), rows, truncated };
+}
+
+/** Chart bounds — mirror the pinned `display_chart` output shape. */
+export const CHART_MAX_SERIES = 4;
+export const CHART_MAX_POINTS_PER_SERIES = 60;
+export const CHART_LABEL_MAX_CHARS = 40;
+
+/** Clamp raw chart series to the marker/part bounds; invalid series and
+ *  non-finite points drop. Empty result → the CLI hard-errors / the parser
+ *  rejects the marker. */
+export function clampChartSeries(raw: unknown): DisplayChartSeries[] {
+  if (!Array.isArray(raw)) return [];
+  const series: DisplayChartSeries[] = [];
+  for (const s of raw) {
+    if (series.length >= CHART_MAX_SERIES) break;
+    if (typeof s !== "object" || s === null) continue;
+    const { label, points } = s as { label?: unknown; points?: unknown };
+    if (typeof label !== "string" || label.trim().length === 0) continue;
+    if (!Array.isArray(points)) continue;
+    const clamped: DisplayChartPoint[] = [];
+    for (const p of points) {
+      if (clamped.length >= CHART_MAX_POINTS_PER_SERIES) break;
+      if (typeof p !== "object" || p === null) continue;
+      const { x, y } = p as { x?: unknown; y?: unknown };
+      if (typeof y !== "number" || !Number.isFinite(y)) continue;
+      if (typeof x === "number" && Number.isFinite(x)) clamped.push({ x, y });
+      else if (typeof x === "string" && x.length > 0) clamped.push({ x: x.slice(0, CHART_LABEL_MAX_CHARS), y });
+    }
+    if (clamped.length === 0) continue;
+    series.push({ label: label.slice(0, CHART_LABEL_MAX_CHARS), points: clamped });
+  }
+  return series;
+}
+
+/** Clamp an axis label to the chart bound; undefined when unusable. */
+export function clampChartAxisLabel(raw: unknown): string | undefined {
+  return typeof raw === "string" && raw.trim().length > 0 ? raw.slice(0, CHART_LABEL_MAX_CHARS) : undefined;
+}
+
+/** Ask bounds — mirror the pinned `display_ask` output shape (the
+ *  promoter path; the approver directive has its own tighter caps in
+ *  directives.ts). */
+export const ASK_PROMPT_MAX_CHARS = 1_000;
+export const ASK_MAX_OPTIONS = 8;
+export const ASK_OPTION_ID_MAX_CHARS = 100;
+export const ASK_OPTION_LABEL_MAX_CHARS = 200;
+
+/** Normalize + clamp ask options. Accepts `["a","b"]` (id = label) or
+ *  `[{ id, label }]`; invalid entries drop, duplicate ids drop. */
+export function clampAskOptions(raw: unknown): DisplayAskOption[] {
+  if (!Array.isArray(raw)) return [];
+  const options: DisplayAskOption[] = [];
+  const seen = new Set<string>();
+  for (const o of raw) {
+    if (options.length >= ASK_MAX_OPTIONS) break;
+    let id: string | null = null;
+    let label: string | null = null;
+    if (typeof o === "string" && o.trim().length > 0) {
+      id = o;
+      label = o;
+    } else if (typeof o === "object" && o !== null) {
+      const cand = o as { id?: unknown; label?: unknown };
+      if (typeof cand.id === "string" && cand.id.length > 0 && typeof cand.label === "string" && cand.label.length > 0) {
+        id = cand.id;
+        label = cand.label;
+      }
+    }
+    if (id === null || label === null) continue;
+    const clampedId = id.slice(0, ASK_OPTION_ID_MAX_CHARS);
+    if (seen.has(clampedId)) continue;
+    seen.add(clampedId);
+    options.push({ id: clampedId, label: label.slice(0, ASK_OPTION_LABEL_MAX_CHARS) });
+  }
+  return options;
+}
+
+/** One-line JSON marker — exactly what `agentc display` prints. */
+export function serializeDisplayMarker(marker: DisplayMarker): string {
+  return JSON.stringify({ [DISPLAY_MARKER_KEY]: DISPLAY_MARKER_VERSION, ...marker });
+}
+
+/** Parse one line as a display marker; null when it isn't one (or fails
+ *  validation — a malformed marker is not a marker). */
+export function parseDisplayMarker(line: string): DisplayMarker | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{") || !trimmed.includes(DISPLAY_MARKER_KEY)) return null;
+  let obj: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    obj = parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  if (obj[DISPLAY_MARKER_KEY] !== DISPLAY_MARKER_VERSION) return null;
+  const str = (key: string): string | undefined => {
+    const v = obj[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+  };
+  switch (obj.kind) {
+    case "run": {
+      const runId = str("runId");
+      return runId && UUID_RE.test(runId) ? { kind: "run", runId } : null;
+    }
+    case "changes": {
+      const runId = str("runId");
+      if (!runId || !UUID_RE.test(runId)) return null;
+      return {
+        kind: "changes", runId,
+        ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
+        endedAt: str("endedAt") ?? null,
+      };
+    }
+    case "document": {
+      const path = str("path");
+      if (!path) return null;
+      return {
+        kind: "document", path,
+        ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
+        preview: str("preview") ?? null,
+      };
+    }
+    case "plan": {
+      const entries = clampPlanEntries(obj.entries);
+      return entries.length > 0 ? { kind: "plan", entries } : null;
+    }
+    case "image": {
+      const path = str("path");
+      if (!path || path.length > IMAGE_PATH_MAX_CHARS) return null;
+      return {
+        kind: "image", path,
+        ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
+      };
+    }
+    case "table": {
+      // Re-clamp through the shared helper — a hand-forged oversized
+      // marker cannot bloat the part beyond the pinned bounds.
+      const data = clampTableData({ columns: obj.columns, rows: obj.rows });
+      if (!data) return null;
+      return { kind: "table", ...data, truncated: data.truncated || obj.truncated === true };
+    }
+    case "chart": {
+      if (obj.chartKind !== "bar" && obj.chartKind !== "line") return null;
+      const series = clampChartSeries(obj.series);
+      if (series.length === 0) return null;
+      const xLabel = clampChartAxisLabel(obj.xLabel);
+      const yLabel = clampChartAxisLabel(obj.yLabel);
+      return {
+        kind: "chart", chartKind: obj.chartKind, series,
+        ...(xLabel !== undefined ? { xLabel } : {}),
+        ...(yLabel !== undefined ? { yLabel } : {}),
+      };
+    }
+    case "ask": {
+      const askId = str("askId");
+      const rawPrompt = str("prompt");
+      if (!askId || !UUID_RE.test(askId) || !rawPrompt) return null;
+      const options = clampAskOptions(obj.options);
+      return {
+        kind: "ask", askId, prompt: rawPrompt.slice(0, ASK_PROMPT_MAX_CHARS),
+        ...(options.length > 0 ? { options } : {}),
+        freeText: true, // always true in v1
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/** First display marker in a tool result's text output (the CLI prints
+ *  exactly one; scanning lines keeps it robust to surrounding stderr/echo). */
+export function findDisplayMarker(text: string): DisplayMarker | null {
+  for (const line of text.split("\n")) {
+    const marker = parseDisplayMarker(line);
+    if (marker) return marker;
+  }
+  return null;
+}
+
+// ── agentc invocation detection ──────────────────────────────────────────────
+
+export type AgentcInvocation =
+  | { verb: "display-run"; runId: string }
+  | { verb: "display-changes"; runId: string; factorySlug?: string }
+  | { verb: "display-document"; path: string; factorySlug?: string }
+  | { verb: "display-plan" }
+  | { verb: "display-image"; path: string; factorySlug?: string }
+  /** Directive verb — detection only arms the tool_call promotion; the
+   *  result keeps its raw output so the directive marker reaches the cloud
+   *  executor. Same for table `source:"file"`, diff, and ask-with-approver. */
+  | { verb: "display-preview"; path: string }
+  | { verb: "display-table"; source: "inline" | "file"; path?: string }
+  | { verb: "display-chart"; chartKind: DisplayChartKind }
+  | { verb: "display-diff"; path: string; from: string; to: string }
+  | { verb: "display-ask"; prompt: string; approver?: string }
+  | { verb: "run-dispatch"; templateName: string; input?: unknown }
+  | { verb: "run-get"; runId: string }
+  | { verb: "files-read"; path: string; factorySlug?: string };
+
+/** Shell operators that end the agentc invocation's own argument list. */
+const SHELL_STOPPERS = new Set(["|", "||", "&&", ";", ">", ">>", "<", "2>", "2>>", "&"]);
+
+/** Minimal shell-word split: whitespace-separated, single/double quotes
+ *  group. Unclosed quotes swallow the rest (matching sh's prompt-for-more
+ *  by simply taking what's there — promotion is best-effort). */
+export function shellWords(command: string): string[] {
+  const words: string[] = [];
+  let current = "";
+  let started = false;
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; started = true; continue; }
+    if (ch === " " || ch === "\t" || ch === "\n") {
+      if (started) { words.push(current); current = ""; started = false; }
+      continue;
+    }
+    current += ch;
+    started = true;
+  }
+  if (started) words.push(current);
+  return words;
+}
+
+/** Flags that take a value — consumed silently when not of interest so
+ *  positional collection stays correct. */
+const VALUE_FLAGS = new Set([
+  "--factory", "--input", "--entries", "--url", "--api-key", "--limit",
+  "--thread", "--content-type", "--file", "--out", "--revision", "--ended-at",
+  "--data", "--kind", "--from", "--to", "--prompt", "--options", "--approver",
+]);
+
+/** Detect a known agentc invocation inside a shell command string. Returns
+ *  null for anything unrecognized or with unparseable arguments (a `$VAR`
+ *  run id, a missing positional) — the pair then persists raw. */
+/** A word that chains, redirects, or substitutes — its presence means the
+ *  command is a PIPELINE/COMPOUND, where agentc is a data source (e.g.
+ *  `agentc run get … --json | python3 …`), not a display action. Promoting
+ *  those turned parse-helper failures into errored "Showed run" cards. */
+function isShellControlWord(w: string): boolean {
+  // `2>&1` (stderr merged INTO stdout) is the one harmless redirect: the
+  // marker still lands in captured output. Agents append it habitually —
+  // live failure: a valid `display chart … 2>&1` stayed a raw text row.
+  if (/^\d*>&\d+$/.test(w)) return false;
+  return SHELL_STOPPERS.has(w) || /^\d*>>?(&\d+)?$/.test(w) || w === "<" || w.startsWith("$(") || w.startsWith("`");
+}
+
+export function detectAgentcInvocation(command: string): AgentcInvocation | null {
+  const words = shellWords(command);
+  const start = words.findIndex((w) => w === "agentc" || w.endsWith("/agentc"));
+  if (start < 0) return null;
+  // Pure invocations only: any control word ANYWHERE (before or after)
+  // makes this a compound command — persist the pair raw.
+  if (words.some(isShellControlWord)) return null;
+  // Words before `agentc` must be env assignments (FOO=bar agentc …) or a
+  // shell-invoker wrapper (codex runs commands as `bash -lc "agentc …"`,
+  // whose argv joins to `bash -lc agentc …`).
+  for (let i = 0; i < start; i += 1) {
+    const w = words[i];
+    const isEnvAssign = /^[A-Za-z_][A-Za-z0-9_]*=/.test(w);
+    const isShellInvoker = /^(?:[\w./-]*\/)?(?:sh|bash|zsh|dash)$/.test(w);
+    if (!isEnvAssign && !isShellInvoker && !w.startsWith("-")) return null;
+  }
+  const args: string[] = [];
+  const flags = new Map<string, string>();
+  for (let i = start + 1; i < words.length; i += 1) {
+    const w = words[i];
+    if (SHELL_STOPPERS.has(w)) break;
+    if (w.startsWith("--")) {
+      if (VALUE_FLAGS.has(w) && i + 1 < words.length && !SHELL_STOPPERS.has(words[i + 1])) {
+        flags.set(w, words[i + 1]);
+        i += 1;
+      }
+      continue;
+    }
+    args.push(w);
+  }
+  const factorySlug = flags.get("--factory");
+  const withSlug = factorySlug ? { factorySlug } : {};
+  const uuid = (v: string | undefined): string | null => (v && UUID_RE.test(v) ? v : null);
+
+  if (args[0] === "display") {
+    switch (args[1]) {
+      case "run": {
+        const runId = uuid(args[2]);
+        return runId ? { verb: "display-run", runId } : null;
+      }
+      case "changes": {
+        const runId = uuid(args[2]);
+        return runId ? { verb: "display-changes", runId, ...withSlug } : null;
+      }
+      case "document":
+        return args[2] ? { verb: "display-document", path: args[2], ...withSlug } : null;
+      case "plan":
+        return { verb: "display-plan" };
+      case "image":
+        return args[2] ? { verb: "display-image", path: args[2], ...withSlug } : null;
+      case "preview":
+        return args[2] ? { verb: "display-preview", path: args[2] } : null;
+      case "table": {
+        const file = flags.get("--file");
+        const hasData = flags.has("--data");
+        // Exactly one source; both or neither is an unpromotable combination.
+        if (file && !hasData) return { verb: "display-table", source: "file", path: file };
+        if (hasData && !file) return { verb: "display-table", source: "inline" };
+        return null;
+      }
+      case "chart": {
+        const chartKind = flags.get("--kind");
+        return chartKind === "bar" || chartKind === "line"
+          ? { verb: "display-chart", chartKind }
+          : null;
+      }
+      case "diff": {
+        const from = flags.get("--from");
+        const to = flags.get("--to");
+        if (!args[2] || !from || !to) return null;
+        if (!REVISION_SELECTOR_RE.test(from) || !REVISION_SELECTOR_RE.test(to)) return null;
+        return { verb: "display-diff", path: args[2], from, to };
+      }
+      case "ask": {
+        const prompt = flags.get("--prompt");
+        if (!prompt || prompt.trim().length === 0) return null;
+        const approver = flags.get("--approver");
+        return {
+          verb: "display-ask",
+          prompt: prompt.slice(0, ASK_PROMPT_MAX_CHARS),
+          ...(approver ? { approver } : {}),
+        };
+      }
+      default:
+        return null;
+    }
+  }
+  if (args[0] === "run" && args[1] === "dispatch" && args[2]) {
+    let input: unknown;
+    const rawInput = flags.get("--input");
+    if (rawInput !== undefined) {
+      try { input = JSON.parse(rawInput); } catch { /* raw string stays out */ }
+    }
+    return { verb: "run-dispatch", templateName: args[2], ...(input !== undefined ? { input } : {}) };
+  }
+  if (args[0] === "run" && args[1] === "get") {
+    const runId = uuid(args[2]);
+    return runId ? { verb: "run-get", runId } : null;
+  }
+  if (args[0] === "files" && args[1] === "read" && args[2]) {
+    return { verb: "files-read", path: args[2], ...withSlug };
+  }
+  return null;
+}
+
+// ── The promoter ─────────────────────────────────────────────────────────────
+
+/** Plain part shapes, structurally identical to the server's `MessagePart`
+ *  union (and the bridge POST schema) — pinned by shape-fidelity tests on
+ *  the server side. */
+export type PromotedPart =
+  | { type: "tool_call"; toolName: string; input: Record<string, unknown>; toolCallId: string }
+  | { type: "tool_result"; toolCallId: string; output: unknown; isError: boolean }
+  | { type: "plan"; entries: DisplayPlanEntry[] };
+
+/** Preview / content clamps for promoted document results. */
+const DOCUMENT_PREVIEW_CHARS = 240;
+const DOCUMENT_CONTENT_CHARS = 4_000;
+
+interface PendingPromotion {
+  invocation: AgentcInvocation;
+}
+
+export interface DisplayPromoterContext {
+  /** The session's factory id (cloud sessions know it from the session row)
+   *  — stamped onto document/changes parts when the command names no
+   *  `--factory` slug, so the renderer can resolve the drive link. */
+  factoryId?: string;
+}
+
+export interface DisplayPromoter {
+  /** Promote a tool_use event. Non-null → persist these parts INSTEAD of
+   *  the default mapping (the promoted tool_call reuses the toolUseId, so
+   *  the eventual result still pairs). Null → not a promotable call. */
+  promoteToolUse(msg: { toolName: string; toolInput: unknown; toolUseId: string }): PromotedPart[] | null;
+  /** Promote the matching tool_result. Non-null → persist these parts
+   *  instead of the default mapping. Null → no promotion pending. */
+  promoteToolResult(msg: { toolUseId: string; output: unknown; isError?: boolean }): PromotedPart[] | null;
+}
+
+/** The command string of a shell-ish tool input — Claude Code's Bash tool
+ *  ({ command: "…" }) and codex's shell tool ({ command: [argv…] }). */
+function commandOf(toolInput: unknown): string | null {
+  if (typeof toolInput !== "object" || toolInput === null) return null;
+  const cmd = (toolInput as { command?: unknown }).command;
+  if (typeof cmd === "string") return cmd;
+  if (Array.isArray(cmd) && cmd.every((c) => typeof c === "string")) return cmd.join(" ");
+  return null;
+}
+
+/** Flatten a tool result's output to text, however the runtime wrapped it. */
+function textOf(output: unknown): string | null {
+  if (typeof output === "string") return output;
+  if (typeof output !== "object" || output === null) return null;
+  const o = output as Record<string, unknown>;
+  if (typeof o.output === "string") return o.output;
+  if (typeof o.text === "string") return o.text;
+  if (typeof o.content === "string") return o.content;
+  return null;
+}
+
+/** Last JSON object found on a line of `text` carrying a string `runId` —
+ *  how a dispatch result names its run with or without `--json`. */
+function runIdIn(text: string): { runId: string; parsed: Record<string, unknown> | null } | null {
+  for (const line of [...text.split("\n")].reverse()) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{")) {
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (typeof parsed === "object" && parsed !== null) {
+          const runId = (parsed as { runId?: unknown }).runId;
+          if (typeof runId === "string" && UUID_RE.test(runId)) {
+            return { runId, parsed: parsed as Record<string, unknown> };
+          }
+        }
+      } catch { /* not JSON — keep scanning */ }
+    }
+  }
+  const m = /run ([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i.exec(text);
+  return m ? { runId: m[1], parsed: null } : null;
+}
+
+export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): DisplayPromoter {
+  const pending = new Map<string, PendingPromotion>();
+
+  /** factorySlug from the command when present, else the session's factory
+   *  id — the renderer accepts either (slug direct, or id via its cached
+   *  factories lookup). */
+  const factoryRef = (slug: string | undefined): Record<string, string> => {
+    if (slug) return { factorySlug: slug };
+    if (ctx.factoryId) return { factoryId: ctx.factoryId };
+    return {};
+  };
+
+  return {
+    promoteToolUse(msg) {
+      // Claude Code's native TodoWrite → ADDITIONALLY forward the durable
+      // `plan` part (the ACP daemon's shape) so the checklist renders; the
+      // raw tool pair still persists unchanged (strictly additive).
+      if (msg.toolName === "TodoWrite") {
+        const todos = (msg.toolInput as { todos?: unknown } | null)?.todos;
+        const entries = clampPlanEntries(todos);
+        if (entries.length === 0) return null;
+        return [
+          { type: "tool_call", toolName: msg.toolName, input: msg.toolInput as Record<string, unknown>, toolCallId: msg.toolUseId },
+          { type: "plan", entries },
+        ];
+      }
+      const command = commandOf(msg.toolInput);
+      if (!command || !command.includes("agentc")) return null;
+      const invocation = detectAgentcInvocation(command);
+      if (!invocation) return null;
+      pending.set(msg.toolUseId, { invocation });
+      const call = (toolName: string, input: Record<string, unknown>): PromotedPart[] => [
+        { type: "tool_call", toolName, input: { ...input, command }, toolCallId: msg.toolUseId },
+      ];
+      switch (invocation.verb) {
+        case "display-run":
+        case "run-get":
+          return call("display_run", { runId: invocation.runId });
+        case "display-changes":
+          return call("display_changes", { runId: invocation.runId, ...factoryRef(invocation.factorySlug) });
+        case "display-document":
+        case "files-read":
+          return call("display_document", { path: invocation.path, ...factoryRef(invocation.factorySlug) });
+        case "display-plan":
+          return call("display_plan", {});
+        case "display-image":
+          return call("display_image", { path: invocation.path, ...factoryRef(invocation.factorySlug) });
+        case "display-preview":
+          return call("display_preview", { path: invocation.path, ...factoryRef(undefined) });
+        case "display-table":
+          return call("display_table", {
+            source: invocation.source,
+            ...(invocation.path !== undefined ? { path: invocation.path } : {}),
+            ...(invocation.source === "file" ? factoryRef(undefined) : {}),
+          });
+        case "display-chart":
+          return call("display_chart", { chartKind: invocation.chartKind });
+        case "display-diff":
+          return call("display_diff", {
+            path: invocation.path, from: invocation.from, to: invocation.to,
+            ...factoryRef(undefined),
+          });
+        case "display-ask":
+          return call("display_ask", { prompt: invocation.prompt });
+        case "run-dispatch":
+          return call("dispatch_workflow", {
+            templateName: invocation.templateName,
+            ...(invocation.input !== undefined ? { input: invocation.input } : {}),
+          });
+      }
+    },
+
+    promoteToolResult(msg) {
+      const entry = pending.get(msg.toolUseId);
+      if (!entry) return null;
+      pending.delete(msg.toolUseId);
+      const isError = msg.isError === true;
+      const result = (output: unknown): PromotedPart => ({
+        type: "tool_result", toolCallId: msg.toolUseId, output, isError,
+      });
+      // An errored command keeps its raw output — failures are never dressed
+      // up as cards (the renderer shows the promoted row with its error).
+      const text = textOf(msg.output);
+      if (isError || text === null) return [result(msg.output)];
+
+      const inv = entry.invocation;
+      switch (inv.verb) {
+        case "display-run": {
+          const marker = findDisplayMarker(text);
+          return [result(marker?.kind === "run" ? { runId: marker.runId } : { runId: inv.runId })];
+        }
+        case "run-get": {
+          const found = runIdIn(text);
+          return [result(found?.parsed ?? { runId: found?.runId ?? inv.runId })];
+        }
+        case "display-changes": {
+          const marker = findDisplayMarker(text);
+          const m = marker?.kind === "changes" ? marker : null;
+          return [result({
+            runId: m?.runId ?? inv.runId,
+            ...factoryRef(m?.factorySlug ?? inv.factorySlug),
+            endedAt: m?.endedAt ?? null,
+          })];
+        }
+        case "display-document": {
+          const marker = findDisplayMarker(text);
+          const m = marker?.kind === "document" ? marker : null;
+          return [result({
+            path: m?.path ?? inv.path,
+            ...factoryRef(m?.factorySlug ?? inv.factorySlug),
+            preview: m?.preview ?? null,
+          })];
+        }
+        case "files-read":
+          return [result({
+            path: inv.path,
+            ...factoryRef(inv.factorySlug),
+            preview: text.slice(0, DOCUMENT_PREVIEW_CHARS) || null,
+            content: text.slice(0, DOCUMENT_CONTENT_CHARS),
+          })];
+        case "display-plan": {
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "plan") return [result(msg.output)];
+          return [
+            result({ entries: marker.entries.length }),
+            { type: "plan", entries: marker.entries },
+          ];
+        }
+        case "display-image": {
+          const marker = findDisplayMarker(text);
+          const m = marker?.kind === "image" ? marker : null;
+          return [result({
+            path: m?.path ?? inv.path,
+            ...factoryRef(m?.factorySlug ?? inv.factorySlug),
+          })];
+        }
+        case "display-table": {
+          // File-sourced tables are a DIRECTIVE: keep the raw output so the
+          // marker inside it reaches the cloud executor (the real card pair).
+          if (inv.source === "file") return [result(msg.output)];
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "table") return [result(msg.output)];
+          return [result({ columns: marker.columns, rows: marker.rows, truncated: marker.truncated })];
+        }
+        case "display-chart": {
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "chart") return [result(msg.output)];
+          return [result({
+            chartKind: marker.chartKind, series: marker.series,
+            ...(marker.xLabel !== undefined ? { xLabel: marker.xLabel } : {}),
+            ...(marker.yLabel !== undefined ? { yLabel: marker.yLabel } : {}),
+          })];
+        }
+        case "display-ask": {
+          // Approver asks are a DIRECTIVE (server-authoritative resolution
+          // + ping) — raw output through, marker intact.
+          if (inv.approver !== undefined) return [result(msg.output)];
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "ask") return [result(msg.output)];
+          return [result({
+            askId: marker.askId, prompt: marker.prompt,
+            ...(marker.options !== undefined ? { options: marker.options } : {}),
+            freeText: marker.freeText,
+          })];
+        }
+        case "display-preview":
+        case "display-diff":
+          // Directive verbs: the promoted tool_call is armed above; the raw
+          // result keeps the directive marker for the cloud executor.
+          return [result(msg.output)];
+        case "run-dispatch": {
+          const found = runIdIn(text);
+          if (!found) return [result(msg.output)];
+          return [result(found.parsed ?? { runId: found.runId })];
+        }
+      }
+    },
+  };
+}