@nanobpm/nano-workforce 0.183.2 → 0.184.1

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();
+  }
+});

package/app/agentic/cockpit/supply-boot-agent-history.test.ts

@@ -0,0 +1,144 @@
+// Unit tests for the SUPPLY cockpit boot layer's engine-native AGENT-HISTORY panel (issue #745/#747).
+//
+// The testable heart of the consumer half: the cockpit renders a settled agent-history list (sourced
+// from engine searchAgentInstances) beside the live supply + relay past-sessions panels; selecting a
+// run renders its ordered conversation turns + metrics (sourced from engine searchAgentInstanceHistory)
+// keyed by agentInstanceKey — never a relay stream id. No browser, no engine, no socket.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import type {
+  AgentHistory as AgentHistoryReport,
+  AgentInstanceList as AgentInstanceListReport,
+} from "../../../nano-generated/api-io.d.ts";
+import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
+import type { SupplyReport } from "./supply-view.ts";
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+const supply: SupplyReport = { count: 0, workers: [], leaves: [] };
+
+const instances: AgentInstanceListReport = {
+  count: 2,
+  instances: [
+    { agentInstanceKey: "ai-old", status: "COMPLETED", processInstanceKey: "pi-1", elementId: "implement-task", completionDate: "2024-01-01T00:00:00Z", metrics: { inputTokens: 100, outputTokens: 20, modelCalls: 2, toolCalls: 1 } },
+    { agentInstanceKey: "ai-new", status: "IDLE", processInstanceKey: "pi-2", lastUpdatedDate: "2024-02-01T00:00:00Z" },
+  ],
+};
+
+const history: AgentHistoryReport = {
+  agentInstanceKey: "ai-old",
+  count: 1,
+  instance: instances.instances[0],
+  records: [
+    { historyItemKey: "h-0", agentInstanceKey: "ai-old", loopIteration: 0, role: "ASSISTANT", commitStatus: "COMMITTED", content: [{ contentType: "TEXT", text: "did the thing" }], toolCalls: [] },
+  ],
+};
+
+interface Rig {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  requestedHistoryKey: string | undefined;
+  errors: unknown[];
+}
+
+function rig(withAgentHistory = true): Rig {
+  const host = new FakeElement("body");
+  const state: Rig = {
+    host,
+    requestedHistoryKey: undefined,
+    errors: [],
+    env: {
+      host,
+      doc: new FakeDocument(),
+      fetchSupply: () => Promise.resolve(supply),
+      ...(withAgentHistory
+        ? {
+            fetchAgentInstances: () => Promise.resolve(instances),
+            fetchAgentHistory: (agentInstanceKey: string) => {
+              state.requestedHistoryKey = agentInstanceKey;
+              return Promise.resolve(history);
+            },
+          }
+        : {}),
+      connectRelay: () => new FakeSocket(),
+      createTerminal: (terminalHost) => {
+        terminalHost.appendChild(new FakeElement("pre"));
+        return { write: () => {}, dispose: () => {} };
+      },
+      setTimer: () => 0,
+      clearTimer: () => {},
+      onError: (err) => state.errors.push(err),
+    },
+  };
+  return state;
+}
+
+test("refresh renders the engine agent-history list, sorted newest-first", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  const rows = r.host.byClass("cockpit-agent-session");
+  assert.equal(rows.length, 2, "one row per engine agent instance");
+  assert.equal(rows[0]?.getAttribute("data-agent-instance-key"), "ai-new", "newest-updated run first");
+  assert.equal(r.host.byData("summary", "agent-history").length, 1);
+  assert.deepEqual(r.errors, []);
+});
+
+test("selecting a run renders its engine history keyed by agentInstanceKey", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+
+  await cockpit.viewAgentHistory("ai-old");
+  await flush();
+  assert.equal(r.requestedHistoryKey, "ai-old", "history fetched by agent-instance key, not a stream id");
+  assert.equal(cockpit.currentAgentInstanceKey, "ai-old");
+  const transcript = r.host.byClass("cockpit-agent-transcript")[0];
+  assert.equal(transcript?.getAttribute("data-agent-instance-key"), "ai-old");
+  assert.equal(r.host.byClass("cockpit-agent-turn-text")[0]?.text(), "did the thing");
+  assert.deepEqual(r.errors, []);
+});
+
+test("clicking a run button drives viewAgentHistory", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  const button = r.host.byClass("cockpit-agent-select").find((b) => b.getAttribute("data-agent-instance-key") === "ai-old");
+  button?.dispatch("click");
+  await flush();
+  assert.equal(cockpit.currentAgentInstanceKey, "ai-old");
+});
+
+test("the embedded shell renders the terminal directly beneath the supply list, matching mount.js", async () => {
+  const r = rig();
+  bootSupplyCockpit(r.env);
+  const shell = r.host.byClass("cockpit-shell")[0];
+  const order = (shell?.children ?? []).map((c) => c.className);
+  assert.deepEqual(order, [
+    "cockpit-supply-region",
+    "cockpit-terminal",
+    "cockpit-agent-region",
+    "cockpit-agent-detail-region",
+  ]);
+});
+
+test("no agent-history panel is rendered when the engine read endpoints are unwired", async () => {
+  const r = rig(false);
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  assert.equal(r.host.byClass("cockpit-agent-region").length, 0);
+  assert.equal(cockpit.currentAgentInstanceKey, undefined);
+});
+
+test("fetchAgentInstances without fetchAgentHistory fails loudly (matched-pair guard)", () => {
+  const r = rig(false);
+  assert.throws(
+    () => bootSupplyCockpit({ ...r.env, fetchAgentInstances: () => Promise.resolve(instances) }),
+    /fetchAgentInstances and fetchAgentHistory must be provided together/,
+  );
+});