agent-comms 8.15.9 → 8.15.11

package/src/core/data-frame-routing.ts

@@ -0,0 +1,309 @@
+/**
+ * WireMeshTransport's own core/data frame dispatch (data-have, data-request, data-entries), split out under the repo's max-lines cap the same way gossip-directory.ts and hub-forwarding.ts were each split from the same owning file.
+ */
+
+import {
+  handleDataEntries,
+  handleDataHave,
+  handleDataRequest,
+} from "wire-mesh-core/domain/data-sync";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { isDataFrame } from "wire-mesh-core/domain/hub-mailbox";
+import type { DataDomainFrame } from "wire-mesh-core/domain/mesh-session";
+import type {
+  DataHaveFrame,
+  DataRequestFrame,
+  Frame,
+} from "wire-mesh-core/generated/protocol";
+import type { Connection } from "wire-mesh-core/ports/transport";
+import type { KeyValueStorage } from "wire-mesh-core/ports/storage";
+import type { AccountLedgerReplica } from "./account-ledger.js";
+import { readMembershipProof } from "./gossip-directory.js";
+import type { WireMeshTransportOptions } from "./wire-mesh-transport-options.js";
+
+/** The most entries one data-entries reply carries, for every log this side answers for, the account ledger's included: a longer log catches up over several rounds, so the bound only caps one frame's size. */
+export const DATA_ENTRIES_RESPONSE_LIMIT = 100;
+
+/** What the router needs to replicate the account's grant ledger (agent-comms#344). */
+export interface AccountReplication {
+  /** The ledger, read on every frame and every announcement round because it opens after the transport is built and is replaced when the machine joins another account. Undefined until it has opened. */
+  ledger: () => AccountLedgerReplica | undefined;
+  /** Whether the peer whose session authenticated it as `deviceHex` holds the same account. Only such a peer is offered the ledger or answered for it, so a device of another account never stores the ciphertext or follows its head. */
+  isAccountPeer: (deviceHex: string) => Promise<boolean>;
+}
+
+/** How core/data frames reach a device that this side meets only through the relay hub, over a relay pairing sealed end to end between the two devices: the hub carries ciphertext and never sees a frame. */
+export interface HubDataChannel {
+  /** The devices (hex) the hub's gossiped directory has admitted, whether or not this side also has a direct session to them. */
+  peers: () => readonly string[];
+  /** Sends one frame to `deviceHex` through the hub. Rejects when no hub session is live. */
+  send: (deviceHex: string, frame: DataDomainFrame) => Promise<void>;
+}
+
+/** The hub data channel over whatever hub session `hub()` currently returns, read on each call because the router is built before the hub it talks through. */
+export function hubDataChannel(
+  hub: () => {
+    peers: () => readonly string[];
+    sendDataFrame: (
+      deviceHex: string,
+      frame: Readonly<DataDomainFrame>,
+    ) => Promise<void>;
+  },
+): HubDataChannel {
+  return {
+    peers: () => hub().peers(),
+    send: async (deviceHex, frame) => hub().sendDataFrame(deviceHex, frame),
+  };
+}
+
+/** Builds the router's account replication from the transport option: a peer is an account peer when the membership proof in its gossiped advert (looked up through `advertOf`) verifies against this machine's own principal. Undefined when the transport has no account ledger. */
+export function accountReplicationFrom(
+  options: Readonly<WireMeshTransportOptions>["accountReplication"],
+  advertOf: (
+    deviceHex: string,
+  ) => Readonly<Record<string, unknown>> | undefined,
+): AccountReplication | undefined {
+  if (options === undefined) return undefined;
+  return {
+    ledger: options.getLedger,
+    isAccountPeer: async (deviceHex) => {
+      const advert = advertOf(deviceHex);
+      const proof =
+        advert === undefined
+          ? undefined
+          : readMembershipProof(advert, "membership");
+      return proof === undefined
+        ? false
+        : options.isAccountMember({ proof, deviceHex });
+    },
+  };
+}
+
+/** Routes one frame received on a raw data connection, tracking the connection against its peer's device-id along the way (connectionsByPeer, mutated in place) so a later data-have, data-request or data-entries send addressed to that same peer reuses it. Nothing further happens until the sender is a tracked peer session. A frame naming one of the account's writer logs goes to the account ledger when the sender holds the same account and is dropped otherwise, without reaching dataStorage either way; any other data frame goes to wire-mesh-core's own core/data handlers over dataStorage, and is dropped when this side has no dataStorage. Any handler error is reported via onError and swallowed, never thrown, since this runs inside the transport's own onFrame callback with no caller awaiting it directly. */
+export async function routeDataFrame(
+  deps: Readonly<{
+    connectionsByPeer: Map<string, Readonly<Connection>>;
+    dataStorage: KeyValueStorage | undefined;
+    account: Readonly<AccountReplication> | undefined;
+    peerSessions: ReadonlyMap<string, unknown>;
+    onError: ((error: Error) => void) | undefined;
+  }>,
+  connection: Readonly<Connection>,
+  frame: Frame,
+): Promise<void> {
+  const peerDeviceId = connection.peerDeviceId;
+  if (peerDeviceId === undefined) return;
+  const deviceIdHex = deviceIdToHex(peerDeviceId);
+  deps.connectionsByPeer.set(deviceIdHex, connection);
+  if (!deps.peerSessions.has(deviceIdHex)) return;
+  try {
+    const ledger = deps.account?.ledger();
+    if (
+      isDataFrame(frame) &&
+      ledger !== undefined &&
+      deps.account !== undefined &&
+      ledger.ownsLog(frame.peer)
+    ) {
+      if (!(await deps.account.isAccountPeer(deviceIdHex))) return;
+      const reply = await ledger.handleDataFrame(frame);
+      if (reply !== null) await connection.send(reply);
+      return;
+    }
+    if (deps.dataStorage === undefined) return;
+    if (frame.type === "data-have") {
+      const request = await handleDataHave(deps.dataStorage, frame);
+      if (request !== null) await connection.send(request);
+    } else if (frame.type === "data-request") {
+      const entries = await handleDataRequest(
+        deps.dataStorage,
+        frame,
+        DATA_ENTRIES_RESPONSE_LIMIT,
+      );
+      if (entries !== null) await connection.send(entries);
+    } else if (frame.type === "data-entries") {
+      await handleDataEntries(deps.dataStorage, frame);
+    }
+  } catch (error: unknown) {
+    deps.onError?.(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
+/** Handles one core/data frame that arrived through a relay pairing, from the device the pairing's secure channel authenticated as `fromDeviceHex`. Only a frame naming one of the account's writer logs, from a device that holds the same account, is acted on, and any answer goes back through the same pairing; every other relayed data frame is dropped, since a device met only through the hub has no standing to read or write this side's other logs. Any handler error is reported via onError and swallowed, as in routeDataFrame. */
+export async function routeRelayedDataFrame(
+  deps: Readonly<{
+    account: Readonly<AccountReplication> | undefined;
+    hub: Readonly<HubDataChannel> | undefined;
+    onError: ((error: Error) => void) | undefined;
+  }>,
+  fromDeviceHex: string,
+  frame: Readonly<DataDomainFrame>,
+): Promise<void> {
+  const { account, hub } = deps;
+  if (account === undefined || hub === undefined) return;
+  try {
+    const ledger = account.ledger();
+    if (ledger?.ownsLog(frame.peer) !== true) return;
+    if (!(await account.isAccountPeer(fromDeviceHex))) return;
+    const reply = await ledger.handleDataFrame(frame);
+    if (reply !== null) await hub.send(fromDeviceHex, reply);
+  } catch (error: unknown) {
+    deps.onError?.(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
+/** Offers every account writer log this machine holds to every device that holds the same account and that this side can reach (agent-comms#344): over a live, trusted data connection, or, for a device it meets only through the relay hub, over a relay pairing. Such a device that is behind asks for what it is missing, which is the data-domain fan-out that carries each machine's grants and revocations to every other. A device reachable both ways is offered the logs once, directly. Called on the gossip cadence, so a machine that was away when an entry was written still catches up the next time it is reachable. A send that fails is reported and the rest carry on; the next round retries it. */
+export async function announceAccountLedger(
+  deps: Readonly<{
+    connectionsByPeer: ReadonlyMap<string, Readonly<Connection>>;
+    account: Readonly<AccountReplication>;
+    hub: Readonly<HubDataChannel> | undefined;
+    peerSessions: ReadonlyMap<string, unknown>;
+    onError: ((error: Error) => void) | undefined;
+  }>,
+): Promise<void> {
+  const ledger = deps.account.ledger();
+  if (ledger === undefined) return;
+  const frames = await ledger.announcements();
+  if (frames.length === 0) return;
+  const reportError = (error: unknown): void => {
+    deps.onError?.(error instanceof Error ? error : new Error(String(error)));
+  };
+  const direct = new Set<string>();
+  const offers: Promise<void>[] = [];
+  for (const [deviceHex, connection] of deps.connectionsByPeer) {
+    if (!deps.peerSessions.has(deviceHex)) continue;
+    if (!(await deps.account.isAccountPeer(deviceHex))) continue;
+    direct.add(deviceHex);
+    for (const frame of frames) {
+      try {
+        await connection.send(frame);
+      } catch (error: unknown) {
+        reportError(error);
+      }
+    }
+  }
+  const { hub } = deps;
+  if (hub === undefined) return;
+  for (const deviceHex of hub.peers()) {
+    if (direct.has(deviceHex)) continue;
+    if (!(await deps.account.isAccountPeer(deviceHex))) continue;
+    // Each device is offered concurrently: a pairing to a device that is not there waits out its own handshake, which must not hold up the others.
+    offers.push(
+      (async () => {
+        for (const frame of frames) {
+          try {
+            await hub.send(deviceHex, frame);
+          } catch (error: unknown) {
+            reportError(error);
+          }
+        }
+      })(),
+    );
+  }
+  await Promise.all(offers);
+}
+
+export interface DataFrameRouterDeps {
+  dataStorage: KeyValueStorage | undefined;
+  /** Absent for a transport with no account ledger. */
+  account: Readonly<AccountReplication> | undefined;
+  /** The transport's own trusted sessions, keyed by device-id hex: the gate every data frame and every announcement passes. */
+  peerSessions: ReadonlyMap<string, unknown>;
+  onError: ((error: Error) => void) | undefined;
+  /** Absent for a transport that never dials a relay hub. */
+  hub: Readonly<HubDataChannel> | undefined;
+  /** How often the account ledger is offered to peers: the transport's own re-advertise cadence. */
+  announceIntervalMs: number;
+}
+
+/** WireMeshTransport's core/data state and dispatch, split out under the repo's max-lines cap: the connection each peer's frames arrive on, routing of every data frame received, the mechanical send primitive, and the periodic offer of the account ledger's writer logs, and the same exchange with a device met only through the relay hub. */
+export class DataFrameRouter {
+  /** Backs this side's own responder for an incoming data-have, data-request or data-entries frame about any log other than the account ledger's (agent-comms#50's P5 integration). When undefined, such frames are dropped; the account ledger's are routed either way. For those logs, deciding when to proactively call sendDataFrame at all (the catch-up policy: which peers' logs to track, when to send an initial data-have) stays the caller's business and this field only backs the mechanical parts (answering a have or request, storing entries); the account ledger's own offers are the router's, sent every announceIntervalMs. */
+  private readonly dataStorage: KeyValueStorage | undefined;
+
+  /** Every peer this side has ever received a frame from, keyed by device-id hex, tracking the raw wire-mesh-core Connection each frame arrived on: what sendDataFrame needs, since neither AcceptedMeshSession nor MeshSession exposes a generic "send an arbitrary frame" method the way the raw Connection itself does. Registered eagerly on the very first frame from a connection (including one still in quarantine, e.g. before connect_request approval) so a later sendDataFrame call can reach it; routeDataFrame's own trust gate (peerSessions.has) is what actually decides whether to act on anything received this way, not this map. */
+  private readonly connectionsByPeer = new Map<string, Connection>();
+
+  private announceInterval: ReturnType<typeof setInterval> | undefined;
+
+  /** Whether an announcement round is still running, so a round slowed by an unreachable hub peer is not stacked on by the next tick. */
+  private announcing = false;
+
+  constructor(private readonly deps: Readonly<DataFrameRouterDeps>) {
+    this.dataStorage = deps.dataStorage;
+    const { account } = deps;
+    if (account === undefined) return;
+    this.announceInterval = setInterval(() => {
+      if (this.announcing) return;
+      this.announcing = true;
+      announceAccountLedger({
+        connectionsByPeer: this.connectionsByPeer,
+        account,
+        hub: deps.hub,
+        peerSessions: deps.peerSessions,
+        onError: deps.onError,
+      })
+        .catch((error: unknown) => {
+          deps.onError?.(
+            error instanceof Error ? error : new Error(String(error)),
+          );
+        })
+        .finally(() => {
+          this.announcing = false;
+        });
+    }, deps.announceIntervalMs);
+    this.announceInterval.unref();
+  }
+
+  /** See routeDataFrame. */
+  async route(connection: Readonly<Connection>, frame: Frame): Promise<void> {
+    await routeDataFrame(
+      {
+        connectionsByPeer: this.connectionsByPeer,
+        dataStorage: this.dataStorage,
+        account: this.deps.account,
+        peerSessions: this.deps.peerSessions,
+        onError: this.deps.onError,
+      },
+      connection,
+      frame,
+    );
+  }
+
+  /** See routeRelayedDataFrame. An arrow property, so the transport can hand it to the hub session as a callback. */
+  readonly routeRelayed = async (
+    fromDeviceHex: string,
+    frame: Readonly<DataDomainFrame>,
+  ): Promise<void> => {
+    await routeRelayedDataFrame(
+      {
+        account: this.deps.account,
+        hub: this.deps.hub,
+        onError: this.deps.onError,
+      },
+      fromDeviceHex,
+      frame,
+    );
+  };
+
+  /** Sends one frame on the connection peerDeviceHex's frames last arrived on. Throws if none has arrived from it yet. */
+  async send(
+    peerDeviceHex: string,
+    frame: Readonly<DataHaveFrame> | Readonly<DataRequestFrame>,
+  ): Promise<void> {
+    const connection = this.connectionsByPeer.get(peerDeviceHex);
+    if (connection === undefined) {
+      throw new Error(
+        `WireMeshTransport: no live connection for peer ${peerDeviceHex}`,
+      );
+    }
+    await connection.send(frame);
+  }
+
+  /** Stops offering the account ledger. A router that never started offering it has no timer to clear. */
+  stop(): void {
+    if (this.announceInterval === undefined) return;
+    clearInterval(this.announceInterval);
+    this.announceInterval = undefined;
+  }
+}

package/src/core/default-command.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolves what a bare `agent-comms` (no subcommand) should do from how it was started (agent-comms#339).
+ *
+ * A terminal on stdin means a person ran it, so it stays the setup tool. A stdin that is not a terminal means a harness launched it and is about to speak MCP over it, so it serves the generic `mcp` bridge, which makes the package name alone a valid MCP server command. Any explicit subcommand is returned untouched, so `setup`, `status`, `remove` and `bridge <id>` keep their meaning.
+ */
+export function resolveDefaultCommand(
+  args: readonly string[],
+  stdinIsTerminal: boolean,
+): readonly string[] {
+  if (args.length > 0 || stdinIsTerminal) return args;
+  return ["bridge", "mcp"];
+}

package/src/core/delegation-policy.ts

@@ -0,0 +1,41 @@
+/**
+ * Issuer-side delegation policy (agent-comms#163): deciding which capability verbs an issuer never lets a bearer redelegate, expressed entirely with wire-mesh-core's own shipped primitives. A capability on the policy's nonDelegable set is always minted with delegationsRemaining forced to 0 -- the grant is usable by its own bearer but cannot be passed further down the chain -- regardless of what the caller would otherwise request; mintCapabilityToken needs no change for this, since delegationsRemaining: 0 already means exactly "no further hops" (tokens-CpLDI5Fo.d.mts's own MintCapabilityTokenOptions.delegationsRemaining doc comment).
+ *
+ * Per-agent overrides are deliberately just a second, bearer-keyed nonDelegable set that entirely REPLACES the policy's own default for that one bearer, never merges with it. This needs no bookkeeping of its own: every bearer's grant is already its own independent mint (mintCapabilityToken places no bound tying separate bearers' root-level grants together), so narrowing one bearer's policy is simply supplying a different nonDelegable set to that bearer's own resolution -- there is no prior per-bearer state to merge into, and an override naming zero verbs makes every capability delegable for that one bearer without touching the default any other bearer still resolves against.
+ */
+
+/**
+ * One issuer's non-delegable policy: `nonDelegable` is the default set of capability verbs this issuer never lets any bearer redelegate; `perAgentOverrides` narrows that default per bearer (device-id hex), replacing it outright for that bearer's own resolution rather than merging with it.
+ */
+export interface DelegationPolicy {
+  readonly nonDelegable: ReadonlySet<string>;
+  readonly perAgentOverrides?: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+/**
+ * Resolves the delegationsRemaining value to actually mint for bearer's grant of capability under policy, given whatever delegationsRemaining the caller would otherwise request. Returns 0 when capability is on the bearer's own effective nonDelegable set (its per-agent override when policy defines one for that bearer, otherwise policy's own default set) -- overriding requested outright, the same "issuer refuses to mint an invalid delegation rather than let the far end discover it later" posture mintCapabilityToken's own parent narrowing already applies. Returns requested unchanged for every other capability.
+ *
+ * Overloaded on requested's own definiteness rather than always returning `number | undefined`: a caller minting a root-level grant always passes a definite `number` (mintCapabilityToken's own `delegationsRemaining?: number` field is entirely absent, never present-as-undefined, under this codebase's exactOptionalPropertyTypes), so the result at those call sites is provably a `number` too -- proper return-type narrowing in place of a defensive `?? 0` the caller would otherwise need purely to satisfy the type checker.
+ */
+export function resolveDelegationsRemaining(
+  policy: Readonly<DelegationPolicy>,
+  capability: string,
+  bearer: string,
+  requested: number,
+): number;
+export function resolveDelegationsRemaining(
+  policy: Readonly<DelegationPolicy>,
+  capability: string,
+  bearer: string,
+  requested: undefined,
+): undefined;
+export function resolveDelegationsRemaining(
+  policy: Readonly<DelegationPolicy>,
+  capability: string,
+  bearer: string,
+  requested: number | undefined,
+): number | undefined {
+  const effectiveNonDelegable =
+    policy.perAgentOverrides?.get(bearer) ?? policy.nonDelegable;
+  return effectiveNonDelegable.has(capability) ? 0 : requested;
+}