@nanobpm/nano-workforce 0.183.1 → 0.184.0

package/app/agentic/cockpit/agent-history-render.ts

@@ -0,0 +1,168 @@
+// The cockpit engine-native "agent history" DOM renderer (ADR 0056, issue #745/#747, umbrella #746).
+//
+// Renders an {@link AgentSessionsView} (the settled agent-run list, sourced from engine
+// `searchAgentInstances`) and a selected instance's {@link AgentHistoryView} (its ordered conversation
+// turns + per-turn / instance metrics, sourced from engine `searchAgentInstanceHistory`) into host
+// elements. This is the CONSUMER render surface of the durable-agent-transcript work: the HISTORICAL
+// transcript is a STRUCTURED conversation (roles / text / tool calls / metrics) read from engine truth,
+// keyed by `agentInstanceKey` — NOT the ANSI terminal replay of a relay stream (`./transcript-render.ts`),
+// which stays the LIVE overlay only.
+//
+// Like the relay renderer it builds against the structural {@link ElementLike} / {@link DocumentLike}
+// subset (reused from the package) rather than the global `document`, so the real DOM satisfies it at
+// runtime AND a plain in-memory fake satisfies it for DOM-free Node tests. It draws only the volatile
+// history; the host region is owned by the boot layer.
+import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import type { AgentHistoryView, AgentSessionsView, AgentSessionView, AgentTurnView } from "./agent-history-view.ts";
+
+export interface RenderAgentSessionsOptions {
+  /** Called with an instance's key when the operator selects it to view its history. */
+  readonly onSelect?: (agentInstanceKey: string) => void;
+  /** The instance currently being viewed, if any — highlighted in the list. */
+  readonly activeInstanceKey?: string;
+  /** Panel title. Defaults to the historical-sessions label. */
+  readonly title?: string;
+  /** Empty-state copy. */
+  readonly emptyText?: string;
+}
+
+export interface AgentSessionsDom {
+  readonly root: ElementLike;
+}
+
+export interface AgentHistoryDom {
+  readonly root: ElementLike;
+}
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function sessionRow(doc: DocumentLike, s: AgentSessionView, options: RenderAgentSessionsOptions): ElementLike {
+  const row = el(doc, "tr", "cockpit-agent-session");
+  row.setAttribute("data-agent-instance-key", s.agentInstanceKey);
+  row.setAttribute("data-status", s.status);
+  if (options.activeInstanceKey === s.agentInstanceKey) row.setAttribute("data-active", "true");
+
+  const nameCell = el(doc, "td", "cockpit-td cockpit-agent-name");
+  const button = el(doc, "button", "cockpit-agent-select", s.label);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-agent-instance-key", s.agentInstanceKey);
+  const onSelect = options.onSelect;
+  if (onSelect !== undefined) button.addEventListener("click", () => onSelect(s.agentInstanceKey));
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-agent-status", s.status));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-agent-metrics", s.metrics ?? ""));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-agent-captured", s.capturedAt ?? ""));
+  return row;
+}
+
+/**
+ * Render the historical agent-sessions list `view` into `host`, replacing whatever was there.
+ * Idempotent: call again on every refresh to reflect the latest engine snapshot.
+ */
+export function renderAgentSessions(
+  host: ElementLike,
+  doc: DocumentLike,
+  view: AgentSessionsView,
+  options: RenderAgentSessionsOptions = {},
+): AgentSessionsDom {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-agent-history");
+  root.setAttribute("data-session-count", String(view.count));
+
+  const header = el(doc, "header", "cockpit-agent-header");
+  header.appendChild(el(doc, "h2", "cockpit-agent-title", options.title ?? "Agent history"));
+  const summary = el(doc, "span", "cockpit-agent-summary", String(view.count));
+  summary.setAttribute("data-summary", "agent-history");
+  header.appendChild(summary);
+  root.appendChild(header);
+
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-agent-empty", options.emptyText ?? "No agent runs recorded yet.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return { root };
+  }
+
+  const table = el(doc, "table", "cockpit-agent-table");
+  const thead = el(doc, "thead", "cockpit-agent-thead");
+  const head = el(doc, "tr", "cockpit-agent-head");
+  for (const label of ["run", "status", "metrics", "captured"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  thead.appendChild(head);
+  table.appendChild(thead);
+  const tbody = el(doc, "tbody", "cockpit-agent-tbody");
+  for (const s of view.sessions) tbody.appendChild(sessionRow(doc, s, options));
+  table.appendChild(tbody);
+  root.appendChild(table);
+
+  host.appendChild(root);
+  return { root };
+}
+
+function turnBlock(doc: DocumentLike, t: AgentTurnView): ElementLike {
+  const block = el(doc, "div", "cockpit-agent-turn");
+  block.setAttribute("data-history-item-key", t.historyItemKey);
+  block.setAttribute("data-role", t.role);
+  block.setAttribute("data-loop-iteration", String(t.loopIteration));
+
+  const meta = el(doc, "div", "cockpit-agent-turn-meta");
+  meta.appendChild(el(doc, "span", "cockpit-agent-turn-role", t.role));
+  meta.appendChild(el(doc, "span", "cockpit-agent-turn-iter", `#${t.loopIteration}`));
+  if (t.metrics !== undefined) meta.appendChild(el(doc, "span", "cockpit-agent-turn-metrics", t.metrics));
+  block.appendChild(meta);
+
+  if (t.text !== "") block.appendChild(el(doc, "pre", "cockpit-agent-turn-text", t.text));
+
+  if (t.toolCalls.length > 0) {
+    const tools = el(doc, "ul", "cockpit-agent-turn-tools");
+    for (const call of t.toolCalls) {
+      const li = el(doc, "li", "cockpit-agent-turn-tool", call.elementId !== undefined ? `${call.toolName} (${call.elementId})` : call.toolName);
+      li.setAttribute("data-tool-call-id", call.toolCallId);
+      tools.appendChild(li);
+    }
+    block.appendChild(tools);
+  }
+  return block;
+}
+
+/**
+ * Render one instance's conversation history `view` into `host`, replacing whatever was there.
+ * Idempotent. A null/empty history renders an explicit empty state (read-as-absence).
+ */
+export function renderAgentHistory(host: ElementLike, doc: DocumentLike, view: AgentHistoryView): AgentHistoryDom {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-agent-transcript");
+  root.setAttribute("data-agent-instance-key", view.agentInstanceKey);
+  root.setAttribute("data-turn-count", String(view.count));
+
+  const header = el(doc, "header", "cockpit-agent-transcript-header");
+  header.appendChild(el(doc, "h3", "cockpit-agent-transcript-title", view.instance?.label ?? view.agentInstanceKey));
+  if (view.instance?.metrics !== undefined) {
+    const m = el(doc, "span", "cockpit-agent-transcript-metrics", view.instance.metrics);
+    m.setAttribute("data-summary", "agent-instance-metrics");
+    header.appendChild(m);
+  }
+  root.appendChild(header);
+
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-agent-transcript-empty", "No history for this run.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return { root };
+  }
+
+  const turns = el(doc, "div", "cockpit-agent-turns");
+  for (const t of view.turns) turns.appendChild(turnBlock(doc, t));
+  root.appendChild(turns);
+
+  host.appendChild(root);
+  return { root };
+}

package/app/agentic/cockpit/agent-history-view.test.ts

@@ -0,0 +1,104 @@
+// Pure view-model tests for the cockpit engine-native agent-history view (issue #745/#747).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type {
+  AgentHistory as AgentHistoryReport,
+  AgentInstanceList as AgentInstanceListReport,
+} from "../../../nano-generated/api-io.d.ts";
+import { agentHistoryView, agentSessionsView } from "./agent-history-view.ts";
+
+const list = (instances: AgentInstanceListReport["instances"]): AgentInstanceListReport => ({
+  count: instances.length,
+  instances,
+});
+
+test("agentSessionsView labels, rolls up metrics, and sorts newest-captured first", () => {
+  const view = agentSessionsView(
+    list([
+      {
+        agentInstanceKey: "old",
+        status: "COMPLETED",
+        processInstanceKey: "pi-1",
+        processDefinitionId: "feature",
+        elementId: "implement-task",
+        completionDate: "2024-01-01T00:00:00Z",
+        metrics: { inputTokens: 1500, outputTokens: 340, modelCalls: 3, toolCalls: 5 },
+      },
+      {
+        agentInstanceKey: "new",
+        status: "THINKING",
+        processInstanceKey: "pi-2",
+        lastUpdatedDate: "2024-02-01T00:00:00Z",
+      },
+    ]),
+  );
+  assert.deepEqual(
+    view.sessions.map((s) => s.agentInstanceKey),
+    ["new", "old"],
+  );
+  const old = view.sessions[1];
+  assert.equal(old?.label, "feature \u00b7 implement-task \u00b7 inst pi-1");
+  assert.equal(old?.metrics, "1.5k in \u00b7 340 out \u00b7 3 calls \u00b7 5 tools");
+  assert.equal(old?.capturedAt, "2024-01-01T00:00:00Z");
+  // No metrics reported -> no metrics string.
+  assert.equal(view.sessions[0]?.metrics, undefined);
+});
+
+test("agentHistoryView projects turns in transport order with text, tool calls and per-turn metrics", () => {
+  const report: AgentHistoryReport = {
+    agentInstanceKey: "ai-1",
+    count: 2,
+    instance: {
+      agentInstanceKey: "ai-1",
+      status: "COMPLETED",
+      processInstanceKey: "pi-1",
+      metrics: { inputTokens: 20, outputTokens: 8, modelCalls: 2, toolCalls: 1 },
+    },
+    records: [
+      {
+        historyItemKey: "h-0",
+        agentInstanceKey: "ai-1",
+        loopIteration: 0,
+        role: "USER",
+        commitStatus: "COMMITTED",
+        content: [{ contentType: "TEXT", text: "do the thing" }],
+        toolCalls: [],
+      },
+      {
+        historyItemKey: "h-1",
+        agentInstanceKey: "ai-1",
+        loopIteration: 1,
+        role: "ASSISTANT",
+        commitStatus: "COMMITTED",
+        content: [
+          { contentType: "TEXT", text: "on it" },
+          { contentType: "OBJECT", object: { ignored: true } },
+        ],
+        toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool", arguments: {} }],
+        metrics: {
+          inputTokens: 12,
+          outputTokens: 4,
+          reasoningTokenCount: 0,
+          cacheCreationTokenCount: 0,
+          cacheReadTokenCount: 0,
+          durationMs: 900,
+        },
+      },
+    ],
+  };
+  const view = agentHistoryView(report);
+  assert.equal(view.count, 2);
+  assert.equal(view.instance?.metrics, "20 in \u00b7 8 out \u00b7 2 calls \u00b7 1 tools");
+  assert.equal(view.turns[0]?.text, "do the thing");
+  // OBJECT blocks drop out of the rendered text; only TEXT joins.
+  assert.equal(view.turns[1]?.text, "on it");
+  assert.equal(view.turns[1]?.toolCalls[0]?.toolName, "grep");
+  assert.equal(view.turns[1]?.metrics, "12 in \u00b7 4 out \u00b7 900ms");
+});
+
+test("agentHistoryView read-as-absence: an empty history yields zero turns", () => {
+  const view = agentHistoryView({ agentInstanceKey: "ai-9", count: 0, records: [] });
+  assert.equal(view.count, 0);
+  assert.equal(view.turns.length, 0);
+  assert.equal(view.instance, undefined);
+});

package/app/agentic/cockpit/agent-history-view.ts

@@ -0,0 +1,186 @@
+// The cockpit engine-native "agent history" view-model (ADR 0056, issue #745/#747, umbrella #746).
+//
+// A pure, deterministic projection of the engine AgentInstance / AgentHistory read model
+// (`GET /agentic/agent-instances` + `…/{agentInstanceKey}/history`, served from
+// `@nanobpm/urban`'s EngineClient `searchAgentInstances` / `searchAgentInstanceHistory`) onto the
+// shapes the cockpit's HISTORICAL (settled) transcript + metrics view renders. This is the CONSUMER
+// half of the durable-agent-transcript work: settled history now derives from engine truth, keyed by
+// AGENT-INSTANCE / PROCESS / ELEMENT-INSTANCE keys — never the slash-bearing `job:<jobKey>` relay
+// stream id (so the #744 gateway-proxy bug class is moot for historical reads). The token-granular
+// relay (`./transcript-view.ts`) stays the LIVE overlay only.
+//
+// Like its relay sibling `./transcript-view.ts` and `./supply-view.ts`, it is framework-free and
+// side-effect-free: the same report always yields the same view, so it renders identically embedded
+// (App View) and standalone, and is unit-testable on Node with no browser.
+
+import type {
+  AgentHistoryRecord,
+  AgentHistory as AgentHistoryReport,
+  AgentInstanceList as AgentInstanceListReport,
+  AgentInstance as AgentInstanceReport,
+} from "../../../nano-generated/api-io.d.ts";
+
+export type { AgentHistoryReport, AgentInstanceListReport };
+
+/** One agent-instance row in the renderable historical-sessions list. */
+export interface AgentSessionView {
+  /** The engine-unique agent-instance key — the identity the history read is keyed on. */
+  readonly agentInstanceKey: string;
+  /** A single stable human label for the run's process / element (falls back to the instance key). */
+  readonly label: string;
+  /** The engine lifecycle status (a bare string, e.g. COMPLETED / THINKING / IDLE). */
+  readonly status: string;
+  /** The owning process-instance key. */
+  readonly processInstanceKey: string;
+  /** The BPMN element id (AI-agent task) that owns the instance, when reported. */
+  readonly elementId?: string;
+  /** A compact human token/call rollup (e.g. "1.2k in · 340 out · 3 calls · 5 tools"), when metrics exist. */
+  readonly metrics?: string;
+  /** When the run was captured — completionDate when sealed, else lastUpdatedDate, else creationDate. */
+  readonly capturedAt?: string;
+}
+
+/** The full renderable historical-sessions list view. */
+export interface AgentSessionsView {
+  readonly sessions: readonly AgentSessionView[];
+  readonly count: number;
+}
+
+/** One tool call in a rendered turn. */
+export interface AgentTurnToolCallView {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly elementId?: string;
+}
+
+/** One conversation turn in the renderable history. */
+export interface AgentTurnView {
+  readonly historyItemKey: string;
+  readonly loopIteration: number;
+  readonly role: AgentHistoryRecord["role"];
+  /** The turn's text content blocks, joined newest-in-order (empty when the turn is non-textual). */
+  readonly text: string;
+  readonly toolCalls: readonly AgentTurnToolCallView[];
+  /** A compact per-turn token/duration rollup, when metrics exist. */
+  readonly metrics?: string;
+}
+
+/** The full renderable history for one agent instance: its rolled-up header + ordered turns. */
+export interface AgentHistoryView {
+  readonly agentInstanceKey: string;
+  /** The owning instance summary row, when the engine still reports it. */
+  readonly instance?: AgentSessionView;
+  readonly turns: readonly AgentTurnView[];
+  readonly count: number;
+}
+
+/** A single stable human label for an agent run's process / element (empty parts dropped). */
+function instanceLabel(i: AgentInstanceReport): string {
+  const parts: string[] = [];
+  if (i.processDefinitionId !== undefined && i.processDefinitionId !== "") parts.push(i.processDefinitionId);
+  if (i.elementId !== undefined && i.elementId !== "") parts.push(i.elementId);
+  if (i.processInstanceKey !== "") parts.push(`inst ${i.processInstanceKey}`);
+  if (parts.length > 0) return parts.join(" \u00b7 ");
+  return i.agentInstanceKey;
+}
+
+/** Render a token count compactly (e.g. 1234 -> "1.2k"), stable and locale-free. */
+function humanCount(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return "0";
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+/** Render a duration (ms) compactly (e.g. "1.2s", "340ms"), or undefined when absent/zero. */
+function humanMs(ms: number | undefined): string | undefined {
+  if (ms === undefined || !Number.isFinite(ms) || ms <= 0) return undefined;
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function instanceMetrics(i: AgentInstanceReport): string | undefined {
+  const m = i.metrics;
+  if (m === undefined) return undefined;
+  return `${humanCount(m.inputTokens)} in \u00b7 ${humanCount(m.outputTokens)} out \u00b7 ${m.modelCalls} calls \u00b7 ${m.toolCalls} tools`;
+}
+
+function turnMetrics(r: AgentHistoryRecord): string | undefined {
+  const m = r.metrics;
+  if (m === undefined) return undefined;
+  const dur = humanMs(m.durationMs);
+  const base = `${humanCount(m.inputTokens)} in \u00b7 ${humanCount(m.outputTokens)} out`;
+  return dur !== undefined ? `${base} \u00b7 ${dur}` : base;
+}
+
+/** The textual content of a turn: TEXT blocks joined in order (non-textual/empty blocks dropped). */
+function turnText(r: AgentHistoryRecord): string {
+  const texts: string[] = [];
+  for (const b of r.content) {
+    if (b.contentType === "TEXT" && b.text !== undefined && b.text !== "") texts.push(b.text);
+  }
+  return texts.join("\n");
+}
+
+/** Project one engine {@link AgentInstanceReport} onto a renderable {@link AgentSessionView}. */
+export function agentSessionView(i: AgentInstanceReport): AgentSessionView {
+  const metrics = instanceMetrics(i);
+  const capturedAt = i.completionDate ?? i.lastUpdatedDate ?? i.creationDate;
+  return {
+    agentInstanceKey: i.agentInstanceKey,
+    label: instanceLabel(i),
+    status: i.status,
+    processInstanceKey: i.processInstanceKey,
+    ...(i.elementId !== undefined && i.elementId !== "" ? { elementId: i.elementId } : {}),
+    ...(metrics !== undefined ? { metrics } : {}),
+    ...(capturedAt !== undefined && capturedAt !== "" ? { capturedAt } : {}),
+  };
+}
+
+/**
+ * Derive the renderable historical-sessions list from the engine AgentInstance list report.
+ *
+ * Pure and total: re-sorts newest-captured-first (stable on the instance key) so the view is
+ * diff-friendly regardless of the report's incoming order; no input mutates and no I/O happens.
+ */
+export function agentSessionsView(report: AgentInstanceListReport): AgentSessionsView {
+  const sessions = report.instances
+    .map(agentSessionView)
+    .sort((a, b) => {
+      const byTime = (b.capturedAt ?? "").localeCompare(a.capturedAt ?? "");
+      return byTime !== 0 ? byTime : a.agentInstanceKey.localeCompare(b.agentInstanceKey);
+    });
+  return { sessions, count: sessions.length };
+}
+
+/** Project one engine {@link AgentHistoryRecord} onto a renderable {@link AgentTurnView}. */
+export function agentTurnView(r: AgentHistoryRecord): AgentTurnView {
+  const metrics = turnMetrics(r);
+  return {
+    historyItemKey: r.historyItemKey,
+    loopIteration: r.loopIteration,
+    role: r.role,
+    text: turnText(r),
+    toolCalls: r.toolCalls.map((c) => ({
+      toolCallId: c.toolCallId,
+      toolName: c.toolName,
+      ...(c.elementId !== undefined && c.elementId !== "" ? { elementId: c.elementId } : {}),
+    })),
+    ...(metrics !== undefined ? { metrics } : {}),
+  };
+}
+
+/**
+ * Derive one agent instance's renderable history from the engine AgentHistory report. The transport
+ * already orders records (loopIteration, then creation-ordered key); this projection preserves that
+ * order. Pure and total; no I/O.
+ */
+export function agentHistoryView(report: AgentHistoryReport): AgentHistoryView {
+  const turns = report.records.map(agentTurnView);
+  return {
+    agentInstanceKey: report.agentInstanceKey,
+    ...(report.instance !== undefined ? { instance: agentSessionView(report.instance) } : {}),
+    turns,
+    count: turns.length,
+  };
+}

package/app/agentic/cockpit/index.ts

@@ -5,6 +5,27 @@
 //
 // The DEMAND×supply matrix, missing-agent-type reds, and diversity-SLO lights are OUT OF SCOPE for
 // this epic (#142) and deferred to the paired enrolment epic #152.
+
+export {
+  type AgentHistoryDom,
+  type AgentSessionsDom,
+  type RenderAgentSessionsOptions,
+  renderAgentHistory,
+  renderAgentSessions,
+} from "./agent-history-render.ts";
+export {
+  type AgentHistoryReport,
+  type AgentHistoryView,
+  type AgentInstanceListReport,
+  type AgentSessionsView,
+  type AgentSessionView,
+  type AgentTurnToolCallView,
+  type AgentTurnView,
+  agentHistoryView,
+  agentSessionsView,
+  agentSessionView,
+  agentTurnView,
+} from "./agent-history-view.ts";
 export {
   type CockpitRoute,
   parseCockpitRoute,

package/app/agentic/cockpit/mount.test.ts

@@ -78,6 +78,7 @@ function fetchStub(replay?: unknown) {
     const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
     if (url.includes("/supply")) return ok(SUPPLY);
     if (replay !== undefined && /[?&]stream=/.test(url)) return ok(replay);
+    if (url.includes("/agent-instances")) return ok({ count: 0, instances: [] });
     if (url.includes("/transcripts")) return ok({ sessions: [] });
     return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
   };
@@ -97,7 +98,13 @@ test("the rendered transcript region sits directly beneath the Workers — suppl
     const handle = mountCockpit(document.getElementById("root"), OPTS);
     const shell = document.querySelector(".cockpit-shell");
     const order = [...(shell?.children ?? [])].map((c: { className: string }) => c.className);
-    assertEquals(order, ["cockpit-supply-region", "cockpit-terminal", "cockpit-past-region"]);
+    assertEquals(order, [
+      "cockpit-supply-region",
+      "cockpit-terminal",
+      "cockpit-past-region",
+      "cockpit-agent-region",
+      "cockpit-agent-detail-region",
+    ]);
     handle.dispose();
   } finally {
     restore();
@@ -213,3 +220,128 @@ test("#744: replay fetches the proxy-safe ?stream= query form — a slash-bearin
     restore();
   }
 });
+
+// Engine-native SETTLED agent-history panel (issue #745/#747): the browser twin renders the run list
+// from /agent-instances and a selected run's turns from /agent-instances/{key}/history, keyed by the
+// agent-instance key — never a relay stream id. mount.js has no byte-drift guard, so this behaviour
+// test is the browser twin's coverage.
+test("agent-history panel renders the engine run list and a selected run's turns", async () => {
+  const instances = {
+    count: 1,
+    instances: [
+      {
+        agentInstanceKey: "ai-42",
+        status: "COMPLETED",
+        processInstanceKey: "pi-1",
+        elementId: "implement-task",
+        completionDate: "2024-01-01T00:00:00Z",
+        metrics: { inputTokens: 1500, outputTokens: 340, modelCalls: 3, toolCalls: 2 },
+      },
+    ],
+  };
+  const history = {
+    agentInstanceKey: "ai-42",
+    count: 1,
+    instance: instances.instances[0],
+    records: [
+      {
+        historyItemKey: "h-0",
+        agentInstanceKey: "ai-42",
+        loopIteration: 0,
+        role: "ASSISTANT",
+        commitStatus: "COMMITTED",
+        content: [{ contentType: "TEXT", text: "did the thing" }],
+        toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool", arguments: {} }],
+        metrics: { inputTokens: 12, outputTokens: 4, reasoningTokenCount: 0, cacheCreationTokenCount: 0, cacheReadTokenCount: 0, durationMs: 900 },
+      },
+    ],
+  };
+  const requested: string[] = [];
+  const restore = installEnv((url) => {
+    const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
+    if (url.includes("/supply")) return ok(SUPPLY);
+    if (/\/agent-instances\/[^/]+\/history/.test(url)) {
+      requested.push(url);
+      return ok(history);
+    }
+    if (url.includes("/agent-instances")) return ok(instances);
+    if (url.includes("/transcripts")) return ok({ sessions: [] });
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+  });
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await handle.refresh();
+      // refresh() kicks the agent-history list fetch fire-and-forget; let it settle.
+      await new Promise((r) => setTimeout(r, 0));
+      const row = document.querySelector('.cockpit-agent-session[data-agent-instance-key="ai-42"]');
+      assert(row != null, "the engine agent run is listed");
+
+      await handle.viewAgentHistory("ai-42");
+      assert(requested.some((u) => u.includes("/agent-instances/ai-42/history")), `history fetched by key (saw: ${requested.join(", ")})`);
+      const transcript = document.querySelector('.cockpit-agent-transcript[data-agent-instance-key="ai-42"]');
+      assert(transcript != null, "the selected run's history rendered");
+      assert((transcript?.textContent ?? "").includes("did the thing"), "the turn text rendered");
+      assert((transcript?.textContent ?? "").includes("grep"), "the tool call rendered");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+// #745 — the browser twin must treat an empty-string tool-call elementId as ABSENT (matching the
+// server SSOT `present()` in app/agentic/agent-history.ts, which drops empty elementIds), rendering
+// just the tool name — never `toolName ()`.
+test("agent-history tool call with an empty-string elementId renders no empty () suffix", async () => {
+  const instances = {
+    count: 1,
+    instances: [{ agentInstanceKey: "ai-77", status: "COMPLETED", processInstanceKey: "pi-1", elementId: "impl" }],
+  };
+  const history = {
+    agentInstanceKey: "ai-77",
+    count: 1,
+    instance: instances.instances[0],
+    records: [
+      {
+        historyItemKey: "h-0",
+        agentInstanceKey: "ai-77",
+        loopIteration: 0,
+        role: "ASSISTANT",
+        commitStatus: "COMMITTED",
+        content: [{ contentType: "TEXT", text: "did the thing" }],
+        toolCalls: [
+          { toolCallId: "t-1", toolName: "grep", elementId: "", arguments: {} },
+          { toolCallId: "t-2", toolName: "view", elementId: "tool", arguments: {} },
+        ],
+      },
+    ],
+  };
+  const restore = installEnv((url) => {
+    const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
+    if (url.includes("/supply")) return ok(SUPPLY);
+    if (/\/agent-instances\/[^/]+\/history/.test(url)) return ok(history);
+    if (url.includes("/agent-instances")) return ok(instances);
+    if (url.includes("/transcripts")) return ok({ sessions: [] });
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+  });
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await handle.refresh();
+      await new Promise((r) => setTimeout(r, 0));
+      await handle.viewAgentHistory("ai-77");
+      const tools = [...document.querySelectorAll(".cockpit-agent-turn-tool")].map((n) => n.textContent ?? "");
+      assert(tools.includes("grep"), `empty elementId renders bare tool name (saw: ${tools.join(", ")})`);
+      assert(!tools.some((t) => t.includes("()")), `no empty () suffix rendered (saw: ${tools.join(", ")})`);
+      assert(tools.includes("view (tool)"), `a present elementId still renders its suffix (saw: ${tools.join(", ")})`);
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});