agent-comms 8.15.9 → 8.15.11

package/src/core/discovery-tailscale.ts

@@ -0,0 +1,224 @@
+/**
+ * Tailscale discovery backend — probes tailnet peers for mesh coordinators.
+ *
+ * Queries the Tailscale local API to get tailnet peers, then probes each
+ * peer's port 19876 with a TCP connection attempt (timeout 500ms).
+ * If reachable, the peer is added as a discovered mesh.
+ *
+ * No broadcasting is needed — Tailscale already knows all peers.
+ * startAdvertising() is a no-op since the coordinator already listens
+ * on the Tailscale IP.
+ */
+
+import * as http from "node:http";
+import * as net from "node:net";
+import { execFile, type ExecException } from "node:child_process";
+import type {
+  DiscoveredMesh,
+  DiscoveryBackend,
+  AdvertiseOptions,
+} from "./discovery.js";
+
+/** Runs `execFile` as a promise, resolving with its stdout/stderr rather than invoking a callback. */
+async function execFileAsync(
+  file: string,
+  args: readonly string[],
+): Promise<{ stdout: string; stderr: string }> {
+  const mutableArgs: string[] = [...args];
+  return new Promise((resolve, reject) => {
+    execFile(
+      file,
+      mutableArgs,
+      (error: ExecException | null, stdout: string, stderr: string) => {
+        if (error) {
+          reject(error instanceof Error ? error : new Error(error.message));
+          return;
+        }
+        resolve({ stdout, stderr });
+      },
+    );
+  });
+}
+
+const TCP_PROBE_TIMEOUT_MS = 500;
+const DEFAULT_DISCOVER_TIMEOUT_MS = 5_000;
+const COORDINATOR_PORT = 19876;
+const TAILSCALE_API_PORT = 49156;
+
+// ---------------------------------------------------------------------------
+// Tailscale peer types (from tailscale status --json)
+// ---------------------------------------------------------------------------
+
+interface TailscalePeer {
+  TailscaleIPs?: string[];
+  HostName?: string;
+  DNSName?: string;
+  Online?: boolean;
+  UserID?: string;
+}
+
+interface TailscaleStatus {
+  Peer?: Record<string, TailscalePeer>;
+  Self?: TailscalePeer;
+}
+
+function parseTailscaleStatus(raw: unknown): TailscaleStatus {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("Invalid TailscaleStatus: expected object");
+  }
+  return raw satisfies TailscaleStatus;
+}
+
+// ---------------------------------------------------------------------------
+// Tailscale backend
+// ---------------------------------------------------------------------------
+
+export class TailscaleDiscoveryBackend implements DiscoveryBackend {
+  readonly name = "tailscale";
+
+  /** No-op — the coordinator already listens on the Tailscale IP. */
+  async startAdvertising(opts: Readonly<AdvertiseOptions>): Promise<string> {
+    return Promise.resolve(`tailscale-${String(opts.port)}`);
+  }
+
+  /** No-op — nothing to stop. */
+  async stopAdvertising(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Stop discovery — no-op since Tailscale has no persistent state to clean up. */
+  async stop(): Promise<void> {
+    // Tailscale discovery is stateless — each discover() call probes peers fresh. No persistent connections or timers to tear down.
+    return Promise.resolve();
+  }
+
+  /**
+   * Discover meshes on the tailnet by probing peers.
+   * Returns peers that respond to a TCP connection on port 19876.
+   */
+  async discover(): Promise<DiscoveredMesh[]> {
+    const peers = await this.getPeers();
+    if (peers.length === 0) return [];
+
+    const probes = peers.map(async (peer) => this.probePeer(peer));
+    const results = await Promise.allSettled(probes);
+
+    const discovered: DiscoveredMesh[] = [];
+    for (const result of results) {
+      if (result.status === "fulfilled" && result.value !== undefined) {
+        discovered.push(result.value);
+      }
+    }
+
+    return discovered;
+  }
+
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get tailnet peers via `tailscale status --json`.
+   * Falls back to the local API at localhost:49156 if the CLI is unavailable.
+   */
+  private async getPeers(): Promise<{ ip: string; hostname: string }[]> {
+    const status = await this.fetchTailscaleStatus();
+    if (!status?.Peer) return [];
+
+    const peers: { ip: string; hostname: string }[] = [];
+    for (const [, peer] of Object.entries(status.Peer)) {
+      if (peer.Online !== true) continue;
+      const ips = peer.TailscaleIPs;
+      if (!ips || ips.length === 0) continue;
+      // Use the first IPv4 address
+      const ip = ips.find((addr) => addr.includes(".")) ?? ips[0];
+      if (ip === undefined || ip === "") continue;
+      const hostname =
+        peer.HostName ?? peer.DNSName?.replace(/\.tailnet.*$/, "") ?? ip;
+      peers.push({ ip, hostname });
+    }
+
+    return peers;
+  }
+
+  /**
+   * Fetch Tailscale status. Tries the CLI first, falls back to the local API.
+   */
+  private async fetchTailscaleStatus(): Promise<TailscaleStatus | undefined> {
+    // Try CLI first
+    try {
+      const { stdout } = await execFileAsync("tailscale", ["status", "--json"]);
+      return parseTailscaleStatus(JSON.parse(stdout));
+    } catch {
+      // CLI not available — try the local API
+    }
+
+    // Fall back to local API
+    try {
+      return await this.fetchLocalApi();
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Query the Tailscale local API at localhost:49156. */
+  private async fetchLocalApi(): Promise<TailscaleStatus> {
+    return new Promise((resolve, reject) => {
+      const req = http.get(
+        `http://localhost:${String(TAILSCALE_API_PORT)}/localapi/v0/status`,
+        { timeout: DEFAULT_DISCOVER_TIMEOUT_MS },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (chunk: Buffer) => {
+            chunks.push(chunk);
+          });
+          res.on("end", () => {
+            try {
+              resolve(
+                parseTailscaleStatus(
+                  JSON.parse(Buffer.concat(chunks).toString()),
+                ),
+              );
+            } catch (err) {
+              reject(err instanceof Error ? err : new Error(String(err)));
+            }
+          });
+        },
+      );
+      req.on("error", reject);
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error("Tailscale local API timeout"));
+      });
+    });
+  }
+
+  /** Probe a single Tailscale peer for a listening mesh coordinator. */
+  private async probePeer(
+    peer: Readonly<{ ip: string; hostname: string }>,
+  ): Promise<DiscoveredMesh | undefined> {
+    return new Promise((resolve) => {
+      const socket = new net.Socket();
+      const timer = setTimeout(() => {
+        socket.destroy();
+        resolve(undefined);
+      }, TCP_PROBE_TIMEOUT_MS);
+
+      socket.connect(COORDINATOR_PORT, peer.ip, () => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve({
+          host: peer.ip,
+          port: COORDINATOR_PORT,
+          name: peer.hostname,
+        });
+      });
+
+      socket.on("error", () => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(undefined);
+      });
+    });
+  }
+}

package/src/core/discovery.ts

@@ -0,0 +1,303 @@
+/**
+ * Discovery — mesh discovery interface and manager.
+ *
+ * Defines the contract for discovery backends (mDNS, Tailscale, etc.)
+ * and a manager that routes calls to the appropriate backend.
+ * Discovery is opt-in — no broadcasting unless the agent explicitly
+ * calls mesh_advertise.
+ */
+
+import type { MeshVisibility } from "./types.js";
+import { nanoid } from "./nanoid.js";
+
+// ---------------------------------------------------------------------------
+// Discovered mesh
+// ---------------------------------------------------------------------------
+
+export interface DiscoveredMesh {
+  /** Host address of the discovered mesh coordinator. */
+  host: string;
+  /** Port the coordinator is listening on. */
+  port: number;
+  /** Human-readable mesh name (from mDNS TXT record or Tailscale hostname). */
+  name: string;
+  /** Number of agents in the mesh (if available). */
+  agentCount?: number;
+  /** Connection policies available (if advertised). */
+  policies?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Advertise options
+// ---------------------------------------------------------------------------
+
+export interface AdvertiseOptions {
+  /** Service name for mDNS / identifier for the mesh. */
+  name: string;
+  /** Port to advertise. */
+  port: number;
+  /** Network adapter/address to broadcast on. */
+  adapter?: string;
+  /** What information to reveal in discovery responses. */
+  policy?: "full" | "name-only";
+}
+
+// ---------------------------------------------------------------------------
+// Discovery backend interface
+// ---------------------------------------------------------------------------
+
+export interface DiscoveryBackend {
+  readonly name: string;
+  startAdvertising: (opts: Readonly<AdvertiseOptions>) => Promise<string>;
+  stopAdvertising: (id: string) => Promise<void>;
+  discover: (timeout?: number) => Promise<DiscoveredMesh[]>;
+  /** Stop all activity (timers, sockets) for this backend. */
+  stop: () => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery manager
+// ---------------------------------------------------------------------------
+
+/** An advertisement DiscoveryManager currently considers live -- the caller-visible external id, which backend to it, the backend's own internal id (needed to address stopAdvertising/a future re-advertisement), and the original opts (needed to genuinely re-advertise on resume, not just forget the advertisement ever happened). */
+interface ActiveAdvertisement {
+  backendName: string;
+  backendId: string;
+  opts: AdvertiseOptions;
+}
+
+export class DiscoveryManager {
+  private readonly backends = new Map<string, DiscoveryBackend>();
+  /** Keyed by the stable, caller-visible external id DiscoveryManager itself mints -- deliberately never the backend's own returned id, since a backend is free to return a different id on every startAdvertising call (a real, un-mocked backend calling it deterministically is incidental, not a contract this class may rely on) and a caller must be able to keep using the same id it was given across a pause/resume cycle. */
+  private readonly activeAdvertisements = new Map<
+    string,
+    ActiveAdvertisement
+  >();
+  private meshVisibility: MeshVisibility = "discoverable";
+  private readonly perAdapterVisibility = new Map<string, MeshVisibility>();
+  /** Advertisements paused due to a visibility change, keyed by the same external id -- carries the real original opts (not a placeholder) so resuming can genuinely call startAdvertising again. */
+  private readonly pausedAdvertisements = new Map<
+    string,
+    { backendName: string; opts: AdvertiseOptions }
+  >();
+
+  /** Register a discovery backend. */
+  registerBackend(backend: Readonly<DiscoveryBackend>): void {
+    this.backends.set(backend.name, backend);
+  }
+
+  /** Start advertising on a specific backend. Returns a stable external advertisement id, distinct from whatever id the backend itself returns internally. */
+  async advertise(
+    backendName: string,
+    opts: Readonly<AdvertiseOptions>,
+  ): Promise<string> {
+    const backend = this.backends.get(backendName);
+    if (!backend) {
+      throw new Error(
+        `Unknown discovery backend: "${backendName}". Available: ${[...this.backends.keys()].join(", ")}`,
+      );
+    }
+    const backendId = await backend.startAdvertising(opts);
+    const id = nanoid();
+    this.activeAdvertisements.set(id, { backendName, backendId, opts });
+    return id;
+  }
+
+  /**
+   * Set mesh-wide visibility level.
+   *
+   * - `discoverable` — normal operation, all backends active.
+   * - `quiet` — stop advertising but backends remain available for discover().
+   * - `dark` — stop all discovery activity (advertising + backend sockets).
+   *
+   * If `adapter` is specified, the visibility applies only to that backend.
+   * Otherwise it applies to the global mesh visibility.
+   */
+  async setVisibility(level: MeshVisibility, adapter?: string): Promise<void> {
+    if (adapter !== undefined) {
+      await this.setAdapterVisibility(adapter, level);
+      return;
+    }
+
+    const prev = this.meshVisibility;
+    this.meshVisibility = level;
+
+    if (prev === level) return;
+
+    if (level === "quiet") {
+      // Pause all advertisements but keep backends running
+      await this.pauseAllAdvertisements();
+    } else if (level === "dark") {
+      // Pause advertisements and stop backends entirely
+      await this.pauseAllAdvertisements();
+      await this.stopAllBackends();
+    } else {
+      // discoverable — resume previously paused advertisements and restart backends
+      await this.resumeAllAdvertisements();
+    }
+  }
+
+  /** Get current mesh visibility level (global or per-adapter). */
+  getVisibility(adapter?: string): MeshVisibility {
+    if (adapter !== undefined) {
+      return this.perAdapterVisibility.get(adapter) ?? this.meshVisibility;
+    }
+    return this.meshVisibility;
+  }
+
+  private async setAdapterVisibility(
+    adapter: string,
+    level: MeshVisibility,
+  ): Promise<void> {
+    const prev = this.perAdapterVisibility.get(adapter) ?? this.meshVisibility;
+    this.perAdapterVisibility.set(adapter, level);
+
+    if (prev === level) return;
+
+    if (level === "quiet" || level === "dark") {
+      // Pause advertisements for this specific backend
+      await this.pauseAdvertisementsForBackend(adapter);
+      if (level === "dark") {
+        const backend = this.backends.get(adapter);
+        if (backend) await backend.stop();
+      }
+    } else {
+      await this.resumeAdvertisementsForBackend(adapter);
+    }
+  }
+
+  private async pauseAllAdvertisements(): Promise<void> {
+    // Capture current ads' real opts before clearing, so resume can genuinely re-advertise rather than merely forgetting the pause happened.
+    for (const [id, active] of this.activeAdvertisements) {
+      this.pausedAdvertisements.set(id, {
+        backendName: active.backendName,
+        opts: active.opts,
+      });
+      const backend = this.backends.get(active.backendName);
+      if (backend) {
+        await backend.stopAdvertising(active.backendId).catch(() => {
+          /* intentionally empty — best-effort stop */
+        });
+      }
+    }
+    this.activeAdvertisements.clear();
+  }
+
+  private async pauseAdvertisementsForBackend(
+    backendName: string,
+  ): Promise<void> {
+    for (const [id, active] of this.activeAdvertisements) {
+      if (active.backendName === backendName) {
+        this.pausedAdvertisements.set(id, {
+          backendName,
+          opts: active.opts,
+        });
+        const backend = this.backends.get(backendName);
+        if (backend) {
+          await backend.stopAdvertising(active.backendId).catch(() => {
+            /* intentionally empty — best-effort stop */
+          });
+        }
+        this.activeAdvertisements.delete(id);
+      }
+    }
+  }
+
+  private async stopAllBackends(): Promise<void> {
+    for (const backend of this.backends.values()) {
+      await backend.stop().catch(() => {
+        /* intentionally empty — best-effort stop */
+      });
+    }
+  }
+
+  private async resumeAllAdvertisements(): Promise<void> {
+    // Backends reinitialise their own sockets/timers on the next startAdvertising call -- nothing extra needed here beyond actually calling it, which is the whole fix: resuming used to just forget the pause happened rather than genuinely re-advertising.
+    for (const [id, entry] of this.pausedAdvertisements) {
+      this.pausedAdvertisements.delete(id);
+      const backend = this.backends.get(entry.backendName);
+      if (!backend) continue;
+      const backendId = await backend.startAdvertising(entry.opts);
+      this.activeAdvertisements.set(id, {
+        backendName: entry.backendName,
+        backendId,
+        opts: entry.opts,
+      });
+    }
+  }
+
+  private async resumeAdvertisementsForBackend(
+    backendName: string,
+  ): Promise<void> {
+    for (const [id, entry] of this.pausedAdvertisements) {
+      if (entry.backendName !== backendName) continue;
+      this.pausedAdvertisements.delete(id);
+      const backend = this.backends.get(backendName);
+      if (!backend) continue;
+      const backendId = await backend.startAdvertising(entry.opts);
+      this.activeAdvertisements.set(id, {
+        backendName,
+        backendId,
+        opts: entry.opts,
+      });
+    }
+  }
+
+  /** Stop a previously started advertisement, addressed by its stable external id. */
+  async stopAdvertising(id: string): Promise<void> {
+    const active = this.activeAdvertisements.get(id);
+    if (active === undefined) return;
+    const backend = this.backends.get(active.backendName);
+    if (!backend) return;
+    await backend.stopAdvertising(active.backendId);
+    this.activeAdvertisements.delete(id);
+  }
+
+  /** Check whether an advertisement ID was paused (visibility change stopped it). */
+  isPaused(id: string): boolean {
+    return this.pausedAdvertisements.has(id);
+  }
+
+  /**
+   * Discover meshes using a specific backend (or all backends if no name given).
+   * Returns deduplicated results.
+   *
+   * Respects visibility: returns empty results for backends that are "dark".
+   */
+  async discover(options?: {
+    backendName?: string | undefined;
+    timeout?: number | undefined;
+  }): Promise<DiscoveredMesh[]> {
+    const { backendName, timeout } = options ?? {};
+    const targets =
+      backendName !== undefined
+        ? [this.backends.get(backendName)].filter(
+            (b): b is DiscoveryBackend => b !== undefined,
+          )
+        : [...this.backends.values()];
+
+    // Filter out backends that are dark (per-adapter or global)
+    const activeTargets = targets.filter((b) => {
+      const vis = this.getVisibility(b.name);
+      return vis !== "dark";
+    });
+
+    const results = await Promise.all(
+      activeTargets.map(async (b) => b.discover(timeout)),
+    );
+
+    // Deduplicate by host+port
+    const seen = new Set<string>();
+    const deduped: DiscoveredMesh[] = [];
+    for (const meshes of results) {
+      for (const mesh of meshes) {
+        const key = `${mesh.host}:${String(mesh.port)}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          deduped.push(mesh);
+        }
+      }
+    }
+    return deduped;
+  }
+}

package/src/core/display-name.ts

@@ -0,0 +1,73 @@
+/**
+ * The one display convention for anything identified by a device-id (agent-comms#345): your own petname for it first, then the name it asserts for itself, then a short id. Every surface that shows an agent, a machine, a principal or a trusted device formats it here, so the CLI, the tool output and the dashboard read the same; wire-mesh's web console follows the same order (ExaDev/wire-mesh#295).
+ *
+ * A petname is yours: set locally, never gossiped, so it needs no trust decision and has no collision problem. A self-asserted name is whatever the subject's own key signed (an agent's registered name, a machine's name claim), so it is shown quoted, as the subject's claim rather than a fact. Where the full id is already printed beside the name, formatNames gives the names alone, since the short id would only repeat its start. The short id is the stable reference when neither name exists, and the fallback that tells two same-named subjects apart. It is a prefix of the full id, never a replacement for it: every tool action takes the full id, so a surface whose entries are acted on also prints the full id.
+ *
+ * Pure and dependency-free, so the browser bundle imports it as it is.
+ */
+
+/** How many leading hex characters of a device-id the short id keeps: 48 bits, enough that two devices a person deals with never share one by chance, and short enough to read and compare at a glance. */
+export const SHORT_ID_LENGTH = 12;
+
+/** Everything a display name is built from. Both names are optional; the id never is. */
+export interface DisplayNameParts {
+  /** The full device-id (hex). */
+  id: string;
+  /** The viewer's own label for this id, if they set one. */
+  petname?: string | undefined;
+  /** The name the subject asserts for itself, if it has one. */
+  selfName?: string | undefined;
+}
+
+/** The leading SHORT_ID_LENGTH characters of id. */
+export function shortId(id: string): string {
+  return id.slice(0, SHORT_ID_LENGTH);
+}
+
+/** The names in parts, in display order: the petname, then the self-asserted name quoted (left out when it only repeats the petname), separated by a space, or the empty string when neither is set. Each name is checked with parseDisplayName first and left out when it fails, so a name that slipped past every other check (a hand-edited file, a peer that does not validate) still never reaches a terminal; the self-asserted name is quoted as a JSON string, so a quote inside it is escaped and cannot close the quotes early to pass the rest off as a separate, unquoted label. */
+export function formatNames(parts: Readonly<DisplayNameParts>): string {
+  const petname = usableName(parts.petname);
+  const selfName = usableName(parts.selfName);
+  const labels: string[] = [];
+  if (petname !== undefined) labels.push(petname);
+  if (selfName !== undefined && selfName !== petname) {
+    labels.push(JSON.stringify(selfName));
+  }
+  return labels.join(" ");
+}
+
+/** parts in display order: formatNames, then the short id. */
+export function formatDisplayName(parts: Readonly<DisplayNameParts>): string {
+  const names = formatNames(parts);
+  const id = shortId(parts.id);
+  return names === "" ? id : `${names} ${id}`;
+}
+
+function usableName(raw: string | undefined): string | undefined {
+  return raw === undefined ? undefined : parseDisplayName(raw);
+}
+
+/** The longest display name, petname or self-asserted, that is accepted: room for a descriptive label ("Joe's work laptop, office"), short enough that one never swamps a listing row. */
+export const MAX_DISPLAY_NAME_LENGTH = 64;
+
+/** The last C0 control character; everything at or below it, DEL, and the C1 range are refused, since a name is printed straight into terminals and a control sequence in one could rewrite what the viewer sees. */
+const LAST_C0_CONTROL = 0x1f;
+const DEL = 0x7f;
+const LAST_C1_CONTROL = 0x9f;
+
+function isControlCharacter(code: number): boolean {
+  return code <= LAST_C0_CONTROL || (code >= DEL && code <= LAST_C1_CONTROL);
+}
+
+/** raw trimmed, when it is usable as a display name: not empty, at most MAX_DISPLAY_NAME_LENGTH characters, and free of control characters. Undefined otherwise. Applied to a petname as it is set, to an agent's name as it is registered or received in an advert, to a machine's name claim as it is verified, and once more by formatNames as any name is shown, so none can carry anything a terminal would interpret. */
+export function parseDisplayName(raw: string): string | undefined {
+  const name = raw.trim();
+  if (name.length === 0 || name.length > MAX_DISPLAY_NAME_LENGTH) {
+    return undefined;
+  }
+  for (const char of name) {
+    const code = char.codePointAt(0);
+    if (code !== undefined && isControlCharacter(code)) return undefined;
+  }
+  return name;
+}

package/src/core/dm-grant-actions.ts

@@ -0,0 +1,72 @@
+/**
+ * CommsTool's dm_admit, dm_use_grant and dm_revoke action handlers -- the tool surface for agent-comms#162's dm:send grants, split out of tool.ts purely to keep it under the repo's max-lines cap.
+ *
+ * A grant lets one device send its first DM to another without the receiver deciding on the spot: the receiver admits the sender ahead of time (dm_admit) and hands over the grant it returns, the sender presents it (dm_use_grant), and the receiver's own user principal verifies it instead of asking a person. dm_revoke withdraws it.
+ */
+
+import type { CommsAction } from "./types.js";
+import type { CommsResult, MeshOnlyFeatures } from "./tool.js";
+import { decodeTokenText, encodeTokenText } from "./token-text.js";
+
+/** Uniform "grants aren't available on this store" result, mirroring the other MeshOnlyFeatures action handlers. */
+function grantsUnavailable(): CommsResult {
+  return {
+    content: "DM grants are not available on this store.",
+    isError: true,
+  };
+}
+
+/** How many further hops a grant admitting a user principal permits: the principal delegating to one of its own devices. */
+const PRINCIPAL_DELEGATION_DEPTH = 1;
+
+/** Admits action.target to DM this user ahead of time: that one device, or, with action.principal, every device of that user principal. `receiverId` is this agent's own device-id, which the returned instructions name so the sender can quote them back verbatim. */
+export async function dmAdmit(
+  store: Readonly<Pick<MeshOnlyFeatures, "admitAgentForDm">>,
+  action: CommsAction & { action: "dm_admit" },
+  receiverId: string,
+): Promise<CommsResult> {
+  if (!store.admitAgentForDm) return grantsUnavailable();
+  const grant = await store.admitAgentForDm(
+    action.target,
+    action.principal === true ? PRINCIPAL_DELEGATION_DEPTH : 0,
+  );
+  const who =
+    action.principal === true
+      ? `${action.target} and every device of that user`
+      : action.target;
+  return {
+    content: [
+      `Admitted ${who} to DM you without asking again.`,
+      `Give them this grant, and have them call dm_use_grant with target ${receiverId} and this grant:`,
+      encodeTokenText(grant),
+    ].join("\n"),
+    isError: false,
+  };
+}
+
+/** Presents action.grant to action.target so this device's DMs to it are admitted without a decision. Throws INVALID_TOKEN, before contacting anyone, when the grant text is not a token. */
+export async function dmUseGrant(
+  store: Readonly<Pick<MeshOnlyFeatures, "presentDmGrant">>,
+  action: CommsAction & { action: "dm_use_grant" },
+): Promise<CommsResult> {
+  if (!store.presentDmGrant) return grantsUnavailable();
+  const grant = decodeTokenText(action.grant);
+  await store.presentDmGrant(action.target, grant);
+  return {
+    content: `DM access to ${action.target} granted; you can now dm it.`,
+    isError: false,
+  };
+}
+
+/** Withdraws the grant admitted for action.target, if one was ever issued. */
+export async function dmRevoke(
+  store: Readonly<Pick<MeshOnlyFeatures, "revokeAgentDmAccess">>,
+  action: CommsAction & { action: "dm_revoke" },
+): Promise<CommsResult> {
+  if (!store.revokeAgentDmAccess) return grantsUnavailable();
+  await store.revokeAgentDmAccess(action.target);
+  return {
+    content: `Revoked ${action.target}'s DM grant.`,
+    isError: false,
+  };
+}