@nanobpm/nano-workforce 0.53.0 → 0.55.0

package/openapi.yaml

@@ -99,6 +99,79 @@ 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 (empty until the H6 correlation seam lands).
+          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"
+    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"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -509,6 +582,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/blackboard.test.ts

@@ -3,35 +3,18 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memBlackboardData } from "../test/blackboardDb.ts";
 import { noopLog } from "../test/log.ts";
 import readBlackboard from "./readBlackboard.ts";
 import appendBlackboard from "./appendBlackboard.ts";
 
-function memApp(): { app: AppApi; stores: Record<string, any[]> } {
-  const stores: Record<string, any[]> = {};
-  const seq: Record<string, number> = {};
-  function tbl(name: string, pk = "id") {
-    const rows = (stores[name] ??= [] as any[]);
-    return {
-      async insert(row: any) {
-        if (pk === "id") {
-          const id = (seq[name] = (seq[name] ?? 0) + 1);
-          rows.push({ id, ...row });
-          return id;
-        }
-        rows.push({ ...row });
-        return row[pk];
-      },
-      async find(where: any = {}) {
-        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-      async findOne(where: any = {}) {
-        return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-    };
-  }
-  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: noopLog() } as any as AppApi;
-  return { app, stores };
+// The operations bind to `app.data`; back it with a real in-memory SQLite DataLayer (the same
+// harness `app/blackboard.test.ts` uses) so the hook path exercises the shared `BlackboardStore` /
+// `agentic_blackboard` table end-to-end. `db` is exposed for row-count assertions.
+function memApp(): { app: AppApi; db: { all<T>(sql: string, params?: unknown[]): T[] } } {
+  const { data, db } = memBlackboardData();
+  const app = { data, log: noopLog() } as unknown as AppApi;
+  return { app, db };
 }
 
 function req(method: string, query: Record<string, string>) {
@@ -106,14 +89,15 @@ test("POST with a blank body → 400", async () => {
 });
 
 test("POST is idempotent on dedupe_key (retry → 200, not a duplicate)", async () => {
-  const { app, stores } = memApp();
+  const { app, db } = memApp();
   await seedPlan(app, "o/r#1", "tok");
   const body = { author_task: "t", body: "claim", dedupe_key: "t:claim:1" };
   assertEquals((await call(app, "POST", { token: "tok" }, body)).status, 201);
   const retry = await call(app, "POST", { token: "tok" }, body);
   assertEquals(retry.status, 200);
   assertEquals(retry.body.inserted, false);
-  assertEquals(stores["plan_blackboard"].length, 1);
+  const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard WHERE scope = ?", ["o/r#1"]);
+  assertEquals(n, 1);
 });
 
 test("GET ?since returns only newer entries", async () => {

package/operations/getAgenticSupply.test.ts

@@ -0,0 +1,153 @@
+// 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 { 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;
+  }
+});

package/operations/getAgenticSupply.ts

@@ -0,0 +1,59 @@
+// 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).
+//
+// 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 { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
+import { envVar } from "../app/version.ts";
+import type { 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") ?? "";
+
+// The relay stream id to subscribe when drilling into a worker's terminal. Presence keys the relay by
+// worker instance; the H6 correlation slice (#149) may repoint this at a jobKey-scoped stream.
+function toWorker(w: SupplyWorker): AgenticSupplyWorker {
+  const out: AgenticSupplyWorker = {
+    instance: w.instance,
+    identity: w.identity,
+    stream: 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;
+}
+
+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: [] };
+    return { status: 200, body: empty };
+  }
+
+  const snapshot = registry.snapshot();
+  const report: AgenticSupplyReport = {
+    count: snapshot.count,
+    generatedAt: new Date().toISOString(),
+    workers: snapshot.workers.map(toWorker),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map(toWorker) })),
+  };
+  return { status: 200, body: report };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.53.0",
+  "version": "0.55.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,145 @@
+/* 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-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>