@nanobpm/nano-workforce 0.183.2 → 0.184.1

package/app/agentic/cockpit/supply-boot.ts

@@ -28,6 +28,13 @@ import {
   TerminalSession,
   type TerminalSink,
 } from "@nanobpm/agentic/cockpit";
+import { renderAgentHistory, renderAgentSessions } from "./agent-history-render.ts";
+import {
+  type AgentHistoryReport,
+  type AgentInstanceListReport,
+  agentHistoryView,
+  agentSessionsView,
+} from "./agent-history-view.ts";
 import type { CockpitRoute } from "./cockpit-route.ts";
 import { renderSupply } from "./supply-render.ts";
 import type { SupplyReport, SupplyView } from "./supply-view.ts";
@@ -69,6 +76,23 @@ export interface SupplyCockpitEnv {
    * Required for the "past sessions" replay to work; must be provided together with {@link fetchTranscripts}.
    */
   readonly fetchTranscript?: (stream: string, from?: number) => Promise<TranscriptDataReport>;
+  /**
+   * Fetches the engine-native AgentInstance list (`GET /agentic/agent-instances`, served from
+   * `@nanobpm/urban`'s EngineClient `searchAgentInstances`) for the SETTLED "agent history" panel
+   * (issue #745/#747). Optional: when omitted the agent-history panel is not rendered. Must be
+   * provided together with {@link fetchAgentHistory}. This is the CONSUMER read path — settled history
+   * derives from engine truth keyed by agent-instance / process keys, NOT the slash-bearing relay
+   * stream id (so the #744 gateway-proxy bug class is moot); the relay past-sessions panel above stays
+   * the LIVE overlay only.
+   */
+  readonly fetchAgentInstances?: (processInstanceKey?: string) => Promise<AgentInstanceListReport>;
+  /**
+   * Fetches one AgentInstance's durable conversation history (turns + per-turn metrics) from engine
+   * `searchAgentInstanceHistory` (`GET /agentic/agent-instances/{agentInstanceKey}/history`), for the
+   * historical transcript view. Required for the agent-history panel's drill-in to work; must be
+   * provided together with {@link fetchAgentInstances}.
+   */
+  readonly fetchAgentHistory?: (agentInstanceKey: string) => Promise<AgentHistoryReport>;
   /** Opens a socket to the app relay channel (one per drill-in connection). */
   readonly connectRelay: SocketFactory;
   /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
@@ -117,6 +141,8 @@ export interface SupplyCockpitHandle {
   drill(stream: string): void;
   /** Replay a captured past session's stored transcript statically into the terminal (no live worker). */
   replay(stream: string): Promise<void>;
+  /** View one engine-native agent instance's settled conversation history in the agent-history panel. */
+  viewAgentHistory(agentInstanceKey: string): Promise<void>;
   /** Open a worker's dedicated detail page. */
   openWorker(instance: string): void;
   /** Return to the main worker list. */
@@ -125,6 +151,8 @@ export interface SupplyCockpitHandle {
   readonly currentRoute: CockpitRoute;
   /** The stream currently drilled into or replayed, if any. */
   readonly currentStream: string | undefined;
+  /** The agent instance whose settled history is currently shown in the agent-history panel, if any. */
+  readonly currentAgentInstanceKey: string | undefined;
   /** Whether the terminal is showing a LIVE stream or a REPLAYED transcript (undefined when idle). */
   readonly currentMode: TerminalMode | undefined;
   /** Stop everything and release the terminal connection. */
@@ -147,6 +175,11 @@ class SupplyCockpit implements SupplyCockpitHandle {
   readonly #env: SupplyCockpitEnv;
   readonly #listRegion: ElementLike;
   readonly #pastRegion: ElementLike | undefined;
+  // The engine-native SETTLED agent-history panel (issue #745): a list region (the AgentInstance runs)
+  // and a detail region (a selected instance's ordered conversation turns + metrics). Present only when
+  // the engine agent-history read endpoints are wired. Distinct from #pastRegion (the relay live overlay).
+  readonly #agentRegion: ElementLike | undefined;
+  readonly #agentDetailRegion: ElementLike | undefined;
   // A dedicated volatile region the STRUCTURED derived view (messages, rich tool/diff cards, permission
   // prompts) is mounted into on a replay — beside, and additive to, the byte-level terminal replay
   // (which is left untouched). Present only when the transcript read endpoints are wired.
@@ -182,6 +215,12 @@ class SupplyCockpit implements SupplyCockpitHandle {
   // hung transcripts endpoint can't accumulate pending calls.
   #pastRefreshing = false;
   #pastRefreshPending = false;
+  // Single-flight latch for the agent-history list refresh (mirrors #pastRefreshing), so the poll can
+  // never stack engine agent-instance fetches against a slow/unresponsive read endpoint.
+  #agentRefreshing = false;
+  #agentRefreshPending = false;
+  // The agent instance whose settled history is currently rendered in the detail region, if any.
+  #shownAgentInstanceKey: string | undefined;
   #route: CockpitRoute = { kind: "main" };
   #view: SupplyView | undefined;
   // Bumped by every start()/stop() so an in-flight #tick() from a previous start cycle can't
@@ -217,6 +256,12 @@ class SupplyCockpit implements SupplyCockpitHandle {
     if ((env.fetchTranscripts === undefined) !== (env.fetchTranscript === undefined)) {
       throw new Error("SupplyCockpitEnv.fetchTranscripts and fetchTranscript must be provided together (or neither)");
     }
+    // The engine agent-history LIST source and the per-instance HISTORY source are likewise a matched
+    // pair: the panel renders whenever the list source is present, but its rows route through
+    // viewAgentHistory(), which no-ops without the history source. Require both together (or neither).
+    if ((env.fetchAgentInstances === undefined) !== (env.fetchAgentHistory === undefined)) {
+      throw new Error("SupplyCockpitEnv.fetchAgentInstances and fetchAgentHistory must be provided together (or neither)");
+    }
     this.#setTimer =
       env.setTimer ??
       ((run, ms) => {
@@ -255,6 +300,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
       this.#pastRegion = env.doc.createElement("div");
       this.#pastRegion.className = "cockpit-past-region";
     }
+    // The engine-native agent-history panel: a list region + a detail region, present only when the
+    // engine agent-history read endpoints are wired.
+    if (env.fetchAgentInstances !== undefined) {
+      this.#agentRegion = env.doc.createElement("div");
+      this.#agentRegion.className = "cockpit-agent-region";
+      this.#agentDetailRegion = env.doc.createElement("div");
+      this.#agentDetailRegion.className = "cockpit-agent-detail-region";
+    }
     this.#terminalPanel = env.doc.createElement("section");
     this.#terminalPanel.className = "cockpit-terminal";
     this.#terminalPanel.setAttribute("data-terminal-mode", "idle");
@@ -282,9 +335,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
     this.#terminalNote.className = "cockpit-terminal-note";
     this.#terminalNote.setAttribute("data-terminal-note", "none");
     this.#terminalPanel.appendChild(this.#terminalNote);
+    // Order MUST match the browser twin (pages/cockpit/mount.js) and its tests: the terminal sits
+    // directly beneath the supply list, since cockpit.css keys layout off DOM order (no grid areas).
+    // supply list → terminal → past sessions → agent list → agent detail.
     shell.appendChild(this.#listRegion);
-    if (this.#pastRegion !== undefined) shell.appendChild(this.#pastRegion);
     shell.appendChild(this.#terminalPanel);
+    if (this.#pastRegion !== undefined) shell.appendChild(this.#pastRegion);
+    if (this.#agentRegion !== undefined) shell.appendChild(this.#agentRegion);
+    if (this.#agentDetailRegion !== undefined) shell.appendChild(this.#agentDetailRegion);
     env.host.appendChild(shell);
   }
 
@@ -292,6 +350,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
     return this.#shownStream;
   }
 
+  get currentAgentInstanceKey(): string | undefined {
+    return this.#shownAgentInstanceKey;
+  }
+
   get currentMode(): TerminalMode | undefined {
     return this.#mode;
   }
@@ -350,6 +412,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
     // transcripts endpoint that hangs (not just rejects) would otherwise stall #refresh() forever and
     // wedge the live worker list. #refreshPast is single-flight, so a slow fetch can't pile up either.
     void this.#refreshPast(this.#route.kind === "worker" ? this.#route.instance : undefined);
+    // Same fire-and-forget discipline for the engine agent-history list: a slow/hung read endpoint must
+    // never gate the supply poll's next tick. #refreshAgentHistory is single-flight + bounded. The list
+    // is engine-global (not route-filtered), so it takes no route instance — call it with no argument.
+    void this.#refreshAgentHistory();
   }
 
   #renderRoute(): void {
@@ -413,6 +479,73 @@ class SupplyCockpit implements SupplyCockpitHandle {
     }
   }
 
+  /** Fetch + render the engine-native SETTLED agent-history list, when the read endpoints are wired.
+   * Single-flight + bounded (mirrors {@link #refreshPast}): an engine read fault/hang never blocks the
+   * live worker list. The list is engine-global (settled AgentInstances), so it is not route-filtered. */
+  async #refreshAgentHistory(): Promise<void> {
+    const fetchAgentInstances = this.#env.fetchAgentInstances;
+    if (fetchAgentInstances === undefined || this.#agentRegion === undefined) return;
+    if (this.#agentRefreshing) {
+      this.#agentRefreshPending = true;
+      return;
+    }
+    this.#agentRefreshing = true;
+    try {
+      let report: AgentInstanceListReport;
+      try {
+        report = await this.#bounded(() => fetchAgentInstances(), "agent-instances");
+      } catch (err) {
+        if (this.#disposed) return;
+        this.#env.onError?.(err);
+        return;
+      }
+      if (this.#disposed || this.#agentRegion === undefined) return;
+      try {
+        renderAgentSessions(this.#agentRegion, this.#env.doc, agentSessionsView(report), {
+          onSelect: (agentInstanceKey) => void this.viewAgentHistory(agentInstanceKey),
+          ...(this.#shownAgentInstanceKey !== undefined ? { activeInstanceKey: this.#shownAgentInstanceKey } : {}),
+        });
+      } catch (err) {
+        this.#env.onError?.(err);
+      }
+    } finally {
+      this.#agentRefreshing = false;
+      if (this.#agentRefreshPending && !this.#disposed) {
+        this.#agentRefreshPending = false;
+        void this.#refreshAgentHistory();
+      }
+    }
+  }
+
+  /**
+   * Fetch + render one engine-native agent instance's SETTLED conversation history (turns + per-turn /
+   * instance metrics) into the detail region, keyed by `agentInstanceKey` — the CONSUMER read path
+   * (issue #745/#747). Bounded so a hung engine read can't wedge the panel. Read-as-absence: an unknown
+   * key renders an explicit empty history, never an error.
+   */
+  async viewAgentHistory(agentInstanceKey: string): Promise<void> {
+    if (this.#disposed) return;
+    const fetchAgentHistory = this.#env.fetchAgentHistory;
+    if (fetchAgentHistory === undefined || this.#agentDetailRegion === undefined) return;
+    let report: AgentHistoryReport;
+    try {
+      report = await this.#bounded(() => fetchAgentHistory(agentInstanceKey), "agent-history");
+    } catch (err) {
+      if (this.#disposed) return;
+      this.#env.onError?.(err);
+      return;
+    }
+    if (this.#disposed || this.#agentDetailRegion === undefined) return;
+    try {
+      this.#shownAgentInstanceKey = agentInstanceKey;
+      renderAgentHistory(this.#agentDetailRegion, this.#env.doc, agentHistoryView(report));
+      // Re-render the list so the just-selected run shows as active (best-effort).
+      void this.#refreshAgentHistory();
+    } catch (err) {
+      this.#env.onError?.(err);
+    }
+  }
+
   /**
    * Race an injected fetch against a timeout so the returned promise ALWAYS settles, even if the fetch
    * HANGS (never settles, not merely rejects). Both single-flight callers below — the past-sessions list

package/app/contracts.ts

@@ -484,9 +484,17 @@ export const WIRE_CONTRACTS = {
     name: "agentTask.agentDefinition",
     owner: "resources/processes/*.bpmn",
     semantics:
-      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half, deferred until the broker read API is reachable from the app's EngineClient). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
+      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
+  "agentTask.historyRead": {
+    category: "wire",
+    name: "agentTask.historyRead",
+    owner: "app/agentic/agent-history.ts",
+    semantics:
+      "The engine-native AgentInstance/AgentHistory READ path (issue #745/#747, umbrella #746 — the CONSUMER half of the PRODUCER `agentTask.agentDefinition` marker). The Cockpit HISTORICAL transcript + per-turn/instance metrics are sourced from the engine read model through the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient.searchAgentInstances`/`searchAgentInstanceHistory`/`getAgentInstance` (added in urban 0.93 / nanobpm/nano-ide#563; the escalation's option (a) — NO `orchestration-cluster-api-js` fork / no second broker-REST client, so the read path is exercised by the testkit WASM double, which records read-as-absence — an empty list / null — while a live engine validates the behavioural parity). ONE narrow reader (`AgentHistoryReader`) + ONE projection (`listAgentInstances`/`readAgentHistory`) in app/agentic/agent-history.ts, served by `GET /agentic/agent-instances` + `GET /agentic/agent-instances/{agentInstanceKey}/history`. Correlation keys are the AGENT-INSTANCE / PROCESS-INSTANCE / ELEMENT-INSTANCE keys (the same #544 per-occupancy element-instance handle the relay correlation uses) — NEVER the slash-bearing `job:<jobKey>` relay stream id, so the #744 gateway-proxy bug class is moot for settled history. The token-granular relay stays the LIVE overlay only (settled history = engine, live tail = relay). Advisory read-only (ADR 0056): it observes the engine read model, never activates/completes a job or gates a sequence flow. The wire shapes (`AgentInstance`/`AgentInstanceList`/`AgentHistoryRecord`/`AgentHistory` + the metrics shapes) are declared in openapi.yaml and reuse the `@nanobpm/agentic/transcript` parity conversation grammar the transcript store already models. Consume this ONE read path — do not add a second agent-history client or a synonym endpoint.",
+    shape: "GET /agentic/agent-instances[?processInstanceKey&rootProcessInstanceKey&elementId&status] → AgentInstanceList; GET /agentic/agent-instances/{agentInstanceKey}/history[?role&loopIteration&elementInstanceKey] → AgentHistory",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/mcpToolSurface.ts

@@ -98,8 +98,15 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * each of the two transcript tools, keeping the `?stream=` form discoverable from the tool surface
  * alone (measured +219 bytes serialized, 83,824 → 84,043 — over the old ceiling's 176-byte
  * headroom). Deliberate, documented growth — not schema fat.
+ *
+ * RAISE PROVENANCE — 84_500 → 86_500 (#745/#747, umbrella #746): the engine-native agent-history
+ * read surface adds two GET tools — `listAgentInstances` and `getAgentInstanceHistory` — that read
+ * the durable AgentInstance / AgentHistory channels for wedge triage (kept on the surface per the
+ * `x-mcp` convention that read/orient doors stay exposed; only operator-only control doors are
+ * excluded, see app/mcpExclusions.test.ts). Measured +1,846 bytes serialized (84,043 → 85,889 —
+ * over the old ceiling's 457-byte headroom). Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 84_500;
+export const MCP_SURFACE_BYTES_BUDGET = 86_500;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/db/migrations/101_agentic_history_read_expand.sql

@@ -0,0 +1,34 @@
+-- Engine-native AgentInstance/AgentHistory read path — EXPAND phase (issue #745/#747, umbrella #746).
+--
+-- The CONSUMER half of the durable-agent-transcript work. The Cockpit HISTORICAL transcript + per-turn
+-- and instance metrics are now sourced from the engine read model (`searchAgentInstances` /
+-- `searchAgentInstanceHistory` / `getAgentInstance` on `@nanobpm/urban`'s EngineClient — urban 0.93 /
+-- nanobpm/nano-ide#563), served by `GET /agentic/agent-instances` and
+-- `GET /agentic/agent-instances/{agentInstanceKey}/history` (app/agentic/agent-history.ts). Settled
+-- history now derives from engine truth, keyed by agent-instance / process-instance / element-instance
+-- keys — never the slash-bearing `job:<jobKey>` relay stream id.
+--
+-- EXPAND / CONTRACT DISCIPLINE (AGENTS.md — forward-only, additive expand; destructive contract later):
+--
+--   • EXPAND (this phase, no schema change): begin sourcing HISTORICAL reads from engine AgentHistory.
+--     The engine read path holds no app-side table (it reads the engine read model over the SDK/broker),
+--     so there is NO new DDL and NOTHING is dropped here. This migration records the transition in the
+--     schema history so the expand phase is an explicit, ordered ledger entry, mirroring the DDL-less
+--     documented-meaning precedent in 013_merge_train_waiting_lane.sql.
+--
+--   • RETAIN (unchanged): the relay transcript tables `agentic_transcript_stream` /
+--     `agentic_transcript_chunk` (024_agentic_transcript.sql) and the `transcript.readUrl` scheme STAY.
+--     They remain the LIVE OVERLAY — the token-granular tail of a still-running agent — which the engine
+--     settled-history read deliberately does NOT replace. Do not drop them here.
+--
+--   • CONTRACT (a LATER, separate phase — tracked, NOT executed here): once nothing reads the relay
+--     tables / the transcript-URL scheme for SETTLED history (i.e. the live overlay is the only remaining
+--     consumer, or it too has moved), a future forward-only migration DROPs `agentic_transcript_*` and
+--     retires the URL scheme. That destructive drop is intentionally deferred behind a release that has
+--     stopped reading the old shape (expand-and-contract), and is tracked as its own issue so the
+--     remainder is a filed, claimable work item rather than invisible prose.
+--     Deferred-to: nanobpm/nano-workforce#755
+--
+-- Additive and idempotent: no column/table is created, altered, or dropped, so it is safe to apply
+-- forward over any earlier schema and re-runs are no-ops.
+SELECT 1;

package/openapi.yaml

@@ -1002,6 +1002,250 @@ components:
           description: The retained chunks with `offset >= from`, in offset order.
           items:
             $ref: "#/components/schemas/AgenticTranscriptChunk"
+    AgentInstanceMetrics:
+      type: object
+      description: >-
+        Aggregated metrics the engine rolls up on an AgentInstance across all of its model
+        calls (issue #745/#747 — the CONSUMER half). Total tokens consumed, and the count of model /
+        tool calls made. Distinct from the per-turn metrics carried on an AgentHistoryRecord.
+      required:
+        - inputTokens
+        - outputTokens
+        - modelCalls
+        - toolCalls
+      properties:
+        inputTokens:
+          type: integer
+          description: Total input (prompt) tokens consumed across the instance's model calls.
+        outputTokens:
+          type: integer
+          description: Total output (completion) tokens produced across the instance's model calls.
+        modelCalls:
+          type: integer
+          description: The number of LLM model calls the agent made.
+        toolCalls:
+          type: integer
+          description: The number of tool calls the agent dispatched.
+    AgentInstance:
+      type: object
+      description: >-
+        One engine-native AgentInstance as `searchAgentInstances` / `getAgentInstance` report
+        it (issue #745/#747, umbrella #746 — Camunda 8.10 parity). The durable projection of an agent
+        task's run, minted by the worker harness against the `<zeebe:agentDefinition agentType="external"/>`
+        marker (#748). Keyed by `agentInstanceKey` (passed to the history read) and correlated by
+        process / element-instance keys — NEVER the slash-bearing `job:<jobKey>` relay stream id.
+      required:
+        - agentInstanceKey
+        - status
+        - processInstanceKey
+      properties:
+        agentInstanceKey:
+          type: string
+          description: The engine-unique agent-instance key — the identity a caller passes to the history read.
+        status:
+          type: string
+          description: The lifecycle status (the engine's broad `AgentInstanceStatusEnum` — e.g.
+            INITIALIZING / THINKING / TOOL_CALLING / IDLE / COMPLETED), a bare string.
+        processInstanceKey:
+          type: string
+          description: The owning process-instance key.
+        elementId:
+          type: string
+          description: The BPMN element id (the AI-agent task) that owns the instance, when reported.
+        elementInstanceKeys:
+          type: array
+          description: The engine element-instance keys the instance's token(s) occupied (#544) — per-occupancy
+            handles, unambiguous across a looping / retried activity. Omitted when the engine reports none.
+          items:
+            type: string
+        rootProcessInstanceKey:
+          type: string
+          description: The root process-instance key of the owning hierarchy, when reported.
+        processDefinitionKey:
+          type: string
+          description: The owning process-definition key, when reported.
+        processDefinitionId:
+          type: string
+          description: The owning process-definition id, when reported.
+        metrics:
+          $ref: "#/components/schemas/AgentInstanceMetrics"
+        creationDate:
+          type: string
+          description: When the instance was created, ISO-8601, when reported.
+        lastUpdatedDate:
+          type: string
+          description: When the instance was last updated, ISO-8601, when reported.
+        completionDate:
+          type: string
+          description: When the instance completed, ISO-8601 (absent while still running).
+    AgentInstanceList:
+      type: object
+      description: >-
+        The list of engine-native agent instances (issue #745/#747), newest-created first —
+        the cockpit "historical sessions" feed sourced from engine history (not the relay store).
+      required:
+        - count
+        - instances
+      properties:
+        count:
+          type: integer
+          description: The number of instances returned (after any filters).
+        generatedAt:
+          type: string
+          description: When this snapshot was taken, ISO-8601.
+        instances:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentInstance"
+    AgentHistoryContentBlock:
+      type: object
+      description: One typed content block in a turn's message (Camunda `AgentHistoryMessageContentValue`
+        parity). Exactly one payload is populated per `contentType`.
+      required:
+        - contentType
+      properties:
+        contentType:
+          type: string
+          enum: [TEXT, DOCUMENT, OBJECT, UNSPECIFIED]
+          description: The content type; selects which payload field is populated.
+        text:
+          type: string
+          description: Text payload; populated when `contentType` is TEXT.
+        documentReference:
+          type: string
+          description: Document reference; populated when `contentType` is DOCUMENT.
+        object:
+          description: JSON value payload (any JSON type); populated when `contentType` is OBJECT.
+    AgentHistoryToolCall:
+      type: object
+      description: A tool call embedded in a turn (Camunda `AgentHistoryEmbeddedToolCallValue` parity).
+      required:
+        - toolCallId
+        - toolName
+        - arguments
+      properties:
+        toolCallId:
+          type: string
+          description: The stable tool-call id (pairs a call to its result).
+        toolName:
+          type: string
+          description: The tool that was called.
+        elementId:
+          type: string
+          description: The tool task's BPMN element id, when reported.
+        arguments:
+          type: object
+          description: The arguments passed to the tool (an arbitrary JSON object).
+          additionalProperties: true
+    AgentHistoryTurnMetrics:
+      type: object
+      description: Per-turn metrics (Camunda `AgentHistoryMetricsValue` parity) — the token counts a
+        single turn's LLM call consumed/produced and its wall-clock duration. Distinct from the
+        instance-level `AgentInstanceMetrics`.
+      required:
+        - inputTokens
+        - outputTokens
+        - reasoningTokenCount
+        - cacheCreationTokenCount
+        - cacheReadTokenCount
+        - durationMs
+      properties:
+        inputTokens:
+          type: integer
+        outputTokens:
+          type: integer
+        reasoningTokenCount:
+          type: integer
+        cacheCreationTokenCount:
+          type: integer
+        cacheReadTokenCount:
+          type: integer
+        durationMs:
+          type: integer
+    AgentHistoryRecord:
+      type: object
+      description: >-
+        One agent-instance history item (a turn) as `searchAgentInstanceHistory` reports it
+        (issue #745/#747) — the projection of the engine's `AgentInstanceHistoryItemResult`, i.e. one
+        Camunda `AgentHistoryRecordValue`. Its conversation grammar reuses the transcript parity types,
+        so the engine-read seam and the relay transcript store project the SAME shape (No Drift Surfaces).
+      required:
+        - historyItemKey
+        - agentInstanceKey
+        - loopIteration
+        - role
+        - content
+        - toolCalls
+        - commitStatus
+      properties:
+        historyItemKey:
+          type: string
+          description: The stable, creation-ordered identity of the history item.
+        agentInstanceKey:
+          type: string
+          description: The owning agent-instance key.
+        loopIteration:
+          type: integer
+          description: The agent-loop counter (one LLM call + its tool dispatches + results share an iteration).
+        role:
+          type: string
+          enum: [USER, ASSISTANT, TOOL_RESULT, CONFIGURATION, UNSPECIFIED]
+          description: The conversation role of the turn.
+        content:
+          type: array
+          description: The turn's typed content blocks.
+          items:
+            $ref: "#/components/schemas/AgentHistoryContentBlock"
+        toolCalls:
+          type: array
+          description: The tool calls embedded in the turn.
+          items:
+            $ref: "#/components/schemas/AgentHistoryToolCall"
+        metrics:
+          $ref: "#/components/schemas/AgentHistoryTurnMetrics"
+        commitStatus:
+          type: string
+          description: The engine's COMMITTED / PENDING / DISCARDED commit flag (a bare string).
+        elementInstanceKey:
+          type: string
+          description: The element instance the item was produced under, when reported (best-effort).
+        jobKey:
+          type: string
+          description: The job key the item was produced under, when reported (best-effort).
+        producedAt:
+          type: string
+          description: When the item was produced, ISO-8601, when reported (best-effort).
+    AgentHistory:
+      type: object
+      description: >-
+        One agent instance's durable conversation history (turns + per-turn metrics) sourced
+        from engine `searchAgentInstanceHistory` (issue #745/#747), in conversational order. The cockpit
+        renders the HISTORICAL transcript + metrics from this; the token-granular relay stays the LIVE
+        overlay only. Keyed by `agentInstanceKey` — never the slash-bearing relay stream id (#744 moot).
+      required:
+        - agentInstanceKey
+        - count
+        - records
+      properties:
+        agentInstanceKey:
+          type: string
+          description: The agent-instance key this history belongs to.
+        count:
+          type: integer
+          description: The number of history records (turns) returned.
+        generatedAt:
+          type: string
+          description: When this snapshot was taken, ISO-8601.
+        instance:
+          allOf:
+            - $ref: "#/components/schemas/AgentInstance"
+          description: The owning instance summary (rolled-up metrics + lifecycle), when the engine still
+            reports it. Absent when the instance is unknown/aged out.
+        records:
+          type: array
+          description: The history records (turns), ordered by loopIteration then creation-ordered key.
+          items:
+            $ref: "#/components/schemas/AgentHistoryRecord"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -3945,6 +4189,122 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agentic/agent-instances:
+    get:
+      operationId: listAgentInstances
+      summary: >-
+        List engine-native AgentInstances (issue #745/#747, umbrella #746) — the durable agent-task
+        runs the worker harness minted against the `<zeebe:agentDefinition agentType="external"/>` marker,
+        read back from the engine read model (`searchAgentInstances`), newest-created first. Keyed/filtered
+        by process / element / status — NOT the slash-bearing relay stream id. Advisory read-only; never
+        gates control flow. Feeds the cockpit "historical sessions" view (settled history = engine; live
+        tail = relay overlay). Read-as-absence — an engine with no AgentInstance channel returns an empty list.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: processInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only agent instances owned by this process instance.
+        - name: rootProcessInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only agent instances in this root process-instance hierarchy.
+        - name: elementId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only agent instances owned by this BPMN element (the AI-agent task).
+        - name: status
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only agent instances in this lifecycle status (the engine's `AgentInstanceStatusEnum`).
+      responses:
+        "200":
+          description: The engine-native agent instances matching the filters.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentInstanceList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "503":
+          description: No engine read path available (no engine client configured).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /agentic/agent-instances/{agentInstanceKey}/history:
+    get:
+      operationId: getAgentInstanceHistory
+      summary: >-
+        Fetch one AgentInstance's durable conversation history (turns + per-turn metrics) from
+        engine `searchAgentInstanceHistory` (issue #745/#747), in conversational order, with the owning
+        instance's rolled-up metrics when still reported. The cockpit renders the HISTORICAL transcript +
+        metrics from this — keyed by `agentInstanceKey`, never the slash-bearing relay stream id (#744
+        moot). Advisory read-only; never gates control flow. Read-as-absence — an unknown key / an engine
+        with no AgentHistory channel returns an empty history.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: agentInstanceKey
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The engine agent-instance key whose history to read (from `listAgentInstances`).
+        - name: role
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [USER, ASSISTANT, TOOL_RESULT, CONFIGURATION, UNSPECIFIED]
+          description: Only turns with this conversation role. Any value from the enum is
+            forwarded verbatim to the engine as the filter.
+        - name: loopIteration
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Only turns produced in this agent-loop iteration.
+        - name: elementInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Only turns produced under this element instance.
+      responses:
+        "200":
+          description: The agent instance's history (turns + metrics), possibly empty.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentHistory"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "503":
+          description: No engine read path available (no engine client configured).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /reconcile:
     post:
       operationId: reconcileEngineState