agent-comms 9.0.8 → 9.0.10

package/src/bridges/user/web/dist/sw.js

@@ -1 +1 @@
-(function(){var e=`agent-comms-v1`,t=[{"revision":"41c6737126547228482ecc2b359801e6","url":"mesh-worker.js"},{"revision":"f1ee3afb8c9e8f0d7315fd93d6457316","url":"index.html"},{"revision":"3c68c960e2ae7cf0918c97b921c287da","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))}),self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t!==e).map(async e=>self.caches.delete(e)))))});var n=200,r=300;function i(e,t){return e.method===`GET`&&t.status>=n&&t.status<r}self.addEventListener(`fetch`,t=>{if(new URL(t.request.url).pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();
+(function(){var e=`agent-comms-v1`,t=[{"revision":"66fb8e407d25a3d34fd7df939ebd2e96","url":"mesh-worker.js"},{"revision":"f1ee3afb8c9e8f0d7315fd93d6457316","url":"index.html"},{"revision":"aef2de9b9f0ed47024e02762fc047436","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))}),self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t!==e).map(async e=>self.caches.delete(e)))))});var n=200,r=300;function i(e,t){return e.method===`GET`&&t.status>=n&&t.status<r}self.addEventListener(`fetch`,t=>{if(new URL(t.request.url).pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();

package/src/bridges/user/web/event-id.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape of an event id, shared by the publisher that issues ids and the contract that bounds what a client may send back, so neither can drift from the other.
+ */
+
+/** Bytes of randomness in a publisher's instance; the instance is their hex form. */
+export const INSTANCE_BYTES = 8;
+
+/** The separator between an id's instance and its sequence number. Hex never contains it. */
+export const ID_SEPARATOR = ".";
+
+/** Characters of an instance: two hex digits per byte. */
+const INSTANCE_LENGTH = INSTANCE_BYTES * 2;
+
+/** The longest id a publisher can issue: its instance, the separator and the digits of the largest sequence number a JavaScript number holds exactly. A longer string cannot be an id of any publisher. */
+export const MAX_EVENT_ID_LENGTH =
+  INSTANCE_LENGTH +
+  ID_SEPARATOR.length +
+  String(Number.MAX_SAFE_INTEGER).length;

package/src/bridges/user/web/event-publisher.ts

@@ -1,13 +1,18 @@
 /**
  * In-memory, resumable event publisher for the web UI's subscribeEvents stream.
  *
- * oRPC v2 beta (`\@orpc/server`, `\@orpc/client`, `\@orpc/contract` at 2.0.0-beta.35 -- confirmed against the actual published tarballs, not just docs) ships no MemoryPublisher/EventPublisher class. This is a hand-written equivalent built on the primitives that do exist: a plain async generator (satisfies AsyncIteratorObject on its own) and withEventMeta (from `\@standard-server/core`, re-exported by `\@orpc/server`) to tag each published event with a monotonic id oRPC's own RetryLinkPlugin already knows how to read back as lastEventId on reconnect.
+ * oRPC v2 beta (`\@orpc/server`, `\@orpc/client`, `\@orpc/contract` at 2.0.0-beta.35 -- confirmed against the actual published tarballs, not just docs) ships no MemoryPublisher/EventPublisher class. This is a hand-written equivalent built on the primitives that do exist: a plain async generator (satisfies AsyncIteratorObject on its own) and withEventMeta (from `\@standard-server/core`, re-exported by `\@orpc/server`) to tag each published event with an id oRPC's own RetryLinkPlugin already knows how to read back as lastEventId on reconnect. An id is `<instance>.<seq>`: the instance is drawn at random when the publisher starts, so an id from before a restart, or from another publisher, can never be mistaken for one of this publisher's events.
  *
  * One instance per WebServerHandle -- not a module-level singleton -- so multiple concurrent web server instances (multiple bridges each starting their own web UI) never share replay buffers.
  */
 
 import { withEventMeta } from "@orpc/server";
 import type { MeshEvent } from "./contract.js";
+import {
+  ID_SEPARATOR,
+  INSTANCE_BYTES,
+  MAX_EVENT_ID_LENGTH,
+} from "./event-id.js";
 
 /** A plain function call is opaque to TS's control-flow narrowing, unlike a direct `signal?.aborted` comparison -- narrowing that across an `await` (the abort can genuinely flip mid-wait) produces a false "these types have no overlap" error at the re-check below the await. */
 function isAborted(signal: AbortSignal | undefined): boolean {
@@ -17,12 +22,20 @@ function isAborted(signal: AbortSignal | undefined): boolean {
 export interface MeshEventPublisherOptions {
   /** How long a published event stays available for replay by a resuming subscriber. */
   retentionMs?: number;
+  /** The most events kept for replay. Defaults to {@link DEFAULT_MAX_BUFFERED_EVENTS}. */
+  maxBufferedEvents?: number;
 }
 
 const DEFAULT_RETENTION_MS = 60_000;
 
+/** The most events a publisher keeps for replay, whatever their age. An event can carry a whole mesh snapshot, so a burst of resynchronisations must not hold sixty seconds of them: past this a subscriber whose id fell off the end starts from a snapshot, as one whose id aged out does. */
+const DEFAULT_MAX_BUFFERED_EVENTS = 1_000;
+
+/** Radix of the hex form of the instance. */
+const HEX_RADIX = 16;
+
 interface BufferedEvent {
-  id: string;
+  seq: number;
   event: MeshEvent;
   publishedAt: number;
 }
@@ -30,23 +43,40 @@ interface BufferedEvent {
 export interface MeshEventSubscribeOptions {
   signal?: AbortSignal;
   lastEventId?: string;
+  /** Builds the snapshot a subscriber starts from when it has no usable id. The snapshot is built after the subscriber is listening, so no event published meanwhile is lost. */
+  snapshot: () => MeshEvent;
+}
+
+function drawInstance(): string {
+  return Array.from(
+    globalThis.crypto.getRandomValues(new Uint8Array(INSTANCE_BYTES)),
+    (byte) => byte.toString(HEX_RADIX).padStart(2, "0"),
+  ).join("");
 }
 
 export class MeshEventPublisher {
   private seq = 0;
+  private readonly instance = drawInstance();
   private readonly buffer: BufferedEvent[] = [];
   private readonly listeners = new Set<(event: MeshEvent) => void>();
   private readonly retentionMs: number;
+  private readonly maxBufferedEvents: number;
 
   constructor(options: Readonly<MeshEventPublisherOptions> = {}) {
     this.retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
+    this.maxBufferedEvents =
+      options.maxBufferedEvents ?? DEFAULT_MAX_BUFFERED_EVENTS;
   }
 
   publish(event: MeshEvent): void {
     this.prune();
-    const id = String(++this.seq);
-    const tagged = withEventMeta(event, { id });
-    this.buffer.push({ id, event: tagged, publishedAt: Date.now() });
+    const seq = ++this.seq;
+    const tagged = withEventMeta(event, {
+      id: `${this.instance}${ID_SEPARATOR}${String(seq)}`,
+    });
+    this.buffer.push({ seq, event: tagged, publishedAt: Date.now() });
+    // Sequence numbers stay contiguous, so dropping from the head leaves "older than the oldest retained" exact.
+    while (this.buffer.length > this.maxBufferedEvents) this.buffer.shift();
     for (const listener of this.listeners) listener(tagged);
   }
 
@@ -61,24 +91,34 @@ export class MeshEventPublisher {
   }
 
   /**
-   * Replays buffered events after `lastEventId` (or every buffered event, if a resuming subscriber's `lastEventId` has already aged out of the retention window), then yields new events as they're published until `signal` aborts.
+   * The events a subscriber holding `lastEventId` is missing, or undefined when they cannot be known: the id is not this publisher's, is malformed, or is older than the oldest retained event, so events between it and the retained ones are gone.
+   */
+  private missedSince(lastEventId: string): BufferedEvent[] | undefined {
+    // Refused before any split: no id of any publisher is this long.
+    if (lastEventId.length > MAX_EVENT_ID_LENGTH) return undefined;
+    const [instance, rawSeq, ...rest] = lastEventId.split(ID_SEPARATOR);
+    if (instance !== this.instance || rawSeq === undefined || rest.length > 0) {
+      return undefined;
+    }
+    if (!/^[0-9]+$/u.test(rawSeq)) return undefined;
+    const seq = Number(rawSeq);
+    if (seq > this.seq) return undefined;
+    const oldest = this.buffer[0];
+    // With nothing retained the only id that is not missing anything is the latest one.
+    if (oldest === undefined) return seq === this.seq ? [] : undefined;
+    if (seq < oldest.seq - 1) return undefined;
+    return this.buffer.filter((buffered) => buffered.seq > seq);
+  }
+
+  /**
+   * Starts a subscriber and yields to it until `signal` aborts. A subscriber with a usable `lastEventId` first gets exactly the events it missed. Any other subscriber, with no id or with one that cannot be resumed from (see {@link MeshEventPublisher.missedSince}), first gets `snapshot()`. Live events follow in both cases, and none published while the replay or snapshot is being delivered is lost.
    */
   async *subscribe(
-    options: Readonly<MeshEventSubscribeOptions> = {},
+    options: Readonly<MeshEventSubscribeOptions>,
   ): AsyncGenerator<MeshEvent, void, void> {
-    const { signal, lastEventId } = options;
+    const { signal, lastEventId, snapshot } = options;
     this.prune();
 
-    if (lastEventId !== undefined) {
-      const startIndex = this.buffer.findIndex((b) => b.id === lastEventId);
-      const replay =
-        startIndex === -1 ? this.buffer : this.buffer.slice(startIndex + 1);
-      for (const buffered of replay) {
-        if (isAborted(signal)) return;
-        yield buffered.event;
-      }
-    }
-
     const queue: MeshEvent[] = [];
     let wake: (() => void) | undefined;
     const listener = (event: MeshEvent): void => {
@@ -88,6 +128,16 @@ export class MeshEventPublisher {
     this.listeners.add(listener);
 
     try {
+      const missed =
+        lastEventId === undefined ? undefined : this.missedSince(lastEventId);
+      if (missed === undefined) {
+        yield snapshot();
+      } else {
+        for (const buffered of missed) {
+          if (isAborted(signal)) return;
+          yield buffered.event;
+        }
+      }
       for (;;) {
         if (isAborted(signal)) return;
         if (queue.length === 0) {

package/src/bridges/user/web/router.ts

@@ -131,16 +131,14 @@ export const meshRouter = {
     // lastEventId is set two ways: oRPC's own RetryLinkPlugin threads it automatically on a mid-stream reconnect (the protocol-level `lastEventId` above); a tab that reconnects from cold (a fresh subscribeEvents call, e.g. after being closed and reopened) has to pass it explicitly as input instead, since there's no in-flight call for the protocol layer to resume.
     const resumeFrom = lastEventId ?? input.lastEventId;
 
-    if (resumeFrom === undefined) {
-      yield {
-        kind: "state_sync" as const,
-        state: toBrowserState(context.controller.meshStore.serialise()),
-      };
-    }
-
+    // The publisher decides between replaying what the id's holder missed and starting from this snapshot: an id from before a restart, or older than the retained events, cannot be resumed from.
     yield* context.publisher.subscribe({
       ...(signal ? { signal } : {}),
       ...(resumeFrom !== undefined ? { lastEventId: resumeFrom } : {}),
+      snapshot: () => ({
+        kind: "state_sync" as const,
+        state: toBrowserState(context.controller.meshStore.serialise()),
+      }),
     });
   }),
 };

package/src/core/machine-list-groups.ts

@@ -4,6 +4,7 @@
 
 import type { AgentIdentity } from "./types.js";
 import type { Namer } from "./naming.js";
+import { compareCodeUnits } from "./ordering.js";
 
 /** One run of listed agents and the heading above it; no heading when nothing is grouped at all. */
 export interface AgentGroup {
@@ -40,7 +41,7 @@ export function groupAgentsByMachine(
     .sort(([a], [b]) => {
       if (a === ownMachine) return -1;
       if (b === ownMachine) return 1;
-      return a.localeCompare(b);
+      return compareCodeUnits(a, b);
     })
     .map(([machine, members]) => ({
       heading: `Machine ${namer(machine)}${machine === ownMachine ? " (this machine)" : ""}:`,

package/src/core/ordering.ts

@@ -0,0 +1,27 @@
+/**
+ * Orderings that depend on neither a locale nor a runtime's collation data, so every implementation sorts the same names the same way. Strings compare by UTF-16 code unit, the order of JavaScript's `<`.
+ */
+
+/**
+ * Compares two strings by UTF-16 code unit.
+ * @returns A negative number when `a` sorts first, a positive one when `b` does, 0 when they are equal.
+ */
+export function compareCodeUnits(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/** Folds the ASCII letters A to Z to lower case and leaves every other character as it is, so no Unicode case table is involved. */
+function foldAsciiCase(name: string): string {
+  return name.replace(/[A-Z]/gu, (letter) => letter.toLowerCase());
+}
+
+/**
+ * Compares two names a person reads: ASCII letters are folded to lower case before comparing by UTF-16 code unit, and names that fold equal are ordered by the names as written, so the order is total and stable.
+ * @returns A negative number when `a` sorts first, a positive one when `b` does, 0 when they are equal.
+ */
+export function compareDisplayNames(a: string, b: string): number {
+  const folded = compareCodeUnits(foldAsciiCase(a), foldAsciiCase(b));
+  return folded === 0 ? compareCodeUnits(a, b) : folded;
+}

package/src/core/relay-selection.ts

@@ -7,6 +7,7 @@
  */
 
 import { BlockList, isIPv4, isIPv6 } from "node:net";
+import { compareCodeUnits } from "./ordering.js";
 
 /** A relay offer this store has heard, with what it knows about the device making it. */
 export interface RelayOffer {
@@ -104,7 +105,7 @@ export function selectRelay(
 ): SelectedRelay {
   const eligible = input.offers
     .filter((offer) => offer.deviceHex !== input.ownDeviceHex)
-    .toSorted((a, b) => a.deviceHex.localeCompare(b.deviceHex));
+    .toSorted((a, b) => compareCodeUnits(a.deviceHex, b.deviceHex));
   for (const tier of OFFER_TIERS) {
     for (const offer of eligible) {
       const admitted =

package/src/core/store.ts

@@ -23,6 +23,7 @@ import {
   RoomMessageSchema,
   RoomSchema,
 } from "./types.js";
+import { compareCodeUnits } from "./ordering.js";
 import type {
   AgentIdentity,
   DeliveryEvent,
@@ -584,7 +585,8 @@ export class FileStore implements CommsStore {
           messages.push(msg);
         }
       }
-      messages.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+      // Every timestamp this store writes is `new Date().toISOString()`: fixed width, UTC, millisecond precision, so UTF-16 order is chronological order (held by a test at the producer).
+      messages.sort((a, b) => compareCodeUnits(a.timestamp, b.timestamp));
       return messages;
     } catch {
       return [];
@@ -653,6 +655,7 @@ export class FileStore implements CommsStore {
         events.push(event);
         await fs.unlink(path.join(dir, file));
       }
+      // Same fixed timestamp form as readRoomMessages sorts on.
       events.sort((a, b) => {
         const ta =
           a.type === "room_message" || a.type === "dm"
@@ -662,7 +665,7 @@ export class FileStore implements CommsStore {
           b.type === "room_message" || b.type === "dm"
             ? b.message.timestamp
             : "";
-        return ta.localeCompare(tb);
+        return compareCodeUnits(ta, tb);
       });
       return events;
     } catch {