@nanobpm/nano-workforce 0.50.0 → 0.52.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.52.0](https://github.com/nanobpm/nano-workforce/compare/v0.51.0...v0.52.0) (2026-08-13)
+
+
+### Features
+
+* presence + registry family over app.data (H1) ([#161](https://github.com/nanobpm/nano-workforce/issues/161)) ([6666ff1](https://github.com/nanobpm/nano-workforce/commit/6666ff148d02bc0f7ae9740511fdc62bbe9c2e70)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#144](https://github.com/nanobpm/nano-workforce/issues/144)
+
+# [0.51.0](https://github.com/nanobpm/nano-workforce/compare/v0.50.0...v0.51.0) (2026-08-13)
+
+
+### Features
+
+* mount agentic channel hub + family-registration seam (H0) ([#154](https://github.com/nanobpm/nano-workforce/issues/154)) ([96a679e](https://github.com/nanobpm/nano-workforce/commit/96a679e0843c76bf93940f09eef1c6c642a4ebed)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#143](https://github.com/nanobpm/nano-workforce/issues/143) [#isMounted](https://github.com/nanobpm/nano-workforce/issues/isMounted)
+
 # [0.50.0](https://github.com/nanobpm/nano-workforce/compare/v0.49.0...v0.50.0) (2026-08-12)
 
 

package/app/agentic/README.md

@@ -0,0 +1,57 @@
+# `app/agentic/` — the app-tier agentic channel (ADR 0056)
+
+This directory hosts the **agentic visibility plane** for nano-workforce (epic #142). H0 (#143)
+owns the keystone wiring; siblings H1/H3/H4 extend it **without touching the boot script**.
+
+## What H0 lands
+
+- **`channel.ts`** — `mountAgenticChannel(...)`. Stands up the `@nanobpm/agentic` WebSocket channel
+  + `AgenticHub` on the app's **own** HTTP server (`app.httpServer`, same port as the pages and
+  `/app/api/hooks/*` — no sidecar port), authenticates upgrades on `/agentic` (ADR 0028 identity
+  token + a required capability credential, mirroring the blackboard hook's `?token=…` pattern), and
+  mounts every discovered family. Returns a handle whose `teardown()` reverses everything.
+- **`registry.ts`** — the `AgenticFamilyRegistry` seam + the `AgenticFamily` / `AgenticContext`
+  contracts. Mounts families on boot, tears them down in **reverse** order on shutdown.
+- **`loader.ts`** — auto-discovers `*.family.ts` modules under `families/`. There is **no central
+  registration list** to append to, so siblings never collide on a shared file.
+- **`families/`** — the discovery directory. Drop a family module here; `families/example.family.ts`
+  is the copyable no-op template.
+
+`main.ts` calls `mountAgenticChannel(...)` once after `runFromEnv`, and its `teardown()` once inside
+the existing `drainAndExit`. **That is the only edit to `main.ts` / `drainAndExit` for the whole
+epic.**
+
+## How a sibling slice extends the channel (H1 / H3 / H4)
+
+1. Copy `families/example.family.ts` to `families/<slice>.family.ts` and implement `mount(ctx)`
+   (and optionally `teardown()`). `ctx` carries the reusable handles: `hub`, `registry`,
+   `transport`, `data` (the app SQLite `DataLayer`), and `log`.
+2. Own a message family via `ctx.hub.registerFamilyHandler("<family>", handler)` — the router
+   refuses a duplicate, so two slices can't both claim one family.
+3. **Do not** edit `main.ts`, `drainAndExit`, `channel.ts`, `registry.ts`, or `loader.ts`. You add
+   exactly one new file.
+
+## Reserved migration prefixes
+
+Forward-only, additive (expand-only). The highest committed prefix when the epic began is `022`, so
+H0 pre-allocates distinct prefixes to stop two siblings independently grabbing "the next" number:
+
+| Slice            | Reserved migration file                     |
+| ---------------- | ------------------------------------------- |
+| H1 presence #144 | `db/migrations/023_agentic_presence.sql`    |
+| H3 transcript #146 | `db/migrations/024_agentic_transcript.sql` |
+| H4 blackboard #147 | `db/migrations/025_agentic_blackboard.sql` (only if a schema change is needed) |
+
+H0 itself needs no migration.
+
+## Configuration
+
+- `NANO_AGENTIC_SECRET` (falls back to `NANO_PR_WEBHOOK_SECRET`) — the shared identity secret peers
+  present as `?token=…`. When neither is set, the channel is **not mounted** (logged), so the app
+  never exposes an unauthenticated upgrade.
+
+## Invariants (ADR 0056)
+
+- **App-tier only** — never the engine. The Camunda-8 job protocol (worker⇄engine) is untouched;
+  the agentic channel is the only new conversation.
+- **Advisory** — a family never hard-locks or gates a BPMN sequence flow.

package/app/agentic/channel.test.ts

@@ -0,0 +1,244 @@
+// Integration tests for the agentic channel mount (ADR 0056, H0 / #143).
+//
+// Exercises the acceptance surface against a locally-constructed `node:http` server: a valid WS
+// client upgrades on `/agentic`, an invalid one is rejected, normal HTTP routes keep working, the
+// hub is visible via `inspect()`, families mount/tear-down through the seam, and shutdown is clean.
+import { type AddressInfo, createServer, type Server } from "node:http";
+import { test } from "node:test";
+import { WebSocket } from "ws";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { type AgenticChannelHandle, mountAgenticChannel } from "./channel.ts";
+import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
+
+const SECRET = "test-agentic-secret";
+
+/** Start a bare HTTP server with one health route, on an ephemeral port. */
+async function startHttp(): Promise<{ server: Server; port: number }> {
+  const server = createServer((req, res) => {
+    if (req.url === "/health") {
+      res.writeHead(200, { "content-type": "text/plain" });
+      res.end("ok");
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = (server.address() as AddressInfo).port;
+  return { server, port };
+}
+
+/** Close an HTTP server and resolve only once it has stopped listening (server.close() is async). */
+function closeServer(server: Server): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/** Open a ws client and resolve on open. Rejects (with the close code) if it closes before opening. */
+function connect(port: number, query: string): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/agentic${query}`);
+  return new Promise<WebSocket>((resolve, reject) => {
+    let opened = false;
+    ws.on("open", () => {
+      opened = true;
+      resolve(ws);
+    });
+    ws.on("error", () => {
+      /* the close frame carries the reason; swallow the paired error event */
+    });
+    ws.on("close", (code, reason) => {
+      if (!opened) reject(new Error(`closed ${code}: ${reason.toString()}`));
+    });
+  });
+}
+
+/**
+ * The application close code an authenticator rejection delivers. The hub authenticates AFTER the
+ * WebSocket upgrade completes, so a rejected peer momentarily opens and is then closed with the app
+ * code (4401/4403) — this waits for that close and returns the code.
+ */
+/** How long rejectionCode waits for the close frame before failing (generous for slow CI). */
+const REJECTION_TIMEOUT_MS = 2000;
+
+function rejectionCode(port: number, query: string): Promise<number> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/agentic${query}`);
+  return new Promise<number>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error("connection neither closed nor timed out")),
+      REJECTION_TIMEOUT_MS,
+    );
+    timer.unref?.();
+    ws.on("error", () => {
+      /* swallow the paired error event; the close frame carries the code */
+    });
+    ws.on("close", (code) => {
+      clearTimeout(timer);
+      resolve(code);
+    });
+  });
+}
+
+async function mount(
+  _port: number,
+  server: Server,
+  families?: () => AgenticFamilyRegistry,
+): Promise<AgenticChannelHandle> {
+  return mountAgenticChannel({
+    server,
+    secret: SECRET,
+    data: undefined,
+    log: noopLog(),
+    families,
+  });
+}
+
+test("a valid identity token + capability credential upgrades on /agentic", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const ws = await connect(port, `?token=${SECRET}&capability=cap-1`);
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  // The hub tracked exactly this one connection.
+  assertEquals(channel.hub.connectionCount, 1);
+  ws.close();
+});
+
+test("an invalid identity token is rejected (4401)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "?token=wrong&capability=cap-1");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+test("a missing capability credential is rejected (4403)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, `?token=${SECRET}`);
+  assertEquals(closedCode, 4403);
+});
+
+test("normal HTTP routes keep working alongside the channel", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const res = await fetch(`http://127.0.0.1:${port}/health`);
+  assertEquals(res.status, 200);
+  assertEquals(await res.text(), "ok");
+});
+
+test("the hub is visible via inspect() and mounts registered families", async (t) => {
+  const { server, port } = await startHttp();
+  const trace: string[] = [];
+  const families = () => {
+    const reg = new AgenticFamilyRegistry();
+    reg.register({
+      name: "probe",
+      mount(ctx: AgenticContext) {
+        trace.push("mount");
+        // Prove the real hub handle is threaded through: registering a family handler must work.
+        ctx.hub.registerFamilyHandler("register", () => {});
+      },
+      teardown() {
+        trace.push("teardown");
+      },
+    });
+    return reg;
+  };
+  const channel = await mount(port, server, families);
+  t.after(() => closeServer(server));
+
+  const snap = channel.inspect();
+  assertEquals(snap.path, "/agentic");
+  assertEquals(snap.families, ["probe"]);
+  assertEquals(trace, ["mount"]);
+  assert(channel.hub.router.has("register"), "family handler should be registered");
+
+  await channel.teardown();
+  assertEquals(trace, ["mount", "teardown"]);
+});
+
+test("teardown closes live connections and is idempotent", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(() => closeServer(server));
+
+  const ws = await connect(port, `?token=${SECRET}&capability=cap-1`);
+  const closed = new Promise<void>((resolve) => ws.on("close", () => resolve()));
+  assertEquals(channel.hub.connectionCount, 1);
+
+  await channel.teardown();
+  await channel.teardown(); // second call is a no-op, must not throw
+  await closed;
+  assertEquals(ws.readyState, WebSocket.CLOSED);
+});
+
+test("a family mount failure tears down already-mounted families and closes the hub", async (t) => {
+  const { server, port } = await startHttp();
+  t.after(() => closeServer(server));
+  const trace: string[] = [];
+  const families = () => {
+    const reg = new AgenticFamilyRegistry();
+    reg.register({
+      name: "ok",
+      mount() {
+        trace.push("mount-ok");
+      },
+      teardown() {
+        trace.push("teardown-ok");
+      },
+    });
+    reg.register({
+      name: "boom",
+      mount() {
+        trace.push("mount-boom");
+        throw new Error("family boom failed to mount");
+      },
+    });
+    return reg;
+  };
+
+  let threw = false;
+  try {
+    await mount(port, server, families);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "mountAgenticChannel must reject when a family mount throws");
+  // The already-mounted family was torn down (reverse order) — no family left half-mounted, and the
+  // hub was closed on the same path (see mountAgenticChannel's failure handler).
+  assertEquals(trace, ["mount-ok", "mount-boom", "teardown-ok"]);
+});
+
+test("a missing secret is refused (never mount an open channel)", async (t) => {
+  const { server, port } = await startHttp();
+  t.after(() => closeServer(server));
+  let threw = false;
+  try {
+    await mountAgenticChannel({ server, secret: "", data: undefined, log: noopLog() });
+  } catch {
+    threw = true;
+  }
+  assert(threw, "mountAgenticChannel must reject an empty secret");
+  assertEquals(port > 0, true);
+});

package/app/agentic/channel.ts

@@ -0,0 +1,124 @@
+// nano-workforce — mount the app-tier agentic channel hub (ADR 0056, H0 / #143).
+//
+// This is the keystone of the agentic-visibility epic (#142): it stands up the WebSocket channel +
+// hub on the app's OWN HTTP server (same port as the pages and `/app/api/hooks/*` — no sidecar
+// port), authenticates each upgrade (ADR 0028 identity token + a capability credential, mirroring
+// the `?token=…` pattern the blackboard hook uses), and mounts every registered family module
+// through the {@link AgenticFamilyRegistry} seam.
+//
+// `main.ts` calls {@link mountAgenticChannel} once after `runFromEnv` and calls the returned
+// handle's `teardown()` inside its existing `drainAndExit`. That is the ONLY place `main.ts` /
+// `drainAndExit` are edited for the whole epic — siblings extend the channel purely by dropping a
+// family module under `app/agentic/families/`.
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
+import type { Server } from "node:http";
+import {
+  AgenticHub,
+  sharedSecretAuthenticator,
+  WebSocketChannelTransport,
+} from "@nanobpm/agentic/channel";
+import type { DataLayer, Logger } from "@nanobpm/urban";
+import { loadAgenticFamilies } from "./loader.ts";
+import { AgenticFamilyRegistry } from "./registry.ts";
+
+/** The path the agentic channel is served on, on the app's own port. */
+export const AGENTIC_PATH = "/agentic";
+
+export interface MountAgenticChannelOptions {
+  /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
+  readonly server: Server;
+  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. */
+  readonly secret: string;
+  /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
+  readonly data: DataLayer | undefined;
+  /** A structured logger for lifecycle lines. */
+  readonly log: Logger;
+  /**
+   * Discover + register family modules from `app/agentic/families/`. Default: the real discovery
+   * loader. Tests inject a fixed set to keep the mount hermetic.
+   */
+  readonly families?: () => Promise<AgenticFamilyRegistry> | AgenticFamilyRegistry;
+}
+
+/** The live channel, returned to `main.ts` so it can inspect it and tear it down on shutdown. */
+export interface AgenticChannelHandle {
+  readonly hub: AgenticHub;
+  readonly transport: WebSocketChannelTransport;
+  readonly registry: AgenticFamilyRegistry;
+  /** A structured snapshot for `inspect()`/logs. */
+  inspect(): Record<string, unknown>;
+  /** Tear the families (reverse order) then the hub + transport down. Idempotent. */
+  teardown(): Promise<void>;
+}
+
+/** Build a family registry from the on-disk discovery loader (the production default). */
+async function discoverRegistry(log: Logger): Promise<AgenticFamilyRegistry> {
+  const registry = new AgenticFamilyRegistry();
+  registry.registerAll(await loadAgenticFamilies(undefined, log));
+  return registry;
+}
+
+/**
+ * Mount the agentic hub on `server`, authenticate upgrades with `secret`, and mount all discovered
+ * family modules. Returns a handle whose `teardown()` reverses everything.
+ */
+export async function mountAgenticChannel(
+  opts: MountAgenticChannelOptions,
+): Promise<AgenticChannelHandle> {
+  const { server, secret, data, log } = opts;
+  if (!secret) throw new Error("mountAgenticChannel requires a non-empty identity secret");
+
+  const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
+  const hub = new AgenticHub({
+    transport,
+    // A valid identity token PLUS a required capability credential upgrades; either missing/invalid
+    // is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an Authenticator.
+    authenticator: sharedSecretAuthenticator({ secret, requireCredential: true }),
+    onError: (err, connectionId) =>
+      log.warn("agentic hub error", { connectionId, err: String(err) }),
+  });
+  // Share the app's port: the transport rode the existing server, so it is already listening.
+  await transport.ready();
+
+  // If discovery or any family mount throws, the transport + hub are already live: tear down whatever
+  // mounted (in reverse) and close the hub before rethrowing, so a failed boot never strands upgrade
+  // handlers or half-open connections.
+  let registry: AgenticFamilyRegistry | undefined;
+  try {
+    registry = await (opts.families ? opts.families() : discoverRegistry(log));
+    await registry.mountAll({ hub, registry: hub.registry, transport, data, log });
+  } catch (err) {
+    await registry?.teardownAll(log);
+    await hub.close();
+    throw err;
+  }
+
+  log.info("agentic channel mounted", {
+    path: AGENTIC_PATH,
+    families: registry.names(),
+  });
+
+  let tornDown = false;
+  return {
+    hub,
+    transport,
+    registry,
+    inspect() {
+      return {
+        path: AGENTIC_PATH,
+        families: registry.names(),
+        connections: hub.connectionCount,
+        address: hub.address,
+      };
+    },
+    async teardown() {
+      if (tornDown) return;
+      tornDown = true;
+      await registry.teardownAll(log);
+      await hub.close();
+      log.info("agentic channel torn down");
+    },
+  };
+}

package/app/agentic/families/example.family.ts

@@ -0,0 +1,35 @@
+// nano-workforce — a no-op EXAMPLE agentic family module (ADR 0056, H0 / #143).
+//
+// This is the concrete, copyable pattern H1 (#144), H3 (#146) and H4 (#147) follow. It lives in the
+// discovery directory (`app/agentic/families/`), so the loader ({@link ../loader.ts}) finds it by
+// the `*.family.ts` suffix and the H0 seam mounts + tears it down — a genuine registered sample. It
+// is a deliberate no-op (no message handler, no state), so mounting it in production is harmless.
+//
+// To add a real family slice, copy this file to `app/agentic/families/<slice>.family.ts`, rename it,
+// and implement `mount` (and optionally `teardown`). That is the WHOLE integration: you add ONE NEW
+// FILE and register NOTHING by hand — you never touch `main.ts` or `drainAndExit`.
+//
+// Reserved forward-only migration prefixes (do NOT compute "the next" number — use your reserved one):
+//   - H1 presence   → `db/migrations/023_agentic_presence.sql`
+//   - H3 transcript → `db/migrations/024_agentic_transcript.sql`
+//   - H4 blackboard → `db/migrations/025_agentic_blackboard.sql` (only if a schema change is needed)
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/**
+ * A minimal, no-op family. A real slice would, inside `mount`:
+ *   - `ctx.hub.registerFamilyHandler("<family>", (frame, conn) => { … })` to own a message family,
+ *   - persist via `ctx.data` (the app's SQLite DataLayer — the same store the blackboard uses),
+ *   - attach presence via `ctx.registry.setPresence(conn.id, …)`,
+ * and release those in `teardown`.
+ */
+export const family: AgenticFamily = {
+  name: "example",
+  mount(_ctx: AgenticContext): void {
+    // No-op template. Replace with the slice's real wiring against `_ctx`.
+  },
+  teardown(): void {
+    // No-op template. Release anything `mount` acquired here.
+  },
+};
+
+export default family;