agent-comms 8.15.9 → 8.15.10

package/src/core/dm-send-delegation.ts

@@ -0,0 +1,73 @@
+/**
+ * Sub-delegation of a received dm:send grant to one of the recipient principal's own devices (agent-comms#187): once a remote user principal has been admitted into another user's DM-communication scope (room-lifecycle.ts's admitAgentForDm, minted with delegationsRemaining \> 0 specifically to allow this), that principal mints a CHILD dm:send token -- parent = the grant it received, bearer = its own device -- so a specific device can present durable admission on the principal's behalf, without the admitting side ever needing to know that device's own device-id in advance. Mirrors device-membership.ts's admitDevice in shape (a plain mint-and-record function, no MeshStore-equivalent orchestrator), but delegates an EXISTING grant via `parent` rather than self-issuing a fresh root-level one -- the first real use of mintCapabilityToken's parent-narrowing machinery in this codebase, every grant minted before this having been an independent root-level token.
+ *
+ * Deliberately does not touch the delegated device's own identity-store.ts slot, mirroring device-membership.ts's own "no assumption about locality" stance: getting the minted token onto that device (this process, or a different one) is left entirely to the caller.
+ */
+
+import {
+  mintCapabilityToken,
+  type MintVerdict,
+} from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type {
+  CapabilityToken,
+  DeviceId,
+} from "wire-mesh-core/generated/protocol";
+import {
+  DM_SEND_CAPABILITY,
+  DM_SEND_SCOPE_KIND,
+} from "./dm-token-verification.js";
+import type { AccountLedger } from "./account-ledger.js";
+
+/** delegationsRemaining a delegated device's own token permits below it, when the caller doesn't ask for more -- 0, matching every other non-delegable grant this codebase already mints by default (device-membership.ts's own NOT_DELEGABLE): an ordinary device is a leaf of the chain, not a further delegator. */
+const LEAF_NOT_DELEGABLE = 0;
+
+export interface DelegateDmSendToDeviceOptions {
+  /** The principal doing the sub-delegating -- must be the same identity the parent grant's own bearer names, or mintCapabilityToken's own parent-bearer-matches-issuer narrowing check refuses the mint outright (`parent_bearer_mismatch`). */
+  userIdentity: IdentityPort;
+  /** The account's replicated grant ledger, which records the delegation so any machine holding the account key can revoke it. */
+  accountLedger: AccountLedger;
+  clock: Clock;
+  tokenId: Uint8Array<ArrayBuffer>;
+  /** The grant this principal itself was admitted with (room-lifecycle.ts's admitAgentForDm, minted with delegationsRemaining \> 0) -- every one of tokens.cddl's own narrowing obligations is checked against it at mint time. */
+  parent: CapabilityToken;
+  /** The device being delegated to -- one of this principal's own devices. */
+  deviceId: DeviceId;
+  /** The remote user principal that originally admitted this identity -- the scope this delegated token must keep naming, unchanged from parent's own scope (tokens.cddl's own narrowing requires an identical "user" scope path down the whole chain). */
+  remoteUserPrincipalDeviceId: DeviceId;
+  expires: number;
+  /** How many further hops the delegated token itself permits below it -- defaults to LEAF_NOT_DELEGABLE; only worth raising for a hierarchy deeper than "principal delegates directly to a device" genuinely needs. */
+  delegationsRemaining?: number;
+}
+
+/**
+ * Mints deviceId's own dm:send delegation from a received grant: bearer = deviceId, parent = the grant this principal itself was admitted with, scope unchanged (still the REMOTE admitting principal's own "user" scope, never this principal's own device-id); mintCapabilityToken's own narrowing refuses this outright if parent's own delegationsRemaining was 0 (nothing left to sub-delegate) or if userIdentity does not match parent's own bearer. On success, records the token-id in THIS principal's own replicated grant ledger as a dm grant keyed by deviceId's hex, so a later revocation on any of the account's machines can find it; admitAgentForDm's own root-level self-grants are recorded the same way, since both are simply grants this identity has issued, keyed by bearer, whether root-level or a delegation.
+ */
+export async function delegateDmSendToDevice(
+  options: Readonly<DelegateDmSendToDeviceOptions>,
+): Promise<MintVerdict> {
+  const verdict = await mintCapabilityToken({
+    identity: options.userIdentity,
+    clock: options.clock,
+    tokenId: options.tokenId,
+    bearer: options.deviceId,
+    capability: DM_SEND_CAPABILITY,
+    scope: {
+      kind: DM_SEND_SCOPE_KIND,
+      path: deviceIdToHex(options.remoteUserPrincipalDeviceId),
+    },
+    expires: options.expires,
+    delegationsRemaining: options.delegationsRemaining ?? LEAF_NOT_DELEGABLE,
+    parent: options.parent,
+  });
+  if (!verdict.ok) return verdict;
+
+  await options.accountLedger.recordGrant(
+    "dm",
+    deviceIdToHex(options.deviceId),
+    options.tokenId,
+  );
+  return verdict;
+}

package/src/core/dm-token-verification.ts

@@ -0,0 +1,76 @@
+/**
+ * Receiver-side verification of a `dm:send` capability token (agent-comms#162): the receiver-controlled admission list a user principal issues, parallel to room-token-verification.ts's own `room:member` obligations but rooted at the user principal's device-id (user-identity.ts) rather than a room's own owner -- a `dm:send` grant admits a bearer device into THIS user's communication scope across every bridge slot sharing that principal, not into one specific room path. Layered on verifyCapabilityToken the same way verifyRoomToken is: obligations 2/4/5 (bearer match, ordinary token-claims checks, delegations-remaining narrowing) live there already; this module adds the dm:send-specific obligations -- the presented token must actually carry the dm:send capability (not merely happen to share a scope shape), its scope must name this exact user principal, and its delegation chain must root at that same user principal (never at the bearer itself, or self-issued authority would let any sender simply mint its own admission).
+ */
+
+import {
+  verifyCapabilityToken,
+  type TokenVerdictReason,
+  type VerifyCapabilityTokenOptions,
+} from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type {
+  CapabilityToken,
+  DeviceId,
+  TokenClaims,
+} from "wire-mesh-core/generated/protocol";
+
+/** The one capability a user principal issues to admit a device into its own DM-communication scope (agent-comms#162) -- checked receiver-side wherever an unsolicited DM contact is admitted, the way room-token-verification.ts's ROOM_MEMBER_CAPABILITY gates every ordinary room-membership verb. */
+export const DM_SEND_CAPABILITY = "dm:send";
+
+/** The scope kind a dm:send grant's own scope always carries -- the resource being granted is "communication with this user principal", named by that principal's own device-id, never a specific bridge slot's peer-id, since a dm:send grant admits a bearer into the user's whole communication scope rather than one particular device. */
+export const DM_SEND_SCOPE_KIND = "user";
+
+export type DmSendTokenVerdictReason =
+  | TokenVerdictReason
+  | "wrong_capability"
+  | "wrong_scope_kind"
+  | "wrong_scope_path"
+  | "wrong_chain_root";
+
+export type DmSendTokenVerdict =
+  | { ok: true; claims: TokenClaims }
+  | { ok: false; reason: DmSendTokenVerdictReason };
+
+export interface VerifyDmSendTokenOptions extends Omit<
+  VerifyCapabilityTokenOptions,
+  "expectedBearer"
+> {
+  /** The peer identity actually authenticated on the arriving connection -- the requester presenting this token as its own authority to contact userPrincipalDeviceId, never a relay-asserted or gossip-derived value. Mandatory here, matching verifyRoomToken's own mandatory expectedBearer: every dm:send check gates a specific counterparty, unlike verifyCapabilityToken's own optional field for a caller presenting a token to authorise itself. */
+  expectedBearer: DeviceId;
+  /** This receiving node's own user-principal device-id (user-identity.ts's loadOrCreateUserIdentity), the only issuer a dm:send grant may validly root at. */
+  userPrincipalDeviceId: DeviceId;
+}
+
+/**
+ * Verifies a `dm:send` capability token against the receiver's own user-principal identity: the token must carry the dm:send capability, its scope must be kind "user" with path equal to userPrincipalDeviceId exactly, and its delegation chain must root at userPrincipalDeviceId itself -- a self-issued or third-party-issued token naming the right scope by coincidence still fails here, since rootIssuer is checked independently of scope.path.
+ */
+export async function verifyDmSendToken(
+  token: CapabilityToken,
+  options: Readonly<VerifyDmSendTokenOptions>,
+): Promise<DmSendTokenVerdict> {
+  const verdict = await verifyCapabilityToken(token, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.expectedBearer,
+  });
+  if (!verdict.ok) {
+    return verdict;
+  }
+
+  if (verdict.claims.capability !== DM_SEND_CAPABILITY) {
+    return { ok: false, reason: "wrong_capability" };
+  }
+  if (verdict.claims.scope.kind !== DM_SEND_SCOPE_KIND) {
+    return { ok: false, reason: "wrong_scope_kind" };
+  }
+  const expectedPath = deviceIdToHex(options.userPrincipalDeviceId);
+  if (verdict.claims.scope.path !== expectedPath) {
+    return { ok: false, reason: "wrong_scope_path" };
+  }
+  if (deviceIdToHex(verdict.rootIssuer) !== expectedPath) {
+    return { ok: false, reason: "wrong_chain_root" };
+  }
+
+  return { ok: true, claims: verdict.claims };
+}

package/src/core/election-sessions.ts

@@ -0,0 +1,135 @@
+/**
+ * ElectionSessions: WireMeshTransport's set of live, trusted sessions to peers on this machine, the only sessions coordinator claims are read from and gossiped over (agent-comms#341), since the elected role's duties are per machine. Split out of wire-mesh-transport.ts to keep it under the repo's max-lines cap.
+ *
+ * A session counts as machine-local when it was accepted on a loopback-only listener (the data server or the default well-known port listener) or dialled at a loopback address (loopback-address.ts), whether at a peer's data server or at the well-known port. A dial at any other address may cross machines, since the dialler knows nothing about the far side's listener beyond the address it dialled, and a peer list or a first-contact beacon heard over LAN broadcast can name any host. A session reached through connectToRemote or an addListener-created listener may cross machines and is never enrolled, and neither is one admitted through an approved connect_request, whose dialling side is a connectToRemote session and so never enrols it either.
+ *
+ * Every session this transport opens is watched from the moment it opens, whether or not it is ever enrolled: a frame is delivered only when its session is enrolled at the moment the frame is read, and is dropped otherwise. So a quarantined session's claims from before its introduce are discarded rather than replayed once it introduces itself, and a session that is never enrolled does not accumulate the frames its peer sends.
+ */
+
+import type { AcceptedMeshSession } from "wire-mesh-core/domain/mesh-session";
+import type { CoordinatorFrame } from "wire-mesh-core/generated/protocol";
+import type { ConnectionHandle, TransportEvents } from "./transport.js";
+
+/** Where a session's outbound claims stand: whether a send is unresolved, and the newest claim that arrived meanwhile. */
+interface OutboundSlot {
+  sending: boolean;
+  waiting: Readonly<CoordinatorFrame> | undefined;
+}
+
+export class ElectionSessions {
+  /** Each enrolled session, with the handle its claims are reported under. */
+  private readonly enrolled = new Map<
+    AcceptedMeshSession,
+    Readonly<ConnectionHandle>
+  >();
+  /** Outbound state per session. A claim is state a later claim supersedes, so a session holds at most one send in flight and one waiting claim: a peer that reads slowly can never make this side's write queue grow with every claim it is answered with. */
+  private readonly outbound = new Map<AcceptedMeshSession, OutboundSlot>();
+
+  constructor(
+    private readonly events: Readonly<
+      Pick<
+        TransportEvents,
+        "onCoordinatorClaim" | "onElectionSessionEnrolled" | "onError"
+      >
+    >,
+  ) {}
+
+  /** Starts reading every coordinator-frame the session's peer gossips, for as long as the session lives, handing each to onCoordinatorClaim only while the session is enrolled. Called exactly once per session, as soon as it is opened and before anything could enrol it. */
+  watch(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+  ): void {
+    void (async () => {
+      for await (const frame of session.coordinatorFrames) {
+        if (this.enrolled.has(session)) {
+          this.events.onCoordinatorClaim(handle, frame);
+        }
+      }
+    })();
+  }
+
+  /** Enrols a trusted machine-local session, then fires onElectionSessionEnrolled so this side tells the peer which claim it accepts. Both ends of every machine-local session enrol it, so each tells the other. */
+  enrol(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+  ): void {
+    this.enrolled.set(session, handle);
+    this.events.onElectionSessionEnrolled(handle);
+  }
+
+  /** Forgets a closed session. A no-op for one never enrolled. */
+  delete(session: AcceptedMeshSession): void {
+    this.enrolled.delete(session);
+    this.outbound.delete(session);
+  }
+
+  clear(): void {
+    this.enrolled.clear();
+    this.outbound.clear();
+  }
+
+  /** Whether this store holds a live machine-local session with the device (hex): a full member of its local mesh on this same machine. */
+  hasPeer(deviceHex: string): boolean {
+    return this.peerIds().has(deviceHex);
+  }
+
+  /** The device-ids of every peer this side has at least one enrolled session to: the peers that take part in the election with it. */
+  peerIds(): ReadonlySet<string> {
+    return new Set([...this.enrolled.values()].map((handle) => handle.id));
+  }
+
+  /** Gossips a claim over every enrolled session. A send fails only on a connection that is already closing, and each failure is reported; the peer is told the incumbent again when its next session is enrolled. */
+  async broadcast(frame: Readonly<CoordinatorFrame>): Promise<void> {
+    await Promise.all(
+      [...this.enrolled].map(async ([session, handle]) =>
+        this.sendOver(session, handle, frame),
+      ),
+    );
+  }
+
+  /** Sends a claim over every enrolled session to one peer, as an announcement or an answer its peer is waiting to converge on; a peer with no enrolled session is not machine-local and never carries a claim. */
+  async sendTo(
+    peerId: string,
+    frame: Readonly<CoordinatorFrame>,
+  ): Promise<void> {
+    await Promise.all(
+      [...this.enrolled]
+        .filter(([, handle]) => handle.id === peerId)
+        .map(async ([session, handle]) =>
+          this.sendOver(session, handle, frame),
+        ),
+    );
+  }
+
+  /** Sends a claim over one session. While an earlier send on it is still unresolved the claim replaces any one already waiting and this call returns at once; the send in flight then writes the newest waiting claim when it settles, so every send that does happen is awaited and the claim a peer finally reads is the newest one. */
+  private async sendOver(
+    session: AcceptedMeshSession,
+    handle: Readonly<ConnectionHandle>,
+    frame: Readonly<CoordinatorFrame>,
+  ): Promise<void> {
+    const slot = this.outbound.get(session) ?? {
+      sending: false,
+      waiting: undefined,
+    };
+    this.outbound.set(session, slot);
+    if (slot.sending) {
+      slot.waiting = frame;
+      return;
+    }
+    slot.sending = true;
+    let next: Readonly<CoordinatorFrame> | undefined = frame;
+    while (next !== undefined) {
+      await session.sendCoordinatorClaim(next).catch((error: unknown) => {
+        this.events.onError?.(
+          error instanceof Error
+            ? error
+            : new Error(`sendCoordinatorClaim(${handle.id}): ${String(error)}`),
+        );
+      });
+      // A session closed meanwhile has no one left to read what waits.
+      next = this.outbound.get(session) === slot ? slot.waiting : undefined;
+      slot.waiting = undefined;
+    }
+    slot.sending = false;
+  }
+}

package/src/core/error-reporting.ts

@@ -0,0 +1,85 @@
+/**
+ * Default sink for a mesh store's error channel. MeshStore.onError carries every failure the mesh handles internally (a hub dial that was refused, a gossip send that failed, a default-front session that could not attach), and nothing shows them unless a bridge assigns a handler, so a bridge without a UI of its own routes them to stderr.
+ */
+
+import { shortId } from "./display-name.js";
+import { errnoCode, PeerLinkError } from "./peer-link-error.js";
+
+/** The causes of a refused or dropped connection to a peer, which all mean the process behind that address has gone. */
+const PEER_GONE_CODES: ReadonlySet<string> = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+]);
+
+/** The causes of a first-contact broadcast that found no network to leave through. */
+const NO_NETWORK_CODES: ReadonlySet<string> = new Set([
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+]);
+
+/** A mesh error as a person should read it: `message` says what happened, what it most likely means and whether anything needs doing, and `key` identifies the condition so a repeat of it can be recognised. */
+export interface DescribedMeshError {
+  key: string;
+  message: string;
+}
+
+function describePeerLinkError(
+  error: Readonly<PeerLinkError>,
+): DescribedMeshError {
+  const peer = shortId(error.peerId);
+  const code = errnoCode(error);
+  if (error.action === "send") {
+    return {
+      key: `peer-send:${error.peerId}`,
+      message: `The connection to peer ${peer} dropped while a message was being sent (${error.cause instanceof Error ? error.cause.message : String(error.cause)}). The peer most likely exited or restarted.`,
+    };
+  }
+  if (code !== undefined && PEER_GONE_CODES.has(code)) {
+    return {
+      key: `peer-gone:${error.peerId}`,
+      message: `Could not connect to peer ${peer} on port ${String(error.port)} (${code}). Its agent most likely exited or restarted, leaving a stale address behind, and no action is needed. If a peer that should be running stays unreachable, check that nothing is blocking connections to localhost.`,
+    };
+  }
+  return {
+    key: `peer-dial:${error.peerId}`,
+    message: `Could not connect to peer ${peer} on port ${String(error.port)}: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}`,
+  };
+}
+
+/** Recognises the mesh failures that have a known meaning and a usual remedy, and returns them described for a person. Anything else is `undefined` and is reported as it came. */
+export function describeMeshError(
+  error: Readonly<Error>,
+): DescribedMeshError | undefined {
+  if (error instanceof PeerLinkError) return describePeerLinkError(error);
+  const code = errnoCode(error);
+  if (code !== undefined && NO_NETWORK_CODES.has(code)) {
+    return {
+      key: `no-network:${code}`,
+      message: `Could not reach the local network to look for agents on other machines (${code}). Check that the network is connected; agents on this machine still find each other, and discovery of other machines resumes once a network is available.`,
+    };
+  }
+  return undefined;
+}
+
+/** The single line a mesh error is reported as. */
+export function formatMeshError(error: Readonly<Error>): string {
+  return `agent-comms: ${describeMeshError(error)?.message ?? error.message}\n`;
+}
+
+/** Builds the handler a bridge assigns to `store.onError`, writing each error to `write` as one line. `write` defaults to the process's stderr, which stdio bridges keep clear of protocol traffic. A recognised condition is written once per reporter: a stale peer or a missing network repeats on every dial and beacon, and a second line says nothing the first did not. Errors with no known meaning are always written. Returns the handler rather than assigning it, so the caller does the assignment itself, like wireDefaultCcPeerFront does for onCoordinatorRoleChanged. */
+export function createMeshErrorReporter(
+  write: (line: string) => void = (line) => {
+    process.stderr.write(line);
+  },
+): (error: Error) => void {
+  const reported = new Set<string>();
+  return (error) => {
+    const described = describeMeshError(error);
+    if (described !== undefined) {
+      if (reported.has(described.key)) return;
+      reported.add(described.key);
+    }
+    write(formatMeshError(error));
+  };
+}

package/src/core/first-contact.ts

@@ -0,0 +1,242 @@
+/**
+ * FirstContact: default-on machine-local mesh formation without a coordinator (agent-comms#341). A small UDP presence on the shared beacon port (19877, the same port and payload shape discovery-mdns.ts's own backend uses, so both interoperate on the wire) that lets two peers on the same network find and dial each other directly.
+ *
+ * The protocol is two packets. A beacon, sent immediately at start and on the same interval discovery-mdns.ts beacons on: `{"type":"agent-comms-beacon","name":...,"port":...,"peerId":...}`, carrying this store's own DATA port, the port a discovering peer actually dials (the coordinator port was never the thing to advertise here: formation needs peers, not a rendezvous). A probe (`{"type":"agent-comms-probe"}`), sent once at start so a joining peer does not wait out a full beacon interval: any peer hearing it answers at once with a fresh beacon.
+ *
+ * Every packet goes to two destinations, never to a unicast address. Peers on the same host all share one UDP port (reuseAddr), and a unicast datagram to a shared port reaches only ONE of the sockets bound to it, which one being platform-dependent: a probe answer sent back to its prober would land on the answerer itself. Loopback multicast (FIRST_CONTACT_GROUP joined on 127.0.0.1) reaches every socket bound to the port and needs no live network, so it carries same-host formation; limited broadcast reaches other machines on the LAN. That is also why a probe is answered with a broadcast beacon rather than a reply to the prober: the reply has to be heard by the prober's socket specifically, and only a many-receiver destination guarantees it.
+ *
+ * Discovered peers are handed to the caller's onPeerDiscovered as (peerId, host, data port), and the caller feeds them through the existing peer_list path (PeerLifecycle.handlePeerList), which already dials every peer it learns about; each established connection then shares its own peer list, so the data-connection graph forms transitively by flooding and no rendezvous peer-list handout is needed. A peer's own beacon reaching itself (loopback delivery, or a second bridge in the same slot) is dropped by peerId, not by address, because a multi-homed host can legitimately hear itself on more than one interface address.
+ *
+ * Deliberately independent of DiscoveryManager: that manager is the opt-in, tool-facing advertise/discover surface (mesh_advertise/mesh_discover) with its own visibility semantics, and default-on formation must not change what those actions mean. This module owns its socket lifecycle entirely (start/stop), keeps no state beyond it, and never blocks a caller: probe answers and discovery callbacks arrive asynchronously on the socket's own events.
+ */
+
+import * as dgram from "node:dgram";
+import type { PeerInfo } from "./wire-protocol.js";
+import { isWebBeaconPayload } from "./web-beacon.js";
+
+/** The shared beacon port, the same one discovery-mdns.ts's backend uses: one presence per machine-local network, interoperable payloads. */
+export const FIRST_CONTACT_PORT = 19877;
+
+/** The administratively scoped multicast group (239.255.0.0/16, organisation-local scope) joined on the loopback interface, so every same-host socket bound to the beacon port hears every packet whatever the state of the network. */
+export const FIRST_CONTACT_GROUP = "239.255.19.77";
+
+/** The loopback interface the group is joined and sent on, and the address same-host multicast packets arrive from. */
+const LOOPBACK_INTERFACE = "127.0.0.1";
+
+/** The limited-broadcast address that carries beacons and probes to other machines on the LAN. */
+export const BROADCAST_ADDRESS = "255.255.255.255";
+
+/** How often the beacon repeats once started; matching discovery-mdns.ts's own interval so the two presences behave alike on the wire. */
+export const FIRST_CONTACT_INTERVAL_MS = 30_000;
+
+/** The one shape every beacon carries. Extension-safe for other consumers: parsers must ignore fields they do not know (discovery-mdns.ts's parseBeacon already does). */
+interface BeaconPayload {
+  type: "agent-comms-beacon";
+  /** This store's own peer id, so a peer can drop its own beacon reaching it back. */
+  peerId: string;
+  /** This store's data-server port: the port a discovering peer dials. */
+  port: number;
+  name: string;
+}
+
+/** A peer this side discovered and can dial directly. */
+export interface DiscoveredPeer {
+  peerId: string;
+  host: string;
+  port: number;
+}
+
+export interface FirstContactOptions {
+  /** This store's own peer id, for the self-beacon guard. */
+  peerId: string;
+  /** This store's own data-server port, the port beacons advertise. */
+  dataPort: number;
+  /** A human-readable name for the beacon payload, matching discovery-mdns.ts's own name field. */
+  name: string;
+  /** Called once per discovered peer (deduplicated by peerId within this instance's lifetime). */
+  onPeerDiscovered: (peer: Readonly<DiscoveredPeer>) => void;
+  /** Called for every web UI beacon heard (agent-comms#353), with the host taken from the datagram's source address. Not deduplicated: a beacon repeats on the presence's own interval, and the receiver refreshes its entry each time. Absent means this presence ignores web beacons, today's behaviour before the receiving side existed. */
+  onWebBeacon?: (
+    beacon: Readonly<{ peerId: string; host: string; webPort: number }>,
+  ) => void;
+  /** The UDP port the presence binds, beacons, and probes on. Defaults to FIRST_CONTACT_PORT; overridable so tests take an OS-assigned free port rather than contending with a real machine presence. */
+  port?: number;
+  /** Reported, never fatal: a network where broadcast is unavailable (some cloud environments) simply yields no discovery. */
+  onError?: (error: Error) => void;
+}
+
+export class FirstContact {
+  private socket: dgram.Socket | undefined;
+  private beaconTimer: ReturnType<typeof setInterval> | undefined;
+  private readonly seenPeerIds = new Set<string>();
+
+  constructor(private readonly opts: Readonly<FirstContactOptions>) {}
+
+  /** Starts the presence: bind, beacon once and on interval, and broadcast one probe round so nearby peers answer at once instead of on their next beacon. Never throws: a bind failure (another process holds the port without reuse, or the network forbids it) is reported through onError and simply leaves this peer discoverable by others' probes unanswered. */
+  start(): void {
+    if (this.socket) return;
+    const socket = dgram.createSocket({ type: "udp4", reuseAddr: true });
+    socket.on("error", (err: Error) => {
+      this.opts.onError?.(err);
+    });
+    socket.on("message", (msg: Buffer, rinfo: dgram.RemoteInfo) => {
+      this.handlePacket(msg, rinfo);
+    });
+    socket.bind(this.opts.port ?? FIRST_CONTACT_PORT, () => {
+      socket.setBroadcast(true);
+      try {
+        socket.addMembership(FIRST_CONTACT_GROUP, LOOPBACK_INTERFACE);
+        socket.setMulticastInterface(LOOPBACK_INTERFACE);
+        socket.setMulticastLoopback(true);
+      } catch (error) {
+        // Reported, not fatal: a host whose loopback interface cannot carry multicast (a Linux container without it, say) still gets LAN broadcast, so the presence degrades to cross-machine discovery rather than failing outright.
+        this.opts.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+      this.sendBeacon();
+      this.sendProbe();
+      this.beaconTimer = setInterval(() => {
+        this.sendBeacon();
+      }, FIRST_CONTACT_INTERVAL_MS);
+    });
+    this.socket = socket;
+  }
+
+  /** Stops the presence and releases the port. Idempotent. */
+  stop(): void {
+    if (this.beaconTimer !== undefined) {
+      clearInterval(this.beaconTimer);
+      this.beaconTimer = undefined;
+    }
+    const socket = this.socket;
+    this.socket = undefined;
+    if (socket) {
+      socket.close();
+    }
+  }
+
+  private handlePacket(msg: Buffer, rinfo: dgram.RemoteInfo): void {
+    const parsed: unknown = this.parseJson(msg);
+    if (isWebBeaconPayload(parsed)) {
+      if (parsed.peerId === this.opts.peerId) return;
+      this.opts.onWebBeacon?.({
+        peerId: parsed.peerId,
+        host: rinfo.address,
+        webPort: parsed.webPort,
+      });
+      return;
+    }
+    if (!isBeaconPayload(parsed)) {
+      // A probe from another peer: answer at once with a fresh beacon on the same many-receiver destinations (see the header comment on why never a unicast reply), so the prober does not wait out our interval.
+      if (isProbePayload(parsed)) {
+        this.sendBeacon();
+      }
+      return;
+    }
+    if (parsed.peerId === this.opts.peerId) return;
+    if (this.seenPeerIds.has(parsed.peerId)) return;
+    this.seenPeerIds.add(parsed.peerId);
+    this.opts.onPeerDiscovered({
+      peerId: parsed.peerId,
+      host: rinfo.address,
+      port: parsed.port,
+    });
+  }
+
+  private sendBeacon(): void {
+    const port = this.opts.port ?? FIRST_CONTACT_PORT;
+    this.sendBeaconTo(FIRST_CONTACT_GROUP, port);
+    this.sendBeaconTo(BROADCAST_ADDRESS, port);
+  }
+
+  private sendBeaconTo(address: string, port: number): void {
+    const socket = this.socket;
+    if (socket === undefined) return;
+    const payload: BeaconPayload = {
+      type: "agent-comms-beacon",
+      peerId: this.opts.peerId,
+      port: this.opts.dataPort,
+      name: this.opts.name,
+    };
+    socket.send(JSON.stringify(payload), port, address, (err) => {
+      if (err) {
+        this.opts.onError?.(err);
+      }
+    });
+  }
+
+  private sendProbe(): void {
+    const socket = this.socket;
+    if (socket === undefined) return;
+    const probe = JSON.stringify({ type: "agent-comms-probe" });
+    const port = this.opts.port ?? FIRST_CONTACT_PORT;
+    for (const address of [FIRST_CONTACT_GROUP, BROADCAST_ADDRESS]) {
+      socket.send(probe, port, address, (err) => {
+        if (err) {
+          this.opts.onError?.(err);
+        }
+      });
+    }
+  }
+
+  private parseJson(msg: Buffer): unknown {
+    try {
+      return JSON.parse(msg.toString());
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function isBeaconPayload(value: unknown): value is BeaconPayload {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("type" in value) || value.type !== "agent-comms-beacon") return false;
+  if (!("peerId" in value) || typeof value.peerId !== "string") return false;
+  if (!("port" in value) || typeof value.port !== "number") return false;
+  if (!("name" in value) || typeof value.name !== "string") return false;
+  return true;
+}
+
+function isProbePayload(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  return "type" in value && value.type === "agent-comms-probe";
+}
+
+/** How much of the peer id the beacon's human-readable name carries: enough to tell two beacons apart in a packet capture, not an identity claim (the full peerId field beside it is that). */
+const BEACON_NAME_PEER_ID_CHARS = 8;
+
+/**
+ * The store-side half of the wiring (agent-comms#341), kept here rather than in mesh-store.ts so that file stays under the repo's max-lines cap, the same reason its other collaborators were split out: constructs, starts, and returns the presence, mapping each discovered peer into a PeerInfo (host from the beacon's source address, port from its payload) for the caller to feed into the ordinary peer-list flood.
+ */
+export function startFirstContact(
+  input: Readonly<{
+    peerId: string;
+    dataPort: number;
+    port: number;
+    onPeer: (peer: Readonly<PeerInfo>) => void;
+    onWebBeacon?: FirstContactOptions["onWebBeacon"];
+    onError: (error: Error) => void;
+  }>,
+): FirstContact {
+  const presence = new FirstContact({
+    peerId: input.peerId,
+    dataPort: input.dataPort,
+    name: `agent-comms-${input.peerId.slice(0, BEACON_NAME_PEER_ID_CHARS)}`,
+    port: input.port,
+    ...(input.onWebBeacon !== undefined
+      ? { onWebBeacon: input.onWebBeacon }
+      : {}),
+    onPeerDiscovered: (peer) => {
+      input.onPeer({
+        id: peer.peerId,
+        port: peer.port,
+        startedAt: new Date().toISOString(),
+        host: peer.host,
+      });
+    },
+    onError: input.onError,
+  });
+  presence.start();
+  return presence;
+}