@nanobpm/nano-workforce 0.183.1 → 0.184.0

package/operations/listAgentInstances.ts

@@ -0,0 +1,42 @@
+// GET /app/api/agentic/agent-instances → operationId `listAgentInstances` (issue #745/#747, umbrella #746).
+//
+// The CONSUMER half of the engine-native agent-transcript work: list the durable AgentInstances the
+// worker harness minted (against the `<zeebe:agentDefinition agentType="external"/>` marker, #748), read
+// back from the engine read model through the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient`
+// (`searchAgentInstances`, added in urban 0.93 / nanobpm/nano-ide#563). Feeds the cockpit "historical
+// sessions" view (settled history = engine; the token-granular relay stays the LIVE overlay only).
+//
+// Keyed/filtered by process / element / status — NEVER the slash-bearing `job:<jobKey>` relay stream id,
+// so the #744 gateway-proxy bug class is moot for settled history. Advisory read-only (ADR 0056): it
+// observes the engine read model, never activates/completes a job or gates a sequence flow.
+//
+// Read-as-absence: the testkit WASM double records no AgentInstance channel (returns an empty list), and
+// a live engine with no matching instance does the same — an empty list is a 200, never an error. The
+// optional shared-secret guard mirrors the other agentic reads (x-hook-secret when NANO_PR_WEBHOOK_SECRET
+// is set; unset -> open).
+
+import { type AgentInstanceQuery, listAgentInstances } from "../app/agentic/agent-history.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("listAgentInstances", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listAgentInstances rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.engine) {
+    app.log.warn("listAgentInstances: no engine client configured — no agent-history read path");
+    return { status: 503, body: { error: "no engine read path available" } };
+  }
+
+  const filter: AgentInstanceQuery = {
+    ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.rootProcessInstanceKey !== undefined ? { rootProcessInstanceKey: query.rootProcessInstanceKey } : {}),
+    ...(query.elementId !== undefined ? { elementId: query.elementId } : {}),
+    ...(query.status !== undefined ? { status: query.status } : {}),
+  };
+  const body = await listAgentInstances(app.engine, filter);
+  return { status: 200, body };
+});

package/operations/listAgenticTranscripts.test.ts

@@ -11,6 +11,7 @@ import type { Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { createRelayFamily, currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
@@ -78,8 +79,8 @@ test("projects the TranscriptStore rows into the list (byteLength, chunkCount, l
   relayFamily.mount(mountCtx(memSqlite()));
   const store = currentRelayTranscriptService()?.store;
   assert(store !== undefined, "the relay family installs a persisted store");
-  // Seed one completed ephemeral session on a jobKey-scoped stream.
-  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "hello " }, { offset: 1, chunk: "world" }] }), nextOffset: 2 }, "ephemeral");
+  // Seed one completed ephemeral session on an instance-scoped stream (issue #738).
+  store.flush(composeStreamId("wk", "6494"), { since: () => ({ entries: [{ offset: 0, chunk: "hello " }, { offset: 1, chunk: "world" }] }), nextOffset: 2 }, "ephemeral");
   try {
     const res = (await handler(input(), app)) as {
       status: number;
@@ -89,8 +90,8 @@ test("projects the TranscriptStore rows into the list (byteLength, chunkCount, l
     assertEquals(res.body.count, 1);
     assert(typeof res.body.retentionMs === "number", "the list surfaces the retention window");
     const t = res.body.transcripts[0];
-    assertEquals(t.stream, "job:6494");
-    assertEquals(t.jobKey, "6494", "the jobKey is decoded from the job: stream id");
+    assertEquals(t.stream, composeStreamId("wk", "6494"));
+    assertEquals(t.jobKey, "6494", "the jobKey is decoded from the instance-scoped stream id");
     assertEquals(t.lifecycle, "ephemeral");
     assertEquals(t.status, "completed");
     assertEquals(t.chunkCount, 2);
@@ -105,7 +106,7 @@ test("enriches with the H6 correlation (process instance / plan) when it is stil
   relayFamily.mount(mountCtx(memSqlite()));
   const store = currentRelayTranscriptService()?.store;
   assert(store !== undefined);
-  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
+  store.flush(composeStreamId("wk-a", "6494"), { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
   correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
   currentCorrelation()?.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", planKey: "o/r#142" });
   try {
@@ -124,18 +125,18 @@ test("filters by jobKey and plan", async () => {
   relayFamily.mount(mountCtx(memSqlite()));
   const store = currentRelayTranscriptService()?.store;
   assert(store !== undefined);
-  store.flush("job:1", { since: () => ({ entries: [{ offset: 0, chunk: "a" }] }), nextOffset: 1 }, "ephemeral");
-  store.flush("job:2", { since: () => ({ entries: [{ offset: 0, chunk: "b" }] }), nextOffset: 1 }, "ephemeral");
+  store.flush(composeStreamId("wk", "1"), { since: () => ({ entries: [{ offset: 0, chunk: "a" }] }), nextOffset: 1 }, "ephemeral");
+  store.flush(composeStreamId("wk", "2"), { since: () => ({ entries: [{ offset: 0, chunk: "b" }] }), nextOffset: 1 }, "ephemeral");
   correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
   currentCorrelation()?.link("wk", "2", { planKey: "o/r#9" });
   try {
     const byJob = (await handler(input({ jobKey: "1" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
     assertEquals(byJob.body.count, 1);
-    assertEquals(byJob.body.transcripts[0]?.stream, "job:1");
+    assertEquals(byJob.body.transcripts[0]?.stream, composeStreamId("wk", "1"));
 
     const byPlan = (await handler(input({ planKey: "o/r#9" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
     assertEquals(byPlan.body.count, 1);
-    assertEquals(byPlan.body.transcripts[0]?.stream, "job:2");
+    assertEquals(byPlan.body.transcripts[0]?.stream, composeStreamId("wk", "2"));
   } finally {
     correlationFamily.teardown?.();
     relayFamily.teardown?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.183.1",
+  "version": "0.184.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -65,12 +65,12 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.13.0",
-    "@nanobpm/urban": "^0.92.0",
+    "@nanobpm/urban": "^0.93.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^1.3.0",
+    "@nanobpm/urban-testkit": "^1.4.0",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",

package/pages/cockpit/cockpit.css

@@ -43,6 +43,8 @@
 
 .cockpit-supply-region,
 .cockpit-past-region,
+.cockpit-agent-region,
+.cockpit-agent-detail-region,
 .cockpit-terminal {
   background: var(--cockpit-panel);
   border: 1px solid var(--cockpit-edge);
@@ -243,6 +245,108 @@
   padding: 8px 0;
 }
 
+/* ── Agent history (engine-native settled AgentInstance/AgentHistory, #745/#747). ─────────────── */
+
+.cockpit-agent-header,
+.cockpit-agent-transcript-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.cockpit-agent-title,
+.cockpit-agent-transcript-title {
+  font-size: 13px;
+  margin: 0;
+  color: var(--cockpit-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-agent-summary,
+.cockpit-agent-transcript-metrics {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-agent-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-agent-select {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-agent-select:hover { color: #58a6ff; }
+
+.cockpit-agent-session[data-active="true"] {
+  background: rgba(88, 166, 255, 0.12);
+}
+
+.cockpit-agent-status { color: var(--cockpit-muted); }
+.cockpit-agent-metrics { color: var(--cockpit-muted); font-size: 12px; }
+.cockpit-agent-captured { color: var(--cockpit-muted); font-size: 12px; }
+
+.cockpit-agent-empty,
+.cockpit-agent-transcript-empty {
+  color: var(--cockpit-muted);
+  padding: 8px 0;
+}
+
+.cockpit-agent-turn {
+  border-top: 1px solid var(--cockpit-edge);
+  padding: 8px 0;
+}
+
+.cockpit-agent-turn-meta {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+  margin-bottom: 4px;
+}
+
+.cockpit-agent-turn-role {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: #58a6ff;
+}
+
+.cockpit-agent-turn-iter,
+.cockpit-agent-turn-metrics {
+  font-size: 11px;
+  color: var(--cockpit-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-agent-turn-text {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font: inherit;
+}
+
+.cockpit-agent-turn-tools {
+  margin: 4px 0 0;
+  padding-left: 18px;
+  color: var(--cockpit-muted);
+  font-size: 12px;
+}
+
 /* ── Worker detail route (#/cockpit/worker/<instance>): header + current job + filtered history. ── */
 
 .cockpit-worker-detail {

package/pages/cockpit/mount.js

@@ -430,6 +430,192 @@ function transcriptSink(host, stream, opts = {}) {
   };
 }
 
+// ── engine agent-history projection + render (mirrors app/agentic/cockpit/agent-history-view.ts + -render.ts) ──
+//
+// The CONSUMER half of the durable-agent-transcript work (issue #745/#747): the SETTLED agent-run list +
+// a selected run's ordered conversation turns + metrics, sourced from the engine read model
+// (`GET /agentic/agent-instances` + `…/{agentInstanceKey}/history`, served from `@nanobpm/urban`'s
+// EngineClient `searchAgentInstances` / `searchAgentInstanceHistory`), keyed by agentInstanceKey — NOT
+// a relay stream id (#744 moot for historical reads). The relay past-sessions panel above stays the
+// LIVE overlay only. Kept a faithful hand-twin of the server view/render modules (mount.js cannot
+// import them); the server modules carry the Node-tested SSOT.
+
+function humanCount(n) {
+  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`;
+}
+
+function humanMs(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return undefined;
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function instanceLabel(i) {
+  const parts = [];
+  if (i.processDefinitionId != null && i.processDefinitionId !== "") parts.push(i.processDefinitionId);
+  if (i.elementId != null && i.elementId !== "") parts.push(i.elementId);
+  if (i.processInstanceKey != null && i.processInstanceKey !== "") parts.push(`inst ${i.processInstanceKey}`);
+  if (parts.length > 0) return parts.join(" \u00b7 ");
+  return i.agentInstanceKey;
+}
+
+function instanceMetrics(m) {
+  if (m == null) return undefined;
+  return `${humanCount(m.inputTokens)} in \u00b7 ${humanCount(m.outputTokens)} out \u00b7 ${m.modelCalls} calls \u00b7 ${m.toolCalls} tools`;
+}
+
+function agentSessionView(i) {
+  const capturedAt = i.completionDate ?? i.lastUpdatedDate ?? i.creationDate;
+  return {
+    agentInstanceKey: i.agentInstanceKey,
+    label: instanceLabel(i),
+    status: i.status,
+    metrics: instanceMetrics(i.metrics),
+    capturedAt: capturedAt != null && capturedAt !== "" ? capturedAt : undefined,
+  };
+}
+
+function agentSessionsView(report) {
+  const sessions = (report.instances ?? [])
+    .map(agentSessionView)
+    .sort((a, b) => {
+      const byTime = String(b.capturedAt ?? "").localeCompare(String(a.capturedAt ?? ""));
+      return byTime !== 0 ? byTime : a.agentInstanceKey.localeCompare(b.agentInstanceKey);
+    });
+  return { sessions, count: sessions.length };
+}
+
+function turnText(r) {
+  return (r.content ?? [])
+    .filter((b) => b.contentType === "TEXT" && b.text != null && b.text !== "")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+function turnMetrics(m) {
+  if (m == null) return undefined;
+  const dur = humanMs(m.durationMs);
+  const base = `${humanCount(m.inputTokens)} in \u00b7 ${humanCount(m.outputTokens)} out`;
+  return dur != null ? `${base} \u00b7 ${dur}` : base;
+}
+
+function agentHistoryView(report) {
+  const turns = (report.records ?? []).map((r) => ({
+    historyItemKey: r.historyItemKey,
+    loopIteration: r.loopIteration,
+    role: r.role,
+    text: turnText(r),
+    toolCalls: (r.toolCalls ?? []).map((c) => ({ toolCallId: c.toolCallId, toolName: c.toolName, elementId: c.elementId })),
+    metrics: turnMetrics(r.metrics),
+  }));
+  return {
+    agentInstanceKey: report.agentInstanceKey,
+    instance: report.instance != null ? agentSessionView(report.instance) : undefined,
+    turns,
+    count: turns.length,
+  };
+}
+
+function agentSessionRow(doc, s, onSelect, activeInstanceKey) {
+  const row = el(doc, "tr", "cockpit-agent-session");
+  row.setAttribute("data-agent-instance-key", s.agentInstanceKey);
+  row.setAttribute("data-status", s.status);
+  if (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);
+  if (onSelect) 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;
+}
+
+function renderAgentSessions(host, doc, view, onSelect, activeInstanceKey) {
+  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", "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", "No agent runs recorded yet.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return;
+  }
+  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(agentSessionRow(doc, s, onSelect, activeInstanceKey));
+  table.appendChild(tbody);
+  root.appendChild(table);
+  host.appendChild(root);
+}
+
+function agentTurnBlock(doc, t) {
+  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 != null) 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 != null && call.elementId !== "" ? `${call.toolName} (${call.elementId})` : call.toolName);
+      li.setAttribute("data-tool-call-id", call.toolCallId);
+      tools.appendChild(li);
+    }
+    block.appendChild(tools);
+  }
+  return block;
+}
+
+function renderAgentHistory(host, doc, view) {
+  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 != null) {
+    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;
+  }
+  const turns = el(doc, "div", "cockpit-agent-turns");
+  for (const t of view.turns) turns.appendChild(agentTurnBlock(doc, t));
+  root.appendChild(turns);
+  host.appendChild(root);
+}
+
 // ── boot orchestration (mirrors app/agentic/cockpit/supply-boot.ts) ────────────────────────────
 
 /** A WebSocket relay socket factory for the agentic channel at `url`. */
@@ -463,14 +649,19 @@ function relaySocketFactory(url) {
  * @param {number} [opts.refreshMs] — poll interval (default 2000).
  * @param {number} [opts.staleAfterMs] — a worker is rendered "stale" once its last heartbeat is at
  *   least this many ms old (default 15000).
- * @param {number} [opts.pastFetchTimeoutMs] — upper bound (ms) on a single past-sessions transcripts
- *   fetch; the fetch is aborted past this so a hung endpoint can't wedge the past panel (default 15000).
+ * @param {number} [opts.pastFetchTimeoutMs] — upper bound (ms) on a single bounded engine JSON fetch:
+ *   both a past-sessions transcripts fetch AND (via `boundedJson`) an engine agent-history fetch are
+ *   aborted past this so a hung endpoint can't wedge the past or agent-history panel (default 15000).
  * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint backing the always-on
  *   "past sessions" history + replay (default
  *   `new URL("../app/api/agentic/transcripts", import.meta.url).href`, module-anchored so it
  *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell
  *   base). The per-session replay read uses the proxy-safe `?stream=` query form on this same URL
  *   (#744 — never a `/…/<id>` path segment, which a decoding gateway splits on encoded slashes).
+ * @param {string} [opts.agentInstancesUrl] — the engine-native SETTLED agent-history list endpoint
+ *   (default `new URL("../app/api/agentic/agent-instances", import.meta.url).href`, module-anchored
+ *   like the others). Selecting a run reads `…/agent-instances/{agentInstanceKey}/history` off this
+ *   same base (issue #745/#747). Keyed by agentInstanceKey — the engine read seam, not a relay stream.
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -494,6 +685,7 @@ export function mountCockpit(host, opts = {}) {
   // injects window.__NANO_APP_VIEW__, so this default is what actually runs there too.
   const reportUrl = opts.reportUrl ?? new URL("../app/api/agentic/supply", import.meta.url).href;
   const transcriptsUrl = opts.transcriptsUrl ?? new URL("../app/api/agentic/transcripts", import.meta.url).href;
+  const agentInstancesUrl = opts.agentInstancesUrl ?? new URL("../app/api/agentic/agent-instances", import.meta.url).href;
   const hookSecret = opts.hookSecret;
   const relayUrl = opts.relayUrl ?? defaultRelayUrl(opts.relayToken, opts.relayCapability);
   const refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
@@ -531,6 +723,11 @@ export function mountCockpit(host, opts = {}) {
   const shell = el(doc, "div", "cockpit-shell");
   const listRegion = el(doc, "div", "cockpit-supply-region");
   const pastRegion = el(doc, "div", "cockpit-past-region");
+  // The engine-native SETTLED agent-history panel (issue #745): a list region + a detail region,
+  // sourced from the engine read model and keyed by agentInstanceKey (distinct from the relay
+  // past-sessions overlay above).
+  const agentRegion = el(doc, "div", "cockpit-agent-region");
+  const agentDetailRegion = el(doc, "div", "cockpit-agent-detail-region");
   const terminalPanel = el(doc, "section", "cockpit-terminal");
   terminalPanel.setAttribute("data-terminal-mode", "idle");
   const terminalTitle = el(doc, "h2", "cockpit-panel-title", "Worker terminal");
@@ -547,6 +744,8 @@ export function mountCockpit(host, opts = {}) {
   shell.appendChild(listRegion);
   shell.appendChild(terminalPanel);
   shell.appendChild(pastRegion);
+  shell.appendChild(agentRegion);
+  shell.appendChild(agentDetailRegion);
   host.appendChild(shell);
 
   let running = false;
@@ -566,6 +765,11 @@ export function mountCockpit(host, opts = {}) {
   // against a slow/hung transcripts endpoint.
   let pastRefreshing = false;
   let pastRefreshPending = false;
+  // Single-flight latch for the engine agent-history list refresh (mirrors pastRefreshing), and the
+  // agent instance whose settled history is currently shown in the detail region.
+  let agentRefreshing = false;
+  let agentRefreshPending = false;
+  let shownAgentInstanceKey;
 
   function setMode(next, stream) {
     mode = next;
@@ -851,6 +1055,85 @@ export function mountCockpit(host, opts = {}) {
     }
     // Fire-and-forget: a hung transcripts endpoint must never stall the supply poll's next tick.
     void refreshPast(routeInstance());
+    // Same discipline for the engine agent-history list (issue #745): single-flight + bounded.
+    void refreshAgentHistory();
+  }
+
+  // The engine-native SETTLED agent-history endpoints (issue #745/#747), anchored module-relatively
+  // like the other API URLs. The per-instance history rides a PATH segment — an engine agent-instance
+  // key is a plain (slash-free) key, so unlike the slash-bearing relay stream id (#744) it is
+  // proxy-safe as a path segment; encode it defensively all the same.
+  function agentHistoryReadUrl(agentInstanceKey) {
+    const base = new URL(agentInstancesUrl, location.href);
+    base.pathname = `${base.pathname.replace(/\/$/, "")}/${encodeURIComponent(agentInstanceKey)}/history`;
+    return base.href;
+  }
+
+  // Shared bounded-fetch helper for the engine JSON read endpoints (agent-instances list +
+  // per-instance agent-history). Reuses `pastFetchTimeoutMs` as the abort bound — the same discipline
+  // as the past-sessions fetches — so a hung engine read endpoint can't wedge the agent-history panel.
+  async function boundedJson(url) {
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), pastFetchTimeoutMs);
+    abortTimer.unref?.();
+    try {
+      const res = await fetch(url, { headers: jsonHeaders(), signal: controller.signal });
+      if (!res.ok) throw new Error(`fetch failed: ${res.status} (${url})`);
+      return await res.json();
+    } finally {
+      clearTimeout(abortTimer);
+    }
+  }
+
+  async function refreshAgentHistory() {
+    // Single-flight (mirrors refreshPast): a slow/hung engine read endpoint never stacks fetches nor
+    // gates the supply poll. The list is engine-global (settled AgentInstances), so it is not route-filtered.
+    if (agentRefreshing) {
+      agentRefreshPending = true;
+      return;
+    }
+    agentRefreshing = true;
+    try {
+      let report;
+      try {
+        report = await boundedJson(agentInstancesUrl);
+      } catch (err) {
+        onError(err);
+        return;
+      }
+      if (disposed) return;
+      try {
+        renderAgentSessions(agentRegion, doc, agentSessionsView(report), viewAgentHistory, shownAgentInstanceKey);
+      } catch (err) {
+        onError(err);
+      }
+    } finally {
+      agentRefreshing = false;
+      if (agentRefreshPending && !disposed) {
+        agentRefreshPending = false;
+        void refreshAgentHistory();
+      }
+    }
+  }
+
+  async function viewAgentHistory(agentInstanceKey) {
+    if (disposed) return;
+    let report;
+    try {
+      report = await boundedJson(agentHistoryReadUrl(agentInstanceKey));
+    } catch (err) {
+      onError(err);
+      return;
+    }
+    if (disposed) return;
+    try {
+      shownAgentInstanceKey = agentInstanceKey;
+      renderAgentHistory(agentDetailRegion, doc, agentHistoryView(report));
+      // Re-render the list so the just-selected run shows as active (best-effort).
+      void refreshAgentHistory();
+    } catch (err) {
+      onError(err);
+    }
   }
 
   function tick(gen) {
@@ -884,7 +1167,7 @@ export function mountCockpit(host, opts = {}) {
   }
 
   start();
-  return { start, stop, dispose, refresh, drill: drillInto, replay: replayInto };
+  return { start, stop, dispose, refresh, drill: drillInto, replay: replayInto, viewAgentHistory };
 }
 
 /**

package/test/agentic-e2e.test.ts

@@ -27,6 +27,7 @@ import type { SqliteDb } from "@nanobpm/agentic/presence";
 import { decodeFrame, encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { loadAgenticFamilies } from "../app/agentic/loader.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "../app/agentic/registry.ts";
@@ -146,7 +147,9 @@ function supplyInput() {
 test("E2E: the whole visibility plane wires up — presence, correlation, supply report, relay drill, and resume across a hub restart", async () => {
   const db = memSqlite();
   const JOB = "6494";
-  const STREAM = `job:${JOB}`;
+  // The producer writes a job's terminal on the instance-scoped stream (issue #738); the drill stream
+  // the supply advertises MUST be this exact id, or the cockpit reads a stream that never existed.
+  const STREAM = composeStreamId("wk-a", JOB);
 
   // Sanity: the fleet the seam discovers really includes presence, relay, and correlation.
   const fleet = await mountFleet(db);