@nanobpm/agentic 0.1.0

package/src/cockpit/relay-client.ts

@@ -0,0 +1,234 @@
+/**
+ * The browser-side relay channel client — S8.
+ *
+ * Ties one relay stream's {@link TerminalSession} to a live WebSocket-style
+ * connection: it encodes the session's outbound relay messages into S0 frames
+ * ({@link encodeFrame}) on the control lane, decodes inbound frames
+ * ({@link decodeFrame}) and routes `relay`-family payloads back to the session,
+ * and — critically for "survives a cockpit reconnect" — re-opens the socket when
+ * it drops and fires {@link RelayChannelClientOptions.onOpen} on **every**
+ * (re)connect, so the caller re-attaches the session and resumes from its last
+ * offset.
+ *
+ * It is transport- and timer-injected: the socket comes from a
+ * {@link SocketFactory} and reconnect scheduling from an injected
+ * {@link Scheduler}, so the whole reconnect→resume path is exercised
+ * deterministically in tests with a fake socket and a manual scheduler — no real
+ * timers, no real network (AGENTS.md: no flaky tests, no test retries).
+ */
+import { isNonNegInt, RELAY_FAMILY } from "../relay/index.ts";
+import { decodeFrame, encodeFrame, MAX_SEQ } from "../protocol/index.ts";
+import type { Frame, RelayPayload } from "../protocol/index.ts";
+import type { RelayInbound, RelayOutbound } from "./terminal-session.ts";
+
+/** The minimal socket surface the client drives (a browser `WebSocket` adapts to this). */
+export interface RawSocket {
+  /** Send one binary frame. */
+  send(bytes: Uint8Array): void;
+  /** Close the socket. */
+  close(): void;
+  /** Register the inbound-binary-frame listener. */
+  onMessage(listener: (bytes: Uint8Array) => void): void;
+  /** Register the open listener (fired once per successful connect). */
+  onOpen(listener: () => void): void;
+  /** Register the close listener (fired once when the socket drops). */
+  onClose(listener: () => void): void;
+}
+
+/** Opens a fresh socket. Called once per (re)connect. */
+export type SocketFactory = () => RawSocket;
+
+/** Schedules a reconnect attempt. Injected so tests can run it synchronously. */
+export type Scheduler = (run: () => void) => void;
+
+export interface RelayChannelClientOptions {
+  /** Opens a fresh socket for each (re)connect. */
+  readonly connect: SocketFactory;
+  /** Receives every inbound `relay`-family payload (data chunk or resume ack). */
+  readonly onRelay: (message: RelayInbound) => void;
+  /** Fired on every (re)connect — the caller re-attaches the session here. */
+  readonly onOpen?: () => void;
+  /** Fired when the socket drops (before a reconnect is scheduled). */
+  readonly onClose?: () => void;
+  /** Notified of a decode/dispatch error on an inbound frame. */
+  readonly onError?: (err: unknown) => void;
+  /** Reconnect scheduler. Default `setTimeout(run, 0)`. */
+  readonly schedule?: Scheduler;
+  /** Reconnect automatically on close. Default true. */
+  readonly autoReconnect?: boolean;
+}
+
+const CONTROL_LANE: Frame["lane"] = "control";
+
+function defaultSchedule(run: () => void): void {
+  setTimeout(run, 0);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Narrow a decoded `relay`-family payload to the inbound sub-protocol without an
+ * unchecked cast (the repo bans `as`): a data chunk `{ stream, offset, chunk }`
+ * or a resume ack `{ op: "subscribed", stream, gap, nextOffset }`. Any payload
+ * carrying an `op` field is treated as an op-message and rejected unless it is a
+ * well-formed known op, so a malformed/unknown op can never fall through and be
+ * mistaken for a data chunk.
+ */
+function asRelayInbound(payload: unknown): RelayInbound | null {
+  if (!isRecord(payload)) return null;
+  if ("op" in payload) {
+    if (
+      payload.op === "subscribed" &&
+      typeof payload.stream === "string" &&
+      typeof payload.gap === "boolean" &&
+      isNonNegInt(payload.nextOffset)
+    ) {
+      return { op: "subscribed", stream: payload.stream, gap: payload.gap, nextOffset: payload.nextOffset };
+    }
+    return null;
+  }
+  if (typeof payload.stream === "string" && isNonNegInt(payload.offset) && typeof payload.chunk === "string") {
+    const data: RelayPayload = { stream: payload.stream, offset: payload.offset, chunk: payload.chunk };
+    return data;
+  }
+  return null;
+}
+
+/**
+ * Manages one relay socket with automatic resume-on-reconnect. Construct once
+ * per drill-in and pair with a {@link TerminalSession}: wire the session's
+ * `send` to {@link sendRelay}, feed {@link RelayChannelClientOptions.onRelay} to
+ * `session.handle`, and call `session.attach()` from `onOpen`.
+ */
+export class RelayChannelClient {
+  readonly #connect: SocketFactory;
+  readonly #onRelay: RelayChannelClientOptions["onRelay"];
+  readonly #onOpen: RelayChannelClientOptions["onOpen"];
+  readonly #onClose: RelayChannelClientOptions["onClose"];
+  readonly #onError: RelayChannelClientOptions["onError"];
+  readonly #schedule: Scheduler;
+  readonly #autoReconnect: boolean;
+  #socket: RawSocket | undefined;
+  #seq = 0;
+  #closed = false;
+
+  constructor(options: RelayChannelClientOptions) {
+    this.#connect = options.connect;
+    this.#onRelay = options.onRelay;
+    this.#onOpen = options.onOpen;
+    this.#onClose = options.onClose;
+    this.#onError = options.onError;
+    this.#schedule = options.schedule ?? defaultSchedule;
+    this.#autoReconnect = options.autoReconnect ?? true;
+  }
+
+  /** True once {@link close} has been called (no further reconnects). */
+  get isClosed(): boolean {
+    return this.#closed;
+  }
+
+  /** Open the first socket and wire its lifecycle. Idempotent while connected. */
+  open(): void {
+    if (this.#closed || this.#socket !== undefined) return;
+    // Guard the injected factory: connect() can throw synchronously (e.g. the
+    // browser adapter's WebSocket constructor on an invalid URL / CSP block).
+    // An unguarded throw here escapes open()/#reconnect() and kills the
+    // reconnect→resume loop with no error surfaced. Route it to onError and, if
+    // autoReconnect is enabled, schedule a retry so the loop survives a
+    // transient connect failure — the same way #handleClose recovers a drop.
+    let socket: RawSocket;
+    try {
+      socket = this.#connect();
+    } catch (err) {
+      this.#onError?.(err);
+      if (!this.#closed && this.#autoReconnect) this.#schedule(() => this.#reconnect());
+      return;
+    }
+    this.#socket = socket;
+    socket.onMessage((bytes) => this.#receive(bytes));
+    // Guard the consumer callback the same way #receive() does: a consumer
+    // onOpen handler can throw, and an unguarded throw escapes the socket open
+    // callback. Route it to onError so a bad handler can't wedge the client.
+    socket.onOpen(() => {
+      try {
+        this.#onOpen?.();
+      } catch (err) {
+        this.#onError?.(err);
+      }
+    });
+    socket.onClose(() => this.#handleClose());
+  }
+
+  /** Encode and send one outbound relay message on the control lane. */
+  sendRelay(message: RelayOutbound): void {
+    const socket = this.#socket;
+    if (socket === undefined) return;
+    const frame: Frame = { lane: CONTROL_LANE, family: RELAY_FAMILY, seq: this.#nextSeq(), payload: message };
+    try {
+      socket.send(encodeFrame(frame));
+    } catch (err) {
+      this.#onError?.(err);
+    }
+  }
+
+  /** Close for good — no reconnect will follow. */
+  close(): void {
+    this.#closed = true;
+    const socket = this.#socket;
+    this.#socket = undefined;
+    socket?.close();
+  }
+
+  #nextSeq(): number {
+    const seq = this.#seq;
+    this.#seq = this.#seq >= MAX_SEQ ? 0 : this.#seq + 1;
+    return seq;
+  }
+
+  #receive(bytes: Uint8Array): void {
+    let frame: Frame;
+    try {
+      frame = decodeFrame(bytes);
+    } catch (err) {
+      this.#onError?.(err);
+      return;
+    }
+    if (frame.family !== RELAY_FAMILY) return;
+    const message = asRelayInbound(frame.payload);
+    if (message === null) {
+      this.#onError?.(new Error("malformed relay payload"));
+      return;
+    }
+    // Guard the consumer the same way decode/malformed errors are guarded: a
+    // handler (e.g. TerminalSession.handle) can throw on an unsafe offset via
+    // addSafeInt, and an unguarded throw here escapes the socket message
+    // callback and can wedge the relay client / page. Route it to onError.
+    try {
+      this.#onRelay(message);
+    } catch (err) {
+      this.#onError?.(err);
+    }
+  }
+
+  #handleClose(): void {
+    this.#socket = undefined;
+    // Guard the consumer onClose: if it throws, an unguarded exception here
+    // skips the reconnect scheduling below and breaks the "survives reconnect"
+    // invariant for reasons unrelated to transport. Route it to onError, then
+    // continue with reconnect regardless.
+    try {
+      this.#onClose?.();
+    } catch (err) {
+      this.#onError?.(err);
+    }
+    if (this.#closed || !this.#autoReconnect) return;
+    this.#schedule(() => this.#reconnect());
+  }
+
+  #reconnect(): void {
+    if (this.#closed || this.#socket !== undefined) return;
+    this.open();
+  }
+}

package/src/cockpit/render.test.ts

@@ -0,0 +1,149 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { FakeDocument, FakeElement } from "./fake-dom.ts";
+import { renderCockpit } from "./render.ts";
+import { type CockpitView, cockpitView } from "./view.ts";
+
+function view(): CockpitView {
+  return cockpitView({
+    status: "red",
+    missing: ["planning.plan#blue"],
+    networks: [
+      {
+        network: "ci",
+        tokens: [{ token: "ci.build", supply: 2, instances: ["ci-a", "ci-b"], satisfied: true }],
+        missing: [],
+      },
+      {
+        network: "planning",
+        tokens: [
+          { token: "planning.plan#blue", supply: 0, instances: [], satisfied: false },
+          { token: "planning.plan#red", supply: 1, instances: ["plan-a"], satisfied: true },
+        ],
+        missing: ["planning.plan#blue"],
+      },
+    ],
+    diversity: { status: "green", roles: [] },
+    nonAgentic: ["send-email"],
+  });
+}
+
+test("renders one section per network with a demand×supply row per token", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+
+  const networks = host.byClass("cockpit-network");
+  assert.deepEqual(
+    networks.map((n) => n.getAttribute("data-network")),
+    ["ci", "planning"],
+  );
+  const tokens = host.byClass("cockpit-token");
+  assert.deepEqual(
+    tokens.map((t) => t.getAttribute("data-token")),
+    ["ci.build", "planning.plan#blue", "planning.plan#red"],
+  );
+});
+
+test("token tables use valid <thead>/<tbody> structure (rows are never direct <table> children)", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+
+  const tables = host.byClass("cockpit-tokens");
+  assert.ok(tables.length >= 1, "at least one token table is rendered");
+  for (const table of tables) {
+    // A <table> must only contain section elements (<thead>/<tbody>), never a bare <tr>.
+    assert.deepEqual(
+      table.children.map((c) => c.tagName),
+      ["thead", "tbody"],
+      "table children are the section wrappers, not rows",
+    );
+    const [thead, tbody] = table.children;
+    assert.deepEqual(
+      thead?.children.map((c) => c.tagName),
+      ["tr"],
+      "the header row lives inside <thead>",
+    );
+    for (const row of tbody?.children ?? []) {
+      assert.equal(row.tagName, "tr", "every data row lives inside <tbody>");
+    }
+  }
+});
+
+test("a missing agent type renders a RED token, a RED network and a red missing light", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+
+  const missingTok = host.byData("token", "planning.plan#blue")[0];
+  assert.equal(missingTok?.getAttribute("data-status"), "red");
+  const planning = host.byData("network", "planning")[0];
+  assert.equal(planning?.getAttribute("data-status"), "red");
+
+  const lights = host.byClass("cockpit-light").filter((l) => l.getAttribute("data-light-id")?.startsWith("missing:"));
+  assert.equal(lights.length, 1);
+  assert.equal(lights[0]?.getAttribute("data-status"), "red");
+  assert.match(lights[0]?.text() ?? "", /planning\.plan#blue/);
+});
+
+test("the overall status and diversity light render in the header", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+  assert.equal(host.byClass("cockpit")[0]?.getAttribute("data-status"), "red");
+  const badge = host.byData("badge-id", "overall")[0];
+  assert.equal(badge?.getAttribute("data-status"), "red");
+  const diversity = host.byData("light-id", "diversity")[0];
+  assert.equal(diversity?.getAttribute("data-status"), "green");
+});
+
+test("clicking a worker chip drills into that instance's relay stream", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  const drilled: string[] = [];
+  renderCockpit(host, doc, view(), { onDrill: (stream) => drilled.push(stream) });
+
+  const chip = host.byData("stream", "ci-a")[0];
+  assert.ok(chip instanceof FakeElement);
+  chip.dispatch("click");
+  assert.deepEqual(drilled, ["ci-a"]);
+});
+
+test("re-rendering replaces prior content (idempotent refresh)", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+  renderCockpit(host, doc, view());
+  assert.equal(host.children.length, 1, "host holds exactly one cockpit root after re-render");
+  assert.equal(host.byClass("cockpit-network").length, 2);
+});
+
+test("embedded and standalone render identically — same view, same host subset ⇒ same DOM", () => {
+  const doc = new FakeDocument();
+  const standaloneHost = new FakeElement("body");
+  const embeddedHost = new FakeElement("div");
+  const v = view();
+  renderCockpit(standaloneHost, doc, v);
+  renderCockpit(embeddedHost, doc, v);
+
+  const shape = (root: FakeElement): unknown => ({
+    tag: root.tagName,
+    cls: root.className,
+    attrs: [...root.attributes.entries()].sort(),
+    text: root.textContent,
+    children: root.children.map(shape),
+  });
+  const standaloneRoot = standaloneHost.children[0];
+  const embeddedRoot = embeddedHost.children[0];
+  assert.ok(standaloneRoot !== undefined && embeddedRoot !== undefined);
+  assert.deepEqual(shape(standaloneRoot), shape(embeddedRoot));
+});
+
+test("non-agentic task types render in a footer", () => {
+  const doc = new FakeDocument();
+  const host = new FakeElement("body");
+  renderCockpit(host, doc, view());
+  assert.match(host.byClass("cockpit-nonagentic")[0]?.text() ?? "", /send-email/);
+});

package/src/cockpit/render.ts

@@ -0,0 +1,194 @@
+/**
+ * The cockpit DOM renderer — S8.
+ *
+ * Renders a {@link CockpitView} into a host element: the demand×supply networks
+ * matrix, a red light per *missing agent type*, and the diversity-SLO light.
+ * Clicking a worker instance calls {@link RenderOptions.onDrill} with that
+ * instance's relay stream id. This renders only the *volatile* part of the page
+ * (the part that refreshes each poll); the drill-in terminal is owned by
+ * {@link mountCockpit} in a persistent region so it survives a matrix refresh.
+ *
+ * It renders against a **structural** DOM subset ({@link ElementLike} /
+ * {@link DocumentLike}) rather than the global `document`, for two reasons that
+ * matter to this slice:
+ *  1. it is the *same* function the standalone shell and the embedded (App View)
+ *     host both call — via the plain-JS `page/mount.js` adapter, which passes the
+ *     browser's real `document` and their own host element — so the two render
+ *     **identically** by construction (one code path, no standalone/embedded
+ *     branch); and
+ *  2. a plain in-memory fake satisfies the structural type, so the renderer is
+ *     unit-tested on Node with no DOM library and no `as` cast.
+ *
+ * These interfaces are a deliberately *minimal* subset, NOT lib.dom's `Element`/
+ * `Document`: the real DOM satisfies them at runtime (as `page/mount.js` — plain
+ * JS, untyped — relies on), but a real `HTMLElement` is not TS-assignable to
+ * {@link ElementLike} (lib.dom's `appendChild` is `Node`-constrained). Keeping the
+ * subset this narrow — rather than widening to lib.dom, which the in-memory fake
+ * could not satisfy without a banned `as` cast — is the tradeoff that buys the
+ * DOM-free Node tests. A TypeScript browser caller wanting to invoke
+ * {@link bootCockpit} directly supplies a thin structural adapter over the real DOM.
+ */
+import type { CockpitLight, CockpitView, SloStatus } from "./view.ts";
+
+/** The minimal element surface the renderer builds against (the in-memory fake, and the real DOM at runtime, satisfy it — see file header). */
+export interface ElementLike {
+  className: string;
+  textContent: string | null;
+  setAttribute(name: string, value: string): void;
+  appendChild(child: ElementLike): ElementLike;
+  replaceChildren(): void;
+  addEventListener(type: string, handler: () => void): void;
+}
+
+/** The minimal document surface the renderer builds against (the in-memory fake, and the real DOM at runtime, satisfy it — see file header). */
+export interface DocumentLike {
+  createElement(tagName: string): ElementLike;
+}
+
+export interface RenderOptions {
+  /** Called with a worker instance's relay stream id when the operator drills in. */
+  readonly onDrill?: (stream: string) => void;
+}
+
+/** Handles into the rendered tree the caller may need. */
+export interface CockpitDom {
+  /** The freshly built root the view was rendered into. */
+  readonly root: ElementLike;
+}
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function lightNode(doc: DocumentLike, light: CockpitLight): ElementLike {
+  const row = el(doc, "div", "cockpit-light");
+  row.setAttribute("data-status", light.status);
+  row.setAttribute("data-light-id", light.id);
+  const dot = el(doc, "span", "cockpit-dot");
+  dot.setAttribute("data-status", light.status);
+  row.appendChild(dot);
+  row.appendChild(el(doc, "span", "cockpit-light-label", light.label));
+  if (light.detail !== undefined) {
+    const detail = el(doc, "span", "cockpit-light-detail", light.detail);
+    detail.setAttribute("title", light.detail);
+    row.appendChild(detail);
+  }
+  return row;
+}
+
+function statusBadge(doc: DocumentLike, id: string, label: string, status: SloStatus): ElementLike {
+  const badge = el(doc, "div", "cockpit-status", `${label}: ${status}`);
+  badge.setAttribute("data-status", status);
+  badge.setAttribute("data-badge-id", id);
+  return badge;
+}
+
+function tokenCell(doc: DocumentLike, network: CockpitView["networks"][number], options: RenderOptions): ElementLike {
+  const table = el(doc, "table", "cockpit-tokens");
+  const thead = el(doc, "thead", "cockpit-tokens-thead");
+  const head = el(doc, "tr", "cockpit-tokens-head");
+  head.appendChild(el(doc, "th", "cockpit-th", "token"));
+  head.appendChild(el(doc, "th", "cockpit-th", "supply"));
+  head.appendChild(el(doc, "th", "cockpit-th", "workers"));
+  thead.appendChild(head);
+  table.appendChild(thead);
+  const tbody = el(doc, "tbody", "cockpit-tokens-tbody");
+  for (const token of network.tokens) {
+    const row = el(doc, "tr", "cockpit-token");
+    row.setAttribute("data-status", token.status);
+    row.setAttribute("data-token", token.token);
+    const dot = el(doc, "td", "cockpit-td");
+    const light = el(doc, "span", "cockpit-dot");
+    light.setAttribute("data-status", token.status);
+    dot.appendChild(light);
+    dot.appendChild(el(doc, "span", "cockpit-token-name", token.token));
+    row.appendChild(dot);
+    row.appendChild(el(doc, "td", "cockpit-td", String(token.supply)));
+    const workers = el(doc, "td", "cockpit-td cockpit-workers");
+    for (const instance of token.instances) {
+      const chip = el(doc, "button", "cockpit-worker", instance);
+      chip.setAttribute("data-stream", instance);
+      chip.setAttribute("type", "button");
+      const onDrill = options.onDrill;
+      if (onDrill !== undefined) {
+        chip.addEventListener("click", () => onDrill(instance));
+      }
+      workers.appendChild(chip);
+    }
+    row.appendChild(workers);
+    tbody.appendChild(row);
+  }
+  table.appendChild(tbody);
+  return table;
+}
+
+function networkSection(doc: DocumentLike, network: CockpitView["networks"][number], options: RenderOptions): ElementLike {
+  const section = el(doc, "section", "cockpit-network");
+  section.setAttribute("data-status", network.status);
+  section.setAttribute("data-network", network.network);
+  const header = el(doc, "div", "cockpit-network-head");
+  const dot = el(doc, "span", "cockpit-dot");
+  dot.setAttribute("data-status", network.status);
+  header.appendChild(dot);
+  header.appendChild(el(doc, "span", "cockpit-network-name", network.network));
+  if (network.missing.length > 0) {
+    header.appendChild(el(doc, "span", "cockpit-network-missing", `missing: ${network.missing.join(", ")}`));
+  }
+  section.appendChild(header);
+  section.appendChild(tokenCell(doc, network, options));
+  return section;
+}
+
+function missingPanel(doc: DocumentLike, view: CockpitView): ElementLike {
+  const panel = el(doc, "aside", "cockpit-missing");
+  panel.setAttribute("data-empty", view.missingLights.length === 0 ? "true" : "false");
+  panel.appendChild(el(doc, "h2", "cockpit-panel-title", "Missing agent types"));
+  if (view.missingLights.length === 0) {
+    panel.appendChild(el(doc, "div", "cockpit-missing-none", "none — every demanded token is served"));
+    return panel;
+  }
+  for (const light of view.missingLights) {
+    panel.appendChild(lightNode(doc, light));
+  }
+  return panel;
+}
+
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it
+ * again on every refresh to reflect the latest demand×supply snapshot.
+ */
+export function renderCockpit(
+  host: ElementLike,
+  doc: DocumentLike,
+  view: CockpitView,
+  options: RenderOptions = {},
+): CockpitDom {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit");
+  root.setAttribute("data-status", view.status);
+
+  const header = el(doc, "header", "cockpit-header");
+  header.appendChild(el(doc, "h1", "cockpit-title", "Agent networks — the cockpit"));
+  header.appendChild(statusBadge(doc, "overall", "overall", view.status));
+  header.appendChild(lightNode(doc, view.diversityLight));
+  root.appendChild(header);
+
+  root.appendChild(missingPanel(doc, view));
+
+  const matrix = el(doc, "div", "cockpit-matrix");
+  for (const network of view.networks) {
+    matrix.appendChild(networkSection(doc, network, options));
+  }
+  root.appendChild(matrix);
+
+  if (view.nonAgentic.length > 0) {
+    const footer = el(doc, "footer", "cockpit-nonagentic", `non-agentic task types: ${view.nonAgentic.join(", ")}`);
+    root.appendChild(footer);
+  }
+
+  host.appendChild(root);
+  return { root };
+}