@nanobpm/nano-workforce 0.183.1 → 0.184.0

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

package/operations/agentHistoryEndpoints.test.ts

@@ -0,0 +1,106 @@
+// Testkit-boot read-back tests for the engine agent-history endpoints (issue #745/#747):
+//   GET /agentic/agent-instances                          → listAgentInstances
+//   GET /agentic/agent-instances/{agentInstanceKey}/history → getAgentInstanceHistory
+//
+// These drive the REAL door through `bootTestApp`'s api driver against the WASM EngineClient double.
+// The testkit engine implements the agent read methods as READ-AS-ABSENCE (it records no AgentInstance
+// channel), so a booted app returns an empty list / empty history rather than an error — exactly the
+// contract the production consumer relies on when an engine has no durable agent history yet.
+// Behavioural parity (non-empty history) is validated against a LIVE engine, out of the testkit's scope.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import type { AppApi } from "@nanobpm/urban";
+import { assertEquals } from "#test-assert";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import type { AgentHistoryReader } from "../app/agentic/agent-history.ts";
+import { noopLog } from "../test/log.ts";
+import type { AgentHistory, AgentInstanceList } from "../nano-generated/api-io.d.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withApp(fn: (app: TestApp) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-agenthist-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("listAgentInstances: read-as-absence → 200 with an empty instance list", async () => {
+  await withApp(async (app) => {
+    const res = await app.api.call<AgentInstanceList>("listAgentInstances", {});
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 0);
+    assertEquals(res.body.instances.length, 0);
+  });
+});
+
+test("getAgentInstanceHistory: an unknown key → 200 with an empty history (read-as-absence)", async () => {
+  await withApp(async (app) => {
+    const res = await app.api.call<AgentHistory>("getAgentInstanceHistory", {
+      params: { agentInstanceKey: "no-such-instance" },
+    });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.agentInstanceKey, "no-such-instance");
+    assertEquals(res.body.count, 0);
+    assertEquals(res.body.records.length, 0);
+  });
+});
+
+// Shared-secret guard regression coverage. Both endpoints implement the same optional guard the other
+// agentic reads pin (x-hook-secret when NANO_PR_WEBHOOK_SECRET is set; unset -> open). `SECRET` is
+// captured at module load, so set the env and re-import with a cache-buster to re-capture it, exactly
+// as the sibling operation guard tests do. A lightweight stub engine (read-as-absence) is enough for
+// the authorised path — the point is to pin 401-without-header / non-401-with-header, so a future
+// refactor can't silently invert the condition or rename the header.
+const stubEngine: AgentHistoryReader = {
+  searchAgentInstances: async () => [],
+  searchAgentInstanceHistory: async () => [],
+  getAgentInstance: async () => null,
+};
+const guardApp = { log: noopLog(), engine: stubEngine } as unknown as AppApi;
+
+function guardInput(headers: Record<string, string>, params: Record<string, string> = {}) {
+  return {
+    req: { method: "GET", headers: new Headers(headers), text: async () => "" } as never,
+    params,
+    query: {},
+    body: undefined,
+  };
+}
+
+test("listAgentInstances: shared-secret guard rejects a missing/invalid secret, admits the correct one", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./listAgentInstances.ts?guard=${Date.now()}`);
+    const handler = mod.default as (i: ReturnType<typeof guardInput>, app: AppApi) => Promise<{ status: number }>;
+    assertEquals((await handler(guardInput({}), guardApp)).status, 401);
+    assertEquals((await handler(guardInput({ "x-hook-secret": "wrong" }), guardApp)).status, 401);
+    assertEquals((await handler(guardInput({ "x-hook-secret": "s3cr3t" }), guardApp)).status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});
+
+test("getAgentInstanceHistory: shared-secret guard rejects a missing/invalid secret, admits the correct one", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getAgentInstanceHistory.ts?guard=${Date.now()}`);
+    const handler = mod.default as (i: ReturnType<typeof guardInput>, app: AppApi) => Promise<{ status: number }>;
+    const params = { agentInstanceKey: "ai-1" };
+    assertEquals((await handler(guardInput({}, params), guardApp)).status, 401);
+    assertEquals((await handler(guardInput({ "x-hook-secret": "wrong" }, params), guardApp)).status, 401);
+    assertEquals((await handler(guardInput({ "x-hook-secret": "s3cr3t" }, params), guardApp)).status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgentInstanceHistory.ts

@@ -0,0 +1,37 @@
+// GET /app/api/agentic/agent-instances/{agentInstanceKey}/history → operationId `getAgentInstanceHistory`
+// (issue #745/#747, umbrella #746).
+//
+// Fetch ONE AgentInstance's durable conversation history (turns + per-turn metrics) from the engine read
+// model through the single engine-read seam — `@nanobpm/urban`'s `EngineClient.searchAgentInstanceHistory`
+// / `getAgentInstance` (added in urban 0.93 / nanobpm/nano-ide#563). The cockpit renders the HISTORICAL
+// transcript + metrics from this, keyed by `agentInstanceKey` — NEVER the slash-bearing relay stream id
+// (#744 moot). The token-granular relay stays the LIVE overlay only.
+//
+// Advisory read-only (ADR 0056): observes the engine read model, never gates control flow. Read-as-absence
+// — a blank/unknown key, or an engine with no AgentHistory channel (the testkit WASM double), yields an
+// empty history (200), never an error. Shared-secret guard mirrors the other agentic reads.
+
+import { type AgentHistoryQuery, readAgentHistory } 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("getAgentInstanceHistory", async ({ params, query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgentInstanceHistory rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.engine) {
+    app.log.warn("getAgentInstanceHistory: no engine client configured — no agent-history read path");
+    return { status: 503, body: { error: "no engine read path available" } };
+  }
+
+  const filter: AgentHistoryQuery = {
+    ...(query.role !== undefined ? { role: query.role } : {}),
+    ...(query.loopIteration !== undefined ? { loopIteration: query.loopIteration } : {}),
+    ...(query.elementInstanceKey !== undefined ? { elementInstanceKey: query.elementInstanceKey } : {}),
+  };
+  const body = await readAgentHistory(app.engine, params.agentInstanceKey, filter);
+  return { status: 200, body };
+});

package/operations/getAgenticSupply.test.ts

@@ -12,6 +12,7 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { composeStreamId, parseStreamId } from "@nanobpm/agentic/emit";
 import { currentClaimRegistry } from "../app/agentic/claim-registry.ts";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { family as claimFamily } from "../app/agentic/families/claim.family.ts";
@@ -172,7 +173,7 @@ test("#713: a claim populates jobKeys and repoints the drill stream with ZERO tr
     assertEquals(res.status, 200);
     const w = res.body.workers[0];
     assertEquals(w.jobKeys, ["8420"], "the claim registry feeds the jobKeys seam");
-    assertEquals(w.stream, "job:8420", "the drill stream repoints at the claimed job, keyed by the claim");
+    assertEquals(w.stream, composeStreamId("wk-a", "8420"), "the drill stream repoints at the claimed job, keyed by the claim");
     assertEquals(res.body.correlations.length, 0, "no correlation context until a terminal lands (drill-in only)");
   } finally {
     claimFamily.teardown?.();
@@ -210,7 +211,7 @@ test("#713: the correlation registry is demoted to drill-in context — a link a
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, "6494");
-    assertEquals(c.stream, "job:6494");
+    assertEquals(c.stream, composeStreamId("wk-a", "6494"));
     assertEquals(c.processInstanceKey, "4612");
     assertEquals(c.bpmnProcessId, "plan-fanout");
     assertEquals(c.planKey, "o/r#142");
@@ -220,3 +221,41 @@ test("#713: the correlation registry is demoted to drill-in context — a link a
     await hub.close();
   }
 });
+
+test("#738 drift: the supply advertises the producer's instance-scoped stream id, round-tripping the shared @nanobpm/agentic codec (not the retired job:<jobKey>)", async () => {
+  // The data-plane naming contract this bug (#738) restores: the producer (c8ctl-plugin-nano) writes a
+  // job's transcript under `composeStreamId(instance, jobKey)`, so the cockpit MUST advertise that exact
+  // id — both the worker drill stream (claim-keyed) and the correlation drill stream — or every
+  // transcript renders empty. This pins the consumer to the ONE shared codec: a regression back to
+  // `job:<jobKey>` (a slash-free id that never round-trips through parseStreamId) fails here.
+  const hub = await mountPresence(memSqlite());
+  const ctx: AgenticContext = { hub, registry: hub.registry, transport: undefined as never, data: undefined, log: noopLog() };
+  claimFamily.mount(ctx);
+  correlationFamily.mount(ctx);
+  const claims = currentClaimRegistry();
+  const correlation = currentCorrelation();
+  assert(claims !== undefined && correlation !== undefined, "both singletons install");
+  claims.claim("wk-a", "12559");
+  correlation.link("wk-a", "12559", { processInstanceKey: "4612", planKey: "o/r#142" });
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { workers: Array<Record<string, unknown>>; correlations: Array<Record<string, unknown>> };
+    };
+    assertEquals(res.status, 200);
+    const producerStream = composeStreamId("wk-a", "12559");
+    const w = res.body.workers[0];
+    assertEquals(w.stream, producerStream, "the cockpit drills the exact stream the producer writes");
+    const c = res.body.correlations[0];
+    assertEquals(c.stream, producerStream, "the correlation drill stream matches the producer stream");
+    // The shared codec round-trips the advertised id back to its {instance, stream} parts.
+    assertEquals(parseStreamId(producerStream), { instance: "wk-a", stream: "12559" });
+    // And it is emphatically NOT the retired job:<jobKey> scheme that left transcripts empty (#738).
+    assert(typeof w.stream === "string" && !w.stream.startsWith("job:"), "the retired job:<jobKey> data-plane scheme is gone");
+  } finally {
+    correlationFamily.teardown?.();
+    claimFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});

package/operations/getAgenticSupply.ts

@@ -6,8 +6,9 @@
 // H6/#713 closes the loop with an EXPLICIT claim registry (`app/agentic/claim-registry.ts`): it is the
 // AUTHORITATIVE source the presence snapshot's `jobKeysFor` seam resolves against, so each worker's
 // current jobKeys light up from `claim` frames — not inferred from the relay terminal — and appear even
-// with ZERO transcript. Each worker's drill `stream` is repointed at its claimed jobKey-scoped relay
-// stream (`job:<jobKey>`), keyed by the CLAIM (explicit instance+jobKey), not by a connection. The
+// with ZERO transcript. Each worker's drill `stream` is repointed at its claimed instance-scoped relay
+// stream (`composeStreamId(instance, jobKey)`, issue #738), keyed by the CLAIM (explicit
+// instance+jobKey), not by a connection. The
 // relay correlation registry is DEMOTED to drill-in context only: it still supplies the `correlations`
 // — the process-instance / plan context for a job's terminal — so the cockpit lines a worker's terminal
 // up with "that process instance / this plan", but it is no longer the visibility source.
@@ -31,9 +32,10 @@ import { defineOperation } from "../nano-generated/operations.ts";
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 // Project a presence-registry row to the wire worker. The drill `stream` defaults to the worker
-// instance (H5) but is repointed at the worker's claimed jobKey-scoped relay stream (`job:<jobKey>`)
-// when the claim registry knows a current claim for it (#713) — keyed by the CLAIM, not by the
-// connection — so drilling in opens the LIVE job's terminal even before any transcript lands.
+// instance (H5) but is repointed at the worker's claimed instance-scoped relay stream
+// (`composeStreamId(instance, jobKey)`, issue #738) when the claim registry knows a current claim for
+// it (#713) — keyed by the CLAIM, not by the connection — so drilling in opens the LIVE job's terminal
+// (the exact stream the producer writes) even before any transcript lands.
 function toWorker(w: SupplyWorker, claims: ClaimRegistry | undefined): AgenticSupplyWorker {
   const out: AgenticSupplyWorker = {
     instance: w.instance,

package/operations/getAgenticTranscript.test.ts

@@ -9,6 +9,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 { createRelayFamily, currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
 import { noopLog } from "../test/log.ts";
@@ -82,17 +83,17 @@ test("returns the whole transcript from offset 0, then a resume slice from a lat
   const store = currentRelayTranscriptService()?.store;
   assert(store !== undefined);
   store.flush(
-    "job:6494",
+    composeStreamId("wk", "6494"),
     { since: () => ({ entries: [{ offset: 0, chunk: "aa" }, { offset: 1, chunk: "bb" }, { offset: 2, chunk: "cc" }] }), nextOffset: 3 },
     "ephemeral",
   );
   try {
-    const whole = (await handler(input("job:6494"), app)) as {
+    const whole = (await handler(input(composeStreamId("wk", "6494")), app)) as {
       status: number;
       body: { stream: string; from: number; gap: boolean; nextOffset: number; chunkCount: number; byteLength: number; entries: Array<{ offset: number; chunk: string }>; jobKey?: string };
     };
     assertEquals(whole.status, 200);
-    assertEquals(whole.body.stream, "job:6494");
+    assertEquals(whole.body.stream, composeStreamId("wk", "6494"));
     assertEquals(whole.body.jobKey, "6494");
     assertEquals(whole.body.from, 0);
     assertEquals(whole.body.gap, false);
@@ -101,7 +102,7 @@ test("returns the whole transcript from offset 0, then a resume slice from a lat
     assertEquals(whole.body.byteLength, 6);
     assertEquals(whole.body.entries.map((e) => e.offset), [0, 1, 2]);
 
-    const resume = (await handler(input("job:6494", { from: 2 }), app)) as {
+    const resume = (await handler(input(composeStreamId("wk", "6494"), { from: 2 }), app)) as {
       body: { from: number; chunkCount: number; entries: Array<{ offset: number; chunk: string }> };
     };
     assertEquals(resume.body.from, 2);