@nanobpm/nano-workforce 0.183.1 → 0.184.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **cockpit:** read transcripts on instance-scoped composeStreamId stream, not job:<jobKey> ([#754](https://github.com/nanobpm/nano-workforce/issues/754)) ([03fabb5](https://github.com/nanobpm/nano-workforce/commit/03fabb57c79c25ac0334bc0bd4a672348e5e507c)), closes [c8ctl-plugin-nano#186](https://github.com/nanobpm/c8ctl-plugin-nano/issues/186) [nano-ide#557](https://github.com/nanobpm/nano-ide/issues/557) [#543](https://github.com/nanobpm/nano-workforce/issues/543) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#543](https://github.com/nanobpm/nano-workforce/issues/543)
+
 ## [0.183.1](https://github.com/nanobpm/nano-workforce/compare/v0.183.0...v0.183.1) (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/claim-registry.test.ts

@@ -9,6 +9,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import {
   ClaimRegistry,
   currentClaimRegistry,
@@ -22,7 +23,7 @@ test("claim records both projections; jobKeysFor and primaryStreamFor resolve ag
   assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
   assert.equal(reg.ownerOf("8420"), "wk-a");
   assert.equal(reg.isClaimed("8420"), true);
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:8420");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "8420"));
   assert.equal(reg.count(), 1);
 });
 
@@ -62,7 +63,7 @@ test("a worker can hold several claims; jobKeysFor is sorted and primaryStreamFo
   reg.claim("wk-a", "8419");
   reg.claim("wk-a", "8421");
   assert.deepEqual(reg.jobKeysFor("wk-a"), ["8419", "8420", "8421"]);
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:8419");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "8419"));
 });
 
 test("release clears one claim; a late / duplicate release is a no-op", () => {

package/app/agentic/claim-registry.ts

@@ -25,7 +25,7 @@
 // type on the job protocol; ADVISORY — the registry is a read-only visibility source and NEVER
 // hard-locks or gates a BPMN sequence flow.
 
-import { jobStream } from "./correlation.ts";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 
 /** One ownership record: a worker instance's claim over a job. */
 export interface Claim {
@@ -138,14 +138,16 @@ export class ClaimRegistry {
 
   /**
    * The jobKey-scoped relay stream a worker's terminal should drill into: its lowest-sorted current
-   * claim's stream (`job:<jobKey>`). A worker runs one job at a time in this fleet, but sorting keeps
-   * it stable if it ever holds several. Undefined when the worker holds no claim — the caller then
-   * falls back to the instance-keyed stream. This is the "relay demoted to drill-in, keyed by the
-   * CLAIM (not by `instanceForConnection`)" seam.
+   * claim's stream (`composeStreamId(instance, jobKey)`). A worker runs one job at a time in this
+   * fleet, but sorting keeps it stable if it ever holds several. Undefined when the worker holds no
+   * claim — the caller then falls back to the instance-keyed stream. This is the "relay demoted to
+   * drill-in, keyed by the CLAIM (not by `instanceForConnection`)" seam. The instance-scoped stream id
+   * is the one canonical `@nanobpm/agentic/emit` codec the producer writes under (issue #738), so the
+   * cockpit drills the SAME stream the transcript bytes actually land on.
    */
   primaryStreamFor(instance: string): string | undefined {
     const [first] = this.jobKeysFor(instance);
-    return first === undefined ? undefined : jobStream(first);
+    return first === undefined ? undefined : composeStreamId(instance, first);
   }
 
   /** Whether any instance currently owns `jobKey`. */

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