@nanobpm/nano-workforce 0.54.0 → 0.56.0

package/openapi.yaml

@@ -99,6 +99,111 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    AgenticSupplyWorker:
+      type: object
+      description: One connected worker in the supply mirror (H5 cockpit; sourced from the H1 presence registry).
+      required:
+        - instance
+        - identity
+        - stream
+        - jobKeys
+        - live
+        - staleMs
+      properties:
+        instance:
+          type: string
+          description: The worker instance id.
+        identity:
+          type: string
+          description: The ADR 0028 leaf token the worker registered under.
+        stream:
+          type: string
+          description: The relay stream id to subscribe when drilling into this worker's terminal.
+        family:
+          type: string
+          description: Declared family (enrolment attribute), if any.
+        host:
+          type: string
+          description: Declared host (where the worker runs), if any.
+        jobKeys:
+          type: array
+          description: The jobKeys this worker is currently processing (populated by the H6 correlation registry).
+          items:
+            type: string
+        live:
+          type: boolean
+          description: Whether the worker's channel connection is still open.
+        staleMs:
+          type: integer
+          description: Milliseconds since the last liveness refresh (0 when fresh).
+    AgenticSupplyLeaf:
+      type: object
+      description: The supply for one leaf token — the workers registered under it.
+      required:
+        - token
+        - workers
+      properties:
+        token:
+          type: string
+        workers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyWorker"
+    AgenticJobCorrelation:
+      type: object
+      description: One current job's engine context (H6) — lines a worker's terminal up with its process
+        instance / plan. The relay stream a job's terminal is on is the jobKey-scoped stream `job:<jobKey>`.
+      required:
+        - jobKey
+        - stream
+      properties:
+        jobKey:
+          type: string
+          description: The Camunda-8 job key the worker activated.
+        stream:
+          type: string
+          description: The relay stream id the job's terminal is relayed on (`job:<jobKey>`).
+        processInstanceKey:
+          type: string
+          description: The owning process instance key, if known.
+        bpmnProcessId:
+          type: string
+          description: The BPMN process id the job belongs to, if known.
+        elementId:
+          type: string
+          description: The BPMN element id (activity/task) the job is for, if known.
+        planKey:
+          type: string
+          description: The plan / epic key this job is part of (e.g. owner/repo#142), if known.
+    AgenticSupplyReport:
+      type: object
+      description: The SUPPLY-ONLY visibility report — the live worker list grouped by leaf. No demand-side
+        fields (the demand×supply matrix / diversity SLO are deferred to enrolment epic #152).
+      required:
+        - count
+        - workers
+        - leaves
+      properties:
+        count:
+          type: integer
+          description: The number of connected workers.
+        generatedAt:
+          type: string
+          description: When this snapshot was taken, ISO-8601.
+        workers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyWorker"
+        leaves:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyLeaf"
+        correlations:
+          type: array
+          description: The engine context (process instance / plan) for every jobKey currently being
+            processed, so the cockpit can line each worker's terminal up with its process instance / plan (H6).
+          items:
+            $ref: "#/components/schemas/AgenticJobCorrelation"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -509,6 +614,27 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agentic/supply:
+    get:
+      operationId: getAgenticSupply
+      summary: The SUPPLY-ONLY agentic visibility report — the live worker list (family, host, current jobs,
+        liveness) grouped by leaf, sourced from the H1 presence registry. Feeds the H5 cockpit page.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The supply report.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticSupplyReport"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /version:
     get:
       operationId: getVersion

package/operations/getAgenticSupply.test.ts

@@ -0,0 +1,193 @@
+// Tests for GET /app/api/agentic/supply → operation `getAgenticSupply` (H5 / #148).
+//
+// Covers: the empty report when no presence family is mounted; the shared-secret guard; and the
+// end-to-end mapping of a mounted presence registry's snapshot into the supply report (stream keyed
+// by instance, family/host/jobKeys/liveness) — driven through a REAL AgenticHub + in-memory transport
+// exactly as the presence family is exercised, so the singleton the operation reads is the live one.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { AgenticHub } from "@nanobpm/agentic/channel";
+import type { Authenticator, ChannelConnection, ChannelTransport } from "@nanobpm/agentic/channel";
+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 { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
+import { family } from "../app/agentic/families/presence.family.ts";
+import type { AgenticContext } from "../app/agentic/registry.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./getAgenticSupply.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 memTransport(): { transport: ChannelTransport; connect(conn: ChannelConnection): void } {
+  let onConnection: ((conn: ChannelConnection) => void) | undefined;
+  const transport: ChannelTransport = {
+    onConnection: (l) => {
+      onConnection = l;
+    },
+    address: { port: 0 },
+    close: async () => {},
+  };
+  return { transport, connect: (conn) => onConnection?.(conn) };
+}
+
+function fakeConn(id: string, identity: string): { conn: ChannelConnection; feed(frame: Frame): void } {
+  let onMessage: ((bytes: Uint8Array) => void) | undefined;
+  const conn: ChannelConnection = {
+    id,
+    handshake: { query: { identity }, token: "t", credential: "c" },
+    send: () => {},
+    close: () => {},
+    onMessage: (l) => {
+      onMessage = l;
+    },
+    onClose: () => {},
+  };
+  return { conn, feed: (frame) => onMessage?.(encodeFrame(frame)) };
+}
+
+const authenticator: Authenticator = (req) => ({ ok: true, grant: { identity: req.query?.identity ?? "anon" } });
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+async function mountPresence(db: SqliteDb): Promise<AgenticHub> {
+  const transport = memTransport();
+  const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    transport: transport.transport as never,
+    data: memData(db),
+    log: noopLog(),
+  };
+  await family.mount(ctx);
+  // Register one live worker under leaf "leafA" with declared family + host.
+  const peer = fakeConn("c1", "leafA");
+  transport.connect(peer.conn);
+  await flush();
+  peer.feed({ lane: "control", family: "register", seq: 1, payload: { instance: "wk-a", capability: { family: "opus", host: "boxA" } } });
+  await flush();
+  return hub;
+}
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/agentic/supply",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as never,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+test("returns an empty supply report when no presence family is mounted", async () => {
+  family.teardown?.();
+  const res = (await handler(input(), app)) as { status: number; body: { count: number; workers: unknown[]; leaves: unknown[] } };
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.workers.length, 0);
+  assertEquals(res.body.leaves.length, 0);
+});
+
+test("maps the presence snapshot into the supply report (stream, family, host, liveness)", async () => {
+  const hub = await mountPresence(memSqlite());
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { count: number; workers: Array<Record<string, unknown>>; leaves: Array<{ token: string; workers: unknown[] }> };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 1);
+    const w = res.body.workers[0];
+    assertEquals(w.instance, "wk-a");
+    assertEquals(w.identity, "leafA");
+    assertEquals(w.stream, "wk-a", "the drill stream is keyed by the worker instance");
+    assertEquals(w.family, "opus");
+    assertEquals(w.host, "boxA");
+    assertEquals(w.live, true);
+    assertEquals(w.jobKeys, []);
+    assertEquals(res.body.leaves[0]?.token, "leafA");
+    assertEquals(res.body.leaves[0]?.workers.length, 1);
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+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(`./getAgenticSupply.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; body: Record<string, unknown> };
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});
+
+test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+  const hub = await mountPresence(memSqlite());
+  correlationFamily.mount({
+    hub,
+    registry: hub.registry,
+    transport: undefined as never,
+    data: undefined,
+    log: noopLog(),
+  });
+  const correlation = currentCorrelation();
+  assert(correlation !== undefined, "the correlation family installs the singleton");
+  correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", 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 w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(res.body.correlations.length, 1);
+    const c = res.body.correlations[0];
+    assertEquals(c.jobKey, "6494");
+    assertEquals(c.stream, "job:6494");
+    assertEquals(c.processInstanceKey, "4612");
+    assertEquals(c.bpmnProcessId, "plan-fanout");
+    assertEquals(c.planKey, "o/r#142");
+  } finally {
+    correlationFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});

package/operations/getAgenticSupply.ts

@@ -0,0 +1,82 @@
+// GET /app/api/agentic/supply → operationId `getAgenticSupply` (ADR 0058/0059 OpenAPI surface, mounted
+// under base /app/api). The SUPPLY-ONLY visibility report the H5 cockpit page (#148) polls: the live
+// worker list — family, host, current jobs, liveness — grouped by leaf token, sourced from the H1
+// presence registry (#144). Read-only projection; it NEVER gates control flow (advisory-only, ADR 0056).
+//
+// H6 (#149) closes the loop: the correlation registry (`app/agentic/correlation.ts`) supplies the
+// `jobKeysFor` resolver the presence snapshot exposes as a seam, so each worker's current jobKeys light
+// up; each worker's drill `stream` is repointed at its jobKey-scoped relay stream (`job:<jobKey>`); and
+// the report carries the `correlations` — the process-instance / plan context for every current job —
+// so the cockpit lines a worker's terminal up with "that process instance / this plan".
+//
+// This is the supply half of the visibility plane only. The demand×supply matrix, missing-agent-type
+// reds, and diversity-SLO lights are DE-SCOPED to the enrolment epic #152 — this report carries no
+// demand-side fields, and the cockpit renders none.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
+// NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
+
+import { type CorrelationRegistry, currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
+import { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
+import { envVar } from "../app/version.ts";
+import type { AgenticJobCorrelation, AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+// The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
+// the x-hook-secret header. Captured once, at module load.
+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 jobKey-scoped relay stream (`job:<jobKey>`) when the
+// correlation registry knows a current job for it (H6) — so drilling in opens the LIVE job's terminal.
+function toWorker(w: SupplyWorker, correlation: CorrelationRegistry | undefined): AgenticSupplyWorker {
+  const out: AgenticSupplyWorker = {
+    instance: w.instance,
+    identity: w.identity,
+    stream: correlation?.primaryStreamFor(w.instance) ?? w.instance,
+    jobKeys: [...w.jobKeys],
+    live: w.live,
+    staleMs: w.staleMs,
+  };
+  if (w.family !== undefined) out.family = w.family;
+  if (w.host !== undefined) out.host = w.host;
+  return out;
+}
+
+// Project a correlation-registry entry to the wire correlation. Optional fields are only set when
+// known (biome bans `undefined`-valued keys crossing the boundary).
+function toCorrelation(c: JobCorrelation): AgenticJobCorrelation {
+  const out: AgenticJobCorrelation = { jobKey: c.jobKey, stream: c.stream };
+  if (c.processInstanceKey !== undefined) out.processInstanceKey = c.processInstanceKey;
+  if (c.bpmnProcessId !== undefined) out.bpmnProcessId = c.bpmnProcessId;
+  if (c.elementId !== undefined) out.elementId = c.elementId;
+  if (c.planKey !== undefined) out.planKey = c.planKey;
+  return out;
+}
+
+export default defineOperation("getAgenticSupply", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgenticSupply rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  const registry = currentPresenceRegistry();
+  if (!registry) {
+    // The presence family has not mounted (or has torn down) — no supply to report, not an error.
+    const empty: AgenticSupplyReport = { count: 0, generatedAt: new Date().toISOString(), workers: [], leaves: [], correlations: [] };
+    return { status: 200, body: empty };
+  }
+
+  // Thread the H6 correlation registry (if mounted) as the presence snapshot's jobKeysFor resolver so a
+  // worker's current jobKeys populate; absent → jobKeys stay empty (advisory, never an error).
+  const correlation = currentCorrelation();
+  const snapshot = registry.snapshot(correlation ? { jobKeysFor: (instance) => correlation.jobKeysFor(instance) } : {});
+  const report: AgenticSupplyReport = {
+    count: snapshot.count,
+    generatedAt: new Date().toISOString(),
+    workers: snapshot.workers.map((w) => toWorker(w, correlation)),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, correlation)) })),
+    correlations: correlation ? correlation.snapshot().correlations.map(toCorrelation) : [],
+  };
+  return { status: 200, body: report };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.54.0",
+  "version": "0.56.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

@@ -0,0 +1,162 @@
+/* The SUPPLY cockpit stylesheet (H5 / #148) — a compact, phone-friendly dark cockpit shared by the
+   standalone shell and the console App-View embed, so the two render identically. The three-state
+   liveness dot keys off `data-liveness` (live | stale | down). It styles the SUPPLY worker list only
+   — no demand×supply matrix / diversity-SLO light (deferred to enrolment epic #152). */
+
+:root {
+  --cockpit-bg: #0b0f14;
+  --cockpit-panel: #131a22;
+  --cockpit-edge: #223041;
+  --cockpit-text: #e6edf3;
+  --cockpit-muted: #8b98a5;
+  --cockpit-green: #2ea043;
+  --cockpit-amber: #d29922;
+  --cockpit-red: #f85149;
+}
+
+.cockpit-shell {
+  color: var(--cockpit-text);
+  background: var(--cockpit-bg);
+  font: 14px/1.4 ui-sans-serif, system-ui, sans-serif;
+  display: grid;
+  gap: 12px;
+  padding: 12px;
+  min-height: 100%;
+}
+
+.cockpit-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+}
+
+.cockpit-title {
+  font-size: 16px;
+  margin: 0;
+}
+
+.cockpit-supply-summary {
+  color: var(--cockpit-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-supply-region,
+.cockpit-terminal {
+  background: var(--cockpit-panel);
+  border: 1px solid var(--cockpit-edge);
+  border-radius: 8px;
+  padding: 12px;
+}
+
+.cockpit-panel-title {
+  font-size: 13px;
+  margin: 0 0 8px;
+  color: var(--cockpit-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-leaf {
+  margin-bottom: 12px;
+}
+
+.cockpit-leaf-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: 6px;
+}
+
+.cockpit-leaf-name {
+  font-weight: 600;
+}
+
+.cockpit-leaf-count {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-supply-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-th {
+  text-align: left;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--cockpit-muted);
+  padding: 4px 8px;
+  border-bottom: 1px solid var(--cockpit-edge);
+}
+
+.cockpit-td {
+  padding: 6px 8px;
+  border-bottom: 1px solid rgba(34, 48, 65, 0.5);
+}
+
+.cockpit-supply-name {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.cockpit-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  display: inline-block;
+  flex: 0 0 auto;
+  background: var(--cockpit-muted);
+}
+
+.cockpit-dot[data-liveness="live"] { background: var(--cockpit-green); }
+.cockpit-dot[data-liveness="stale"] { background: var(--cockpit-amber); }
+.cockpit-dot[data-liveness="down"] { background: var(--cockpit-red); }
+
+.cockpit-worker {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-worker:hover { color: #58a6ff; }
+
+.cockpit-supply-process { color: var(--cockpit-muted); }
+
+.cockpit-correlation {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  display: block;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-correlation:hover { color: #58a6ff; }
+
+.cockpit-supply-liveness { color: var(--cockpit-muted); }
+
+.cockpit-supply-empty {
+  color: var(--cockpit-muted);
+  padding: 8px 0;
+}
+
+.cockpit-terminal-host {
+  min-height: 220px;
+  background: #05080b;
+  border-radius: 6px;
+}

package/pages/cockpit/embed.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Agent cockpit — supply (App View embed)</title>
+    <link rel="stylesheet" href="./cockpit.css" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@5/css/xterm.min.css" />
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0f14; }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "@nanobpm/agentic/cockpit": "https://cdn.jsdelivr.net/npm/@nanobpm/agentic@0.1.0/dist/cockpit/index.js",
+          "@xterm/xterm": "https://cdn.jsdelivr.net/npm/@xterm/xterm@5/+esm"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <!--
+      Console App-View embed (ADR 0057). The console loads this document into its App-View surface and
+      hands it a host element; we mount the SAME supply cockpit via the SAME ./mount.js as the
+      standalone shell — only the host and the injected endpoints differ, so the page renders
+      identically. When the console injects endpoint config via `window.__NANO_APP_VIEW__`, it wins.
+    -->
+    <main id="cockpit-root"></main>
+    <script type="module">
+      import { mountCockpit } from "./mount.js";
+
+      const cfg = window.__NANO_APP_VIEW__ ?? {};
+      mountCockpit(cfg.host ?? document.getElementById("cockpit-root"), {
+        reportUrl: cfg.reportUrl,
+        relayUrl: cfg.relayUrl,
+        hookSecret: cfg.hookSecret,
+        relayToken: cfg.relayToken,
+        relayCapability: cfg.relayCapability,
+      });
+    </script>
+  </body>
+</html>