agent-comms 8.15.8 → 8.15.10

package/src/core/capability-ask.ts

@@ -0,0 +1,162 @@
+/**
+ * CapabilityAskAdmission — the ask tier surfaced at the tool layer (agent-comms#165): the generic, capability-agnostic counterpart to RoomProtocol's own pendingRoomJoins and ConnectionApproval's own pendingInboundConnections, built directly on wire-mesh-core's createCapabilityRequestHandler (the ask primitive agent-comms#164's own bubble-up module already builds on top of, wire-mesh#78). Three tiers exist at the tool layer for whether an action gets a capability token: allow (a held token already answers canGrant), deny (canGrant says no and resolveBubbleUpRoute finds no route to bubble the ask up to either), and ask -- a capability-request held open pending a human decision, which is what this module gives a name and a surface to. A capability-gated verb that lands in that third tier registers a handler built by createAskHandler below instead of failing outright: the request is held open exactly as core/room's own room.join admission holds one open, surfaced to the owning agent as a capability_request delivery event a human can act on (the approval prompt), and the outcome (acceptCapabilityRequest/rejectCapabilityRequest) resolves the held request in place, minting the granted token on acceptance -- the same accept/reject/list shape room_accept/room_reject/room_pending and mesh_accept/mesh_reject/mesh_pending already establish in tool.ts, generalised the way the issue's own framing asks for ("mirror its shape for capability requests generally"). With only one user-principal identity per machine today (agent-comms#160/#161), "the right device or principal" the issue's own framing anticipates routing an ask to is currently always this device -- the same simplification core/room's own single-decision-maker admission already makes; createAskHandler is the integration point a future capability-gated verb (e.g. agent-comms#162's dm:send) registers against its own session to get a ready `(incoming) => Promise<void>` handler backed by this admission's live pending state.
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { createCapabilityRequestHandler } from "wire-mesh-core/domain/capability-request";
+import type {
+  CapabilityGrantRequestEvent,
+  CapabilityGrantDecision,
+} from "wire-mesh-core/domain/capability-request";
+import type { IncomingManageRequest } from "wire-mesh-core/domain/mesh-session";
+import type {
+  CapabilityScope,
+  DeviceId,
+} from "wire-mesh-core/generated/protocol";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import { nanoid } from "./nanoid.js";
+import { CommsError } from "./store.js";
+import type { DeliveryEngine } from "./delivery-engine.js";
+import type { DeliveryEvent } from "./types.js";
+
+/** The state and collaborators CapabilityAskAdmission needs from MeshStore -- getPeerId/getOnDelivery/queueDelivery mirror ConnectionApprovalDeps exactly, since surfacing a capability_request event to the owning agent is the identical "queue it, then push it live if a callback is registered" mechanism connection_request already uses. */
+export interface CapabilityAskAdmissionDeps {
+  getPeerId: () => string;
+  getOnDelivery: () =>
+    | ((agentId: string, event: DeliveryEvent) => void | Promise<void>)
+    | undefined;
+  queueDelivery: DeliveryEngine["queueDelivery"];
+}
+
+export interface CreateCapabilityAskHandlerOptions {
+  /** The capability this handler surfaces asks for -- one handler per capability, the same convention createCapabilityRequestHandler and createBubbleUpCapabilityRequestHandler already establish. */
+  capability: string;
+  identity: IdentityPort;
+  clock: Clock;
+  /** The peer device-id authenticated on this session's own connection -- the requester, and so the future bearer of any token accepting the ask mints. */
+  bearerDevice: DeviceId;
+  /** Receiver-side auto-reject window (wire-mesh#81): how long the ask may sit awaiting a human decision before wire-mesh-core's own createCapabilityRequestHandler responds with a manage-error timeout on this admission's behalf. */
+  timeoutMs: number;
+}
+
+interface PendingCapabilityAsk {
+  capability: string;
+  scope: Readonly<CapabilityScope>;
+  requesterDevice: DeviceId;
+  decide: (decision: Readonly<CapabilityGrantDecision>) => Promise<void>;
+}
+
+export class CapabilityAskAdmission {
+  private readonly pending = new Map<string, PendingCapabilityAsk>();
+
+  constructor(private readonly deps: Readonly<CapabilityAskAdmissionDeps>) {}
+
+  /** Builds a manage-request handler for one capability's incoming capability-requests that never decides on its own: every not-malformed, not-yet-expired ask is held open and surfaced as a capability_request delivery event, exactly like handleConnectionRequest already does for an inbound mesh connection. */
+  createAskHandler(
+    options: Readonly<CreateCapabilityAskHandlerOptions>,
+  ): (incoming: Readonly<IncomingManageRequest>) => Promise<void> {
+    return createCapabilityRequestHandler({
+      capability: options.capability,
+      identity: options.identity,
+      clock: options.clock,
+      bearerDevice: options.bearerDevice,
+      timeoutMs: options.timeoutMs,
+      onRequest: (event: Readonly<CapabilityGrantRequestEvent>) => {
+        this.handleCapabilityRequest(options.capability, event);
+      },
+    });
+  }
+
+  private handleCapabilityRequest(
+    capability: string,
+    event: Readonly<CapabilityGrantRequestEvent>,
+  ): void {
+    const requestId = nanoid();
+    this.pending.set(requestId, {
+      capability,
+      scope: event.scope,
+      requesterDevice: event.requesterDevice,
+      decide: event.decide,
+    });
+
+    const deliveryEvent: DeliveryEvent = {
+      type: "capability_request",
+      requestId,
+      capability,
+      scopeKind: event.scope.kind,
+      ...(event.scope.path !== undefined
+        ? { scopePath: event.scope.path }
+        : {}),
+      requesterDevice: deviceIdToHex(event.requesterDevice),
+    };
+    const peerId = this.deps.getPeerId();
+    this.deps.queueDelivery(peerId, deliveryEvent);
+    const onDelivery = this.deps.getOnDelivery();
+    if (onDelivery) {
+      void onDelivery(peerId, deliveryEvent);
+    }
+  }
+
+  /** Every capability-request currently held open awaiting a human decision. */
+  listPendingCapabilityRequests(): {
+    requestId: string;
+    capability: string;
+    scopeKind: string;
+    scopePath?: string;
+    requesterDevice: string;
+  }[] {
+    return [...this.pending.entries()].map(([requestId, ask]) => ({
+      requestId,
+      capability: ask.capability,
+      scopeKind: ask.scope.kind,
+      ...(ask.scope.path !== undefined ? { scopePath: ask.scope.path } : {}),
+      requesterDevice: deviceIdToHex(ask.requesterDevice),
+    }));
+  }
+
+  /** Approves a pending capability-request, resolving its held decide() with an accept -- wire-mesh-core's own createCapabilityRequestHandler mints the granted token and responds on this admission's behalf. `capability`, when given, grants something narrower than what was originally asked for (the primitive's own CapabilityGrantDecision allows this); absent, the request's own originally-asked-for capability is granted unchanged. */
+  async acceptCapabilityRequest(
+    requestId: string,
+    options: Readonly<{
+      expires: number;
+      delegationsRemaining?: number;
+      capability?: string;
+    }>,
+  ): Promise<void> {
+    const pending = this.requirePending(requestId);
+    this.pending.delete(requestId);
+    await pending.decide({
+      kind: "accept",
+      capability: options.capability ?? pending.capability,
+      expires: options.expires,
+      ...(options.delegationsRemaining !== undefined
+        ? { delegationsRemaining: options.delegationsRemaining }
+        : {}),
+    });
+  }
+
+  /** Denies a pending capability-request, optionally with a reason surfaced to the requester in the resulting manage-error's own message field. */
+  async rejectCapabilityRequest(
+    requestId: string,
+    reason?: string,
+  ): Promise<void> {
+    const pending = this.requirePending(requestId);
+    this.pending.delete(requestId);
+    await pending.decide({
+      kind: "reject",
+      ...(reason !== undefined ? { reason } : {}),
+    });
+  }
+
+  private requirePending(requestId: string): PendingCapabilityAsk {
+    const pending = this.pending.get(requestId);
+    if (pending === undefined) {
+      throw new CommsError(
+        `No pending capability request ${requestId}`,
+        "NOT_PENDING",
+      );
+    }
+    return pending;
+  }
+}

package/src/core/capability-bubble-up.ts

@@ -0,0 +1,237 @@
+/**
+ * The routing policy for the ask tier's escalation path (agent-comms#164): walking a held capability token's own issuer chain when the immediate holder cannot grant a request itself. wire-mesh's capability-request primitive (domain/capability-request.ts) already carries the ask/held-open/decide/mint mechanics of a single hop; gossip-advertised grant candidates (domain/grant-candidates.ts) already answer "who nearer than the root can grant" for a requester picking its first hop. Neither decides what an intermediate device, having received a request it cannot fully satisfy from its own authority, should do next: that per-hop decision, and the handler that acts on it by minting a delegated child or forwarding the same ask further up the chain, is what this module adds.
+ *
+ * Two responsibilities, split the same way capability-request.ts already splits its own: resolveBubbleUpRoute is the pure decision (grant from held depth, forward to the held token's own issuer, or no-route), and createBubbleUpCapabilityRequestHandler is the wire-facing orchestration that acts on it. Deliberately built directly on wire-mesh's exported mintCapabilityToken rather than reusing createCapabilityRequestHandler's own decide(): that primitive's accept path always mints a root token (no `parent`), which is correct for the primitive's own reference consumer (a room owner minting membership tokens directly) but cannot express "mint a narrower child of the token I already hold", the one thing granting from delegated depth actually requires.
+ */
+
+import { buildCapabilityRequestCommand } from "wire-mesh-core/domain/capability-request";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type {
+  MeshSession,
+  IncomingManageRequest,
+} from "wire-mesh-core/domain/mesh-session";
+import {
+  canGrant,
+  mintCapabilityToken,
+  verifyCapabilityToken,
+  type RevocationCheck,
+} from "wire-mesh-core/domain/tokens";
+import {
+  capabilityGrantOkSchema,
+  capabilityRequestSchema,
+  type CapabilityScope,
+  type CapabilityToken,
+  type DeviceId,
+} from "wire-mesh-core/generated/protocol";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import { randomId } from "./random-id.js";
+
+export interface ResolveBubbleUpRouteOptions {
+  /** This device's own held credential establishing its authority over `capability`/`scope`, if it holds one at all. A device with none is either the capability's own structural root (which mints fresh from its own identity, outside this module's concern -- see wire-mesh's own createCapabilityRequestHandler for that path) or genuinely has nothing to grant or forward from. */
+  heldToken: CapabilityToken | undefined;
+  /** This device's own identity: both the crypto primitives heldToken is verified with, and (via `.deviceId`) the bearer heldToken must actually name. */
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationCheck;
+  /** The capability and scope the incoming ask is for -- forwarded unchanged from the request this route decides for. */
+  capability: string;
+  scope: Readonly<CapabilityScope>;
+  /** The expiry and delegation depth a grant would carry if minted at this hop, checked against heldToken's own narrowing bounds via canGrant. The caller (see createBubbleUpCapabilityRequestHandler) owns this policy; this module only evaluates it. */
+  expires: number;
+  delegationsRemaining?: number;
+}
+
+export type BubbleUpRoute =
+  | { kind: "grant"; token: CapabilityToken }
+  | { kind: "forward"; target: DeviceId }
+  | {
+      kind: "no-route";
+      reason: "no-held-token" | "held-token-invalid" | "self-issued";
+    };
+
+/**
+ * Decides, for one device holding (or not holding) a capability token, whether it can grant a request for `capability`/`scope`/`expires`/`delegationsRemaining` from its own held depth, must forward the same ask to whoever issued its own token, or has no route to a grantor at all.
+ *
+ * heldToken is independently verified here (signature, expiry, revocation, and that this device is genuinely its bearer) via verifyCapabilityToken rather than trusted as already-checked: a caller's own held-token cache can go stale (expiry, a since-recorded revocation) between when it was stored and when this decision runs, and granting or forwarding on an invalid credential would be a real authority leak, not merely a stale-read symptom.
+ *
+ * Ordering matches the issue's own framing (agent-comms#164): a device with real remaining depth grants outright (checked via canGrant, the same narrowing arithmetic mintCapabilityToken itself enforces, so this decision and the mint it authorises can never disagree); otherwise, absent a nearer route this module has no way to discover on its own (see grant-candidates.ts for the requester's own gossip-based shortcut, deliberately a separate concern), the only further hop toward the root a token's own claims expose is its issuer. Forwarding to that issuer when it is this very device (a self-issued token, which canGrant already found could not satisfy the request) would loop forever, so that case reports no-route instead.
+ */
+export async function resolveBubbleUpRoute(
+  options: Readonly<ResolveBubbleUpRouteOptions>,
+): Promise<BubbleUpRoute> {
+  if (options.heldToken === undefined) {
+    return { kind: "no-route", reason: "no-held-token" };
+  }
+
+  const verdict = await verifyCapabilityToken(options.heldToken, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.identity.deviceId,
+  });
+  if (!verdict.ok) {
+    return { kind: "no-route", reason: "held-token-invalid" };
+  }
+
+  const canGrantDirectly = await canGrant(
+    options.heldToken,
+    options.identity.deviceId,
+    {
+      capability: options.capability,
+      scope: options.scope,
+      expires: options.expires,
+      ...(options.delegationsRemaining !== undefined
+        ? { delegationsRemaining: options.delegationsRemaining }
+        : {}),
+    },
+    options.clock.now(),
+  );
+  if (canGrantDirectly) {
+    return { kind: "grant", token: options.heldToken };
+  }
+
+  if (
+    deviceIdToHex(verdict.claims.issuer) ===
+    deviceIdToHex(options.identity.deviceId)
+  ) {
+    return { kind: "no-route", reason: "self-issued" };
+  }
+  return { kind: "forward", target: verdict.claims.issuer };
+}
+
+export interface CreateBubbleUpCapabilityRequestHandlerOptions {
+  /** The capability this handler grants or forwards asks for, checked against the incoming request's own `params.capability`. One handler is constructed per capability, the same convention capability-request.ts's own createCapabilityRequestHandler already establishes. */
+  capability: string;
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationCheck;
+  /** The peer device-id authenticated on this session's own connection -- the requester, and so the bearer of whichever token this handler ultimately mints (whether granted from own depth or re-delegated from an upstream grant). */
+  bearerDevice: DeviceId;
+  /** The expiry and delegation depth this handler mints with, at either hop (its own grant, or its re-delegation of an upstream one). A fixed per-handler policy, not per-request: the wire-level capability-request carries no requested expiry or depth of its own (management.cddl leaves both to the granter), matching the same policy CapabilityGrantDecision.expires/delegationsRemaining already leaves to the domain in wire-mesh's base primitive. */
+  expires: number;
+  delegationsRemaining?: number;
+  /** Looks up this device's own currently held credential for `capability`, if any, at the moment each request is handled -- a function rather than a static value since a held token can be minted, renewed, or revoked over the handler's own lifetime. */
+  ownToken: () => CapabilityToken | undefined;
+  /** Used to forward an ask this device cannot grant itself further up the issuer chain. Only sendManageRequest is used, so a caller can supply a minimal stand-in in tests rather than a full MeshSession. */
+  session: Pick<MeshSession, "sendManageRequest">;
+  /** Bounds how long a forwarded ask waits for the next hop's own answer, forwarded directly to sendManageRequest's own identically-named parameter. Absent, a forward waits with no time limit of its own, exactly as sendManageRequest already behaves. */
+  forwardTimeoutMs?: number;
+}
+
+/**
+ * Builds a reusable handler for one capability's incoming capability-requests that answers each one by walking the issuer chain: grant a delegated child from this device's own held depth when resolveBubbleUpRoute says it can, forward the identical ask to the held token's own issuer and re-delegate whatever grant comes back when it cannot, or refuse outright when there is no route to a grantor at all.
+ *
+ * Parses and validates the incoming request the same way capability-request.ts's own createCapabilityRequestHandler does (wrong capability or malformed payload refuses `{result:"error",code:"malformed"}`; an already-expired `valid-until` refuses `{result:"error",code:"expired"}`), so a requester using the ordinary requestCapability wrapper sees identical wire behaviour from either handler.
+ *
+ * A forward's own upstream outcome is relayed verbatim on refusal (the exact code and message an intermediate or root grantor sent), rather than collapsed to a generic denial, so the original requester learns exactly what stopped the chain. A forward's own granted token is independently re-verified (expectedBearer this device's own identity) before being trusted as a mint parent: mintCapabilityToken's own `parent` handling only checks structural narrowing against the decoded claims, not the token's signature, expiry, or revocation status, so an unverified inbound grant would otherwise let a malicious or buggy upstream peer hand this device a bogus credential to unknowingly re-delegate.
+ */
+export function createBubbleUpCapabilityRequestHandler(
+  options: Readonly<CreateBubbleUpCapabilityRequestHandlerOptions>,
+): (incoming: Readonly<IncomingManageRequest>) => Promise<void> {
+  return async function handleBubbleUpCapabilityRequest(
+    incoming: Readonly<IncomingManageRequest>,
+  ): Promise<void> {
+    const parsed = capabilityRequestSchema.safeParse(incoming.command.params);
+    if (!parsed.success || parsed.data.capability !== options.capability) {
+      await incoming.respond({ result: "error", code: "malformed" });
+      return;
+    }
+    const validUntil = parsed.data["valid-until"];
+    if (validUntil !== undefined && validUntil <= options.clock.now()) {
+      await incoming.respond({ result: "error", code: "expired" });
+      return;
+    }
+
+    const route = await resolveBubbleUpRoute({
+      heldToken: options.ownToken(),
+      identity: options.identity,
+      clock: options.clock,
+      revocation: options.revocation,
+      capability: options.capability,
+      scope: incoming.scope,
+      expires: options.expires,
+      ...(options.delegationsRemaining !== undefined
+        ? { delegationsRemaining: options.delegationsRemaining }
+        : {}),
+    });
+
+    if (route.kind === "grant") {
+      await mintAndRespond(options, incoming, route.token);
+      return;
+    }
+
+    if (route.kind === "forward") {
+      const forwardOutcome = await options.session.sendManageRequest(
+        buildCapabilityRequestCommand(options.capability, validUntil),
+        incoming.scope,
+        route.target,
+        undefined,
+        options.forwardTimeoutMs,
+      );
+      if (forwardOutcome.result !== "ok") {
+        await incoming.respond(forwardOutcome);
+        return;
+      }
+      const parsedGrant = capabilityGrantOkSchema.safeParse(forwardOutcome);
+      if (!parsedGrant.success) {
+        await incoming.respond({ result: "error", code: "malformed" });
+        return;
+      }
+      const upstreamVerdict = await verifyCapabilityToken(
+        parsedGrant.data["granted-token"],
+        {
+          identity: options.identity,
+          clock: options.clock,
+          revocation: options.revocation,
+          expectedBearer: options.identity.deviceId,
+        },
+      );
+      if (!upstreamVerdict.ok) {
+        await incoming.respond({
+          result: "error",
+          code: upstreamVerdict.reason,
+        });
+        return;
+      }
+      await mintAndRespond(
+        options,
+        incoming,
+        parsedGrant.data["granted-token"],
+      );
+      return;
+    }
+
+    await incoming.respond({
+      result: "error",
+      code: "denied",
+      message: `no route to a grantor for "${options.capability}"`,
+    });
+  };
+}
+
+/** Mints a delegated child of `parent` (this device's own held token, or a freshly re-verified upstream grant) for the requester, and responds with it -- shared by both createBubbleUpCapabilityRequestHandler branches that end in a mint, so the two can never drift into two different ideas of what the resulting token should carry. */
+async function mintAndRespond(
+  options: Readonly<CreateBubbleUpCapabilityRequestHandlerOptions>,
+  incoming: Readonly<IncomingManageRequest>,
+  parent: CapabilityToken,
+): Promise<void> {
+  const verdict = await mintCapabilityToken({
+    identity: options.identity,
+    clock: options.clock,
+    tokenId: randomId(),
+    bearer: options.bearerDevice,
+    capability: options.capability,
+    scope: incoming.scope,
+    expires: options.expires,
+    ...(options.delegationsRemaining !== undefined
+      ? { delegationsRemaining: options.delegationsRemaining }
+      : {}),
+    parent,
+  });
+  if (!verdict.ok) {
+    await incoming.respond({ result: "error", code: "mint_failed" });
+    return;
+  }
+  await incoming.respond({ result: "ok", "granted-token": verdict.token });
+}

package/src/core/comms-store.ts

@@ -0,0 +1,130 @@
+/**
+ * CommsStore — abstract interface for the agent communication store.
+ *
+ * Two implementations: FileStore — filesystem-backed, no server process (fallback) MeshStore — TCP peer mesh, in-memory, real-time push (preferred)
+ *
+ * Bridges depend on this interface, not on a specific implementation.
+ *
+ * Deliberately excludes listener management and connection approval: those are transport concerns MeshStore alone can support -- FileStore has no network transport to manage listeners on or approve inbound connections for. Widening this interface to cover them (as it once did, via always-throwing FileStore stubs) is what forced server.ts and the bridge controller to reach past CommsStore into the concrete MeshStore anyway; CommsTool, the one consumer that genuinely needs to expose these when a MeshStore backs it, takes them as an optional extension (see MeshOnlyFeatures in tool.ts) rather than the shared interface pretending every implementation supports them.
+ */
+
+import type {
+  AgentIdentity,
+  DeliveryEvent,
+  DmMessage,
+  MessageDelivery,
+  Room,
+  RoomMessage,
+  RoomType,
+  StreamingBehavior,
+  Visibility,
+} from "./types.js";
+
+export interface SendRoomMessageOptions {
+  replyTo?: string | undefined;
+  streamingBehavior?: StreamingBehavior | undefined;
+  /** When true, `MeshStore` also records the message as a signed room-notice in the sender's own log for offline catch-up. `FileStore` ignores it, since it already persists every message. */
+  durable?: boolean | undefined;
+}
+
+/** What became of a room message for one specific member of that room. Delivery is per member because a room send fans out one directed request each, and a member that is unreachable right now is independent of every other. */
+export interface MemberDelivery {
+  member: string;
+  delivery: MessageDelivery;
+}
+
+/** A room message as sent: the message itself, plus what became of it for each member other than its sender. A caller that only wants the message reads `message`; one that needs to know whether anybody actually received it reads `deliveries`. */
+export interface SentRoomMessage {
+  message: RoomMessage;
+  deliveries: MemberDelivery[];
+}
+
+/** A DM as sent: the message itself, plus what became of it. Exactly one delivery state, since a DM has exactly one recipient. */
+export interface SentDm {
+  message: DmMessage;
+  delivery: MessageDelivery;
+}
+
+export interface CommsStore {
+  // -- Identity --
+  readIdentity: (
+    harness: string,
+    cwd: string,
+  ) => Promise<{ id: string } | undefined>;
+  writeIdentity: (harness: string, cwd: string, id: string) => Promise<void>;
+
+  // -- Agent registry --
+  registerAgent: (
+    opts: Readonly<{
+      name: string;
+      harness: string;
+      cwd: string;
+      pid: number;
+      visibility: Visibility;
+      tags: string[];
+    }>,
+  ) => Promise<AgentIdentity>;
+  getAgent: (id: string) => Promise<AgentIdentity | undefined>;
+  updateAgent: (
+    id: string,
+    patch: Partial<
+      Pick<AgentIdentity, "name" | "visibility" | "status" | "tags" | "pid">
+    >,
+  ) => Promise<AgentIdentity>;
+  listAgents: (requesterId: string) => Promise<AgentIdentity[]>;
+  setAgentOffline: (id: string) => Promise<void>;
+
+  // -- Rooms --
+  createRoom: (
+    opts: Readonly<{
+      name: string;
+      type: RoomType;
+      owner: string;
+      description: string;
+    }>,
+  ) => Promise<Room>;
+  getRoom: (id: string) => Promise<Room | undefined>;
+  listRooms: (requesterId: string) => Promise<Room[]>;
+  joinRoom: (roomId: string, agentId: string) => Promise<Room>;
+  leaveRoom: (roomId: string, agentId: string) => Promise<void>;
+  inviteToRoom: (
+    roomId: string,
+    targetId: string,
+    inviterId: string,
+  ) => Promise<void>;
+  declineInvite: (
+    roomId: string,
+    agentId: string,
+    reason: string,
+  ) => Promise<void>;
+  kickFromRoom: (
+    roomId: string,
+    targetId: string,
+    kickerId: string,
+  ) => Promise<void>;
+  destroyRoom: (roomId: string, agentId: string) => Promise<void>;
+
+  // -- Messages --
+  sendRoomMessage: (
+    roomId: string,
+    from: string,
+    content: string,
+    options?: SendRoomMessageOptions,
+  ) => Promise<SentRoomMessage>;
+  readRoomMessages: (roomId: string, since?: string) => Promise<RoomMessage[]>;
+
+  // -- DMs --
+  sendDm: (
+    from: string,
+    to: string,
+    content: string,
+    streamingBehavior?: StreamingBehavior,
+  ) => Promise<SentDm>;
+
+  // -- Delivery --
+  deliver: (agentId: string, event: DeliveryEvent) => Promise<void>;
+  drainDelivery: (agentId: string) => Promise<DeliveryEvent[]>;
+
+  // -- Lifecycle --
+  init: () => Promise<void>;
+}

package/src/core/connection-approval.ts

@@ -0,0 +1,134 @@
+/**
+ * ConnectionApproval — inbound mesh-connection admission: queues a connection_request for the owning agent to accept/reject, and the accept/reject/list/connectToRemote/startDataServerOnly operations around it. Split out of mesh-store.ts to reduce it under the repo's max-lines cap. Owns pendingInboundConnections exclusively -- nothing outside this class ever reads or writes it.
+ */
+
+import type { DeliveryEngine } from "./delivery-engine.js";
+import type { ConnectionHandle, MeshTransport } from "./transport.js";
+import type { AgentIdentity, DeliveryEvent } from "./types.js";
+import type { PeerInfo } from "./wire-protocol.js";
+
+/** The state and collaborators ConnectionApproval needs from MeshStore. agents/peerInfo are direct references into MeshStore's own fields; startedAt is a readonly value copied once (MeshStore never reassigns it); the closures read MeshStore's own current peerId/transport/onDelivery, and queueDelivery is DeliveryEngine's own already-constructed method. */
+export interface ConnectionApprovalDeps {
+  agents: Map<string, AgentIdentity>;
+  peerInfo: Map<string, PeerInfo>;
+  startedAt: string;
+  getPeerId: () => string;
+  requireTransport: () => MeshTransport;
+  getOnDelivery: () =>
+    | ((agentId: string, event: DeliveryEvent) => void | Promise<void>)
+    | undefined;
+  queueDelivery: DeliveryEngine["queueDelivery"];
+}
+
+export class ConnectionApproval {
+  private readonly pendingInboundConnections = new Map<
+    string,
+    { peerId: string; dataPort: number; name: string; fingerprint: string }
+  >();
+
+  constructor(private readonly deps: ConnectionApprovalDeps) {}
+
+  handleConnectionRequest(
+    handle: Readonly<ConnectionHandle>,
+    request: Readonly<{
+      peerId: string;
+      dataPort: number;
+      name: string;
+      fingerprint: string;
+    }>,
+  ): void {
+    this.pendingInboundConnections.set(handle.id, {
+      peerId: request.peerId,
+      dataPort: request.dataPort,
+      name: request.name,
+      fingerprint: request.fingerprint,
+    });
+
+    // Deliver connection_request event to the owning agent
+    const connectionId = handle.id;
+    const event: DeliveryEvent = {
+      type: "connection_request",
+      connectionId,
+      peerId: request.peerId,
+      dataPort: request.dataPort,
+      name: request.name,
+      fingerprint: request.fingerprint,
+    };
+    const peerId = this.deps.getPeerId();
+    this.deps.queueDelivery(peerId, event);
+    const onDelivery = this.deps.getOnDelivery();
+    if (onDelivery) {
+      void onDelivery(peerId, event);
+    }
+  }
+
+  /** Accept a pending inbound connection. */
+  async acceptConnection(connectionId: string): Promise<void> {
+    const pending = this.pendingInboundConnections.get(connectionId);
+    if (!pending) {
+      throw new Error(`No pending connection ${connectionId}`);
+    }
+    this.pendingInboundConnections.delete(connectionId);
+    const handle: ConnectionHandle = { id: connectionId };
+    await this.deps.requireTransport().acceptConnection(handle);
+  }
+
+  /** Reject a pending inbound connection. */
+  async rejectConnection(connectionId: string, reason: string): Promise<void> {
+    const pending = this.pendingInboundConnections.get(connectionId);
+    if (!pending) {
+      throw new Error(`No pending connection ${connectionId}`);
+    }
+    this.pendingInboundConnections.delete(connectionId);
+    const handle: ConnectionHandle = { id: connectionId };
+    await this.deps.requireTransport().rejectConnection(handle, reason);
+  }
+
+  /** List all pending inbound connections awaiting approval. */
+  listPendingConnections(): {
+    connectionId: string;
+    peerId: string;
+    dataPort: number;
+    name: string;
+    fingerprint: string;
+  }[] {
+    return [...this.pendingInboundConnections.entries()].map(([id, info]) => ({
+      connectionId: id,
+      ...info,
+    }));
+  }
+
+  /** Initiate an outbound connection to a remote coordinator requiring approval. Fires the connect_request and returns immediately. The connection completes asynchronously when the coordinator accepts or rejects. `host` is either a hostname (TLS-dialled with `port`) or a ws:// / wss:// URL (WebSocket-dialled to a hub such as mesh.exadev.io; the port is ignored). */
+  async connectToRemote(host: string, port: number): Promise<void> {
+    const peerId = this.deps.getPeerId();
+    const agent = this.deps.agents.get(peerId);
+    // Fire-and-forget: don't await the full approval handshake. The coordinator will either accept (triggering normal introduction flow) or reject (closing the socket). Handle rejection to avoid unhandled rejection.
+    this.deps
+      .requireTransport()
+      .connectToRemote({
+        host,
+        port,
+        peerId,
+        dataPort: this.deps.requireTransport().dataPort,
+        name: agent?.name ?? "",
+        fingerprint: "",
+      })
+      .catch(() => {
+        // Rejection is expected when the coordinator denies the connection. Log silently — the calling tool already returned success.
+      });
+
+    return Promise.resolve();
+  }
+
+  /** Start only the data server without connecting to a coordinator. Used for testing scenarios where the peer connects via connectToRemote. */
+  async startDataServerOnly(): Promise<void> {
+    await this.deps.requireTransport().startDataServer();
+    const peerId = this.deps.getPeerId();
+    this.deps.peerInfo.set(peerId, {
+      id: peerId,
+      port: this.deps.requireTransport().dataPort,
+      startedAt: this.deps.startedAt,
+    });
+    this.deps.requireTransport().unref();
+  }
+}