@nanobpm/nano-workforce 0.183.2 → 0.184.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.184.0](https://github.com/nanobpm/nano-workforce/compare/v0.183.2...v0.184.0) (2026-09-07)
+
+### Features
+
+* **agent:** consume engine-native AgentInstance/AgentHistory for cockpit history ([#756](https://github.com/nanobpm/nano-workforce/issues/756)) ([555463f](https://github.com/nanobpm/nano-workforce/commit/555463fb4b65f3aaf3aa27a36b518855dddce5b8)), closes [#745](https://github.com/nanobpm/nano-workforce/issues/745) [#747](https://github.com/nanobpm/nano-workforce/issues/747) [#755](https://github.com/nanobpm/nano-workforce/issues/755) [jwulf/c8ctl-plugin-nano#195](https://github.com/jwulf/c8ctl-plugin-nano/issues/195) [#194](https://github.com/nanobpm/nano-workforce/issues/194) [745/#747](https://github.com/745/nano-workforce/issues/747) [#refreshAgentHistory](https://github.com/nanobpm/nano-workforce/issues/refreshAgentHistory) [745/#747](https://github.com/745/nano-workforce/issues/747)
+
 ## [0.183.2](https://github.com/nanobpm/nano-workforce/compare/v0.183.1...v0.183.2) (2026-09-07)
 
 ### Bug Fixes

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

@@ -0,0 +1,165 @@
+// Pure projection tests for the engine-native AgentInstance/AgentHistory READ path (issue #745/#747).
+// Exercises app/agentic/agent-history.ts against a fake AgentHistoryReader — no engine, no I/O — so the
+// engine→wire projection, keying, ordering, optional-field dropping, and read-as-absence are pinned on
+// Node. Behavioural parity against a LIVE engine is validated separately; the testkit WASM double
+// records nothing (read-as-absence), which the boot test asserts.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type {
+  AgentHistoryFilter,
+  AgentHistoryRecord,
+  AgentInstanceFilter,
+  AgentInstanceSummary,
+} from "@nanobpm/urban";
+import {
+  type AgentHistoryReader,
+  listAgentInstances,
+  readAgentHistory,
+  toWireInstance,
+  toWireRecord,
+} from "./agent-history.ts";
+
+class FakeReader implements AgentHistoryReader {
+  instanceFilter: AgentInstanceFilter | undefined;
+  historyFilter: AgentHistoryFilter | undefined;
+  historyKey: string | undefined;
+  readonly #instances: readonly AgentInstanceSummary[];
+  readonly #history: readonly AgentHistoryRecord[];
+  readonly #byKey: Record<string, AgentInstanceSummary>;
+  constructor(
+    instances: readonly AgentInstanceSummary[],
+    history: readonly AgentHistoryRecord[] = [],
+    byKey: Record<string, AgentInstanceSummary> = {},
+  ) {
+    this.#instances = instances;
+    this.#history = history;
+    this.#byKey = byKey;
+  }
+  async searchAgentInstances(filter?: AgentInstanceFilter): Promise<readonly AgentInstanceSummary[]> {
+    this.instanceFilter = filter;
+    return this.#instances;
+  }
+  async searchAgentInstanceHistory(
+    agentInstanceKey: string,
+    filter?: AgentHistoryFilter,
+  ): Promise<readonly AgentHistoryRecord[]> {
+    this.historyKey = agentInstanceKey;
+    this.historyFilter = filter;
+    return this.#history;
+  }
+  async getAgentInstance(agentInstanceKey: string): Promise<AgentInstanceSummary | null> {
+    return this.#byKey[agentInstanceKey] ?? null;
+  }
+}
+
+const instance = (over: Partial<AgentInstanceSummary> & { agentInstanceKey: string }): AgentInstanceSummary => ({
+  status: "COMPLETED",
+  processInstanceKey: "pi-1",
+  ...over,
+});
+
+const record = (over: Partial<AgentHistoryRecord> & { historyItemKey: string }): AgentHistoryRecord => ({
+  agentInstanceKey: "ai-1",
+  loopIteration: 0,
+  role: "ASSISTANT",
+  content: [],
+  toolCalls: [],
+  commitStatus: "COMMITTED",
+  ...over,
+});
+
+test("toWireInstance drops unreported optional fields and copies metrics", () => {
+  const bare = toWireInstance(instance({ agentInstanceKey: "ai-1", elementId: "", creationDate: "" }));
+  assert.deepEqual(bare, { agentInstanceKey: "ai-1", status: "COMPLETED", processInstanceKey: "pi-1" });
+
+  const full = toWireInstance(
+    instance({
+      agentInstanceKey: "ai-2",
+      elementId: "implement-task",
+      elementInstanceKeys: ["ei-9"],
+      rootProcessInstanceKey: "root-1",
+      metrics: { inputTokens: 10, outputTokens: 4, modelCalls: 2, toolCalls: 1 },
+      creationDate: "2024-01-01T00:00:00Z",
+      completionDate: "2024-01-01T00:05:00Z",
+    }),
+  );
+  assert.equal(full.elementId, "implement-task");
+  assert.deepEqual(full.elementInstanceKeys, ["ei-9"]);
+  assert.deepEqual(full.metrics, { inputTokens: 10, outputTokens: 4, modelCalls: 2, toolCalls: 1 });
+  assert.equal(full.completionDate, "2024-01-01T00:05:00Z");
+});
+
+test("toWireRecord preserves conversation grammar and per-turn metrics", () => {
+  const wire = toWireRecord(
+    record({
+      historyItemKey: "h-1",
+      loopIteration: 3,
+      role: "ASSISTANT",
+      content: [
+        { contentType: "TEXT", text: "hello" },
+        { contentType: "OBJECT", object: { a: 1 } },
+      ],
+      toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool-task", arguments: { q: "x" } }],
+      metrics: {
+        inputTokens: 5,
+        outputTokens: 2,
+        reasoningTokenCount: 1,
+        cacheCreationTokenCount: 0,
+        cacheReadTokenCount: 0,
+        durationMs: 1200,
+      },
+      elementInstanceKey: "ei-3",
+    }),
+  );
+  assert.equal(wire.content.length, 2);
+  assert.equal(wire.content[0]?.text, "hello");
+  assert.deepEqual(wire.content[1]?.object, { a: 1 });
+  assert.equal(wire.toolCalls[0]?.elementId, "tool-task");
+  assert.deepEqual(wire.toolCalls[0]?.arguments, { q: "x" });
+  assert.equal(wire.metrics?.durationMs, 1200);
+  assert.equal(wire.elementInstanceKey, "ei-3");
+});
+
+test("listAgentInstances applies only non-blank selectors and sorts newest-created first", async () => {
+  const reader = new FakeReader([
+    instance({ agentInstanceKey: "old", creationDate: "2024-01-01T00:00:00Z" }),
+    instance({ agentInstanceKey: "new", creationDate: "2024-02-01T00:00:00Z" }),
+  ]);
+  const out = await listAgentInstances(reader, { processInstanceKey: "pi-1", status: "", elementId: undefined });
+  assert.deepEqual(reader.instanceFilter, { processInstanceKey: "pi-1" });
+  assert.equal(out.count, 2);
+  assert.deepEqual(
+    out.instances.map((i) => i.agentInstanceKey),
+    ["new", "old"],
+  );
+});
+
+test("readAgentHistory sorts by loopIteration then key, enriches with the owning instance", async () => {
+  const owner = instance({ agentInstanceKey: "ai-1", metrics: { inputTokens: 1, outputTokens: 1, modelCalls: 1, toolCalls: 0 } });
+  const reader = new FakeReader(
+    [],
+    [
+      record({ historyItemKey: "h-2", loopIteration: 1 }),
+      record({ historyItemKey: "h-1", loopIteration: 1 }),
+      record({ historyItemKey: "h-0", loopIteration: 0 }),
+    ],
+    { "ai-1": owner },
+  );
+  const out = await readAgentHistory(reader, "ai-1", { role: "ASSISTANT", loopIteration: 1, elementInstanceKey: "" });
+  assert.equal(reader.historyKey, "ai-1");
+  assert.deepEqual(reader.historyFilter, { role: "ASSISTANT", loopIteration: 1 });
+  assert.deepEqual(
+    out.records.map((r) => r.historyItemKey),
+    ["h-0", "h-1", "h-2"],
+  );
+  assert.equal(out.instance?.agentInstanceKey, "ai-1");
+  assert.equal(out.instance?.metrics?.inputTokens, 1);
+});
+
+test("readAgentHistory read-as-absence: a blank key yields an empty history and no engine call", async () => {
+  const reader = new FakeReader([instance({ agentInstanceKey: "x" })], [record({ historyItemKey: "h" })]);
+  const out = await readAgentHistory(reader, "");
+  assert.equal(out.count, 0);
+  assert.equal(out.agentInstanceKey, "");
+  assert.equal(reader.historyKey, undefined);
+});

package/app/agentic/agent-history.ts

@@ -0,0 +1,211 @@
+// nano-workforce — the engine-native AgentInstance/AgentHistory READ path (issue #745 / #747,
+// umbrella #746). The CONSUMER half of the durable-agent-transcript work.
+//
+// The write path is engine-native: the worker harness (jwulf/c8ctl-plugin-nano#194) mints
+// Create/Update/Complete AgentInstance/AgentHistory records against the engine for every element that
+// carries the `<zeebe:agentDefinition agentType="external"/>` marker (the PRODUCER half, landed in
+// #748). This module is the READ counterpart: it projects the engine's durable AgentInstance +
+// AgentHistory read model onto the wire shapes the Cockpit "historical" transcript + per-turn metrics
+// view renders — keyed by AGENT-INSTANCE / PROCESS-INSTANCE / ELEMENT-INSTANCE keys, never the
+// slash-bearing `job:<jobKey>` relay stream id (so the #744 gateway-proxy bug class is moot for
+// settled history; live tail stays on the relay overlay).
+//
+// The engine reach is the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient`
+// (`searchAgentInstances` / `searchAgentInstanceHistory` / `getAgentInstance`, added in urban 0.93 /
+// nanobpm/nano-ide#563). No second broker-REST client, no `orchestration-cluster-api-js` fork: option
+// (a) from the escalation, so the read path is exercised by the testkit WASM double
+// (`@nanobpm/urban-testkit` ≥ 1.4 records none — read-as-absence — while a live engine validates the
+// behavioural parity).
+//
+// Invariant fit (ADR 0056): this is an ADVISORY, READ-ONLY engine query. It observes the engine read
+// model to render a visibility view; it NEVER activates/completes a job, publishes a message, or gates
+// a BPMN sequence flow. It is deliberately expressed against a NARROW reader shape (not the whole
+// `EngineClient`) so the callers that drive it stay structurally decoupled from the engine — the same
+// discipline as `./element-instance.ts`.
+//
+// Pure and side-effect-free apart from the injected reader: unit-testable on Node with a fake reader.
+
+import type {
+  AgentHistoryFilter,
+  AgentHistoryRecord,
+  AgentInstanceFilter,
+  AgentInstanceSummary,
+} from "@nanobpm/urban";
+import type {
+  AgentHistory as WireAgentHistory,
+  AgentHistoryRecord as WireAgentHistoryRecord,
+  AgentInstance as WireAgentInstance,
+  AgentInstanceList as WireAgentInstanceList,
+} from "../../nano-generated/api-io.d.ts";
+
+/**
+ * The narrow slice of the engine read model the historical-transcript consumer needs: the three
+ * engine-native agent read methods. `@nanobpm/urban`'s `EngineClient` satisfies it structurally; a
+ * test supplies a fake. Kept minimal (three methods, not the whole `EngineClient`) so a caller depends
+ * on a capability, not the engine.
+ */
+export interface AgentHistoryReader {
+  searchAgentInstances(filter?: AgentInstanceFilter): Promise<readonly AgentInstanceSummary[]>;
+  searchAgentInstanceHistory(
+    agentInstanceKey: string,
+    filter?: AgentHistoryFilter,
+  ): Promise<readonly AgentHistoryRecord[]>;
+  getAgentInstance(agentInstanceKey: string): Promise<AgentInstanceSummary | null>;
+}
+
+/** The selectors {@link listAgentInstances} understands (all optional; an empty filter lists all). */
+export interface AgentInstanceQuery {
+  readonly processInstanceKey?: string;
+  readonly rootProcessInstanceKey?: string;
+  readonly status?: string;
+  readonly elementId?: string;
+}
+
+/** The selectors {@link readAgentHistory} understands beyond the required `agentInstanceKey`. */
+export interface AgentHistoryQuery {
+  readonly role?: AgentHistoryRecord["role"];
+  readonly loopIteration?: number;
+  readonly elementInstanceKey?: string;
+}
+
+/** Drop an empty/blank string filter value (No Drift Surfaces — the presence rule the key selectors
+ *  elsewhere in this seam use: an omitted/blank selector is not applied). */
+function present(value: string | undefined): value is string {
+  return value !== undefined && value !== "";
+}
+
+/** Project an engine {@link AgentInstanceSummary} onto the wire {@link WireAgentInstance}, dropping the
+ *  optional fields the engine did not report (so the wire object is minimal and stable). */
+export function toWireInstance(summary: AgentInstanceSummary): WireAgentInstance {
+  const out: WireAgentInstance = {
+    agentInstanceKey: summary.agentInstanceKey,
+    status: summary.status,
+    processInstanceKey: summary.processInstanceKey,
+  };
+  if (present(summary.elementId)) out.elementId = summary.elementId;
+  if (summary.elementInstanceKeys !== undefined && summary.elementInstanceKeys.length > 0) {
+    out.elementInstanceKeys = [...summary.elementInstanceKeys];
+  }
+  if (present(summary.rootProcessInstanceKey)) out.rootProcessInstanceKey = summary.rootProcessInstanceKey;
+  if (present(summary.processDefinitionKey)) out.processDefinitionKey = summary.processDefinitionKey;
+  if (present(summary.processDefinitionId)) out.processDefinitionId = summary.processDefinitionId;
+  if (summary.metrics !== undefined) {
+    out.metrics = {
+      inputTokens: summary.metrics.inputTokens,
+      outputTokens: summary.metrics.outputTokens,
+      modelCalls: summary.metrics.modelCalls,
+      toolCalls: summary.metrics.toolCalls,
+    };
+  }
+  if (present(summary.creationDate)) out.creationDate = summary.creationDate;
+  if (present(summary.lastUpdatedDate)) out.lastUpdatedDate = summary.lastUpdatedDate;
+  if (present(summary.completionDate)) out.completionDate = summary.completionDate;
+  return out;
+}
+
+/** Project one engine {@link AgentHistoryRecord} (turn) onto the wire {@link WireAgentHistoryRecord},
+ *  preserving the Camunda `AgentHistoryRecordValue` conversation grammar (role, content blocks, tool
+ *  calls, per-turn metrics) the transcript store already models — one shape, no drift. */
+export function toWireRecord(record: AgentHistoryRecord): WireAgentHistoryRecord {
+  const out: WireAgentHistoryRecord = {
+    historyItemKey: record.historyItemKey,
+    agentInstanceKey: record.agentInstanceKey,
+    loopIteration: record.loopIteration,
+    role: record.role,
+    commitStatus: record.commitStatus,
+    content: record.content.map((block) => {
+      const b: WireAgentHistoryRecord["content"][number] = { contentType: block.contentType };
+      if (block.text !== undefined) b.text = block.text;
+      if (block.documentReference !== undefined) b.documentReference = block.documentReference;
+      if (block.object !== undefined) b.object = block.object;
+      return b;
+    }),
+    toolCalls: record.toolCalls.map((call) => {
+      const c: WireAgentHistoryRecord["toolCalls"][number] = {
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        arguments: { ...call.arguments },
+      };
+      if (present(call.elementId)) c.elementId = call.elementId;
+      return c;
+    }),
+  };
+  if (record.metrics !== undefined) {
+    out.metrics = {
+      inputTokens: record.metrics.inputTokens,
+      outputTokens: record.metrics.outputTokens,
+      reasoningTokenCount: record.metrics.reasoningTokenCount,
+      cacheCreationTokenCount: record.metrics.cacheCreationTokenCount,
+      cacheReadTokenCount: record.metrics.cacheReadTokenCount,
+      durationMs: record.metrics.durationMs,
+    };
+  }
+  if (present(record.elementInstanceKey)) out.elementInstanceKey = record.elementInstanceKey;
+  if (present(record.jobKey)) out.jobKey = record.jobKey;
+  if (present(record.producedAt)) out.producedAt = record.producedAt;
+  return out;
+}
+
+/**
+ * List the engine-native agent instances matching `query`, projected onto the wire list shape and
+ * sorted newest-created-first (stable on `agentInstanceKey`). Only non-blank selectors are applied.
+ * Read-as-absence: an engine with no AgentInstance channel (or no matching instance) yields an empty
+ * list, never an error.
+ */
+export async function listAgentInstances(
+  reader: AgentHistoryReader,
+  query: AgentInstanceQuery = {},
+): Promise<WireAgentInstanceList> {
+  const filter: AgentInstanceFilter = {
+    ...(present(query.processInstanceKey) ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(present(query.rootProcessInstanceKey) ? { rootProcessInstanceKey: query.rootProcessInstanceKey } : {}),
+    ...(present(query.status) ? { status: query.status } : {}),
+    ...(present(query.elementId) ? { elementId: query.elementId } : {}),
+  };
+  const summaries = await reader.searchAgentInstances(filter);
+  const instances = summaries.map(toWireInstance).sort((a, b) => {
+    // Newest-created first; a missing creationDate sorts last (oldest), stable on the key.
+    const byTime = (b.creationDate ?? "").localeCompare(a.creationDate ?? "");
+    return byTime !== 0 ? byTime : a.agentInstanceKey.localeCompare(b.agentInstanceKey);
+  });
+  return { count: instances.length, generatedAt: new Date().toISOString(), instances };
+}
+
+/**
+ * Read one agent instance's durable conversation history (turns + per-turn metrics) from the engine,
+ * projected onto the wire shape and sorted in conversational order — by `loopIteration`, then by the
+ * creation-ordered `historyItemKey` within an iteration. Enriched with the owning instance's summary
+ * (its rolled-up metrics + lifecycle) when the engine still reports it. A blank key or an unknown
+ * instance yields an empty history (read-as-absence), never an error.
+ */
+export async function readAgentHistory(
+  reader: AgentHistoryReader,
+  agentInstanceKey: string,
+  query: AgentHistoryQuery = {},
+): Promise<WireAgentHistory> {
+  if (!present(agentInstanceKey)) {
+    return { agentInstanceKey: "", count: 0, generatedAt: new Date().toISOString(), records: [] };
+  }
+  const filter: AgentHistoryFilter = {
+    ...(query.role !== undefined ? { role: query.role } : {}),
+    ...(query.loopIteration !== undefined ? { loopIteration: query.loopIteration } : {}),
+    ...(present(query.elementInstanceKey) ? { elementInstanceKey: query.elementInstanceKey } : {}),
+  };
+
+  const [rawRecords, summary] = await Promise.all([
+    reader.searchAgentInstanceHistory(agentInstanceKey, filter),
+    reader.getAgentInstance(agentInstanceKey),
+  ]);
+  const records = rawRecords.map(toWireRecord).sort((a, b) => {
+    if (a.loopIteration !== b.loopIteration) return a.loopIteration - b.loopIteration;
+    return a.historyItemKey.localeCompare(b.historyItemKey);
+  });
+  const out: WireAgentHistory = {
+    agentInstanceKey,
+    count: records.length,
+    generatedAt: new Date().toISOString(),
+    records,
+  };
+  if (summary !== null) out.instance = toWireInstance(summary);
+  return out;
+}

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

@@ -0,0 +1,85 @@
+// DOM-render tests for the cockpit engine-native agent-history renderer (issue #745/#747). Exercises
+// the pure renderer against the in-memory FakeDocument/FakeElement doubles — no browser.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { FakeDocument, FakeElement } from "../../../test/agentic-cockpit-doubles.ts";
+import type { AgentHistoryView, AgentSessionsView } from "./agent-history-view.ts";
+import { renderAgentHistory, renderAgentSessions } from "./agent-history-render.ts";
+
+const doc = new FakeDocument();
+
+test("renderAgentSessions lists runs and wires onSelect to the instance key", () => {
+  const host = new FakeElement("div");
+  const view: AgentSessionsView = {
+    count: 1,
+    sessions: [
+      {
+        agentInstanceKey: "ai-1",
+        label: "feature \u00b7 implement-task",
+        status: "COMPLETED",
+        processInstanceKey: "pi-1",
+        metrics: "1.5k in \u00b7 340 out \u00b7 3 calls \u00b7 5 tools",
+        capturedAt: "2024-01-01T00:00:00Z",
+      },
+    ],
+  };
+  const selected: string[] = [];
+  renderAgentSessions(host, doc, view, { onSelect: (k) => selected.push(k), activeInstanceKey: "ai-1" });
+
+  const rows = host.byClass("cockpit-agent-session");
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0]?.getAttribute("data-agent-instance-key"), "ai-1");
+  assert.equal(rows[0]?.getAttribute("data-active"), "true");
+  const button = host.byClass("cockpit-agent-select")[0];
+  assert.ok(button);
+  button?.dispatch("click");
+  assert.deepEqual(selected, ["ai-1"]);
+});
+
+test("renderAgentSessions renders an explicit empty state (read-as-absence)", () => {
+  const host = new FakeElement("div");
+  renderAgentSessions(host, doc, { count: 0, sessions: [] });
+  assert.equal(host.byData("empty", "true").length, 1);
+  assert.equal(host.byClass("cockpit-agent-session").length, 0);
+});
+
+test("renderAgentHistory renders turns with role, text, tool calls and per-turn metrics", () => {
+  const host = new FakeElement("div");
+  const view: AgentHistoryView = {
+    agentInstanceKey: "ai-1",
+    count: 1,
+    instance: {
+      agentInstanceKey: "ai-1",
+      label: "feature",
+      status: "COMPLETED",
+      processInstanceKey: "pi-1",
+      metrics: "20 in \u00b7 8 out \u00b7 2 calls \u00b7 1 tools",
+    },
+    turns: [
+      {
+        historyItemKey: "h-1",
+        loopIteration: 1,
+        role: "ASSISTANT",
+        text: "on it",
+        toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool" }],
+        metrics: "12 in \u00b7 4 out \u00b7 900ms",
+      },
+    ],
+  };
+  renderAgentHistory(host, doc, view);
+
+  const root = host.byClass("cockpit-agent-transcript")[0];
+  assert.equal(root?.getAttribute("data-agent-instance-key"), "ai-1");
+  assert.equal(host.byData("summary", "agent-instance-metrics").length, 1);
+  const turn = host.byClass("cockpit-agent-turn")[0];
+  assert.equal(turn?.getAttribute("data-role"), "ASSISTANT");
+  assert.equal(host.byClass("cockpit-agent-turn-text")[0]?.text(), "on it");
+  assert.equal(host.byClass("cockpit-agent-turn-tool")[0]?.text(), "grep (tool)");
+  assert.equal(host.byClass("cockpit-agent-turn-metrics")[0]?.text(), "12 in \u00b7 4 out \u00b7 900ms");
+});
+
+test("renderAgentHistory renders an empty history state", () => {
+  const host = new FakeElement("div");
+  renderAgentHistory(host, doc, { agentInstanceKey: "ai-9", count: 0, turns: [] });
+  assert.equal(host.byData("empty", "true").length, 1);
+});

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