agent-comms 8.15.9 → 8.15.10

package/src/core/room-lookup.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolves a caller-supplied room identifier against the rooms this store knows of, replicated or merely discovered -- every room-touching tool action (send/join_room/leave_room/read_room/invite/kick/destroy_room) documents its room/target parameter as accepting a room's plain local `name`, matching the README's own usage examples (e.g. `target: "code-review"`) and createRoom's own confirmation message, which surfaces the name back to the caller rather than the owner-qualified id. MeshStore's real room identity is `<owner-hex>/<local-name>` (room-path.ts's ownerNamedRoomPath), a value no caller can construct from a bare name alone, so this is the one place that gap gets closed -- every local-facing RoomLifecycle/RoomMessaging method resolves a name the same way here rather than each reimplementing (or forgetting to reimplement) its own lookup. Wire-protocol-received room paths (room-protocol.ts's own verb handlers) never need this: those always arrive as the real path a remote peer already resolved on its own side.
+ */
+
+import { CommsError } from "./store.js";
+
+/** The two fields of a room that name resolution needs: its real id and the plain local name a caller may use instead. A full `Room` satisfies this, and so does a room known only from a gossiped hosted-room advert. */
+export interface RoomRef {
+  id: string;
+  name: string;
+}
+
+/**
+ * Resolves `roomIdOrName` against every room the caller knows of: rooms replicated into this store and rooms other devices merely advertise as hosted, since list_rooms shows both under their bare `name`. The same room appearing in both sources (same id) is one candidate, not two.
+ *
+ * Returns `roomIdOrName` unchanged when it already is a known room's id, or when no known room has that name (leaving the caller's own not-found or remote-join handling to fire exactly as it would for any unrecognised id). Resolves to the matching room's id when exactly one candidate's `name` equals `roomIdOrName`. Throws AMBIGUOUS_ROOM_NAME, naming every candidate id, when more than one candidate shares that name: distinct owners can legitimately pick the same local name, so silently picking one would be a correctness bug, not a convenience.
+ */
+export function resolveRoomId(
+  candidates: Readonly<Iterable<RoomRef>>,
+  roomIdOrName: string,
+): string {
+  const byId = new Map<string, RoomRef>();
+  for (const candidate of candidates) {
+    if (!byId.has(candidate.id)) byId.set(candidate.id, candidate);
+  }
+  if (byId.has(roomIdOrName)) return roomIdOrName;
+
+  const matches: RoomRef[] = [];
+  for (const candidate of byId.values()) {
+    if (candidate.name === roomIdOrName) matches.push(candidate);
+  }
+  const [match, ...rest] = matches;
+  if (match === undefined) return roomIdOrName;
+  if (rest.length > 0) {
+    throw new CommsError(
+      `Room name ${JSON.stringify(roomIdOrName)} is ambiguous (matches ${matches.map((candidate) => candidate.id).join(", ")}); address it by its full room id instead`,
+      "AMBIGUOUS_ROOM_NAME",
+    );
+  }
+  return match.id;
+}

package/src/core/room-messaging.ts

@@ -0,0 +1,247 @@
+/**
+ * RoomMessaging — the sending side of room messages and DMs: sendRoomMessage/sendDm fan out one directed, wire-authenticated room.send per member via RoomProtocol's own retry-queueing sendRoomRequestToMember (P3.5), and readRoomMessages reads back a room's local history. Split out of mesh-store.ts to reduce it under the repo's max-lines cap.
+ */
+
+import { bytesFromHex, bytesToHex } from "wire-mesh-core/domain/device-id";
+import { dmRoomPath } from "./room-path.js";
+import { loadRoomTokens } from "./identity-store.js";
+import { randomId } from "./random-id.js";
+import { recordRoomSendNotice } from "./room-notice-log.js";
+import { CommsError } from "./store.js";
+import { describeRefusal } from "./send-outcome.js";
+import type { RoomRequestOutcome } from "./send-outcome.js";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import type { RoomProtocol } from "./room-protocol.js";
+import type { CapabilityToken } from "wire-mesh-core/generated/protocol";
+import type {
+  AgentIdentity,
+  DmMessage,
+  MessageDelivery,
+  Room,
+  RoomMessage,
+  StreamingBehavior,
+} from "./types.js";
+import type {
+  MemberDelivery,
+  SentDm,
+  SentRoomMessage,
+  SendRoomMessageOptions,
+} from "./comms-store.js";
+
+/** Turns one member's send outcome into the delivery state its sender is told about. A refusal is not represented here at all: a refused send raises rather than resolving, so this only ever maps the two states a resolved send can be in. */
+function deliveryFromOutcome(
+  outcome: Readonly<Exclude<RoomRequestOutcome, { kind: "refused" }>>,
+): MessageDelivery {
+  return outcome.kind === "delivered"
+    ? { status: "delivered" }
+    : { status: "queued", reason: outcome.reason };
+}
+
+/** The state and collaborators RoomMessaging needs from MeshStore. rooms/messages/dms are direct references into MeshStore's own fields; roomProtocol is the already-constructed instance (construction order: ... -\> roomProtocol -\> roomMessaging -\> ...), narrowed to what sending a message or DM ever needs; resolveAgent is AgentRegistry's own getAgent (deferred the same lazy-closure way DeliveryEngine's sendRoomRequestToMember closure is, since AgentRegistry doesn't exist yet at RoomMessaging's own construction point) rather than a bare `agents.get` lookup, so sendDm's own existence check also resolves a gossip-discovered agent (a remote, hub-learned one included, agent-comms#155) that will never appear in the agents map directly. */
+export interface RoomMessagingDeps {
+  rooms: Map<string, Room>;
+  messages: Map<string, RoomMessage[]>;
+  dms: Map<string, DmMessage[]>;
+  requireIdentity: () => MeshStoreIdentity;
+  roomProtocol: Pick<RoomProtocol, "sendRoomRequestToMember">;
+  /** Runs the requester half of the DM consent flow against a counterpart device (RoomLifecycle.requestDmAccess), persisting the room:member token it is granted. Resolves once the counterpart admits this device, rejects if it refuses or never answers. */
+  requestDmAccess: (counterpart: string) => Promise<void>;
+  /** Resolves a room id or plain room name to a real room id (RoomLifecycle.resolveRoomId), against rooms this store holds and rooms other devices advertise as hosted, so a name means the same room here as it does to join_room. Throws AMBIGUOUS_ROOM_NAME when the name is shared by more than one room. */
+  resolveRoomId: (roomIdOrName: string) => string;
+  resolveAgent: (id: string) => Promise<AgentIdentity | undefined>;
+}
+
+export class RoomMessaging {
+  constructor(private readonly deps: RoomMessagingDeps) {}
+
+  /**
+   * Sends a room message via a real, wire-authenticated room.send fan-out (P3.5): one directed request per member, each carrying this sender's own persisted room:member token, rather than the legacy broadcastPatch's full-state replication. A member unreachable right now is queued for retry (see sendRoomRequestToMember/flushPendingRoomRequests) instead of blocking or failing the whole send -- delivery to any one recipient is independent of every other.
+   *
+   * durable, when true, additionally records this same message as a room-notice in the sender's own oplog via recordRoomSendNotice (P5, agent-comms#50) -- deliberately opt-in per call, not automatic: matching this codebase's own design principle that delivery and durable catch-up are the same artifact only when a caller actually opts a message into it. A caller that wants an offline member to be able to catch up on this specific message later passes true; every other send stays exactly as before.
+   *
+   * Returns the message alongside one delivery state per remote member, so the caller can tell who actually received it from who it is merely queued for. A member that refuses the message outright raises: a refusal is the member's settled answer, not a state to report as pending, and a fan-out whose members cannot all be reported honestly is not a successful send.
+   */
+  async sendRoomMessage(
+    roomIdOrName: string,
+    from: string,
+    content: string,
+    options?: SendRoomMessageOptions,
+  ): Promise<SentRoomMessage> {
+    const { replyTo, streamingBehavior, durable } = options ?? {};
+    const roomId = this.deps.resolveRoomId(roomIdOrName);
+    const room = this.deps.rooms.get(roomId);
+    if (!room)
+      throw new CommsError(`Room ${roomId} not found`, "ROOM_NOT_FOUND");
+    if (!room.members.includes(from))
+      throw new CommsError(`Not a member of ${roomId}`, "NOT_MEMBER");
+
+    const { slot, clock, identity, dataStorage } = this.deps.requireIdentity();
+    const token = loadRoomTokens(slot)[roomId];
+    if (token === undefined) {
+      throw new CommsError(`No room:member token for ${roomId}`, "NOT_MEMBER");
+    }
+
+    if (durable === true) {
+      await recordRoomSendNotice(
+        { identity, clock, storage: dataStorage },
+        {
+          room: roomId,
+          token,
+          contentType: "text/plain",
+          content: new TextEncoder().encode(content),
+        },
+      );
+    }
+
+    const messageId = randomId();
+    const id = bytesToHex(messageId);
+    const message: RoomMessage = {
+      id,
+      from,
+      room: roomId,
+      content,
+      timestamp: new Date().toISOString(),
+      readBy: [from],
+      ...(replyTo !== undefined && { replyTo }),
+      ...(streamingBehavior !== undefined && { streamingBehavior }),
+    };
+
+    const arr = this.deps.messages.get(roomId) ?? [];
+    arr.push(message);
+    this.deps.messages.set(roomId, arr);
+
+    const params: Record<string, unknown> = {
+      verb: "room.send",
+      "message-id": messageId,
+      "sent-at": clock.now(),
+      text: content,
+      ...(replyTo !== undefined && {
+        refs: [{ id: bytesFromHex(replyTo), relation: "reply" }],
+      }),
+      ...(streamingBehavior !== undefined && {
+        "streaming-behavior": streamingBehavior,
+      }),
+    };
+
+    const deliveries: MemberDelivery[] = [];
+    for (const memberId of room.members) {
+      if (memberId === from) continue;
+      const outcome = await this.deps.roomProtocol.sendRoomRequestToMember(
+        memberId,
+        roomId,
+        token,
+        params,
+      );
+      // A refusal is reported as this member's own delivery state rather than raised, unlike sendDm's single recipient: delivery to any one member is independent of every other, so one member's refusal must neither stop the message reaching the rest nor discard what became of them.
+      deliveries.push({
+        member: memberId,
+        delivery:
+          outcome.kind === "refused"
+            ? { status: "refused", code: describeRefusal(outcome) }
+            : deliveryFromOutcome(outcome),
+      });
+    }
+
+    return { message, deliveries };
+  }
+
+  async readRoomMessages(
+    roomIdOrName: string,
+    since?: string,
+  ): Promise<RoomMessage[]> {
+    await Promise.resolve();
+    const roomId = this.deps.resolveRoomId(roomIdOrName);
+    const arr = this.deps.messages.get(roomId) ?? [];
+    if (since === undefined || since === "") return [...arr];
+    return arr.filter((m) => m.timestamp > since);
+  }
+
+  /**
+   * Sends a DM via the same wire-authenticated room.send fan-out sendRoomMessage uses (P3.5): a DM is just a dm-shaped room path with exactly one other member, so it rides the identical mechanism rather than a separate one. Self-DM is the one exception -- a purely local scratchpad note that never leaves the process, so it needs no token and no wire round trip at all, and is delivered the moment it is recorded.
+   *
+   * Returns the message alongside what actually became of it, so a caller can never mistake a message merely held for retry for one the recipient received. A recipient that refuses the message raises SEND_REFUSED naming its own reason: a DM has exactly one recipient, so its refusal is the whole send failing, and no retry will change it.
+   */
+  async sendDm(
+    from: string,
+    to: string,
+    content: string,
+    streamingBehavior?: StreamingBehavior,
+  ): Promise<SentDm> {
+    if (to !== from) {
+      const recipient = await this.deps.resolveAgent(to);
+      if (!recipient)
+        throw new CommsError(`Agent ${to} not found`, "AGENT_NOT_FOUND");
+      if (recipient.visibility === "ghost")
+        throw new CommsError(`Cannot DM agent ${to}`, "AGENT_NOT_FOUND");
+    }
+
+    // A cross-device DM needs a room:member token for the pair's dm path. The first message to a counterpart has none yet, so obtain one via the consent flow before anything is recorded or sent: a refused or unanswered request must leave no trace of a message that never went out.
+    const token =
+      to === from ? undefined : await this.dmRoomMemberToken(from, to);
+
+    const messageId = randomId();
+    const id = bytesToHex(messageId);
+    const message: DmMessage = {
+      id,
+      from,
+      to,
+      content,
+      timestamp: new Date().toISOString(),
+      readBy: [from],
+      ...(streamingBehavior !== undefined && { streamingBehavior }),
+    };
+
+    // Self-DM is a purely local scratchpad note -- it never leaves the process, so it needs no room-path and dmRoomPath's own a===b refusal (a path naming the same device twice is not a valid DM path at all) correctly does not apply.
+    const key = to === from ? `self:${from}` : dmRoomPath(from, to);
+    const arr = this.deps.dms.get(key) ?? [];
+    arr.push(message);
+    this.deps.dms.set(key, arr);
+
+    // A self-DM never leaves the process, so it is already exactly as delivered as it will ever be by the time it is recorded above.
+    if (token === undefined)
+      return { message, delivery: { status: "delivered" } };
+
+    const { clock } = this.deps.requireIdentity();
+    const params: Record<string, unknown> = {
+      verb: "room.send",
+      "message-id": messageId,
+      "sent-at": clock.now(),
+      text: content,
+      ...(streamingBehavior !== undefined && {
+        "streaming-behavior": streamingBehavior,
+      }),
+    };
+    const outcome = await this.deps.roomProtocol.sendRoomRequestToMember(
+      to,
+      key,
+      token,
+      params,
+    );
+    if (outcome.kind === "refused") {
+      throw new CommsError(
+        `DM to ${to} refused (${describeRefusal(outcome)})`,
+        "SEND_REFUSED",
+      );
+    }
+
+    return { message, delivery: deliveryFromOutcome(outcome) };
+  }
+
+  /** The room:member token this device holds for its DM path with `to`, requesting DM access from `to` first when none is persisted yet. Throws NOT_MEMBER if the request resolves without a token having been persisted, since no send can be authenticated without one. */
+  private async dmRoomMemberToken(
+    from: string,
+    to: string,
+  ): Promise<CapabilityToken> {
+    const key = dmRoomPath(from, to);
+    const { slot } = this.deps.requireIdentity();
+    const existing = loadRoomTokens(slot)[key];
+    if (existing !== undefined) return existing;
+
+    await this.deps.requestDmAccess(to);
+    const granted = loadRoomTokens(slot)[key];
+    if (granted === undefined) {
+      throw new CommsError(`No room:member token for ${key}`, "NOT_MEMBER");
+    }
+    return granted;
+  }
+}

package/src/core/room-notice-log.ts

@@ -0,0 +1,61 @@
+/**
+ * Records a room.send as a durable, catch-up-able room-notice in the sender's own oplog -- P5's mint-and-append half (agent-comms#50), riding wire-mesh-core's createRoomNotice + appendOwnEntry directly. Deliberately opt-in per call, not wired into sendRoomMessage's own default path: a caller decides per-message whether durability is worth the extra local write, matching the plan's own "delivery and durable catch-up are the same artifact, opt-in per message" design. Wiring this into a bridge's own send path, and the actual catch-up policy (when to send data-have, which peers' logs to track), stay their own separate, still-open piece.
+ */
+
+import { encode as cborEncode, cdeEncodeOptions } from "cbor2";
+import { createRoomNotice } from "wire-mesh-core/domain/room";
+import { appendOwnEntry } from "wire-mesh-core/domain/data-sync";
+import type {
+  CapabilityToken,
+  DataHaveFrame,
+  MessageRef,
+  RoomPath,
+} from "wire-mesh-core/generated/protocol";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { KeyValueStorage } from "wire-mesh-core/ports/storage";
+import { randomId } from "./random-id.js";
+
+export interface RecordRoomSendNoticeDeps {
+  identity: IdentityPort;
+  clock: Clock;
+  storage: KeyValueStorage;
+}
+
+export interface RecordRoomSendNoticeOptions {
+  room: RoomPath;
+  /** The sender's own room:member token for `room`, embedded in full in the minted notice -- see createRoomNotice's own token field for why. */
+  token: CapabilityToken;
+  contentType: string;
+  content: Uint8Array<ArrayBuffer>;
+  refs?: readonly MessageRef[];
+  validUntil?: number;
+}
+
+/** Mints a self-certifying room-notice for this send, CBOR-encodes it (cbor2's own deterministic-encoding preset, matching handshake.ts's established convention for every other wire-mesh value this codebase serialises), and appends it to the sender's own oplog. Returns the new sequence number and the data-have frame announcing it -- sending that frame to any peer is the caller's own policy, not this function's. */
+export async function recordRoomSendNotice(
+  deps: Readonly<RecordRoomSendNoticeDeps>,
+  options: Readonly<RecordRoomSendNoticeOptions>,
+): Promise<{ seq: number; haveFrame: DataHaveFrame }> {
+  const notice = await createRoomNotice({
+    identity: deps.identity,
+    clock: deps.clock,
+    room: options.room,
+    token: options.token,
+    noticeId: randomId(),
+    contentType: options.contentType,
+    content: options.content,
+    ...(options.refs !== undefined ? { refs: options.refs } : {}),
+    ...(options.validUntil !== undefined
+      ? { validUntil: options.validUntil }
+      : {}),
+  });
+  // cbor2's encode() returns Uint8Array<ArrayBufferLike>; appendOwnEntry needs the narrower Uint8Array<ArrayBuffer> every other wire-mesh-core byte-string field already uses. Uint8Array.from copies into a fresh, plain ArrayBuffer-backed array rather than asserting the existing buffer's type.
+  const encoded: Uint8Array<ArrayBuffer> = Uint8Array.from(
+    cborEncode(notice, cdeEncodeOptions),
+  );
+  return appendOwnEntry(
+    { identity: deps.identity, storage: deps.storage },
+    encoded,
+  );
+}

package/src/core/room-path.ts

@@ -0,0 +1,84 @@
+/**
+ * Room paths — the naming and parsing convention core/room's device-keyed membership uses, mirroring wire-mesh spec/room.cddl exactly: an owner-named room is `<owner-hex>/<local-name>`, trust rooted at the owner named in the path; a DM is the bytewise-ascending sorted pair `<lower-hex>+<higher-hex>`, trust rooted at the verifier itself rather than either named party (see room.cddl's own comments for why that asymmetry is load-bearing, not incidental).
+ */
+
+const DEVICE_ID_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const LOCAL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const SLUG_INVALID_RUN = /[^A-Za-z0-9_-]+/g;
+
+/** Whether value is a full device-id in its canonical text form: 64 lowercase hex characters. */
+export function isDeviceIdHex(value: string): boolean {
+  return DEVICE_ID_HEX_PATTERN.test(value);
+}
+
+function assertDeviceIdHex(value: string, label: string): void {
+  if (!isDeviceIdHex(value)) {
+    throw new Error(
+      `expected ${label} to be a 64-character lowercase hex device-id, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+/** `<owner-hex>/<local-name>`. localName must already satisfy [A-Za-z0-9_-]+ -- run an untrusted name through slugRoomName first. */
+export function ownerNamedRoomPath(owner: string, localName: string): string {
+  assertDeviceIdHex(owner, "owner");
+  if (!LOCAL_NAME_PATTERN.test(localName)) {
+    throw new Error(
+      `expected localName to match [A-Za-z0-9_-]+, got ${JSON.stringify(localName)}`,
+    );
+  }
+  return `${owner}/${localName}`;
+}
+
+/** `<lower-hex>+<higher-hex>`, the bytewise-ascending sorted pair. Refuses a==b outright: a path naming the same device twice is not a valid DM path at all, and self-DM is a purely local scratchpad note that needs no path (see mesh-store.ts's own sendDm). */
+export function dmRoomPath(a: string, b: string): string {
+  assertDeviceIdHex(a, "a");
+  assertDeviceIdHex(b, "b");
+  if (a === b) {
+    throw new Error(`a DM room path cannot name the same device twice (${a})`);
+  }
+  return a < b ? `${a}+${b}` : `${b}+${a}`;
+}
+
+export type ParsedRoomPath =
+  | { kind: "owner-named"; owner: string; localName: string }
+  | { kind: "dm"; participants: [string, string] };
+
+/** Parses a room-path back into its owner-named or DM shape. Throws on anything matching neither -- there is no third path shape. */
+export function parseRoomPath(path: string): ParsedRoomPath {
+  const slashIndex = path.indexOf("/");
+  if (slashIndex !== -1) {
+    const owner = path.slice(0, slashIndex);
+    const localName = path.slice(slashIndex + 1);
+    if (
+      DEVICE_ID_HEX_PATTERN.test(owner) &&
+      LOCAL_NAME_PATTERN.test(localName)
+    ) {
+      return { kind: "owner-named", owner, localName };
+    }
+  }
+  const plusIndex = path.indexOf("+");
+  if (plusIndex !== -1) {
+    const first = path.slice(0, plusIndex);
+    const second = path.slice(plusIndex + 1);
+    if (
+      DEVICE_ID_HEX_PATTERN.test(first) &&
+      DEVICE_ID_HEX_PATTERN.test(second) &&
+      first !== second
+    ) {
+      return { kind: "dm", participants: [first, second] };
+    }
+  }
+  throw new Error(`${JSON.stringify(path)} is not a valid room-path`);
+}
+
+/** Sanitises an arbitrary name (e.g. a directory basename) into a valid room-path localName by replacing every run of characters outside [A-Za-z0-9_-] with a single hyphen. Throws if nothing valid remains. */
+export function slugRoomName(name: string): string {
+  const slug = name.replace(SLUG_INVALID_RUN, "-").replace(/^-+|-+$/g, "");
+  if (slug.length === 0) {
+    throw new Error(
+      `${JSON.stringify(name)} has no valid room-name characters to slug`,
+    );
+  }
+  return slug;
+}