@nanobpm/agentic 0.1.0

package/dist/cockpit/boot.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The cockpit boot/orchestration layer — S8.
+ *
+ * Wires the whole page together from injected capabilities, with **no** direct
+ * dependency on the browser, a socket implementation, or xterm.js — everything is
+ * passed in ({@link CockpitEnv}). That is what makes the page render *identically*
+ * embedded (console App View) and standalone (the two shells differ only in the
+ * `host` element and the concrete capabilities they inject), and what makes the
+ * live-refresh + drill-in + resume-on-reconnect path unit-testable on Node.
+ *
+ * Responsibilities:
+ *  - a **self-scheduling** poll of the S4 demand×supply report that re-renders the
+ *    matrix/lights each pass (a slow fetch can't overlap the next — mirrors the
+ *    nano-workforce poller discipline);
+ *  - **drill-into-a-worker**: open a {@link RelayChannelClient} + {@link TerminalSession}
+ *    for the selected stream, mount its output into a *persistent* terminal region
+ *    (so a matrix refresh never wipes it), and re-attach on every reconnect so the
+ *    terminal **survives a cockpit reconnect** via resume-from-offset.
+ */
+import type { DemandSupplyReport } from "../demand/index.ts";
+import { type Scheduler, type SocketFactory } from "./relay-client.ts";
+import { type DocumentLike, type ElementLike } from "./render.ts";
+import { type TerminalSink } from "./terminal-session.ts";
+/** Mounts a terminal into `host` and returns the sink relay output is written to. */
+export type CreateTerminal = (host: ElementLike) => TerminalSink;
+/** An opaque poll-timer handle (a Node `Timeout` or a browser timer id). */
+export type TimerHandle = unknown;
+export interface CockpitEnv {
+    /** The element the cockpit renders into (standalone: `document.body`; embedded: the App View host). */
+    readonly host: ElementLike;
+    /** The document the renderer creates elements from. */
+    readonly doc: DocumentLike;
+    /** Fetches the latest S4 demand×supply report (e.g. over HTTP or the channel). */
+    readonly fetchReport: () => Promise<DemandSupplyReport>;
+    /** Opens a socket to the app relay channel (one per drill-in connection). */
+    readonly connectRelay: SocketFactory;
+    /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
+    readonly createTerminal: CreateTerminal;
+    /** Reconnect scheduler for the relay client. Default `setTimeout(run, 0)`. */
+    readonly schedule?: Scheduler;
+    /** Poll scheduler. Default `setTimeout`. Injected so tests drive it by hand. Must be paired with {@link clearTimer}. */
+    readonly setTimer?: (run: () => void, ms: number) => TimerHandle;
+    /** Cancels a poll timer. Default `clearTimeout`. Must be paired with {@link setTimer}. */
+    readonly clearTimer?: (handle: TimerHandle) => void;
+    /** Poll interval in ms. Default 2000. */
+    readonly refreshMs?: number;
+    /** Bulk credit granted per terminal (re)subscribe. Default 1024. */
+    readonly credit?: number;
+    /** Notified of a fetch/render/relay error (the poll keeps going). */
+    readonly onError?: (err: unknown) => void;
+}
+/** The running cockpit; dispose to stop polling and tear down the terminal. */
+export interface CockpitHandle {
+    /** Run one fetch→render pass now (also the poll body). Resolves when rendered. */
+    refresh(): Promise<void>;
+    /** Start the self-scheduling poll loop (runs one pass immediately). */
+    start(): void;
+    /** Stop the poll loop (leaves the last render in place). */
+    stop(): void;
+    /** Drill into a worker's relay stream, opening a resumable live terminal. */
+    drill(stream: string): void;
+    /** The stream currently drilled into, if any. */
+    readonly currentStream: string | undefined;
+    /** Stop everything and release the terminal connection. */
+    dispose(): void;
+}
+/** Boot the cockpit against an injected environment. Call {@link CockpitHandle.start} to poll. */
+export declare function bootCockpit(env: CockpitEnv): CockpitHandle;

package/dist/cockpit/boot.js

@@ -0,0 +1,202 @@
+import { isPosInt } from "../relay/index.js";
+import { RelayChannelClient } from "./relay-client.js";
+import { renderCockpit } from "./render.js";
+import { TerminalSession } from "./terminal-session.js";
+import { cockpitView } from "./view.js";
+const DEFAULT_REFRESH_MS = 2000;
+class Cockpit {
+    #env;
+    #matrixRegion;
+    #terminalHost;
+    #refreshMs;
+    #setTimer;
+    #clearTimer;
+    #timeouts = new Map();
+    #nextTimerId = 0;
+    #timer;
+    #running = false;
+    #disposed = false;
+    #drill;
+    // The currently mounted terminal, tracked so switching streams (and dispose)
+    // tears down the prior xterm instance instead of leaking it + its listeners.
+    #terminal;
+    // Bumped by every start()/stop() so an in-flight #tick() from a previous
+    // start cycle can't reschedule after a stop→start race and leave two
+    // overlapping poll chains running against the same cockpit.
+    #generation = 0;
+    constructor(env) {
+        this.#env = env;
+        this.#refreshMs = env.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 demand endpoint and burns CPU. Require a positive safe
+        // integer up-front so a bad env option fails loudly instead.
+        if (!isPosInt(this.#refreshMs)) {
+            throw new RangeError(`CockpitEnv.refreshMs must be a positive safe integer, got ${this.#refreshMs}`);
+        }
+        // setTimer/clearTimer are a matched pair: a caller-supplied setTimer returns
+        // opaque handles the default clearTimer (which only understands the internal
+        // numeric-handle Map) cannot cancel, leaving an un-stoppable poll loop. Fail
+        // fast rather than silently accept one without the other.
+        if ((env.setTimer === undefined) !== (env.clearTimer === undefined)) {
+            throw new Error("CockpitEnv.setTimer and clearTimer must be provided together (or neither)");
+        }
+        // Default timer path uses numeric handles backed by a Map, so no unchecked
+        // cast is needed to feed an opaque handle back to clearTimeout (`as` is banned).
+        this.#setTimer =
+            env.setTimer ??
+                ((run, ms) => {
+                    const id = this.#nextTimerId++;
+                    this.#timeouts.set(id, setTimeout(() => {
+                        this.#timeouts.delete(id);
+                        run();
+                    }, ms));
+                    return id;
+                });
+        this.#clearTimer =
+            env.clearTimer ??
+                ((handle) => {
+                    if (typeof handle !== "number")
+                        return;
+                    const timeout = this.#timeouts.get(handle);
+                    if (timeout !== undefined) {
+                        clearTimeout(timeout);
+                        this.#timeouts.delete(handle);
+                    }
+                });
+        // Build the stable skeleton once: a volatile matrix region the poll
+        // re-renders, and a PERSISTENT terminal region a refresh never touches.
+        env.host.replaceChildren();
+        const shell = env.doc.createElement("div");
+        shell.className = "cockpit-shell";
+        this.#matrixRegion = env.doc.createElement("div");
+        this.#matrixRegion.className = "cockpit-matrix-region";
+        const terminalPanel = env.doc.createElement("section");
+        terminalPanel.className = "cockpit-terminal";
+        const title = env.doc.createElement("h2");
+        title.className = "cockpit-panel-title";
+        title.textContent = "Worker terminal";
+        terminalPanel.appendChild(title);
+        this.#terminalHost = env.doc.createElement("div");
+        this.#terminalHost.className = "cockpit-terminal-host";
+        this.#terminalHost.setAttribute("data-terminal", "host");
+        terminalPanel.appendChild(this.#terminalHost);
+        shell.appendChild(this.#matrixRegion);
+        shell.appendChild(terminalPanel);
+        env.host.appendChild(shell);
+    }
+    get currentStream() {
+        return this.#drill?.stream;
+    }
+    async refresh() {
+        if (this.#disposed)
+            return;
+        let report;
+        try {
+            report = await this.#env.fetchReport();
+        }
+        catch (err) {
+            this.#env.onError?.(err);
+            return;
+        }
+        if (this.#disposed)
+            return;
+        try {
+            renderCockpit(this.#matrixRegion, this.#env.doc, cockpitView(report), {
+                onDrill: (stream) => this.drill(stream),
+            });
+        }
+        catch (err) {
+            this.#env.onError?.(err);
+        }
+    }
+    start() {
+        if (this.#disposed || this.#running)
+            return;
+        this.#running = true;
+        const generation = ++this.#generation;
+        this.#tick(generation);
+    }
+    stop() {
+        this.#running = false;
+        // Invalidate any in-flight tick so its finally can't reschedule after this.
+        this.#generation++;
+        if (this.#timer !== undefined) {
+            this.#clearTimer(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+    #tick(generation) {
+        // Self-scheduling: schedule the NEXT pass only after this one settles, so a
+        // slow fetch can never overlap its successor. The generation guard drops a
+        // stale tick whose start cycle was already stopped (and possibly restarted),
+        // so a stop→start race never leaves two poll chains scheduling in parallel.
+        void this.refresh().finally(() => {
+            if (generation !== this.#generation || !this.#running || this.#disposed)
+                return;
+            this.#timer = this.#setTimer(() => this.#tick(generation), this.#refreshMs);
+        });
+    }
+    drill(stream) {
+        if (this.#disposed)
+            return;
+        if (this.#drill?.stream === stream)
+            return;
+        // Close and drop the prior drill up-front so a synchronous failure while
+        // building the new one (e.g. createTerminal, an invalid TerminalSession
+        // credit, or connect throwing) can't leave #drill pointing at an
+        // already-closed client — currentStream would then report a dead stream.
+        // #drill is re-set only once the new client is fully wired and opened, so
+        // state stays consistent even when the new drill fails to initialize; the
+        // failure is routed to onError like every other relay/terminal error.
+        this.#drill?.client.close();
+        this.#drill = undefined;
+        // Tear down the prior terminal before mounting a fresh one so repeated
+        // drills don't leak xterm instances/listeners (replaceChildren only drops
+        // the DOM node, not the widget). Tracked in #terminal so a failed (re)drill
+        // still cleans it up on the next drill or on dispose().
+        this.#terminal?.dispose?.();
+        this.#terminal = undefined;
+        try {
+            // Fresh terminal for the newly selected worker.
+            this.#terminalHost.replaceChildren();
+            const sink = this.#env.createTerminal(this.#terminalHost);
+            this.#terminal = sink;
+            let session;
+            const client = new RelayChannelClient({
+                connect: this.#env.connectRelay,
+                onRelay: (message) => session?.handle(message),
+                // Re-attach on EVERY (re)connect → resume-from-offset: the terminal
+                // survives a cockpit reconnect without losing or double-writing output.
+                onOpen: () => session?.attach(),
+                schedule: this.#env.schedule,
+                onError: (err) => this.#env.onError?.(err),
+            });
+            session = new TerminalSession({
+                stream,
+                sink,
+                send: (message) => client.sendRelay(message),
+                credit: this.#env.credit,
+            });
+            client.open();
+            this.#drill = { stream, client };
+        }
+        catch (err) {
+            this.#env.onError?.(err);
+        }
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.stop();
+        this.#drill?.client.close();
+        this.#drill = undefined;
+        this.#terminal?.dispose?.();
+        this.#terminal = undefined;
+    }
+}
+/** Boot the cockpit against an injected environment. Call {@link CockpitHandle.start} to poll. */
+export function bootCockpit(env) {
+    return new Cockpit(env);
+}

package/dist/cockpit/fake-dom.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A minimal in-memory DOM that satisfies the renderer's structural
+ * {@link ElementLike} / {@link DocumentLike} types, for unit tests only.
+ *
+ * It is NOT part of the published build (excluded in `tsconfig.build.json`); it
+ * lets the DOM renderer and the boot layer be exercised on Node with no DOM
+ * library and no `as` cast — the fake is *structurally* the same subset the
+ * browser's real `Document`/`Element` provide.
+ */
+import type { DocumentLike, ElementLike } from "./render.ts";
+export declare class FakeElement implements ElementLike {
+    #private;
+    className: string;
+    textContent: string | null;
+    readonly tagName: string;
+    readonly attributes: Map<string, string>;
+    readonly children: FakeElement[];
+    constructor(tagName: string);
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | undefined;
+    appendChild(child: ElementLike): ElementLike;
+    replaceChildren(): void;
+    addEventListener(type: string, handler: () => void): void;
+    /** Fire every listener registered for `type` (test driver for clicks). */
+    dispatch(type: string): void;
+    /** Depth-first walk of this element and its descendants. */
+    walk(): IterableIterator<FakeElement>;
+    /** Every descendant (and self) whose className contains `cls`. */
+    byClass(cls: string): FakeElement[];
+    /** Every descendant (and self) with `data-<key>` equal to `value` (any value if omitted). */
+    byData(key: string, value?: string): FakeElement[];
+    /** The concatenated text content of this subtree (own text then children). */
+    text(): string;
+}
+export declare class FakeDocument implements DocumentLike {
+    createElement(tagName: string): ElementLike;
+}

package/dist/cockpit/fake-dom.js

@@ -0,0 +1,73 @@
+export class FakeElement {
+    className = "";
+    textContent = null;
+    tagName;
+    attributes = new Map();
+    children = [];
+    #listeners = new Map();
+    constructor(tagName) {
+        this.tagName = tagName;
+    }
+    setAttribute(name, value) {
+        this.attributes.set(name, value);
+    }
+    getAttribute(name) {
+        return this.attributes.get(name);
+    }
+    appendChild(child) {
+        if (child instanceof FakeElement)
+            this.children.push(child);
+        return child;
+    }
+    replaceChildren() {
+        this.children.length = 0;
+    }
+    addEventListener(type, handler) {
+        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) {
+        for (const handler of this.#listeners.get(type) ?? [])
+            handler();
+    }
+    /** Depth-first walk of this element and its descendants. */
+    *walk() {
+        yield this;
+        for (const child of this.children)
+            yield* child.walk();
+    }
+    /** Every descendant (and self) whose className contains `cls`. */
+    byClass(cls) {
+        const out = [];
+        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, value) {
+        const attr = `data-${key}`;
+        const out = [];
+        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() {
+        let out = this.textContent ?? "";
+        for (const child of this.children)
+            out += child.text();
+        return out;
+    }
+}
+export class FakeDocument {
+    createElement(tagName) {
+        return new FakeElement(tagName);
+    }
+}

package/dist/cockpit/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @nanobpm/agentic-cockpit — the visibility page (the cockpit) for the Nano
+ * agentic protocol (ADR 0056, slice S8).
+ *
+ * The operator's cockpit over the one app-tier channel: a per-network
+ * demand×supply matrix, a red light per *missing agent type*, the diversity-SLO
+ * state (all from the S4 {@link cockpitView} projection of `@nanobpm/agentic-demand`),
+ * and drill-into-a-worker → a live terminal over the S5 relay
+ * ({@link TerminalSession} + {@link RelayChannelClient}) that **survives a cockpit
+ * reconnect** via resume-from-offset.
+ *
+ * The package is a framework-free, injection-based core: {@link bootCockpit}
+ * wires polling, rendering and the terminal from an injected {@link CockpitEnv},
+ * with no hard dependency on the DOM, a socket implementation, or xterm.js. Both
+ * shells under `page/` — the standalone one and the console App-View embed — call
+ * the SAME {@link bootCockpit} against the SAME {@link renderCockpit}, so the page
+ * renders identically whether embedded or standalone.
+ *
+ * The wire contract is `@nanobpm/agentic-protocol`; the report comes from
+ * `@nanobpm/agentic-demand`; the relay sub-protocol from `@nanobpm/agentic-relay`.
+ * Nothing here rides the Camunda-8 engine or its transport.
+ */
+export { cockpitView, type CockpitLight, type CockpitNetworkRow, type CockpitTokenRow, type CockpitView, type SloStatus, } from "./view.ts";
+export { TerminalSession, type RelayInbound, type RelayOutbound, type RelaySend, type TerminalSessionOptions, type TerminalSink, } from "./terminal-session.ts";
+export { RelayChannelClient, type RawSocket, type RelayChannelClientOptions, type Scheduler, type SocketFactory, } from "./relay-client.ts";
+export { renderCockpit, type CockpitDom, type DocumentLike, type ElementLike, type RenderOptions, } from "./render.ts";
+export { bootCockpit, type CockpitEnv, type CockpitHandle, type CreateTerminal, type TimerHandle, } from "./boot.ts";

package/dist/cockpit/index.js

@@ -0,0 +1,27 @@
+/**
+ * @nanobpm/agentic-cockpit — the visibility page (the cockpit) for the Nano
+ * agentic protocol (ADR 0056, slice S8).
+ *
+ * The operator's cockpit over the one app-tier channel: a per-network
+ * demand×supply matrix, a red light per *missing agent type*, the diversity-SLO
+ * state (all from the S4 {@link cockpitView} projection of `@nanobpm/agentic-demand`),
+ * and drill-into-a-worker → a live terminal over the S5 relay
+ * ({@link TerminalSession} + {@link RelayChannelClient}) that **survives a cockpit
+ * reconnect** via resume-from-offset.
+ *
+ * The package is a framework-free, injection-based core: {@link bootCockpit}
+ * wires polling, rendering and the terminal from an injected {@link CockpitEnv},
+ * with no hard dependency on the DOM, a socket implementation, or xterm.js. Both
+ * shells under `page/` — the standalone one and the console App-View embed — call
+ * the SAME {@link bootCockpit} against the SAME {@link renderCockpit}, so the page
+ * renders identically whether embedded or standalone.
+ *
+ * The wire contract is `@nanobpm/agentic-protocol`; the report comes from
+ * `@nanobpm/agentic-demand`; the relay sub-protocol from `@nanobpm/agentic-relay`.
+ * Nothing here rides the Camunda-8 engine or its transport.
+ */
+export { cockpitView, } from "./view.js";
+export { TerminalSession, } from "./terminal-session.js";
+export { RelayChannelClient, } from "./relay-client.js";
+export { renderCockpit, } from "./render.js";
+export { bootCockpit, } from "./boot.js";

package/dist/cockpit/relay-client.d.ts

@@ -0,0 +1,52 @@
+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;
+}
+/**
+ * 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 declare class RelayChannelClient {
+    #private;
+    constructor(options: RelayChannelClientOptions);
+    /** True once {@link close} has been called (no further reconnects). */
+    get isClosed(): boolean;
+    /** Open the first socket and wire its lifecycle. Idempotent while connected. */
+    open(): void;
+    /** Encode and send one outbound relay message on the control lane. */
+    sendRelay(message: RelayOutbound): void;
+    /** Close for good — no reconnect will follow. */
+    close(): void;
+}