@nanobpm/nano-workforce 0.69.0 → 0.70.0

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

package/operations/listAgenticTranscripts.test.ts

@@ -0,0 +1,169 @@
+// Tests for GET /app/api/agentic/transcripts → operation `listAgenticTranscripts` (H3 read path, #222).
+//
+// Covers: the empty list when no relay/transcript family is mounted; the shared-secret guard; the
+// end-to-end projection of a mounted TranscriptStore's rows into the list (byteLength, chunkCount,
+// lifecycle/status, jobKey decoded from the stream id); correlation enrichment (process instance /
+// plan) when the H6 correlation family is mounted; and the jobKey / plan / time filters.
+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 { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
+import { createRelayFamily, currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import type { AgenticContext } from "../app/agentic/registry.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./listAgenticTranscripts.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;
+}
+
+/** A hub double that just captures the relay family handler (unused here — we seed the store directly). */
+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(query: Record<string, unknown> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: { method: "GET", path: "/app/api/agentic/transcripts", query: new URLSearchParams(), headers: new Headers(headers), text: async () => "" } as never,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+const app = { log: noopLog() } as unknown as AppApi;
+const relayFamily = createRelayFamily();
+
+test("returns an empty list when no relay/transcript family is mounted", async () => {
+  relayFamily.teardown?.();
+  const res = (await handler(input(), app)) as { status: number; body: { count: number; transcripts: unknown[] } };
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.transcripts.length, 0);
+});
+
+test("projects the TranscriptStore rows into the list (byteLength, chunkCount, lifecycle, jobKey)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined, "the relay family installs a persisted store");
+  // Seed one completed ephemeral session on a jobKey-scoped stream.
+  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "hello " }, { offset: 1, chunk: "world" }] }), nextOffset: 2 }, "ephemeral");
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { count: number; retentionMs?: number; transcripts: Array<Record<string, unknown>> };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 1);
+    assert(typeof res.body.retentionMs === "number", "the list surfaces the retention window");
+    const t = res.body.transcripts[0];
+    assertEquals(t.stream, "job:6494");
+    assertEquals(t.jobKey, "6494", "the jobKey is decoded from the job: stream id");
+    assertEquals(t.lifecycle, "ephemeral");
+    assertEquals(t.status, "completed");
+    assertEquals(t.chunkCount, 2);
+    assertEquals(t.byteLength, "hello world".length);
+    assertEquals(t.nextOffset, 2);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("enriches with the H6 correlation (process instance / plan) when it is still live", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
+  correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
+  currentCorrelation()?.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", planKey: "o/r#142" });
+  try {
+    const res = (await handler(input(), app)) as { body: { transcripts: Array<Record<string, unknown>> } };
+    const t = res.body.transcripts[0];
+    assertEquals(t.processInstanceKey, "4612");
+    assertEquals(t.bpmnProcessId, "plan-fanout");
+    assertEquals(t.planKey, "o/r#142");
+  } finally {
+    correlationFamily.teardown?.();
+    relayFamily.teardown?.();
+  }
+});
+
+test("filters by jobKey and plan", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush("job:1", { since: () => ({ entries: [{ offset: 0, chunk: "a" }] }), nextOffset: 1 }, "ephemeral");
+  store.flush("job:2", { since: () => ({ entries: [{ offset: 0, chunk: "b" }] }), nextOffset: 1 }, "ephemeral");
+  correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
+  currentCorrelation()?.link("wk", "2", { planKey: "o/r#9" });
+  try {
+    const byJob = (await handler(input({ jobKey: "1" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
+    assertEquals(byJob.body.count, 1);
+    assertEquals(byJob.body.transcripts[0]?.stream, "job:1");
+
+    const byPlan = (await handler(input({ planKey: "o/r#9" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
+    assertEquals(byPlan.body.count, 1);
+    assertEquals(byPlan.body.transcripts[0]?.stream, "job:2");
+  } finally {
+    correlationFamily.teardown?.();
+    relayFamily.teardown?.();
+  }
+});
+
+test("rejects a malformed since/until with a 400", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input({ since: "not-a-date" }), 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(`./listAgenticTranscripts.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as { status: number };
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as { status: number };
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/listAgenticTranscripts.ts

@@ -0,0 +1,61 @@
+// GET /app/api/agentic/transcripts → operationId `listAgenticTranscripts` (ADR 0056, H3 read path #222).
+//
+// The READ counterpart to the write-only transcript store (H3 #146): it lists the durable transcripts an
+// ephemeral agent flushed on job completion, so an operator can review "what did that agent do" AFTER it
+// is gone. Sourced from the mounted relay/transcript service's TranscriptStore (over `app.data`) and
+// correlated via `app/agentic/correlation.ts` (best-effort — jobKey is always recovered from the stream
+// id, engine context only while the job is still live). Feeds the cockpit "past sessions" view.
+//
+// Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Optional filters (jobKey / process
+// instance / plan / time) narrow the feed. The optional shared-secret guard mirrors getAgenticSupply:
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header; unset -> open.
+
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import { listTranscripts, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
+import { envVar } from "../app/version.ts";
+import type { AgenticTranscriptList } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+/** Reject an ISO-8601 filter that does not parse (a malformed since/until is a 400, not a silent no-op). */
+function badInstant(value: string | undefined): boolean {
+  return value !== undefined && !Number.isFinite(Date.parse(value));
+}
+
+export default defineOperation("listAgenticTranscripts", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listAgenticTranscripts rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  if (badInstant(query.since) || badInstant(query.until)) {
+    return { status: 400, body: { error: "invalid since/until: expected an ISO-8601 instant" } };
+  }
+
+  const service = currentRelayTranscriptService();
+  const store = service?.store;
+  if (!store) {
+    // The relay family has not mounted, or is running unpersisted (no DataLayer) - no transcripts to
+    // report, not an error (advisory).
+    const empty: AgenticTranscriptList = { count: 0, generatedAt: new Date().toISOString(), transcripts: [] };
+    return { status: 200, body: empty };
+  }
+
+  const filter: TranscriptFilter = {
+    ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
+    ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
+    ...(query.since !== undefined ? { since: query.since } : {}),
+    ...(query.until !== undefined ? { until: query.until } : {}),
+  };
+  const transcripts = listTranscripts(store, currentCorrelation(), filter);
+  const body: AgenticTranscriptList = {
+    count: transcripts.length,
+    generatedAt: new Date().toISOString(),
+    retentionMs: store.ephemeralRetentionMs,
+    transcripts,
+  };
+  return { status: 200, body };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/cockpit/cockpit.css

@@ -42,6 +42,7 @@
 }
 
 .cockpit-supply-region,
+.cockpit-past-region,
 .cockpit-terminal {
   background: var(--cockpit-panel);
   border: 1px solid var(--cockpit-edge);
@@ -160,3 +161,72 @@
   background: #05080b;
   border-radius: 6px;
 }
+
+/* ── Past sessions (H3 read path / #222): the captured-session history + replay. ──────────────── */
+
+.cockpit-past-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.cockpit-past-title {
+  font-size: 13px;
+  margin: 0;
+  color: var(--cockpit-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-past-summary {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-replay {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-past-replay:hover { color: #58a6ff; }
+
+.cockpit-past-session[data-active="true"] {
+  background: rgba(88, 166, 255, 0.12);
+}
+
+.cockpit-past-status { color: var(--cockpit-muted); }
+.cockpit-past-size { color: var(--cockpit-muted); }
+.cockpit-past-captured { color: var(--cockpit-muted); font-size: 12px; }
+
+.cockpit-past-empty {
+  color: var(--cockpit-muted);
+  padding: 8px 0;
+}
+
+/* Distinguish a live terminal from a replayed (static) past session at a glance. */
+.cockpit-terminal[data-terminal-mode="replay"] {
+  border-color: #8957e5;
+}
+.cockpit-terminal[data-terminal-mode="replay"] .cockpit-panel-title {
+  color: #b392f0;
+}
+.cockpit-terminal[data-terminal-mode="live"] .cockpit-panel-title {
+  color: var(--cockpit-green);
+}