agent-comms 8.15.8 → 8.15.10

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

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ *
+ * 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";
+
+/** 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 {
+  return signal?.aborted === true;
+}
+
+export interface MeshEventPublisherOptions {
+  /** How long a published event stays available for replay by a resuming subscriber. */
+  retentionMs?: number;
+}
+
+const DEFAULT_RETENTION_MS = 60_000;
+
+interface BufferedEvent {
+  id: string;
+  event: MeshEvent;
+  publishedAt: number;
+}
+
+export interface MeshEventSubscribeOptions {
+  signal?: AbortSignal;
+  lastEventId?: string;
+}
+
+export class MeshEventPublisher {
+  private seq = 0;
+  private readonly buffer: BufferedEvent[] = [];
+  private readonly listeners = new Set<(event: MeshEvent) => void>();
+  private readonly retentionMs: number;
+
+  constructor(options: Readonly<MeshEventPublisherOptions> = {}) {
+    this.retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
+  }
+
+  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() });
+    for (const listener of this.listeners) listener(tagged);
+  }
+
+  private prune(): void {
+    const cutoff = Date.now() - this.retentionMs;
+    while (
+      this.buffer.length > 0 &&
+      (this.buffer[0]?.publishedAt ?? Infinity) < cutoff
+    ) {
+      this.buffer.shift();
+    }
+  }
+
+  /**
+   * 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.
+   */
+  async *subscribe(
+    options: Readonly<MeshEventSubscribeOptions> = {},
+  ): AsyncGenerator<MeshEvent, void, void> {
+    const { signal, lastEventId } = 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 => {
+      queue.push(event);
+      wake?.();
+    };
+    this.listeners.add(listener);
+
+    try {
+      for (;;) {
+        if (isAborted(signal)) return;
+        if (queue.length === 0) {
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+            signal?.addEventListener(
+              "abort",
+              () => {
+                resolve();
+              },
+              { once: true },
+            );
+          });
+          wake = undefined;
+          if (isAborted(signal)) return;
+        }
+        const next = queue.shift();
+        if (next !== undefined) yield next;
+      }
+    } finally {
+      this.listeners.delete(listener);
+    }
+  }
+}

package/src/bridges/user/web/port-discovery.ts

@@ -0,0 +1,49 @@
+/**
+ * Port discovery — walk up from a base port to find a free one.
+ *
+ * Extracted from server.ts so the logic can be unit-tested without
+ * loading the full server module (which reads built assets at import time).
+ */
+
+import * as http from "node:http";
+
+const WEB_HOST = "127.0.0.1";
+
+/** Maximum number of ports to try when searching for a free one. */
+export const DEFAULT_MAX_ATTEMPTS = 10;
+
+/**
+ * Try binding sequentially from `base`.
+ * Returns the first port that succeeds, or undefined if all are taken.
+ */
+export async function findFreePort(
+  base: number,
+  maxAttempts: number = DEFAULT_MAX_ATTEMPTS,
+): Promise<number | undefined> {
+  return new Promise((resolve) => {
+    let attempts = 0;
+
+    function tryPort(port: number): void {
+      if (attempts >= maxAttempts) {
+        resolve(undefined);
+        return;
+      }
+      attempts++;
+
+      const probe = http.createServer();
+      probe.on("error", () => {
+        probe.close();
+        tryPort(port + 1);
+      });
+      probe.listen(port, WEB_HOST, () => {
+        const addr = probe.address();
+        const actualPort = typeof addr === "object" && addr ? addr.port : port;
+        probe.close(() => {
+          resolve(actualPort);
+        });
+      });
+    }
+
+    tryPort(base);
+  });
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Plain read functions -- one per structured one-shot read (agent-comms#206), extracted so both the REST handlers in server.ts and the new oRPC procedures in router.ts call the same implementation instead of two copies drifting apart, the same de-duplication actions.ts already established for mutations.
+ *
+ * Deliberately excludes agents/rooms: those are already fully covered by subscribeEvents' state_sync/state_patch stream (router.ts), so there is no REST-vs-oRPC pair to de-duplicate for them.
+ */
+
+import type { RoomMessage } from "../../../core/types.js";
+import type { ChatController } from "../controller.js";
+import type { DisplayNameParts } from "../../../core/display-name.js";
+import type { MeshGraph, MeshTraceResult } from "./contract.js";
+
+export async function getRoomMessagesRead(
+  controller: ChatController,
+  input: Readonly<{ room: string; since?: string | undefined }>,
+): Promise<RoomMessage[]> {
+  return controller.getRoomMessages(input.room, input.since);
+}
+
+export function getMeshGraphRead(controller: ChatController): MeshGraph {
+  return controller.meshStore.meshGraph();
+}
+
+/** Every id this bridge's viewer has a name for (a petname or a known self name), for the dashboard to label ids by the shared display convention (agent-comms#345). */
+export async function getDisplayNamesRead(
+  controller: ChatController,
+): Promise<DisplayNameParts[]> {
+  return controller.meshStore.naming.nameParts(controller.agentId);
+}
+
+export async function getMeshTraceRead(
+  controller: ChatController,
+  input: Readonly<{ target: string; timeoutMs?: number | undefined }>,
+): Promise<MeshTraceResult> {
+  return controller.meshStore.meshTrace(input.target, input.timeoutMs);
+}

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

@@ -0,0 +1,158 @@
+/**
+ * oRPC router -- implements meshContract against a real ChatController.
+ *
+ * Every mutating procedure is a one-line passthrough to the plain action functions in actions.ts, the same functions the legacy REST /api/action dispatcher calls, so both paths share one implementation. subscribeEvents is the one genuinely new procedure: it unifies the old chat socket's delivery frames and the old mesh socket's state_sync/state_update methods into a single resumable stream, backed by a per-handle MeshEventPublisher.
+ */
+
+import { implement } from "@orpc/server";
+import type { PushManager } from "../../../core/push-manager.js";
+import type { ChatController } from "../controller.js";
+import {
+  createRoomAction,
+  declineInviteAction,
+  destroyRoomAction,
+  dmAction,
+  inviteAction,
+  joinRoomAction,
+  kickAction,
+  leaveRoomAction,
+  listAgentsAction,
+  listRoomsAction,
+  pushSubscribeAction,
+  pushUnsubscribeAction,
+  readRoomAction,
+  renameAgentAction,
+  sendAction,
+} from "./actions.js";
+import { meshContract } from "./contract.js";
+import type { SerialisedState } from "./contract.js";
+import type { MeshEventPublisher } from "./event-publisher.js";
+import {
+  getMeshGraphRead,
+  getDisplayNamesRead,
+  getMeshTraceRead,
+  getRoomMessagesRead,
+} from "./reads.js";
+
+export interface MeshRouterContext {
+  controller: ChatController;
+  publisher: MeshEventPublisher;
+  pushManager: PushManager | undefined;
+}
+
+/** Drops deliveryQueues -- mesh-internal replay state for offline agents, not something a browser tab needs to see -- from a MeshStore snapshot before it goes out as a state_sync event. */
+function toBrowserState(state: {
+  agents: SerialisedState["agents"];
+  rooms: SerialisedState["rooms"];
+  messages: SerialisedState["messages"];
+  dms: SerialisedState["dms"];
+}): SerialisedState {
+  return {
+    agents: state.agents,
+    rooms: state.rooms,
+    messages: state.messages,
+    dms: state.dms,
+  };
+}
+
+const impl = implement(meshContract).$context<MeshRouterContext>();
+
+export const meshRouter = {
+  send: impl.send.handler(async ({ context, input }) =>
+    sendAction(context.controller, input),
+  ),
+
+  dm: impl.dm.handler(async ({ context, input }) =>
+    dmAction(context.controller, input),
+  ),
+
+  joinRoom: impl.joinRoom.handler(async ({ context, input }) =>
+    joinRoomAction(context.controller, input),
+  ),
+
+  leaveRoom: impl.leaveRoom.handler(async ({ context, input }) =>
+    leaveRoomAction(context.controller, input),
+  ),
+
+  createRoom: impl.createRoom.handler(async ({ context, input }) =>
+    createRoomAction(context.controller, input),
+  ),
+
+  listRooms: impl.listRooms.handler(async ({ context }) =>
+    listRoomsAction(context.controller),
+  ),
+
+  listAgents: impl.listAgents.handler(async ({ context }) =>
+    listAgentsAction(context.controller),
+  ),
+
+  readRoom: impl.readRoom.handler(async ({ context, input }) =>
+    readRoomAction(context.controller, input),
+  ),
+
+  destroyRoom: impl.destroyRoom.handler(async ({ context, input }) =>
+    destroyRoomAction(context.controller, input),
+  ),
+
+  invite: impl.invite.handler(async ({ context, input }) =>
+    inviteAction(context.controller, input),
+  ),
+
+  declineInvite: impl.declineInvite.handler(async ({ context, input }) =>
+    declineInviteAction(context.controller, input),
+  ),
+
+  kick: impl.kick.handler(async ({ context, input }) =>
+    kickAction(context.controller, input),
+  ),
+
+  renameAgent: impl.renameAgent.handler(async ({ context, input }) =>
+    renameAgentAction(context.controller, input),
+  ),
+
+  pushSubscribe: impl.pushSubscribe.handler(({ context, input }) =>
+    pushSubscribeAction(context.controller, context.pushManager, input),
+  ),
+
+  pushUnsubscribe: impl.pushUnsubscribe.handler(({ context, input }) =>
+    pushUnsubscribeAction(context.controller, context.pushManager, input),
+  ),
+
+  getRoomMessages: impl.getRoomMessages.handler(async ({ context, input }) =>
+    getRoomMessagesRead(context.controller, input),
+  ),
+
+  getMeshGraph: impl.getMeshGraph.handler(({ context }) =>
+    getMeshGraphRead(context.controller),
+  ),
+
+  getDisplayNames: impl.getDisplayNames.handler(async ({ context }) =>
+    getDisplayNamesRead(context.controller),
+  ),
+
+  getMeshTrace: impl.getMeshTrace.handler(async ({ context, input }) =>
+    getMeshTraceRead(context.controller, input),
+  ),
+
+  subscribeEvents: impl.subscribeEvents.handler(async function* ({
+    context,
+    input,
+    signal,
+    lastEventId,
+  }) {
+    // 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()),
+      };
+    }
+
+    yield* context.publisher.subscribe({
+      ...(signal ? { signal } : {}),
+      ...(resumeFrom !== undefined ? { lastEventId: resumeFrom } : {}),
+    });
+  }),
+};