agent-comms 8.15.9 → 8.15.10

package/src/core/atomic-file.ts

@@ -0,0 +1,46 @@
+/**
+ * Whole-file writes that a concurrent reader never observes half done, shared by the per-slot identity store (identity-store.ts), the grouping-issuer identity files (issuer-identity-file.ts) and the petnames file (petnames.ts). Every bridge on the machine may read these files while another bridge is writing them, so a reader must see either the complete previous content or the complete new content, never an empty or partial file.
+ */
+
+import * as fs from "node:fs";
+
+/** A sibling path unique to this process and call, on the same filesystem as filePath so a rename or link from it is atomic. */
+function temporarySibling(filePath: string): string {
+  return `${filePath}.${String(process.pid)}.${String(Math.random()).slice(2)}.tmp`;
+}
+
+/**
+ * Writes content to filePath atomically: the full content is written to a temporary sibling file first, then renamed into place. rename() on the same filesystem is atomic, so a concurrent reader of filePath always sees either the complete previous content or the complete new content, never a truncated or partially-written file, unlike a bare writeFileSync, whose own open(O_TRUNC)-then-write leaves a real window where a concurrent reader can observe an empty or partial file.
+ */
+export function writeFileAtomic(
+  filePath: string,
+  content: string,
+  mode: number,
+): void {
+  const tmpFile = temporarySibling(filePath);
+  fs.writeFileSync(tmpFile, content, { encoding: "utf-8", mode });
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Creates filePath with content only if nothing exists there yet, atomically: the full content is written to a temporary sibling first and then hard-linked into place. link() fails with EEXIST when the name already exists and never replaces it, and the name appears only once its content is complete, unlike open with the "wx" flag followed by a write, which leaves the file empty for a moment. Returns false when another writer created filePath first, leaving that writer's file untouched.
+ */
+export function createFileExclusive(
+  filePath: string,
+  content: string,
+  mode: number,
+): boolean {
+  const tmpFile = temporarySibling(filePath);
+  fs.writeFileSync(tmpFile, content, { encoding: "utf-8", mode });
+  try {
+    fs.linkSync(tmpFile, filePath);
+    return true;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+      return false;
+    }
+    throw err;
+  } finally {
+    fs.unlinkSync(tmpFile);
+  }
+}

package/src/core/bind-retry.ts

@@ -0,0 +1,38 @@
+/**
+ * retryOnAddrInUse — bind-retry backoff for WireMeshTransport.becomeCoordinator (agent-comms#170). Split out of wire-mesh-transport.ts to keep that file under the repo's max-lines cap, matching the same split-out-a-collaborator convention peer-lifecycle.ts and friends already use.
+ */
+
+/** Number of extra attempts becomeCoordinator makes after an initial EADDRINUSE before giving up. Covers PeerLifecycle's own graceful coordinator handover: the outgoing coordinator's listening socket may not have finished releasing the coordinator port yet when the successor's own become_coordinator handler tries to rebind it moments later. Retrying a plain server bind carries none of the risk documented elsewhere against retrying a TLS connectToCoordinator (a Node TLS session-cache bug that can freeze the event loop) -- this is ordinary bind-after-close backoff, the same class of transient conflict any two processes racing to acquire the same port would need to tolerate. */
+export const BECOME_COORDINATOR_BIND_RETRIES = 5;
+/** Delay between each becomeCoordinator bind retry -- five retries at this interval gives ~150ms of tolerance, comparable to the crash-race path's own documented "~100ms recovery". */
+export const BECOME_COORDINATOR_BIND_RETRY_DELAY_MS = 30;
+
+/** Whether an error is a port-already-bound failure, the one condition a bind is worth retrying (and, for PeerLifecycle's crash-race takeover, the one that means another survivor won the race rather than that binding is impossible). Matched on the message because Node surfaces the code there for every listen-path failure this codebase sees, including the ones wrapped by wire-mesh-core's own transport adapters, which carry no `code` property of their own. */
+export function isAddrInUse(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("EADDRINUSE");
+}
+
+/** Whether an error is a nothing-is-listening dial failure. Distinguished from every other dial failure because it alone means the port is genuinely free, which is what tells PeerLifecycle's takeover that re-entering the bind race is worth it rather than that the coordinator is there but unreachable. Matched on the message for the same reason isAddrInUse is. */
+export function isConnectionRefused(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("ECONNREFUSED");
+}
+
+/** Retries `attempt` while it keeps rejecting with an EADDRINUSE-shaped error, up to `retries` further attempts, waiting `delayMs` between each. Any other error, or exhausting the retry budget, rethrows immediately -- never silently swallowed. A pure, transport-agnostic helper (no socket knowledge of its own) so becomeCoordinator's bind-retry race is fast and deterministic to test directly. */
+export async function retryOnAddrInUse<T>(
+  attempt: () => Promise<T>,
+  retries: number,
+  delayMs: number,
+): Promise<T> {
+  for (let tryNumber = 0; ; tryNumber++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!isAddrInUse(error) || tryNumber >= retries) throw error;
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, delayMs);
+      });
+    }
+  }
+}

package/src/core/bridge-mesh.ts

@@ -0,0 +1,176 @@
+/**
+ * Shared bootstrap for a bridge's own mesh participation: load or create this bridge's persisted identity, construct a MeshStore wired to WireMeshTransport, and build the CommsTool that sits on top of it. Every bridge previously repeated this same four-line block against TlsTransport/identity.fingerprint directly; this factory is the single place that wiring lives now, so the substrate a bridge runs on is a one-line change here rather than six repeated ones.
+ *
+ * peerId is deviceIdToHex(identity.deviceId), not identity.fingerprint -- WireMeshTransport's own session bookkeeping is keyed by device-id, so MeshStore's own notion of "this peer's id" has to be the same value for the two to correlate. Every existing agent id changes the first time a bridge starts through this factory: there is no migration path, since the value is a hash of genuinely different bytes (device-id is SHA-256(raw public key); fingerprint is SHA-256(certificate DER)) -- a hard cutover, already established as correct when identity.ts first grew deviceId, not relitigated here.
+ *
+ * Split into a synchronous half (wireBridgeMesh) and an async half (attachMintingIdentity, wrapping toIdentityPort's WebCrypto import) because deriving the IdentityPort MeshStore mints room-membership grants against is unavoidably async, but not every bridge entry point can await one inline -- a plugin loader that calls its extension's default export synchronously (e.g. pi's own) cannot. createBridgeMeshSync exposes both halves for that case, deferring attachIdentity() to wherever the bridge's own lifecycle first has an async context (its own session-start hook), which is always well before the bridge does anything identity-dependent like createRoom. createBridgeMesh remains the convenient all-in-one for every bridge whose own entry point is already async.
+ *
+ * Also starts this bridge's own VersionDriftChecker (agent-comms#166) and wires its result into the CommsTool it builds, so every real bridge gets npm release-drift reporting on whoami/update for free from this one construction point, with no per-bridge wiring. fetchLatestVersion is exposed purely for tests -- every real caller omits it and gets VersionDriftChecker's own default (a real npm registry lookup); a test that would otherwise trigger real network I/O on every createBridgeMesh call injects a fake resolver instead.
+ *
+ * createBridgeMeshSync/createBridgeMesh own loadOrCreateIdentity's slot lock on the caller's behalf; createBridgeMeshSyncFromIdentity/createBridgeMeshFromIdentity take an already-loaded identity instead and never touch the lock at all -- the cc-peer front (agent-comms#157) uses these directly, via loadIdentityForFront's lock-free load, to build a mesh identity for a not-yet-live session's slot while leaving that slot's own lock free for its real bridge to acquire normally later.
+ *
+ * Passes slot through to MeshStore's own constructor (agent-comms#186) so the gatewayTrust allowlist it builds loads whatever remote device-ids were trusted before the last restart, and persists every subsequent addTrustedGateway/removeTrustedGateway back to the identity directory's one shared trust file, which every other store on the machine reads as well (agent-comms#293). The same slot backs MeshStore's connectionCodes ledger (agent-comms#188), which stays per slot.
+ *
+ * The returned store's own getCcPeerVersion field starts undefined and is read live (never snapshotted) by both WireMeshTransport's gossip tick and CommsTool's whoami/update/list_agents -- front-runtime.ts and bridges/cc-peer/run.ts set it once, right after this factory returns, rather than this factory taking it as a parameter: only those two call sites ever have a value for it, so threading it through every createBridgeMesh* signature here would be dead weight on every other caller (agent-comms#198).
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { createSystemClock } from "wire-mesh-core/adapters/system-clock";
+import { createRevocationView } from "wire-mesh-core/domain/revocation-view";
+import { createNodeFsStorage } from "wire-mesh-core/adapters/node-fs-storage";
+import { MeshStore } from "./mesh-store.js";
+import { resolveHubUrl } from "./mesh-store-shared.js";
+import { FIRST_CONTACT_PORT } from "./first-contact.js";
+import { CommsTool } from "./tool.js";
+import { WireMeshTransport } from "./wire-mesh-transport.js";
+import { loadOrCreateIdentity, oplogDirFor } from "./identity-store.js";
+import { openAccountLedger } from "./account-ledger-store.js";
+import type { IdentitySlot } from "./identity-store.js";
+import { toIdentityPort } from "./wire-mesh-identity.js";
+import type { PeerIdentity } from "./identity.js";
+import { VersionDriftChecker } from "./version-check.js";
+import { getOwnPackageVersion } from "./package-version.js";
+import { loadOrCreateUserIdentity } from "./user-identity.js";
+import { loadOrCreateMachineIdentity } from "./machine-identity.js";
+import { resolveDataDir } from "./data-directory.js";
+
+export interface BridgeMesh {
+  store: MeshStore;
+  tool: CommsTool;
+}
+
+export interface BridgeMeshSync extends BridgeMesh {
+  /** Derives and wires this store's IdentityPort (the collaborator createRoom and every other identity-using method require). Must be awaited before any such method runs; safe to call from the bridge's own first async lifecycle hook rather than its (necessarily synchronous) entry point. */
+  attachIdentity: () => Promise<void>;
+}
+
+/** coordinatorPort/hubUrl thread straight into MeshStore's own constructor, hubUrl defaulting here and nowhere below to resolveHubUrl() (AGENT_COMMS_HUB_URL, else the production hub); fetchLatestVersion is exposed purely for tests -- every real caller omits it and gets VersionDriftChecker's own default (a real npm registry lookup). firstContactPort defaults to FIRST_CONTACT_PORT, the default-on coordinator-free formation presence (agent-comms#341); a bridge-level test overrides it with an OS-assigned free port so test bridges never cross-discover each other. */
+export interface BridgeMeshOptions {
+  coordinatorPort?: number | undefined;
+  hubUrl?: string | undefined;
+  fetchLatestVersion?: (() => Promise<string | undefined>) | undefined;
+  firstContactPort?: number | undefined;
+}
+
+/** Seams that let a test run a real bridge against an isolated mesh; every real launch omits them. */
+export interface BridgeRunOptions {
+  /** Ports and hub for the bridge's own mesh store; see BridgeMeshOptions. */
+  mesh?: BridgeMeshOptions | undefined;
+  /** The identity slot. Defaults to this process's working directory under the bridge's own harness. */
+  slot?: IdentitySlot | 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. */
+export function createBridgeMeshSync(
+  slot: Readonly<IdentitySlot>,
+  options?: BridgeMeshOptions,
+): BridgeMeshSync {
+  return createBridgeMeshSyncFromIdentity(
+    loadOrCreateIdentity(slot),
+    slot,
+    options,
+  );
+}
+
+/**
+ * The same synchronous construction as createBridgeMeshSync, but taking an already-loaded identity rather than calling loadOrCreateIdentity itself -- see this file's own header comment for who this is for. Every other caller should go through createBridgeMeshSync/createBridgeMesh above, which own the lock on the caller's behalf.
+ */
+export function createBridgeMeshSyncFromIdentity(
+  identity: PeerIdentity,
+  slot: Readonly<IdentitySlot>,
+  options?: BridgeMeshOptions,
+): BridgeMeshSync {
+  const {
+    coordinatorPort,
+    hubUrl = resolveHubUrl(),
+    fetchLatestVersion,
+    firstContactPort = FIRST_CONTACT_PORT,
+  } = options ?? {};
+  // Account and machine keys are shared within the configured data directory, not scoped to the device's harness/cwd. Legacy slot.dir still overrides only the device's own files.
+  const userIdentityOptions = { dir: resolveDataDir({ dir: slot.dataDir }) };
+  const userIdentity = loadOrCreateUserIdentity(userIdentityOptions);
+  const machineIdentity = loadOrCreateMachineIdentity(userIdentityOptions);
+  const store = new MeshStore({
+    coordinatorPort,
+    hubUrl,
+    slot,
+    firstContactPort,
+  });
+  store.peerId = deviceIdToHex(Uint8Array.from(identity.deviceId));
+  // One shared dataStorage instance for both the transport's own data-domain frame responder and the store's own durable-send mint path (P5, agent-comms#50) -- oplogDirFor(slot) needs only the slot, not the async identity below, so this can be constructed synchronously right here.
+  const dataStorage = createNodeFsStorage({ dir: oplogDirFor(slot) });
+  const transport = new WireMeshTransport(store.events, identity, {
+    roomVerbHandlers: store.roomVerbHandlers,
+    roomJoinApprovalTimeoutMs: store.roomJoinApprovalTimeoutMs,
+    verifyMembership: async (claim) => store.membership.verify(claim),
+    getCurrentPresence: () => store.selfStatus,
+    getHostedRooms: () => store.hostedRooms,
+    dataStorage,
+    getSelfAgentAdvert: () => store.selfAgentAdvert,
+    accountReplication: {
+      getLedger: () => store.accountLedger,
+      isAccountMember: async (claim) => store.membership.isAccountMember(claim),
+    },
+    gatewayTrust: store.gatewayTrust,
+  });
+  transport.getCcPeerVersion = () => store.getCcPeerVersion?.();
+  store.setTransport(transport);
+  const versionChecker = new VersionDriftChecker({
+    currentVersion: getOwnPackageVersion(),
+    ...(fetchLatestVersion !== undefined ? { fetchLatestVersion } : {}),
+  });
+  versionChecker.start();
+  const tool = new CommsTool(store, {
+    discovery: store.discovery,
+    naming: store.naming,
+    getNewerVersionIfAny: () => versionChecker.getNewerVersionIfAny(),
+  });
+  const revocation = createRevocationView();
+  return {
+    store,
+    tool,
+    attachIdentity: async () => {
+      const clock = createSystemClock();
+      store.setIdentity({
+        identity: await toIdentityPort(identity),
+        clock,
+        slot,
+        revocation,
+        dataStorage,
+        userIdentity: await toIdentityPort(userIdentity),
+        accountLedger: await openAccountLedger({
+          userIdentityOptions,
+          userIdentity,
+          clock,
+        }),
+        userIdentityOptions,
+        machineIdentity: await toIdentityPort(machineIdentity),
+        machineIdentityOptions: userIdentityOptions,
+      });
+    },
+  };
+}
+
+export async function createBridgeMesh(
+  slot: Readonly<IdentitySlot>,
+  options?: BridgeMeshOptions,
+): Promise<BridgeMesh> {
+  const { store, tool, attachIdentity } = createBridgeMeshSync(slot, options);
+  await attachIdentity();
+  return { store, tool };
+}
+
+/** The async, already-loaded-identity counterpart to createBridgeMesh, mirroring createBridgeMeshSyncFromIdentity's relationship to createBridgeMeshSync. */
+export async function createBridgeMeshFromIdentity(
+  identity: PeerIdentity,
+  slot: Readonly<IdentitySlot>,
+  options?: BridgeMeshOptions,
+): Promise<BridgeMesh> {
+  const { store, tool, attachIdentity } = createBridgeMeshSyncFromIdentity(
+    identity,
+    slot,
+    options,
+  );
+  await attachIdentity();
+  return { store, tool };
+}