@nanobpm/nano-workforce 0.69.1 → 0.70.0

package/app/blackboard.test.ts

@@ -36,15 +36,23 @@ test("publicBaseUrl: honours the env override and trims a trailing slash", () =>
 });
 
 test("publicBaseUrl: a blank/whitespace override falls back instead of yielding a bad URL", () => {
-  const prev = process.env.NANO_PR_BASE_URL;
-  delete process.env.NANO_PR_BASE_URL;
+  // Explicit override args bypass the `process.env.NANO_WORKFORCE_BASE_URL` default, so this test
+  // needs no env manipulation — the env-read path is covered by the dedicated test below.
+  assertEquals(publicBaseUrl(""), "http://localhost:3000");
+  assertEquals(publicBaseUrl("   "), "http://localhost:3000");
+  assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/app/api/hooks/blackboard?token=t");
+});
+
+test("publicBaseUrl: reads NANO_WORKFORCE_BASE_URL from the environment by default", () => {
+  const prev = process.env.NANO_WORKFORCE_BASE_URL;
   try {
-    assertEquals(publicBaseUrl(""), "http://localhost:3000");
-    assertEquals(publicBaseUrl("   "), "http://localhost:3000");
-    assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/app/api/hooks/blackboard?token=t");
+    process.env.NANO_WORKFORCE_BASE_URL = "https://fleet.example.com/console/app-view/Workforce/";
+    assertEquals(publicBaseUrl(), "https://fleet.example.com/console/app-view/Workforce");
+    delete process.env.NANO_WORKFORCE_BASE_URL;
+    assertEquals(publicBaseUrl(), "http://localhost:3000");
   } finally {
-    if (prev === undefined) delete process.env.NANO_PR_BASE_URL;
-    else process.env.NANO_PR_BASE_URL = prev;
+    if (prev === undefined) delete process.env.NANO_WORKFORCE_BASE_URL;
+    else process.env.NANO_WORKFORCE_BASE_URL = prev;
   }
 });
 

package/app/blackboard.ts

@@ -70,11 +70,11 @@ export function mintBlackboardToken(): string {
 
 /** The externally-reachable base URL agents use to reach this app. Must resolve from WHEREVER the
  * agent runs (co-located or remote/containerised), so it is configured, never hardcoded. */
-export function publicBaseUrl(env: string | undefined = process.env.NANO_PR_PUBLIC_BASE_URL): string {
-  // Cascade through the fallback chain, skipping any value that is unset OR blank/whitespace, so an
-  // explicitly-set-but-empty NANO_PR_PUBLIC_BASE_URL can't yield a malformed capability URL.
+export function publicBaseUrl(env: string | undefined = process.env.NANO_WORKFORCE_BASE_URL): string {
+  // Skip the override if it is unset OR blank/whitespace, so an explicitly-set-but-empty
+  // NANO_WORKFORCE_BASE_URL can't yield a malformed capability URL.
   const base =
-    [env, process.env.NANO_PR_BASE_URL, "http://localhost:3000"]
+    [env, "http://localhost:3000"]
       .map((v) => v?.trim())
       .find((v): v is string => Boolean(v)) ?? "http://localhost:3000";
   return base.replace(/\/+$/, "");

package/openapi.yaml

@@ -204,6 +204,167 @@ components:
             processed, so the cockpit can line each worker's terminal up with its process instance / plan (H6).
           items:
             $ref: "#/components/schemas/AgenticJobCorrelation"
+    AgenticTranscript:
+      type: object
+      description: One captured agent session's transcript metadata (H3/#146 transcript store). A durable
+        record of an ephemeral agent's terminal stream, readable AFTER the agent has exited. jobKey and
+        the process-instance / plan correlation are derived from the stream id (`job:<jobKey>`) and, when
+        the H6 correlation registry still holds the (live) job, its engine context (advisory, best-effort).
+      required:
+        - stream
+        - lifecycle
+        - status
+        - createdAt
+        - nextOffset
+        - byteLength
+        - chunkCount
+      properties:
+        stream:
+          type: string
+          description: The relay stream id the transcript was captured under (`job:<jobKey>` for a job stream).
+        lifecycle:
+          type: string
+          enum: [ephemeral, long-lived]
+          description: Retention lifecycle — ephemeral (flushed once on job completion, swept after retention)
+            or long-lived (checkpointed, bounded by a rolling offset window).
+        status:
+          type: string
+          enum: [open, completed]
+          description: open (still capturing / reattachable) or completed (the ephemeral run flushed & sealed).
+        createdAt:
+          type: string
+          description: When the stream was first opened, ISO-8601.
+        completedAt:
+          type: string
+          description: When an ephemeral run was flushed & completed, ISO-8601 (absent while open).
+        firstOffset:
+          type: integer
+          description: The oldest retained chunk offset, or absent when the transcript holds no chunks.
+        nextOffset:
+          type: integer
+          description: One past the highest offset ever recorded (the resume high-water mark).
+        byteLength:
+          type: integer
+          description: Total captured bytes across every retained chunk.
+        chunkCount:
+          type: integer
+          description: The number of retained chunks.
+        jobKey:
+          type: string
+          description: The Camunda-8 job key, decoded from a `job:<jobKey>` stream id (absent for other streams).
+        processInstanceKey:
+          type: string
+          description: The owning process instance key, when the correlation is still known (advisory).
+        bpmnProcessId:
+          type: string
+          description: The BPMN process id the job belonged to, when still known (advisory).
+        elementId:
+          type: string
+          description: The BPMN element id (activity/task) the job was for, when still known (advisory).
+        planKey:
+          type: string
+          description: The plan / epic key this job was part of (e.g. owner/repo#142), when still known (advisory).
+    AgenticTranscriptList:
+      type: object
+      description: The list of captured agent sessions (past + open) — the cockpit "past sessions" feed.
+      required:
+        - count
+        - transcripts
+      properties:
+        count:
+          type: integer
+          description: The number of transcripts returned (after any filters).
+        generatedAt:
+          type: string
+          description: When this snapshot was taken, ISO-8601.
+        retentionMs:
+          type: integer
+          description: The completed-ephemeral retention window in ms (how long a finished session is kept
+            before a retention sweep may drop it). Absent when no transcript store is mounted.
+        transcripts:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticTranscript"
+    AgenticTranscriptChunk:
+      type: object
+      description: One durable transcript chunk and the offset it was recorded at.
+      required:
+        - offset
+        - chunk
+      properties:
+        offset:
+          type: integer
+          description: The chunk's offset (resume key) — the terminal renderer resumes-from-offset off it.
+        chunk:
+          type: string
+          description: The captured terminal bytes for this offset.
+    AgenticTranscriptData:
+      type: object
+      description: A stored transcript's bytes, range/offset-based so the cockpit terminal replays it through
+        the SAME resume-from-offset renderer it uses for a live stream (static playback of a closed stream).
+      required:
+        - stream
+        - lifecycle
+        - status
+        - createdAt
+        - nextOffset
+        - byteLength
+        - chunkCount
+        - from
+        - gap
+        - entries
+      properties:
+        stream:
+          type: string
+          description: The relay stream id.
+        lifecycle:
+          type: string
+          enum: [ephemeral, long-lived]
+        status:
+          type: string
+          enum: [open, completed]
+        createdAt:
+          type: string
+          description: When the stream was first opened, ISO-8601.
+        completedAt:
+          type: string
+          description: When an ephemeral run was flushed & completed, ISO-8601 (absent while open).
+        nextOffset:
+          type: integer
+          description: One past the highest recorded offset (where a live stream would continue).
+        byteLength:
+          type: integer
+          description: Total captured bytes across the returned chunks.
+        chunkCount:
+          type: integer
+          description: The number of returned chunks.
+        from:
+          type: integer
+          description: The requested resume offset (inclusive) this page starts at.
+        gap:
+          type: boolean
+          description: True when `from` predates the oldest retained offset — earlier chunks were dropped by
+            retention, so the replay is a best-effort resume, not gap-free from `from`.
+        jobKey:
+          type: string
+          description: The Camunda-8 job key, decoded from a `job:<jobKey>` stream id (absent otherwise).
+        processInstanceKey:
+          type: string
+          description: The owning process instance key, when still known (advisory).
+        bpmnProcessId:
+          type: string
+          description: The BPMN process id, when still known (advisory).
+        elementId:
+          type: string
+          description: The BPMN element id, when still known (advisory).
+        planKey:
+          type: string
+          description: The plan / epic key, when still known (advisory).
+        entries:
+          type: array
+          description: The retained chunks with `offset >= from`, in offset order.
+          items:
+            $ref: "#/components/schemas/AgenticTranscriptChunk"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -759,6 +920,112 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agentic/transcripts:
+    get:
+      operationId: listAgenticTranscripts
+      summary: List captured agent sessions (H3/#146) — the durable transcripts an ephemeral agent flushed
+        on job completion, readable AFTER it exited. Optional filters by jobKey / process instance / plan /
+        time. Advisory read-only; never gates control flow. Feeds the cockpit "past sessions" view.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: jobKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only the transcript for this Camunda-8 job key (its `job:<jobKey>` stream).
+        - name: processInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only transcripts whose (still-known) correlation names this process instance.
+        - name: planKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only transcripts whose (still-known) correlation names this plan / epic key.
+        - name: since
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only sessions created at or after this ISO-8601 instant.
+        - name: until
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only sessions created at or before this ISO-8601 instant.
+      responses:
+        "200":
+          description: The captured session list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticTranscriptList"
+        "400":
+          description: A malformed filter (e.g. an unparseable since/until).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /agentic/transcripts/{stream}:
+    get:
+      operationId: getAgenticTranscript
+      summary: Fetch a stored transcript's bytes (H3/#146), range/offset-based so the cockpit terminal
+        replays it through the same resume-from-offset renderer it uses for a live stream. Advisory
+        read-only; never gates control flow.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: stream
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The relay stream id to fetch (`job:<jobKey>` for a job stream).
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Resume from this offset (inclusive). Default 0 (the whole retained transcript).
+      responses:
+        "200":
+          description: The stored transcript bytes from `from`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticTranscriptData"
+        "400":
+          description: A malformed `from` offset.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: No transcript exists for the given stream.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /version:
     get:
       operationId: getVersion

package/operations/getAgenticTranscript.test.ts

@@ -0,0 +1,165 @@
+// Tests for GET /app/api/agentic/transcripts/{stream} → operation `getAgenticTranscript` (H3, #222).
+//
+// Covers: 404 when no store / unknown stream; the range/offset fetch (from=0 whole transcript, from>0
+// resume-from-offset with the mirrored gap flag); the shared-secret guard; and correlation enrichment.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+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 { createRelayFamily, currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import type { AgenticContext } from "../app/agentic/registry.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./getAgenticTranscript.ts";
+
+function memSqlite(): SqliteDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: Number(r.lastInsertRowid) };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+  };
+}
+
+function memData(db: SqliteDb): DataLayer {
+  return { source: () => ({ db }) } as unknown as DataLayer;
+}
+
+function fakeHub() {
+  return {
+    registerFamilyHandler(_family: string, _handler: (frame: Frame, conn: never) => void) {},
+    registry: { has: () => false, list: () => [] },
+  };
+}
+
+function mountCtx(db: SqliteDb): AgenticContext {
+  const hub = fakeHub();
+  return {
+    hub: hub as never,
+    registry: hub.registry as unknown as ConnectionRegistry,
+    transport: undefined as never,
+    data: memData(db),
+    log: noopLog(),
+  };
+}
+
+function input(stream: string, query: Record<string, unknown> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: { method: "GET", path: `/app/api/agentic/transcripts/${stream}`, query: new URLSearchParams(), headers: new Headers(headers), text: async () => "" } as never,
+    params: { stream },
+    query,
+    body: undefined,
+  };
+}
+
+const app = { log: noopLog() } as unknown as AppApi;
+const relayFamily = createRelayFamily();
+
+test("404 when no store is mounted", async () => {
+  relayFamily.teardown?.();
+  const res = (await handler(input("job:1"), app)) as { status: number };
+  assertEquals(res.status, 404);
+});
+
+test("404 for an unknown stream", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input("job:nope"), app)) as { status: number };
+    assertEquals(res.status, 404);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("returns the whole transcript from offset 0, then a resume slice from a later offset", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush(
+    "job: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 {
+      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.jobKey, "6494");
+    assertEquals(whole.body.from, 0);
+    assertEquals(whole.body.gap, false);
+    assertEquals(whole.body.nextOffset, 3);
+    assertEquals(whole.body.chunkCount, 3);
+    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 {
+      body: { from: number; chunkCount: number; entries: Array<{ offset: number; chunk: string }> };
+    };
+    assertEquals(resume.body.from, 2);
+    assertEquals(resume.body.chunkCount, 1);
+    assertEquals(resume.body.entries.map((e) => e.chunk), ["cc"]);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("rejects a malformed from offset with a 400", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input("job:1", { from: -1 }), app)) as { status: number };
+    assertEquals(res.status, 400);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getAgenticTranscript.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input("job:1"), app)) as { status: number };
+    assertEquals(bad.status, 401);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});
+
+test("shared-secret guard admits a correct secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush(
+    "job:6494",
+    { since: () => ({ entries: [{ offset: 0, chunk: "aa" }] }), nextOffset: 1 },
+    "ephemeral",
+  );
+  try {
+    const mod = await import(`./getAgenticTranscript.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const ok = (await guarded(input("job:6494", {}, { "x-hook-secret": "s3cr3t" }), app)) as {
+      status: number;
+      body: { stream: string; chunkCount: number };
+    };
+    assertEquals(ok.status, 200);
+    assertEquals(ok.body.stream, "job:6494");
+    assertEquals(ok.body.chunkCount, 1);
+  } finally {
+    relayFamily.teardown?.();
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgenticTranscript.ts

@@ -0,0 +1,42 @@
+// GET /app/api/agentic/transcripts/{stream} → operationId `getAgenticTranscript` (ADR 0056, H3 #222).
+//
+// Fetch a stored transcript's bytes, range/offset-based (?from=<offset>, default 0) so the cockpit
+// terminal replays a closed stream through the SAME resume-from-offset renderer it uses for a live one
+// (static playback of an exited agent). Sourced from the mounted relay/transcript service's
+// TranscriptStore over `app.data`, correlated best-effort via `app/agentic/correlation.ts`.
+//
+// Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Unknown stream -> 404; a
+// malformed `from` -> 400. Shared-secret guard mirrors getAgenticSupply (x-hook-secret when
+// NANO_PR_WEBHOOK_SECRET is set; unset -> open).
+
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import { readTranscriptFrom } from "../app/agentic/transcript-read.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getAgenticTranscript", async ({ params, query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgenticTranscript rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  const from = query.from ?? 0;
+  if (!Number.isSafeInteger(from) || from < 0) {
+    return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
+  }
+
+  const store = currentRelayTranscriptService()?.store;
+  if (!store) {
+    // No transcript store mounted (relay unmounted or unpersisted) - nothing to replay.
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+
+  const data = readTranscriptFrom(params.stream, from, store, currentCorrelation());
+  if (data === undefined) {
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+  return { status: 200, body: data };
+});