@nanobpm/agentic 0.1.0

package/src/cockpit/terminal-session.test.ts

@@ -0,0 +1,252 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import type { RelayPayload } from "../protocol/index.ts";
+
+import { type RelayOutbound, TerminalSession } from "./terminal-session.ts";
+
+interface Harness {
+  readonly session: TerminalSession;
+  readonly sent: RelayOutbound[];
+  readonly writes: string[];
+  data(offset: number, chunk: string, stream?: string): RelayPayload;
+}
+
+function harness(options: { from?: number; credit?: number; stream?: string } = {}): Harness {
+  const stream = options.stream ?? "worker-1";
+  const sent: RelayOutbound[] = [];
+  const writes: string[] = [];
+  const session = new TerminalSession({
+    stream,
+    sink: { write: (chunk) => writes.push(chunk) },
+    send: (message) => sent.push(message),
+    from: options.from,
+    credit: options.credit,
+  });
+  return {
+    session,
+    sent,
+    writes,
+    data: (offset, chunk, s = stream) => ({ stream: s, offset, chunk }),
+  };
+}
+
+test("attach subscribes from the initial offset with the configured credit", () => {
+  const h = harness({ from: 0, credit: 256 });
+  h.session.attach();
+  assert.deepEqual(h.sent, [{ op: "subscribe", stream: "worker-1", from: 0, credit: 256 }]);
+});
+
+test("data chunks are written in order and advance the resume offset", () => {
+  const h = harness();
+  h.session.attach();
+  h.session.handle(h.data(0, "hello "));
+  h.session.handle(h.data(1, "world"));
+  assert.deepEqual(h.writes, ["hello ", "world"]);
+  assert.equal(h.session.nextOffset, 2);
+});
+
+test("a chunk at Number.MAX_SAFE_INTEGER fails fast instead of overflowing nextOffset", () => {
+  // Advancing nextOffset past MAX_SAFE_INTEGER would produce an unsafe integer
+  // that loses precision on any JSON round-trip when echoed back in subscribe.from,
+  // silently corrupting resume semantics. Guard the increment so it throws instead.
+  const h = harness();
+  h.session.attach();
+  assert.throws(
+    () => h.session.handle(h.data(Number.MAX_SAFE_INTEGER, "x")),
+    RangeError,
+    "a boundary chunk must reject rather than corrupt the resume offset",
+  );
+  // The apply must be atomic: rejecting the boundary chunk must NOT write it to
+  // the sink. A write-then-throw would leave output applied but nextOffset not
+  // advanced, so the chunk re-delivers and duplicates on reconnect.
+  assert.deepEqual(h.writes, [], "a rejected boundary chunk must not be written");
+  assert.equal(h.session.nextOffset, 0);
+});
+
+test("a reconnect resumes from nextOffset — no lost and no duplicated output", () => {
+  const h = harness();
+  h.session.attach(); // subscribe from 0
+  h.session.handle(h.data(0, "a"));
+  h.session.handle(h.data(1, "b"));
+  assert.equal(h.session.nextOffset, 2);
+
+  // Socket drops and the client reconnects → the session re-attaches.
+  h.session.attach();
+  assert.deepEqual(h.sent[1], { op: "subscribe", stream: "worker-1", from: 2, credit: 1024 });
+
+  // The hub replays from offset 2 (the retained tail). The boundary is not
+  // re-sent because we resumed *past* it; new chunks flow through.
+  h.session.handle(h.data(2, "c"));
+  h.session.handle(h.data(3, "d"));
+  assert.deepEqual(h.writes, ["a", "b", "c", "d"]);
+  assert.equal(h.session.nextOffset, 4);
+});
+
+test("an already-applied replayed chunk (offset < nextOffset) is dropped idempotently", () => {
+  const h = harness();
+  h.session.attach();
+  h.session.handle(h.data(0, "a"));
+  h.session.handle(h.data(1, "b"));
+
+  // Reconnect and the hub re-delivers the already-seen tail from a lower offset
+  // (e.g. a subscribe raced with in-flight data): duplicates must not reappear.
+  h.session.attach();
+  h.session.handle(h.data(0, "a"));
+  h.session.handle(h.data(1, "b"));
+  h.session.handle(h.data(2, "c"));
+  assert.deepEqual(h.writes, ["a", "b", "c"]);
+  assert.equal(h.session.nextOffset, 3);
+});
+
+test("data for another stream is ignored", () => {
+  const h = harness();
+  h.session.attach();
+  h.session.handle(h.data(0, "mine"));
+  h.session.handle(h.data(1, "theirs", "worker-2"));
+  assert.deepEqual(h.writes, ["mine"]);
+  assert.equal(h.session.nextOffset, 1);
+});
+
+test("a subscribed ack reporting a gap fires onGap and records it", () => {
+  let gaps = 0;
+  const session = new TerminalSession({
+    stream: "worker-1",
+    sink: { write: () => {} },
+    send: () => {},
+    onGap: () => {
+      gaps += 1;
+    },
+  });
+  session.handle({ op: "subscribed", stream: "worker-1", gap: true, nextOffset: 5 });
+  assert.equal(gaps, 1);
+  assert.equal(session.gap, true);
+});
+
+test("a subscribed ack with no gap does not fire onGap", () => {
+  let gaps = 0;
+  const session = new TerminalSession({
+    stream: "worker-1",
+    sink: { write: () => {} },
+    send: () => {},
+    onGap: () => {
+      gaps += 1;
+    },
+  });
+  session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: 0 });
+  assert.equal(gaps, 0);
+  assert.equal(session.gap, false);
+});
+
+test("a later no-gap ack clears a gap recorded by an earlier ack", () => {
+  const session = new TerminalSession({
+    stream: "worker-1",
+    sink: { write: () => {} },
+    send: () => {},
+  });
+  session.handle({ op: "subscribed", stream: "worker-1", gap: true, nextOffset: 5 });
+  assert.equal(session.gap, true);
+  session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: 5 });
+  assert.equal(session.gap, false);
+});
+
+test("a subscribed ack with a negative/unsafe nextOffset is rejected and does not corrupt the resume point", () => {
+  // nextOffset is echoed into subscribe.from on the next attach, so a
+  // negative/NaN/unsafe value from a buggy or malicious transport that bypasses
+  // RelayChannelClient's validation must fail fast rather than corrupt resume.
+  const h = harness({ from: 4 });
+  h.session.attach();
+  assert.throws(
+    () => h.session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: -1 }),
+    RangeError,
+    "a negative ack nextOffset must reject",
+  );
+  assert.throws(
+    () =>
+      h.session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: Number.MAX_SAFE_INTEGER + 1 }),
+    RangeError,
+    "an unsafe ack nextOffset must reject",
+  );
+  // A rejected ack must leave the resume point untouched.
+  assert.equal(h.session.nextOffset, 4);
+});
+
+test("an ack whose head is below our resume point clamps nextOffset down so fresh chunks are not dropped", () => {
+  // (we are ahead of the stream). Without a clamp, offsets 3,4,… stay below our
+  // resume point and every fresh chunk is dropped as a stale replay — output lost.
+  const h = harness({ from: 10 });
+  h.session.attach();
+  h.session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: 3 });
+  assert.equal(h.session.nextOffset, 3);
+  // Chunks from the restarted hub now apply instead of being dropped.
+  h.session.handle(h.data(3, "fresh"));
+  h.session.handle(h.data(4, "output"));
+  assert.deepEqual(h.writes, ["fresh", "output"]);
+  assert.equal(h.session.nextOffset, 5);
+});
+
+test("an ack whose head is at or above our resume point never advances nextOffset (no skipped chunks)", () => {
+  // The normal case: the hub has more data than we have applied. The ack must
+  // NOT bump nextOffset up to the head, or the un-applied tail would be skipped.
+  const h = harness({ from: 2 });
+  h.session.attach();
+  h.session.handle({ op: "subscribed", stream: "worker-1", gap: false, nextOffset: 9 });
+  assert.equal(h.session.nextOffset, 2);
+  h.session.handle(h.data(2, "tail"));
+  assert.deepEqual(h.writes, ["tail"]);
+  assert.equal(h.session.nextOffset, 3);
+});
+
+test("resuming from a non-zero offset subscribes there and drops earlier replays", () => {
+  const h = harness({ from: 10 });
+  h.session.attach();
+  assert.deepEqual(h.sent[0], { op: "subscribe", stream: "worker-1", from: 10, credit: 1024 });
+  h.session.handle(h.data(8, "old")); // below resume point
+  h.session.handle(h.data(10, "new"));
+  assert.deepEqual(h.writes, ["new"]);
+  assert.equal(h.session.nextOffset, 11);
+});
+
+test("grant sends a credit message", () => {
+  const h = harness();
+  h.session.grant(512);
+  assert.deepEqual(h.sent, [{ op: "credit", credit: 512 }]);
+});
+
+test("an invalid from offset is rejected at construction", () => {
+  assert.throws(
+    () => new TerminalSession({ stream: "s", sink: { write: () => {} }, send: () => {}, from: -1 }),
+    RangeError,
+  );
+});
+
+test("an unsafe-integer from offset is rejected at construction", () => {
+  assert.throws(
+    () =>
+      new TerminalSession({
+        stream: "s",
+        sink: { write: () => {} },
+        send: () => {},
+        from: Number.MAX_SAFE_INTEGER + 1,
+      }),
+    RangeError,
+  );
+});
+
+test("a non-positive or unsafe credit is rejected at construction", () => {
+  for (const credit of [0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) {
+    assert.throws(
+      () => new TerminalSession({ stream: "s", sink: { write: () => {} }, send: () => {}, credit }),
+      RangeError,
+      `credit ${credit} should be rejected`,
+    );
+  }
+});
+
+test("grant rejects a non-positive or unsafe credit", () => {
+  const h = harness();
+  for (const credit of [0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) {
+    assert.throws(() => h.session.grant(credit), RangeError, `grant(${credit}) should be rejected`);
+  }
+});
+

package/src/cockpit/terminal-session.ts

@@ -0,0 +1,194 @@
+/**
+ * The worker terminal session — S8's drill-into-a-worker live terminal.
+ *
+ * A consumer of the S5 relay sub-protocol that **survives a cockpit reconnect**
+ * via resume-from-offset. It is deliberately timer-free and transport-free: it
+ * emits the relay messages to send ({@link RelaySend}) and consumes the relay
+ * messages received ({@link TerminalSession.handle}), tracking exactly one piece
+ * of durable state — `nextOffset`, the offset to resume from. On any (re)attach
+ * it re-subscribes from `nextOffset`, and it drops any replayed chunk it has
+ * already applied, so a reconnect neither loses nor double-writes output (within
+ * the relay ring's retained window). If the hub's `subscribed` ack reports a
+ * `nextOffset` (stream head) *below* our resume point — a hub restart/reset left
+ * us ahead of the stream — it clamps `nextOffset` back down so fresh chunks are
+ * not dropped as stale.
+ *
+ * The S5 relay wire (see `@nanobpm/agentic-relay`):
+ *  - outbound `{ op: "subscribe", stream, from, credit }` — (re)attach and resume,
+ *  - outbound `{ op: "credit", credit }`                  — grant more bulk credit,
+ *  - inbound  `{ op: "subscribed", stream, gap, nextOffset }` — the resume ack
+ *             (`gap: boolean` — the S5 wire flags whether chunks aged out),
+ *  - inbound  {@link RelayPayload} `{ stream, offset, chunk }` — a data chunk.
+ */
+import type { RelayPayload } from "../protocol/index.ts";
+import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.ts";
+
+/** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
+export interface TerminalSink {
+  /** Append a chunk of terminal output. */
+  write(chunk: string): void;
+  /** Tear down the underlying terminal widget and its listeners, if any. */
+  dispose?(): void;
+}
+
+/** An outbound relay message the session asks its transport to send. */
+export type RelayOutbound =
+  | { readonly op: "subscribe"; readonly stream: string; readonly from: number; readonly credit: number }
+  | { readonly op: "credit"; readonly credit: number };
+
+/** An inbound relay message the session consumes (a data chunk or a resume ack). */
+export type RelayInbound =
+  | RelayPayload
+  | { readonly op: "subscribed"; readonly stream: string; readonly gap: boolean; readonly nextOffset: number };
+
+/** Sends one outbound relay message over the channel. */
+export type RelaySend = (message: RelayOutbound) => void;
+
+export interface TerminalSessionOptions {
+  /** The relay stream id (one worker's terminal). */
+  readonly stream: string;
+  /** Where decoded output is written. */
+  readonly sink: TerminalSink;
+  /** Emits outbound relay messages. */
+  readonly send: RelaySend;
+  /** Bulk credit requested on each (re)subscribe. Default 1024. */
+  readonly credit?: number;
+  /** Offset to resume from on first attach. Default 0 (from the start). */
+  readonly from?: number;
+  /** Notified when the resume ack reports a gap (chunks aged out of the ring). */
+  readonly onGap?: () => void;
+}
+
+const DEFAULT_CREDIT = 1024;
+
+function isRelayData(message: RelayInbound): message is RelayPayload {
+  return !("op" in message);
+}
+
+/**
+ * A resume-from-offset consumer of one relay stream. Construct once per worker
+ * drill-in; call {@link attach} on every (re)connection and feed every inbound
+ * relay message to {@link handle}.
+ */
+export class TerminalSession {
+  readonly #stream: string;
+  readonly #sink: TerminalSink;
+  readonly #send: RelaySend;
+  readonly #credit: number;
+  readonly #onGap: TerminalSessionOptions["onGap"];
+  /** The next offset we still need — everything below it has been applied. */
+  #nextOffset: number;
+  /** Whether the most recent resume ack reported a gap (retained window overrun). */
+  #gap = false;
+
+  constructor(options: TerminalSessionOptions) {
+    this.#stream = options.stream;
+    this.#sink = options.sink;
+    this.#send = options.send;
+    this.#credit = options.credit ?? DEFAULT_CREDIT;
+    if (!isPosInt(this.#credit)) {
+      throw new RangeError(`TerminalSession.credit must be a positive safe integer, got ${this.#credit}`);
+    }
+    this.#onGap = options.onGap;
+    const from = options.from ?? 0;
+    if (!isNonNegInt(from)) {
+      throw new RangeError(`TerminalSession.from must be a non-negative safe integer, got ${from}`);
+    }
+    this.#nextOffset = from;
+  }
+
+  /** The stream id this session follows. */
+  get stream(): string {
+    return this.#stream;
+  }
+
+  /** The offset the session will resume from on the next {@link attach}. */
+  get nextOffset(): number {
+    return this.#nextOffset;
+  }
+
+  /** Whether the most recent resume ack reported a gap (false when none was lost). */
+  get gap(): boolean {
+    return this.#gap;
+  }
+
+  /**
+   * (Re)subscribe to the stream, resuming from {@link nextOffset}. Call this on
+   * first connect AND after every reconnect — because it always resumes from the
+   * offset just past the last applied chunk, a reconnect replays only the
+   * un-applied tail (no loss) and re-delivered chunks below `nextOffset` are
+   * dropped by {@link handle} (no duplication).
+   */
+  attach(): void {
+    this.#send({ op: "subscribe", stream: this.#stream, from: this.#nextOffset, credit: this.#credit });
+  }
+
+  /** Grant additional bulk credit (backpressure release) mid-stream. */
+  grant(credit: number): void {
+    if (!isPosInt(credit)) {
+      throw new RangeError(`TerminalSession.grant credit must be a positive safe integer, got ${credit}`);
+    }
+    this.#send({ op: "credit", credit });
+  }
+
+  /**
+   * Process one inbound relay message. A data chunk at or beyond `nextOffset` is
+   * written and advances the resume point; a chunk below it (a duplicate replay
+   * after a reconnect) is dropped. A resume ack records any gap and clamps the
+   * resume point down to the hub's head when we are ahead of it.
+   */
+  handle(message: RelayInbound): void {
+    if (isRelayData(message)) {
+      this.#onData(message);
+      return;
+    }
+    if (message.op === "subscribed" && message.stream === this.#stream) {
+      this.#onSubscribed(message.gap, message.nextOffset);
+    }
+  }
+
+  #onData(data: RelayPayload): void {
+    if (data.stream !== this.#stream) return;
+    // Idempotent apply: a reconnect resubscribes from nextOffset, so the hub may
+    // re-deliver the boundary chunk; anything we have already applied is dropped.
+    if (data.offset < this.#nextOffset) return;
+    // Compute the next resume point BEFORE writing so the apply is atomic: a
+    // chunk at Number.MAX_SAFE_INTEGER makes addSafeInt throw, and it must throw
+    // before we touch the sink — otherwise the chunk is written but #nextOffset
+    // is not advanced, leaving a partially-applied state that re-delivers (and
+    // so duplicates) the chunk on reconnect. Advancing via addSafeInt also fails
+    // fast rather than overflowing into an unsafe nextOffset — that value would
+    // later be echoed in subscribe.from and lose precision on any JSON
+    // round-trip, silently corrupting resume semantics.
+    const nextOffset = addSafeInt(data.offset, 1, "nextOffset");
+    this.#sink.write(data.chunk);
+    this.#nextOffset = nextOffset;
+  }
+
+  #onSubscribed(gap: boolean, nextOffset: number): void {
+    // Validate the ack's resume point exactly as the constructor validates
+    // `from`: `nextOffset` is echoed back into subscribe.from on the next
+    // attach, so a negative/NaN/unsafe value (from a buggy or malicious
+    // transport that bypasses RelayChannelClient's validation) would corrupt
+    // resume semantics or lose precision on a JSON round-trip. Fail fast.
+    if (!isNonNegInt(nextOffset)) {
+      throw new RangeError(
+        `TerminalSession.subscribed nextOffset must be a non-negative safe integer, got ${nextOffset}`,
+      );
+    }
+    // Clamp our resume point down to the hub's current head when we are ahead of
+    // it. Without this, a hub restart/reset (or a `from` seeded past the head)
+    // leaves #nextOffset above every offset the hub will now emit, so #onData
+    // silently drops all fresh chunks until the stream catches back up — losing
+    // terminal output, possibly indefinitely. Only clamp DOWN: a head at or above
+    // #nextOffset is the normal case and must not skip un-applied chunks.
+    if (nextOffset < this.#nextOffset) {
+      this.#nextOffset = nextOffset;
+    }
+    // Record the gap on every ack so a later no-gap resume clears a prior gap.
+    this.#gap = gap;
+    if (gap) {
+      this.#onGap?.();
+    }
+  }
+}

package/src/cockpit/view.test.ts

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import type { DemandSupplyReport } from "../demand/index.ts";
+import type { DiversityReport } from "../vocab/index.ts";
+
+import { cockpitView } from "./view.ts";
+
+const greenDiversity: DiversityReport = { status: "green", roles: [] };
+
+const amberDiversity: DiversityReport = {
+  status: "amber",
+  roles: [
+    {
+      token: "planning.plan",
+      seatsDistinctFamily: false,
+      assignments: [
+        { seat: "red", family: "acme", instance: "a" },
+        { seat: "blue", family: "acme", instance: "b" },
+      ],
+      collidingFamilies: ["acme"],
+      status: "amber",
+    },
+  ],
+};
+
+function report(overrides: Partial<DemandSupplyReport> = {}): DemandSupplyReport {
+  return {
+    networks: [],
+    missing: [],
+    diversity: greenDiversity,
+    status: "green",
+    nonAgentic: [],
+    ...overrides,
+  };
+}
+
+test("a fully-served, green report yields a green view with no missing lights", () => {
+  const view = cockpitView(
+    report({
+      networks: [
+        {
+          network: "ci",
+          tokens: [{ token: "ci.build", supply: 2, instances: ["a", "b"], satisfied: true }],
+          missing: [],
+        },
+      ],
+    }),
+  );
+
+  assert.equal(view.status, "green");
+  assert.equal(view.missing.length, 0);
+  assert.equal(view.missingLights.length, 0);
+  assert.equal(view.networks[0]?.status, "green");
+  assert.equal(view.networks[0]?.tokens[0]?.status, "green");
+  assert.equal(view.diversityLight.status, "green");
+});
+
+test("a missing agent type lights the token, the row and the report RED", () => {
+  const view = cockpitView(
+    report({
+      status: "red",
+      missing: ["planning.plan#blue"],
+      networks: [
+        {
+          network: "planning",
+          tokens: [
+            { token: "planning.plan#blue", supply: 0, instances: [], satisfied: false },
+            { token: "planning.plan#red", supply: 1, instances: ["a"], satisfied: true },
+          ],
+          missing: ["planning.plan#blue"],
+        },
+      ],
+    }),
+  );
+
+  assert.equal(view.status, "red");
+  assert.equal(view.networks[0]?.status, "red");
+  const [missingTok, servedTok] = view.networks[0]?.tokens ?? [];
+  assert.equal(missingTok?.status, "red");
+  assert.equal(servedTok?.status, "green");
+
+  assert.equal(view.missingLights.length, 1);
+  assert.equal(view.missingLights[0]?.id, "missing:planning.plan#blue");
+  assert.equal(view.missingLights[0]?.label, "planning.plan#blue");
+  assert.equal(view.missingLights[0]?.status, "red");
+});
+
+test("the diversity SLO is surfaced as a light with the colliding family in the detail", () => {
+  const view = cockpitView(report({ status: "amber", diversity: amberDiversity }));
+
+  assert.equal(view.status, "amber");
+  assert.equal(view.diversity, amberDiversity);
+  assert.equal(view.diversityLight.status, "amber");
+  assert.match(view.diversityLight.detail ?? "", /planning\.plan/);
+  assert.match(view.diversityLight.detail ?? "", /acme/);
+});
+
+test("non-agentic task types pass through unchanged for operator visibility", () => {
+  const view = cockpitView(report({ nonAgentic: ["send-email", "resize-image"] }));
+  assert.deepEqual(view.nonAgentic, ["send-email", "resize-image"]);
+});
+
+test("the derivation is pure — the same report yields a deep-equal view", () => {
+  const input = report({
+    status: "red",
+    missing: ["qa.review#blue"],
+    networks: [
+      {
+        network: "qa",
+        tokens: [{ token: "qa.review#blue", supply: 0, instances: [], satisfied: false }],
+        missing: ["qa.review#blue"],
+      },
+    ],
+  });
+  assert.deepEqual(cockpitView(input), cockpitView(input));
+});