@nanobpm/nano-workforce 0.69.0 → 0.70.0

package/app/agentic/transcript-read.ts

@@ -0,0 +1,161 @@
+// nano-workforce — the transcript READ projection (ADR 0056, H3 / #146, read path #222).
+//
+// The write path (relay.family.ts) flushes an ephemeral agent's PTY stream to a durable transcript on
+// job completion; this module is the READ counterpart the advisory `GET /agentic/transcripts*`
+// endpoints share. It projects a {@link TranscriptStore} row (+ its retained chunks) onto the wire
+// shape and enriches it with the H6 correlation (`app/agentic/correlation.ts`) so a captured session
+// lines up with "that process instance / this plan" — even after the ephemeral agent has exited.
+//
+// Correlation is BEST-EFFORT and advisory: the correlation registry is in-memory and only holds
+// currently-linked jobs, so a completed session's process-instance / plan context is present only
+// while the job is still live. The jobKey itself is always recoverable — it is encoded in the stream
+// id (`job:<jobKey>`), so a past session is never anonymous even once its correlation has been released.
+//
+// Pure and side-effect-free apart from reading the store: no I/O beyond the injected store, so it is
+// unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
+
+import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
+import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+
+/** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
+export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
+  let total = 0;
+  for (const c of chunks) total += Buffer.byteLength(c.chunk, "utf8");
+  return total;
+}
+
+/** The correlation fields (jobKey + engine context) a stream id resolves to, best-effort. */
+interface CorrelationFields {
+  jobKey?: string;
+  processInstanceKey?: string;
+  bpmnProcessId?: string;
+  elementId?: string;
+  planKey?: string;
+}
+
+/**
+ * Resolve a stream id to its correlation fields: the jobKey is always decoded from a `job:<jobKey>`
+ * stream id; the engine context (process instance / plan) is added only when the correlation registry
+ * still holds the (live) job. Non-job streams yield an empty object.
+ */
+export function correlationFieldsFor(stream: string, correlation: CorrelationRegistry | undefined): CorrelationFields {
+  const jobKey = jobKeyOfStream(stream);
+  if (jobKey === undefined) return {};
+  const fields: CorrelationFields = { jobKey };
+  const context = correlation?.resolve(jobKey);
+  if (context) {
+    if (context.processInstanceKey !== undefined) fields.processInstanceKey = context.processInstanceKey;
+    if (context.bpmnProcessId !== undefined) fields.bpmnProcessId = context.bpmnProcessId;
+    if (context.elementId !== undefined) fields.elementId = context.elementId;
+    if (context.planKey !== undefined) fields.planKey = context.planKey;
+  }
+  return fields;
+}
+
+/** Project a stored transcript's metadata (+ its retained chunks) onto the list wire shape. */
+export function toTranscript(
+  meta: TranscriptStream,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscript {
+  const chunks = store.read(meta.stream);
+  const out: AgenticTranscript = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: meta.nextOffset,
+    byteLength: byteLengthOf(chunks),
+    chunkCount: chunks.length,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  if (meta.firstOffset !== undefined) out.firstOffset = meta.firstOffset;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}
+
+/** The filters {@link listTranscripts} understands (all optional; an empty filter returns everything). */
+export interface TranscriptFilter {
+  readonly jobKey?: string;
+  readonly processInstanceKey?: string;
+  readonly planKey?: string;
+  /** ISO-8601 lower bound (inclusive) on the session's createdAt. */
+  readonly since?: string;
+  /** ISO-8601 upper bound (inclusive) on the session's createdAt. */
+  readonly until?: string;
+}
+
+/**
+ * List every captured session projected to the wire shape, sorted newest-first by createdAt (then by
+ * stream for a stable tie-break), after applying the (advisory) filters. jobKey / process-instance /
+ * plan filters match the correlation-enriched fields; since/until bound createdAt.
+ */
+export function listTranscripts(
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+  filter: TranscriptFilter = {},
+): AgenticTranscript[] {
+  const sinceMs = filter.since !== undefined ? Date.parse(filter.since) : undefined;
+  const untilMs = filter.until !== undefined ? Date.parse(filter.until) : undefined;
+  const rows = store
+    .list()
+    .map((meta) => toTranscript(meta, store, correlation))
+    .filter((t) => {
+      if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
+      if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) return false;
+      if (filter.planKey !== undefined && t.planKey !== filter.planKey) return false;
+      const createdMs = Date.parse(t.createdAt);
+      if (sinceMs !== undefined && Number.isFinite(createdMs) && createdMs < sinceMs) return false;
+      if (untilMs !== undefined && Number.isFinite(createdMs) && createdMs > untilMs) return false;
+      return true;
+    });
+  // Newest session first (a "past sessions" feed reads best most-recent-first); stable on stream id.
+  rows.sort((a, b) => {
+    const byTime = b.createdAt.localeCompare(a.createdAt);
+    return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+  });
+  return rows;
+}
+
+/**
+ * Fetch a stored transcript's bytes from offset `from` (inclusive), projected onto the range/offset
+ * wire shape — the SAME resume-from-offset contract the live terminal renders, so the cockpit replays
+ * a closed stream through its existing renderer. Returns undefined when the stream has no transcript.
+ */
+export function readTranscriptFrom(
+  stream: string,
+  from: number,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscriptData | undefined {
+  const meta = store.get(stream);
+  if (meta === undefined) return undefined;
+  const slice = store.since(stream, from);
+  const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
+  const out: AgenticTranscriptData = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: slice.nextOffset,
+    byteLength: byteLengthOf(slice.entries),
+    chunkCount: entries.length,
+    from,
+    gap: slice.gap,
+    entries,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}

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