agent-comms 9.0.2 → 9.0.4

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

@@ -1 +1 @@
-(function(){var e=`agent-comms-v1`,t=[{"revision":"194357f4b022a304e068ddaeeb4cf799","url":"mesh-worker.js"},{"revision":"f1ee3afb8c9e8f0d7315fd93d6457316","url":"index.html"},{"revision":"f1e3596f5e09029800e9862a7cb9335a","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":"194357f4b022a304e068ddaeeb4cf799","url":"mesh-worker.js"},{"revision":"f1ee3afb8c9e8f0d7315fd93d6457316","url":"index.html"},{"revision":"89590c500b7ccdfdb97fec446e4a685b","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/server.ts

@@ -8,6 +8,7 @@
  * When AGENT_COMMS_WEB_CONSOLE_DIST points at a built wire-mesh web-console (see web-console-static.ts), GET /web-console/* also serves that as an alternate, generic reference-client UI alongside the frontend above.
  */
 
+import { once } from "node:events";
 import * as http from "node:http";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
@@ -56,6 +57,7 @@ import {
   type AccessDecision,
   type AccessPolicy,
 } from "./web-access.js";
+import { bridgePortRange } from "./bridge-port-range.js";
 import { startWebBeacon } from "./web-beacon.js";
 import {
   createFrontendAssetLoader,
@@ -112,7 +114,7 @@ export interface WebServerHandle {
   accessToken: string | undefined;
 }
 
-/** Resolve the listening port from a running web server handle, or undefined if the OS hasn't assigned one yet. */
+/** The port a web server handle holds. A handle is returned only once its server is listening, so this is undefined only after the server has been closed. */
 export function getWebPort(handle: WebServerHandle): number | undefined {
   const addr = handle.server.address();
   return typeof addr === "object" && addr ? addr.port : undefined;
@@ -135,14 +137,15 @@ export function getWebUrlStatus(
 /**
  * Starts the web UI for a bridge on top of the bridge's own store, so the process stays one mesh peer and one agent (the agent id is the store's peer id, before or after the agent registers). Every bridge entry point that owns a store uses this, and only the standalone dashboard command builds a controller, and so a store, of its own.
  *
- * The server listens on an OS-assigned free port (port 0) to avoid TOCTOU races when multiple bridges start web servers concurrently: the OS atomically allocates a unique free port for each. The PWA discovery path (probe from 19877) is only used when the page is served from a non-local host (e.g. GitHub Pages); when served locally, the browser connects via location.host directly, so the port number doesn't need to be predictable.
+ * The server binds the first free port of the bridge port range (see bridge-port-range.ts), which is where the hosted dashboard looks for a bridge, and takes an operating-system port only when the whole range is taken. Each port is bound for real rather than tested first, so bridges starting at the same moment cannot be handed the same port. `options.bridgePortBase` is the first port of the range to bind from; it defaults to the range the dashboard probes, and tests pass a free range of their own.
  */
 export async function tryStartBridgeWebServer(
   store: MeshStore,
   harness: string,
+  options?: Readonly<{ bridgePortBase?: number | undefined }>,
 ): Promise<WebServerHandle | undefined> {
   return createWebServer({
-    port: 0,
+    bridgePortBase: options?.bridgePortBase,
     existingController: ChatController.fromExisting(store, {
       agentId: store.peerId,
       harness,
@@ -152,8 +155,72 @@ export async function tryStartBridgeWebServer(
   });
 }
 
+/** Whether a listen failure means the port is already taken. */
+function isAddressInUse(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "EADDRINUSE"
+  );
+}
+
+/** Binds `server` to `port` on `host`; true once listening, false when the port is taken, and rejects on any other failure. */
+async function tryListen(
+  server: http.Server,
+  port: number,
+  host: string,
+): Promise<boolean> {
+  // once() rejects when the server emits "error" before "listening", and removes both of its listeners either way.
+  const listening = once(server, "listening");
+  server.listen(port, host);
+  try {
+    await listening;
+    return true;
+  } catch (error) {
+    if (isAddressInUse(error)) return false;
+    throw error;
+  }
+}
+
+/**
+ * Binds `server` to the first of `ports` that is free, in order, and returns the port it holds.
+ *
+ * Each port is bound for real, so a port another process takes between two attempts is simply skipped, where a test-then-bind would hand two processes the same port. Only "already in use" moves on to the next port: any other bind error rejects with that error. When `fallBackToAnyPort` is set and every port is taken the operating system picks one; when nothing could be bound the error names every port tried.
+ */
+async function listen(
+  server: http.Server,
+  host: string,
+  ports: readonly number[],
+  fallBackToAnyPort: boolean,
+): Promise<number> {
+  for (const port of ports) {
+    if (await tryListen(server, port, host)) return boundPortOf(server);
+  }
+  if (fallBackToAnyPort && (await tryListen(server, 0, host))) {
+    return boundPortOf(server);
+  }
+  const tried = fallBackToAnyPort
+    ? [...ports.map(String), "an operating-system port"]
+    : ports.map(String);
+  throw new Error(
+    `Agent Comms web UI: every port tried is already in use on ${host}: ${tried.join(", ")}`,
+  );
+}
+
+/** The port a listening server holds. */
+function boundPortOf(server: http.Server): number {
+  const addr = server.address();
+  if (typeof addr !== "object" || addr === null) {
+    throw new Error("Agent Comms web UI: the listening server has no address");
+  }
+  return addr.port;
+}
+
 /**
- * Create and start the web server on a dynamic port.
+ * Create the web server and resolve once it is listening.
+ *
+ * Without an explicit `port` it binds the first free port of the bridge port range, falling back to an operating-system port when the whole range is taken. An explicit `port` (0 for an operating-system port) is bound as given, and a port that is taken rejects instead of moving on. When binding fails nothing is left behind: the server is bound before the publisher, the listeners and the websocket server are created, and a controller this call created is shut down.
  *
  * Accepts an optional ChatController for reuse — bridges that already
  * have a MeshStore and agent identity pass theirs in so the web UI
@@ -162,7 +229,9 @@ export async function tryStartBridgeWebServer(
  * Dashboard controller is created.
  */
 export async function createWebServer(options?: {
-  port?: number;
+  port?: number | undefined;
+  /** The first port of the bridge port range tried when no explicit `port` is given. Defaults to the range the hosted dashboard probes; tests pass a free range so they neither wait on nor disturb a bridge running on the machine. */
+  bridgePortBase?: number | undefined;
   /** The IP address to bind. Defaults to AGENT_COMMS_WEB_HOST, then loopback. A non-loopback address makes the server reachable from the LAN and turns on the access token (see web-access.ts). */
   host?: string | undefined;
   /** The addresses whose clients count as on this machine besides loopback. Defaults to every interface address of this machine; tests replace it to make a client on the machine's own address stand in for a remote device (see AccessPolicy.localClientAddresses). */
@@ -177,7 +246,8 @@ export async function createWebServer(options?: {
   hubUrl?: string | undefined;
 }): Promise<WebServerHandle> {
   const {
-    port = 0,
+    port,
+    bridgePortBase,
     host: requestedHost,
     localClientAddresses = ownInterfaceAddresses,
     beaconPort,
@@ -204,11 +274,11 @@ export async function createWebServer(options?: {
     ? generateAccessToken()
     : undefined;
 
-  // The port is only known once the server listens (port 0 asks the OS), so the policy's port is filled in by the listen callback, before any request can arrive.
+  // The port is only known once the server listens (port 0 asks the OS), so the policy's port is filled in once the server is bound, before any request can arrive.
   const accessPolicy: AccessPolicy = {
     token: accessToken,
     bindHost: host,
-    port,
+    port: port ?? 0,
     localClientAddresses,
   };
 
@@ -217,6 +287,21 @@ export async function createWebServer(options?: {
     handleRequest(req, res, controller, webConsoleDist);
   });
 
+  let boundPort: number;
+  try {
+    boundPort = await listen(
+      server,
+      host,
+      port === undefined ? bridgePortRange(bridgePortBase) : [port],
+      port === undefined,
+    );
+  } catch (error) {
+    // A controller this call created is this call's to release; one passed in belongs to its caller.
+    if (!existingController) await controller.shutdown();
+    throw error;
+  }
+  accessPolicy.port = boundPort;
+
   const publisher = new MeshEventPublisher();
   ensurePatchListener(controller.meshStore, publisher);
   controller.on("message", (event: DeliveryEvent) => {
@@ -263,22 +348,16 @@ export async function createWebServer(options?: {
     });
   });
 
-  server.listen(port, host, () => {
-    const addr = server.address();
-    accessPolicy.port = typeof addr === "object" && addr ? addr.port : port;
-    // stderr, not stdout: a stdio MCP bridge owns stdout for JSON-RPC, so any other line there is protocol noise to a strictly framed client.
-    console.error(
-      `Agent Comms web UI: ${localWebUrl(host, accessPolicy.port)}`,
+  // stderr, not stdout: a stdio MCP bridge owns stdout for JSON-RPC, so any other line there is protocol noise to a strictly framed client.
+  console.error(`Agent Comms web UI: ${localWebUrl(host, boundPort)}`);
+  if (accessToken !== undefined) {
+    announceLanAccess(
+      server,
+      { ...accessPolicy, token: accessToken },
+      controller.meshStore.peerId,
+      beaconPort,
     );
-    if (accessToken !== undefined) {
-      announceLanAccess(
-        server,
-        { ...accessPolicy, token: accessToken },
-        controller.meshStore.peerId,
-        beaconPort,
-      );
-    }
-  });
+  }
 
   return { server, controller, wss, publisher, host, accessToken };
 }
@@ -363,13 +442,9 @@ function announceLanAccess(
 // Standalone mode — `npx agent-comms chat`
 // ---------------------------------------------------------------------------
 
-export async function runWeb(userName: string, port = 0): Promise<void> {
+export async function runWeb(userName: string, port?: number): Promise<void> {
   const handle = await createWebServer({ port });
-  handle.server.on("listening", () => {
-    console.log(
-      `Connected as ${userName} (user) [${handle.controller.agentId}]`,
-    );
-  });
+  console.log(`Connected as ${userName} (user) [${handle.controller.agentId}]`);
 
   // Graceful shutdown
   const cleanup = async (): Promise<void> => {

package/src/bridges/user/web/test/bridge-web-server.helper.ts

@@ -0,0 +1,54 @@
+/**
+ * Starting and stopping a bridge's web server on its own store, as a bridge starts it, for tests of the port range and of what probes it.
+ */
+import { MeshStore } from "../../../../core/mesh-store.js";
+import {
+  freeLocalPort,
+  type TeardownStack,
+} from "../../../../test/hub-helpers.js";
+import { wireTestTransport } from "../../../../test/test-transport.js";
+import { tryStartBridgeWebServer, type WebServerHandle } from "../server.js";
+
+/** Closes the web socket server and the HTTP server of a handle, whether or not it is still listening. */
+export async function stopWebServer(handle: WebServerHandle): Promise<void> {
+  await new Promise<void>((resolve) => {
+    handle.wss.close(() => {
+      resolve();
+    });
+  });
+  if (!handle.server.listening) return;
+  await new Promise<void>((resolve) => {
+    handle.server.close(() => {
+      resolve();
+    });
+    handle.server.closeAllConnections();
+  });
+}
+
+/** A mesh store with an isolated coordinator and first-contact port, shut down by `cleanups`. */
+export async function startTestStore(
+  cleanups: Readonly<TeardownStack>,
+): Promise<MeshStore> {
+  const store = new MeshStore({
+    coordinatorPort: await freeLocalPort(),
+    firstContactPort: await freeLocalPort(),
+  });
+  await wireTestTransport(store);
+  await store.init();
+  cleanups.push(async () => store.shutdown());
+  return store;
+}
+
+/** A bridge's web server on a store of its own, bound from `bridgePortBase` and stopped by `cleanups`. */
+export async function startTestBridge(
+  cleanups: Readonly<TeardownStack>,
+  bridgePortBase: number,
+): Promise<WebServerHandle> {
+  const store = await startTestStore(cleanups);
+  const handle = await tryStartBridgeWebServer(store, "test", {
+    bridgePortBase,
+  });
+  if (handle === undefined) throw new Error("expected the web server to start");
+  cleanups.push(async () => stopWebServer(handle));
+  return handle;
+}

package/src/core/bridge-mesh.ts

@@ -58,6 +58,8 @@ export interface BridgeRunOptions {
   mesh?: BridgeMeshOptions | undefined;
   /** The identity slot. Defaults to this process's working directory under the bridge's own harness. */
   slot?: IdentitySlot | undefined;
+  /** The first port of the bridge port range the bridge's web server binds from; see bridge-port-range.ts. Defaults to the range the hosted dashboard probes, so only a test that must not bind it sets this. */
+  webPortBase?: number | undefined;
 }
 
 /** The synchronous half of bridge construction: everything loadOrCreateIdentity's own synchronous key material makes possible. Use this directly only when the calling entry point cannot await inline (see this file's own header comment); every other caller should use createBridgeMesh below. */

package/src/core/bridge.ts

@@ -162,9 +162,38 @@ class BuildActionError extends Error {
   }
 }
 
+/** Thrown by buildAction for parameters MCP_TOOL_PARAMS rejects, so a malformed tool call reaches its caller as an error naming what is wrong and is never run as some other action. `issues` is every problem found, each with the path of the parameter at fault. */
+export class InvalidToolParamsError extends Error {
+  constructor(
+    readonly issues: readonly {
+      readonly path: readonly (string | number)[];
+      readonly message: string;
+    }[],
+  ) {
+    super(
+      `Invalid parameters: ${issues
+        .map(
+          (issue) =>
+            `${issue.path.length === 0 ? "(root)" : issue.path.join(".")}: ${issue.message}`,
+        )
+        .join("; ")}`,
+    );
+    this.name = "InvalidToolParamsError";
+  }
+}
+
 export function buildAction(params: Record<string, unknown>): CommsAction {
   const parsed = MCP_TOOL_PARAMS.safeParse(params);
-  if (!parsed.success) return { action: "whoami" };
+  if (!parsed.success) {
+    throw new InvalidToolParamsError(
+      parsed.error.issues.map((issue) => ({
+        path: issue.path.map((step) =>
+          typeof step === "number" ? step : String(step),
+        ),
+        message: issue.message,
+      })),
+    );
+  }
   const p = parsed.data;
 
   switch (p.action) {

package/src/core/index.ts

@@ -36,6 +36,7 @@ export type { IdentitySlot } from "./identity-store.js";
 export type { CommsContext, CommsResult } from "./tool.js";
 export {
   buildAction,
+  InvalidToolParamsError,
   formatDeliveryEvent,
   extractStreamingBehavior,
   isActionableEvent,

package/src/core/tool.ts

@@ -89,7 +89,7 @@ export interface CommsContext {
   pid: number;
 }
 
-/** The calling bridge's own web UI address, as reported by the web_url action -- mirrors comms-url's own three-way distinction between a server that was never started, one whose OS-assigned port hasn't come back yet, and one that's actually reachable. */
+/** The calling bridge's own web UI address, as reported by the web_url action; mirrors comms-url's own three-way distinction between a server that was never started, one with no port because it is not listening, and one that's actually reachable. */
 export type WebUrlStatus =
   | { kind: "not_running" }
   | { kind: "pending" }

package/dist/bridges/user/web/port-discovery.d.ts

@@ -1,14 +0,0 @@
-/**
- * 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).
- */
-/** Maximum number of ports to try when searching for a free one. */
-export declare const DEFAULT_MAX_ATTEMPTS = 10;
-/**
- * Try binding sequentially from `base`.
- * Returns the first port that succeeds, or undefined if all are taken.
- */
-export declare function findFreePort(base: number, maxAttempts?: number): Promise<number | undefined>;
-//# sourceMappingURL=port-discovery.d.ts.map

package/dist/bridges/user/web/port-discovery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"port-discovery.d.ts","sourceRoot":"","sources":["../../../../src/bridges/user/web/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,MAA6B,GACzC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2B7B"}

package/dist/bridges/user/web/port-discovery.js

@@ -1,40 +0,0 @@
-/**
- * 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, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
-    return new Promise((resolve) => {
-        let attempts = 0;
-        function tryPort(port) {
-            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);
-    });
-}
-//# sourceMappingURL=port-discovery.js.map

package/dist/bridges/user/web/port-discovery.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"port-discovery.js","sourceRoot":"","sources":["../../../../src/bridges/user/web/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,QAAQ,GAAG,WAAW,CAAC;AAE7B,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,cAAsB,oBAAoB;IAE1C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,QAAQ,GAAG,CAAC,CAAC;QAEjB,SAAS,OAAO,CAAC,IAAY;YAC3B,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;gBAC5B,OAAO,CAAC,SAAS,CAAC,CAAC;gBACnB,OAAO;YACT,CAAC;YACD,QAAQ,EAAE,CAAC;YAEX,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAClC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;gBACrB,KAAK,CAAC,KAAK,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE;gBAChC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,UAAU,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;gBACvE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;oBACf,OAAO,CAAC,UAAU,CAAC,CAAC;gBACtB,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bridges/user/web/test/port-discovery.unit.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * Unit tests for port-discovery.ts — sequential port probing.
- */
-export {};
-//# sourceMappingURL=port-discovery.unit.test.d.ts.map

package/dist/bridges/user/web/test/port-discovery.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"port-discovery.unit.test.d.ts","sourceRoot":"","sources":["../../../../../src/bridges/user/web/test/port-discovery.unit.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/bridges/user/web/test/port-discovery.unit.test.js

@@ -1,180 +0,0 @@
-/**
- * Unit tests for port-discovery.ts — sequential port probing.
- */
-import { describe, it, expect } from "vitest";
-import * as http from "node:http";
-import { findFreePort } from "../port-discovery.js";
-/** How many times to retry a single bind attempt against a transient EADDRINUSE before giving up for real. */
-const BLOCK_PORT_MAX_ATTEMPTS = 10;
-/** Delay between retries, long enough for a port an unrelated process grabbed as its own ephemeral source port to be released again. Raised from 50ms/5 attempts (a ~250ms total window) after that budget still wasn't always enough on a loaded CI runner -- 10 attempts at 100ms gives a ~1s window before genuinely giving up. */
-const BLOCK_PORT_RETRY_DELAY_MS = 100;
-function isErrnoException(error) {
-    return error instanceof Error && "code" in error;
-}
-async function delay(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
-/**
- * Create a server that blocks a specific port. Returns a cleanup function.
- *
- * These tests deliberately use fixed port numbers (kept below PORT_RANGE_SAFE_CEILING, see below) so findFreePort's own sequential-scan behaviour is exercised deterministically. That keeps them clear of the OS's own ephemeral/dynamic port allocation range, but retrying briefly on EADDRINUSE is kept as a second line of defence for any other transient bind contention (e.g. another process on the same fixed port left over from a prior run) without weakening what the test actually asserts.
- */
-async function blockPort(port) {
-    for (let attempt = 1;; attempt++) {
-        try {
-            return await new Promise((resolve, reject) => {
-                const server = http.createServer();
-                server.on("error", reject);
-                server.listen(port, "127.0.0.1", () => {
-                    resolve(async () => {
-                        return new Promise((res) => {
-                            server.close(() => res());
-                        });
-                    });
-                });
-            });
-        }
-        catch (error) {
-            const isAddrInUse = isErrnoException(error) && error.code === "EADDRINUSE";
-            if (!isAddrInUse || attempt >= BLOCK_PORT_MAX_ATTEMPTS) {
-                throw error;
-            }
-            await delay(BLOCK_PORT_RETRY_DELAY_MS);
-        }
-    }
-}
-/** Ceiling every fixture port below must stay under: the lower bound of the ephemeral/dynamic port range both Linux (default 32768-60999, via net.ipv4.ip_local_port_range) and macOS (default 49152-65535, via net.inet.ip.portrange.first/last) draw from when the kernel auto-assigns a source port to an outbound connection. A fixture port inside either range can be transiently claimed by a completely unrelated process's outbound socket at the exact moment a test tries to bind it as a listening server, producing a genuine EADDRINUSE race no amount of retrying fully closes out. Staying below it removes the collision domain outright rather than tolerating it. */
-const PORT_RANGE_SAFE_CEILING = 32768;
-/** Base port for the "base port is free" scenario. */
-const TEST_PORT_AVAILABLE_BASE = 20000;
-/** Base port for the "single port taken" scenario. */
-const TEST_PORT_SINGLE_TAKEN_BASE = 20100;
-/** The port findFreePort should land on once TEST_PORT_SINGLE_TAKEN_BASE is blocked. */
-const TEST_PORT_SINGLE_TAKEN_RESULT = 20101;
-/** Base port for the "multiple consecutive ports taken" scenario. */
-const TEST_PORT_MULTIPLE_TAKEN_BASE = 20200;
-/** Second port blocked in the "multiple consecutive ports taken" scenario. */
-const TEST_PORT_MULTIPLE_TAKEN_SECOND = 20201;
-/** Third port blocked in the "multiple consecutive ports taken" scenario. */
-const TEST_PORT_MULTIPLE_TAKEN_THIRD = 20202;
-/** The port findFreePort should land on once all three ports above are blocked. */
-const TEST_PORT_MULTIPLE_TAKEN_RESULT = 20203;
-/** Base port for the "every port in range is taken" scenario. */
-const TEST_PORT_ALL_TAKEN_BASE = 20300;
-/** How many consecutive ports get blocked, and the maxAttempts passed to findFreePort, in the "every port in range is taken" scenario -- both are the same number by design so the scan exhausts exactly the blocked range. */
-const TEST_ALL_TAKEN_PORT_COUNT = 3;
-/** Base port for the "maxAttempts allows walking past taken ports" scenario. */
-const TEST_PORT_MAX_ATTEMPTS_BASE = 20400;
-/** Second port blocked in the "maxAttempts allows walking past taken ports" scenario. */
-const TEST_PORT_MAX_ATTEMPTS_SECOND = 20401;
-/** maxAttempts passed to findFreePort in the "maxAttempts allows walking past taken ports" scenario -- deliberately larger than the number of blocked ports so the scan walks past them. */
-const TEST_MAX_ATTEMPTS_LIMIT = 5;
-/** The port findFreePort should land on once both ports above are blocked. */
-const TEST_PORT_MAX_ATTEMPTS_RESULT = 20402;
-/** Port a test transiently occupies to prove blockPort's own EADDRINUSE retry, not luck, is what recovers. */
-const TEST_PORT_TRANSIENT_CONTENTION = 20500;
-/** Every literal fixture port declared above, gathered so the ephemeral-range invariant can be checked once for all of them rather than per-constant. */
-const ALL_FIXTURE_PORTS = [
-    TEST_PORT_AVAILABLE_BASE,
-    TEST_PORT_SINGLE_TAKEN_BASE,
-    TEST_PORT_SINGLE_TAKEN_RESULT,
-    TEST_PORT_MULTIPLE_TAKEN_BASE,
-    TEST_PORT_MULTIPLE_TAKEN_SECOND,
-    TEST_PORT_MULTIPLE_TAKEN_THIRD,
-    TEST_PORT_MULTIPLE_TAKEN_RESULT,
-    TEST_PORT_ALL_TAKEN_BASE,
-    TEST_PORT_MAX_ATTEMPTS_BASE,
-    TEST_PORT_MAX_ATTEMPTS_SECOND,
-    TEST_PORT_MAX_ATTEMPTS_RESULT,
-    TEST_PORT_TRANSIENT_CONTENTION,
-];
-describe("findFreePort fixture ports", () => {
-    it("all stay below the OS ephemeral port range", () => {
-        for (const port of ALL_FIXTURE_PORTS) {
-            expect(port).toBeLessThan(PORT_RANGE_SAFE_CEILING);
-        }
-    });
-});
-describe("blockPort", () => {
-    it("recovers from a transient EADDRINUSE instead of failing on the first attempt", async () => {
-        const contender = http.createServer();
-        await new Promise((resolve, reject) => {
-            contender.on("error", reject);
-            contender.listen(TEST_PORT_TRANSIENT_CONTENTION, "127.0.0.1", () => {
-                resolve();
-            });
-        });
-        // Release the port partway through blockPort's own retry window, well before it gives up, so the recovery below is provably the retry loop's own doing rather than the contender happening to already be gone before blockPort's first attempt.
-        setTimeout(() => {
-            contender.close();
-        }, BLOCK_PORT_RETRY_DELAY_MS * 2);
-        const unblock = await blockPort(TEST_PORT_TRANSIENT_CONTENTION);
-        await unblock();
-    });
-});
-describe("findFreePort", () => {
-    it("returns the base port when it is available", async () => {
-        const port = await findFreePort(TEST_PORT_AVAILABLE_BASE);
-        expect(typeof port).toBe("number");
-        expect(port).toBe(TEST_PORT_AVAILABLE_BASE);
-    });
-    it("walks to the next port when the base is taken", async () => {
-        const unblock = await blockPort(TEST_PORT_SINGLE_TAKEN_BASE);
-        try {
-            const port = await findFreePort(TEST_PORT_SINGLE_TAKEN_BASE);
-            expect(typeof port).toBe("number");
-            expect(port).toBe(TEST_PORT_SINGLE_TAKEN_RESULT);
-        }
-        finally {
-            await unblock();
-        }
-    });
-    it("skips multiple taken ports", async () => {
-        const unblock1 = await blockPort(TEST_PORT_MULTIPLE_TAKEN_BASE);
-        const unblock2 = await blockPort(TEST_PORT_MULTIPLE_TAKEN_SECOND);
-        const unblock3 = await blockPort(TEST_PORT_MULTIPLE_TAKEN_THIRD);
-        try {
-            const port = await findFreePort(TEST_PORT_MULTIPLE_TAKEN_BASE);
-            expect(typeof port).toBe("number");
-            expect(port).toBe(TEST_PORT_MULTIPLE_TAKEN_RESULT);
-        }
-        finally {
-            await unblock1();
-            await unblock2();
-            await unblock3();
-        }
-    });
-    it("returns undefined when all ports in range are taken", async () => {
-        // Block TEST_ALL_TAKEN_PORT_COUNT ports with maxAttempts=TEST_ALL_TAKEN_PORT_COUNT
-        const blockers = [];
-        for (let i = 0; i < TEST_ALL_TAKEN_PORT_COUNT; i++) {
-            blockers.push(await blockPort(TEST_PORT_ALL_TAKEN_BASE + i));
-        }
-        try {
-            const port = await findFreePort(TEST_PORT_ALL_TAKEN_BASE, TEST_ALL_TAKEN_PORT_COUNT);
-            expect(port).toBe(undefined);
-        }
-        finally {
-            for (const unblock of blockers) {
-                await unblock();
-            }
-        }
-    });
-    it("respects the maxAttempts parameter", async () => {
-        // Block 2 ports but allow TEST_MAX_ATTEMPTS_LIMIT attempts — should walk past them
-        const unblock1 = await blockPort(TEST_PORT_MAX_ATTEMPTS_BASE);
-        const unblock2 = await blockPort(TEST_PORT_MAX_ATTEMPTS_SECOND);
-        try {
-            const port = await findFreePort(TEST_PORT_MAX_ATTEMPTS_BASE, TEST_MAX_ATTEMPTS_LIMIT);
-            expect(typeof port).toBe("number");
-            expect(port).toBe(TEST_PORT_MAX_ATTEMPTS_RESULT);
-        }
-        finally {
-            await unblock1();
-            await unblock2();
-        }
-    });
-});
-//# sourceMappingURL=port-discovery.unit.test.js.map

package/dist/bridges/user/web/test/port-discovery.unit.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"port-discovery.unit.test.js","sourceRoot":"","sources":["../../../../../src/bridges/user/web/test/port-discovery.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/core/test/bridge.unit.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * Unit tests for bridge.ts — formatDeliveryEvent.
- */
-export {};
-//# sourceMappingURL=bridge.unit.test.d.ts.map

package/dist/core/test/bridge.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bridge.unit.test.d.ts","sourceRoot":"","sources":["../../../src/core/test/bridge.unit.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}