@nanobpm/nano-workforce 0.53.0 → 0.55.0

package/pages/cockpit/mount.js

@@ -0,0 +1,331 @@
+// Browser adapter for the SUPPLY-only agentic cockpit (H5 / #148).
+//
+// This is the ONE wiring both the standalone shell and the console App-View embed call — they differ
+// only in the host element they pass, so the supply cockpit renders identically embedded and
+// standalone. It supplies the browser capabilities the injection-based core needs: the real
+// `document`, a `fetch`-based supply report source, a `WebSocket` relay socket factory, and an
+// xterm.js terminal sink.
+//
+// The genuinely reusable, correctness-critical parts — the relay client and the resume-from-offset
+// terminal session — are REUSED from `@nanobpm/agentic/cockpit` (resolved via the host page's import
+// map). Only the SUPPLY projection + render + poll orchestration the package does NOT provide is
+// re-expressed here in plain browser ESM (the app has no build step, so the typed core under
+// `app/agentic/cockpit/` cannot be imported directly by the browser). It is kept faithful to that
+// tested TypeScript core: same DOM shape (`data-worker`, `data-liveness`, `data-stream`, …), same
+// liveness grading, same self-scheduling poll + persistent-terminal discipline.
+//
+// It renders the SUPPLY worker list ONLY — NOT the packaged demand×supply matrix / missing-agent reds
+// / diversity-SLO light (deferred to enrolment epic #152).
+import { RelayChannelClient, TerminalSession } from "@nanobpm/agentic/cockpit";
+import { Terminal } from "@xterm/xterm";
+
+const DEFAULT_REFRESH_MS = 2000;
+const DEFAULT_STALE_AFTER_MS = 15_000;
+
+function isPosInt(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+// ── supply projection (mirrors app/agentic/cockpit/supply-view.ts) ─────────────────────────────
+
+function liveness(worker, staleAfterMs) {
+  if (!worker.live) return "down";
+  return worker.staleMs >= staleAfterMs ? "stale" : "live";
+}
+
+function workerView(worker, staleAfterMs) {
+  const jobKeys = [...(worker.jobKeys ?? [])].sort((a, b) => a.localeCompare(b));
+  return {
+    instance: worker.instance,
+    identity: worker.identity,
+    stream: worker.stream,
+    family: worker.family ?? "\u2014",
+    host: worker.host ?? "\u2014",
+    jobKeys,
+    jobs: jobKeys.length,
+    liveness: liveness(worker, staleAfterMs),
+    staleMs: worker.staleMs,
+  };
+}
+
+function supplyView(report, staleAfterMs) {
+  const byInstance = (a, b) => a.instance.localeCompare(b.instance);
+  const leaves = (report.leaves ?? [])
+    .map((leaf) => {
+      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+      return {
+        token: leaf.token,
+        workers,
+        liveCount: workers.filter((w) => w.liveness === "live").length,
+        total: workers.length,
+      };
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+  const workers = (report.workers ?? []).map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+  return { leaves, workers, count: workers.length, live: workers.filter((w) => w.liveness === "live").length };
+}
+
+// ── supply render (mirrors app/agentic/cockpit/supply-render.ts) ───────────────────────────────
+
+function el(doc, tag, className, text) {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function dot(doc, live) {
+  const node = el(doc, "span", "cockpit-dot");
+  node.setAttribute("data-liveness", live);
+  return node;
+}
+
+function workerRow(doc, worker, onDrill) {
+  const row = el(doc, "tr", "cockpit-supply-worker");
+  row.setAttribute("data-worker", worker.instance);
+  row.setAttribute("data-liveness", worker.liveness);
+  row.setAttribute("data-stream", worker.stream);
+
+  const nameCell = el(doc, "td", "cockpit-td cockpit-supply-name");
+  nameCell.appendChild(dot(doc, worker.liveness));
+  const button = el(doc, "button", "cockpit-worker", worker.instance);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-stream", worker.stream);
+  if (onDrill) button.addEventListener("click", () => onDrill(worker.stream));
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-family", worker.family));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-host", worker.host));
+  const jobsCell = el(doc, "td", "cockpit-td cockpit-supply-jobs", worker.jobs === 0 ? "\u2014" : worker.jobKeys.join(", "));
+  jobsCell.setAttribute("data-jobs", String(worker.jobs));
+  row.appendChild(jobsCell);
+  const livenessCell = el(doc, "td", "cockpit-td cockpit-supply-liveness", worker.liveness);
+  livenessCell.setAttribute("data-liveness", worker.liveness);
+  row.appendChild(livenessCell);
+  return row;
+}
+
+function leafSection(doc, leaf, onDrill) {
+  const section = el(doc, "section", "cockpit-leaf");
+  section.setAttribute("data-leaf", leaf.token);
+  const header = el(doc, "div", "cockpit-leaf-head");
+  header.appendChild(el(doc, "span", "cockpit-leaf-name", leaf.token));
+  header.appendChild(el(doc, "span", "cockpit-leaf-count", `${leaf.liveCount}/${leaf.total} live`));
+  section.appendChild(header);
+  const table = el(doc, "table", "cockpit-supply-table");
+  const thead = el(doc, "thead", "cockpit-supply-thead");
+  const head = el(doc, "tr", "cockpit-supply-head");
+  for (const label of ["worker", "family", "host", "jobs", "liveness"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  thead.appendChild(head);
+  table.appendChild(thead);
+  const tbody = el(doc, "tbody", "cockpit-supply-tbody");
+  for (const worker of leaf.workers) tbody.appendChild(workerRow(doc, worker, onDrill));
+  table.appendChild(tbody);
+  section.appendChild(table);
+  return section;
+}
+
+function renderSupply(host, doc, view, onDrill) {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-supply");
+  root.setAttribute("data-worker-count", String(view.count));
+  root.setAttribute("data-live-count", String(view.live));
+  const header = el(doc, "header", "cockpit-header");
+  header.appendChild(el(doc, "h1", "cockpit-title", "Workers — supply"));
+  const summary = el(doc, "span", "cockpit-supply-summary", `${view.live}/${view.count} live`);
+  summary.setAttribute("data-summary", "supply");
+  header.appendChild(summary);
+  root.appendChild(header);
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-supply-empty", "No workers connected.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return;
+  }
+  const list = el(doc, "div", "cockpit-supply-list");
+  for (const leaf of view.leaves) list.appendChild(leafSection(doc, leaf, onDrill));
+  root.appendChild(list);
+  host.appendChild(root);
+}
+
+// ── boot orchestration (mirrors app/agentic/cockpit/supply-boot.ts) ────────────────────────────
+
+/** An xterm.js-backed terminal sink mounted into `host`. */
+function xtermSink(host) {
+  const term = new Terminal({ convertEol: true, fontFamily: "ui-monospace, monospace", fontSize: 13 });
+  term.open(host);
+  return { write: (chunk) => term.write(chunk), dispose: () => term.dispose() };
+}
+
+/** A WebSocket relay socket factory for the agentic channel at `url`. */
+function relaySocketFactory(url) {
+  return () => {
+    const ws = new WebSocket(url);
+    ws.binaryType = "arraybuffer";
+    return {
+      send: (bytes) => ws.send(bytes),
+      close: () => ws.close(),
+      onMessage: (cb) => ws.addEventListener("message", (event) => cb(new Uint8Array(event.data))),
+      onOpen: (cb) => ws.addEventListener("open", () => cb()),
+      onClose: (cb) => ws.addEventListener("close", () => cb()),
+    };
+  };
+}
+
+/**
+ * Mount the SUPPLY cockpit into `host` and start polling.
+ *
+ * @param {Element} host — where the cockpit renders (standalone: document.body; embedded: the App-View host).
+ * @param {object} [opts]
+ * @param {string} [opts.reportUrl] — the supply JSON endpoint the app serves.
+ * @param {string} [opts.relayUrl]  — the agentic channel WebSocket URL (with auth token + capability query).
+ * @param {string} [opts.hookSecret] — shared secret sent as `x-hook-secret` on the report fetch when the
+ *   app's supply endpoint is guarded by NANO_PR_WEBHOOK_SECRET (omit for open deployments).
+ * @param {string} [opts.relayToken] — identity token appended to the default relay URL as `?token=…`.
+ * @param {string} [opts.relayCapability] — capability credential appended to the default relay URL as `&capability=…`.
+ * @param {number} [opts.refreshMs] — poll interval (default 2000).
+ * @param {number} [opts.staleAfterMs] — a worker is rendered "stale" once its last heartbeat is at
+ *   least this many ms old (default 15000).
+ * @returns a handle with `.dispose()`.
+ */
+export function mountCockpit(host, opts = {}) {
+  if (host == null || typeof host.replaceChildren !== "function") {
+    throw new Error(
+      `mountCockpit(host): host must be a mounted DOM element (got ${host === null ? "null" : typeof host}).`,
+    );
+  }
+  const doc = document;
+  const reportUrl = opts.reportUrl ?? "/app/api/agentic/supply";
+  const hookSecret = opts.hookSecret;
+  const relayUrl = opts.relayUrl ?? defaultRelayUrl(opts.relayToken, opts.relayCapability);
+  const refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
+  // refreshMs feeds setTimeout as a poll delay. A negative/NaN/fractional/unsafe value silently
+  // collapses to a ~0ms delay, turning the poll into a hot loop that hammers the supply endpoint.
+  // Require a positive safe integer up-front (mirroring the TS boot layer) so a bad opt fails loudly.
+  if (!isPosInt(refreshMs)) {
+    throw new RangeError(`mountCockpit(opts.refreshMs): must be a positive safe integer, got ${refreshMs}.`);
+  }
+  const staleAfterMs = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  const connectRelay = relaySocketFactory(relayUrl);
+  const onError = (err) => console.error("[cockpit]", err);
+
+  // Stable skeleton: a volatile list region the poll re-renders + a PERSISTENT terminal region a
+  // refresh never touches (so a drilled-in terminal survives a list refresh).
+  host.replaceChildren();
+  const shell = el(doc, "div", "cockpit-shell");
+  const listRegion = el(doc, "div", "cockpit-supply-region");
+  const terminalPanel = el(doc, "section", "cockpit-terminal");
+  terminalPanel.appendChild(el(doc, "h2", "cockpit-panel-title", "Worker terminal"));
+  const terminalHost = el(doc, "div", "cockpit-terminal-host");
+  terminalHost.setAttribute("data-terminal", "host");
+  terminalPanel.appendChild(terminalHost);
+  shell.appendChild(listRegion);
+  shell.appendChild(terminalPanel);
+  host.appendChild(shell);
+
+  let running = false;
+  let disposed = false;
+  let timer;
+  let generation = 0;
+  let drill; // { stream, client }
+  let terminal; // the current xterm sink
+
+  function drillInto(stream) {
+    if (disposed || drill?.stream === stream) return;
+    drill?.client.close();
+    drill = undefined;
+    terminal?.dispose?.();
+    terminal = undefined;
+    try {
+      terminalHost.replaceChildren();
+      const sink = xtermSink(terminalHost);
+      terminal = sink;
+      let session;
+      const client = new RelayChannelClient({
+        connect: connectRelay,
+        onRelay: (message) => session?.handle(message),
+        onOpen: () => session?.attach(),
+        onError,
+      });
+      session = new TerminalSession({ stream, sink, send: (message) => client.sendRelay(message) });
+      client.open();
+      drill = { stream, client };
+    } catch (err) {
+      onError(err);
+    }
+  }
+
+  async function refresh() {
+    if (disposed) return;
+    let report;
+    try {
+      const headers = { accept: "application/json" };
+      if (hookSecret) headers["x-hook-secret"] = hookSecret;
+      const res = await fetch(reportUrl, { headers });
+      if (!res.ok) throw new Error(`supply fetch failed: ${res.status}`);
+      report = await res.json();
+    } catch (err) {
+      onError(err);
+      return;
+    }
+    if (disposed) return;
+    try {
+      renderSupply(listRegion, doc, supplyView(report, staleAfterMs), drillInto);
+    } catch (err) {
+      onError(err);
+    }
+  }
+
+  function tick(gen) {
+    void refresh().finally(() => {
+      if (gen !== generation || !running || disposed) return;
+      timer = setTimeout(() => tick(gen), refreshMs);
+    });
+  }
+
+  function start() {
+    if (disposed || running) return;
+    running = true;
+    tick(++generation);
+  }
+  function stop() {
+    running = false;
+    generation++;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  }
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    stop();
+    drill?.client.close();
+    drill = undefined;
+    terminal?.dispose?.();
+    terminal = undefined;
+  }
+
+  start();
+  return { start, stop, dispose, refresh, drill: drillInto };
+}
+
+/**
+ * Derive the channel WebSocket URL from the current origin (path `/agentic`).
+ *
+ * The agentic hub authenticates upgrades with `sharedSecretAuthenticator({ requireCredential: true })`,
+ * so a bare `ws(s)://host/agentic` is rejected (4401/4403). When a `token` (and optional `capability`)
+ * are supplied, they are appended as the `?token=…&capability=…` query the hub requires; without them
+ * the default URL cannot authenticate and drill-in will be refused — pass credentials (or an explicit
+ * `relayUrl`) for secured deployments.
+ */
+function defaultRelayUrl(token, capability) {
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  const base = `${proto}//${location.host}/agentic`;
+  if (!token) return base;
+  const query = new URLSearchParams({ token });
+  if (capability) query.set("capability", capability);
+  return `${base}?${query}`;
+}

package/pages/cockpit/standalone.html

@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>Agent cockpit — supply</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>
+    <!--
+      Resolve the reusable cockpit ESM (the relay client + resume-from-offset terminal session) and
+      xterm.js. Only these correctness-critical primitives are imported from the package; the supply
+      projection/render/poll lives inline in ./mount.js (the app has no build step to share its typed
+      core with the browser). The SAME ./mount.js the console App-View embed uses is loaded here, so
+      the standalone phone view and the embedded console view render identically.
+    -->
+    <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>
+    <main id="cockpit-root"></main>
+    <script type="module">
+      import { mountCockpit } from "./mount.js";
+
+      // Standalone: mount into the page body. Endpoints default to the current origin; override via
+      // ?report= and ?relay= for a remote app. For a secured deployment, pass the report guard secret
+      // via ?secret= (sent as x-hook-secret) and the relay credentials via ?token= and ?capability=.
+      const params = new URLSearchParams(location.search);
+      mountCockpit(document.getElementById("cockpit-root"), {
+        reportUrl: params.get("report") ?? undefined,
+        relayUrl: params.get("relay") ?? undefined,
+        hookSecret: params.get("secret") ?? undefined,
+        relayToken: params.get("token") ?? undefined,
+        relayCapability: params.get("capability") ?? undefined,
+      });
+    </script>
+  </body>
+</html>

package/pages/cockpit.page.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Cockpit",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epics", "page": "epic" },
+          { "label": "Cockpit", "page": "cockpit" }
+        ],
+        "sticky": true
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": {
+        "text": "Agent cockpit — live supply",
+        "variant": "heading"
+      }
+    },
+    {
+      "type": "text",
+      "id": "intro",
+      "props": {
+        "text": "The live worker/supply view: every connected worker grouped by leaf token, with family, host, current jobs, and liveness — sourced from the agentic presence registry. Drill into a worker to stream its terminal live over the relay; the terminal stays mounted across a list refresh and re-attaches (resume-from-offset) on reconnect. The same view renders embedded here (App View) and standalone on a phone. (The demand×supply matrix, missing-agent-type lights, and the diversity SLO are the enrolment epic's board — not shown here.)",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "appView",
+      "id": "cockpit",
+      "props": {
+        "title": "Live supply",
+        "embed": "./cockpit/embed.html",
+        "standalone": "./cockpit/standalone.html",
+        "fill": true
+      }
+    }
+  ]
+}

package/pages/epic-detail.page.json

@@ -11,7 +11,8 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" }
+          { "label": "Epics", "page": "epic" },
+          { "label": "Cockpit", "page": "cockpit" }
         ]
       }
     },

package/pages/epic.page.json

@@ -11,7 +11,8 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" }
+          { "label": "Epics", "page": "epic" },
+          { "label": "Cockpit", "page": "cockpit" }
         ]
       }
     },

package/pages/home.page.json

@@ -16,6 +16,10 @@
           {
             "label": "Epics",
             "page": "epic"
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
           }
         ],
         "sticky": true

package/test/agentic-cockpit-doubles.ts

@@ -0,0 +1,136 @@
+// Test-only doubles for the SUPPLY cockpit core (H5 / #148): an in-memory DOM that satisfies the
+// renderer's structural {@link ElementLike} / {@link DocumentLike} types, and a fake relay socket that
+// satisfies {@link RawSocket}. They let the supply renderer + boot layer be exercised on Node with no
+// DOM library, no real WebSocket, and no `as` cast — the fakes are STRUCTURALLY the same subsets the
+// browser's real `Document`/`Element`/`WebSocket` provide (mirrors the packaged cockpit's own fakes).
+import { decodeFrame, encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
+import type { DocumentLike, ElementLike, RawSocket } from "@nanobpm/agentic/cockpit";
+
+export class FakeElement implements ElementLike {
+  className = "";
+  textContent: string | null = null;
+  readonly tagName: string;
+  readonly attributes = new Map<string, string>();
+  readonly children: FakeElement[] = [];
+  readonly #listeners = new Map<string, Array<() => void>>();
+
+  constructor(tagName: string) {
+    this.tagName = tagName;
+  }
+
+  setAttribute(name: string, value: string): void {
+    this.attributes.set(name, value);
+  }
+
+  getAttribute(name: string): string | undefined {
+    return this.attributes.get(name);
+  }
+
+  appendChild(child: ElementLike): ElementLike {
+    if (child instanceof FakeElement) this.children.push(child);
+    return child;
+  }
+
+  replaceChildren(): void {
+    this.children.length = 0;
+  }
+
+  addEventListener(type: string, handler: () => void): void {
+    const list = this.#listeners.get(type) ?? [];
+    list.push(handler);
+    this.#listeners.set(type, list);
+  }
+
+  /** Fire every listener registered for `type` (test driver for clicks). */
+  dispatch(type: string): void {
+    for (const handler of this.#listeners.get(type) ?? []) handler();
+  }
+
+  /** Depth-first walk of this element and its descendants. */
+  *walk(): IterableIterator<FakeElement> {
+    yield this;
+    for (const child of this.children) yield* child.walk();
+  }
+
+  /** Every descendant (and self) whose className contains `cls`. */
+  byClass(cls: string): FakeElement[] {
+    const out: FakeElement[] = [];
+    for (const node of this.walk()) {
+      if (node.className.split(/\s+/).includes(cls)) out.push(node);
+    }
+    return out;
+  }
+
+  /** Every descendant (and self) with `data-<key>` equal to `value` (any value if omitted). */
+  byData(key: string, value?: string): FakeElement[] {
+    const attr = `data-${key}`;
+    const out: FakeElement[] = [];
+    for (const node of this.walk()) {
+      const got = node.attributes.get(attr);
+      if (got !== undefined && (value === undefined || got === value)) out.push(node);
+    }
+    return out;
+  }
+
+  /** The concatenated text content of this subtree (own text then children). */
+  text(): string {
+    let out = this.textContent ?? "";
+    for (const child of this.children) out += child.text();
+    return out;
+  }
+}
+
+export class FakeDocument implements DocumentLike {
+  createElement(tagName: string): ElementLike {
+    return new FakeElement(tagName);
+  }
+}
+
+/** A fake relay socket: records sent frames and lets a test drive open/close/deliver by hand. */
+export class FakeSocket implements RawSocket {
+  readonly sent: Uint8Array[] = [];
+  closed = false;
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onOpen: (() => void) | undefined;
+  #onClose: (() => void) | undefined;
+
+  send(bytes: Uint8Array): void {
+    this.sent.push(bytes);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  onMessage(listener: (bytes: Uint8Array) => void): void {
+    this.#onMessage = listener;
+  }
+
+  onOpen(listener: () => void): void {
+    this.#onOpen = listener;
+  }
+
+  onClose(listener: () => void): void {
+    this.#onClose = listener;
+  }
+
+  /** Fire the open listener (a successful connect). */
+  fireOpen(): void {
+    this.#onOpen?.();
+  }
+
+  /** Fire the close listener (the socket dropped). */
+  fireClose(): void {
+    this.#onClose?.();
+  }
+
+  /** Deliver one inbound frame to the client. */
+  deliver(frame: Frame): void {
+    this.#onMessage?.(encodeFrame(frame));
+  }
+
+  /** The relay-family frames this socket sent, decoded. */
+  subscribeFrames(): Frame[] {
+    return this.sent.map(decodeFrame).filter((f) => f.family === "relay");
+  }
+}