agent-comms 8.15.9 → 8.15.11

package/dist/test/pi-manifest-packed.integration.test.js

@@ -0,0 +1,68 @@
+/**
+ * Every extension the `pi` manifest in package.json names must ship in the published package. `pi install npm:agent-comms` reported success and then could not load the extension when the manifest pointed at `src/`, which `files` did not publish (ExaDev/agent-comms#412, #440); nothing in the suite noticed, because the manifest and the tarball were never compared.
+ *
+ * The tarball contents come from `npm pack --dry-run`, the same file selection a publish uses, so a `files` entry or an ignore rule that drops the manifest's path fails here and not in a user's install.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+const packageRoot = path.resolve(import.meta.dirname, "../..");
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+function manifestExtensions() {
+    const manifest = readJson(path.join(packageRoot, "package.json"));
+    if (!isRecord(manifest) || !isRecord(manifest.pi)) {
+        throw new Error("package.json has no pi manifest");
+    }
+    const { extensions } = manifest.pi;
+    if (!isStringArray(extensions)) {
+        throw new Error("package.json pi.extensions is not a list of paths");
+    }
+    return extensions;
+}
+function packedPaths() {
+    // --ignore-scripts keeps prepack and prepare out of a listing that only needs the file selection.
+    const result = spawnSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], { cwd: packageRoot, encoding: "utf-8" });
+    if (result.status !== 0) {
+        throw new Error(`npm pack --dry-run failed: ${result.stderr}`);
+    }
+    const listing = JSON.parse(result.stdout);
+    if (!Array.isArray(listing) || !isRecord(listing[0])) {
+        throw new Error("npm pack --dry-run printed no package listing");
+    }
+    const { files } = listing[0];
+    if (!Array.isArray(files)) {
+        throw new Error("npm pack --dry-run listing has no files");
+    }
+    return files.map((file) => {
+        if (!isRecord(file) || typeof file.path !== "string") {
+            throw new Error("npm pack --dry-run listed a file without a path");
+        }
+        return file.path;
+    });
+}
+describe("the pi manifest", () => {
+    it("names at least one extension, so the loop below cannot pass by checking nothing", () => {
+        expect(manifestExtensions().length).toBeGreaterThan(0);
+    });
+    it("names only extensions that exist in the repository", () => {
+        for (const extension of manifestExtensions()) {
+            expect(fs.existsSync(path.join(packageRoot, extension)), extension).toBe(true);
+        }
+    });
+    it("names only extensions the published package contains", () => {
+        const packed = new Set(packedPaths());
+        for (const extension of manifestExtensions()) {
+            expect(packed.has(path.posix.normalize(extension)), extension).toBe(true);
+        }
+    });
+});
+//# sourceMappingURL=pi-manifest-packed.integration.test.js.map

package/dist/test/pi-manifest-packed.integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-manifest-packed.integration.test.js","sourceRoot":"","sources":["../../src/test/pi-manifest-packed.integration.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-comms",
   "description": "Cross-harness communication mesh for LLM agents — rooms, DMs, presence, and real-time push delivery over TCP",
-  "version": "8.15.9",
+  "version": "8.15.11",
   "bin": {
     "agent-comms": "dist/cli.js"
   },
@@ -84,6 +84,12 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/test",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/bridges/user/web/e2e",
+    "!src/bridges/user/web/frontend",
     ".claude-plugin/",
     "commands/",
     "hooks/"
@@ -134,7 +140,7 @@
     "generate:server-json": "tsx scripts/sync-release-metadata.ts",
     "lint": "turbo run _lint",
     "mutation": "stryker run stryker.config.ts",
-    "prepare": "husky",
+    "prepare": "husky || true",
     "prepush": "turbo run _prepush",
     "publish:mcp-registry": "tsx scripts/publish-mcp-registry.ts",
     "test": "turbo run _test",

package/src/account-cli.ts

@@ -0,0 +1,195 @@
+/**
+ * `agent-comms account <export|import|invite|join>` (agent-comms#344): the deliberate, consented ways the account key that lets one user principal span machines leaves or reaches a machine. Export and import carry the key as a passphrase-sealed bundle (account-bundle.ts), written to a new owner-only file and never printed; the passphrase comes from AGENT_COMMS_ACCOUNT_PASSPHRASE when set, else from a prompt that does not echo. Invite and join carry it over the mesh (account-join-cli.ts). All four are commands a person runs, never agent_comms tool actions, so nothing an agent is told can move the account and no key or invite lands in an agent's transcript.
+ */
+
+import * as fs from "node:fs";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import {
+  inviteToAccount,
+  joinAccount,
+  type AccountCliStore,
+} from "./account-join-cli.js";
+import { openAccountBundle, sealAccountBundle } from "./core/account-bundle.js";
+import {
+  importAccountKey,
+  loadOrCreateUserIdentity,
+  readAccountContents,
+  type UserIdentityOptions,
+} from "./core/user-identity.js";
+
+/** Where a script supplies the passphrase instead of typing it. */
+export const ACCOUNT_PASSPHRASE_ENV = "AGENT_COMMS_ACCOUNT_PASSPHRASE";
+
+/** A bundle holds the account key, so its file is readable by its owner alone. */
+const BUNDLE_FILE_MODE = 0o600;
+
+export const ACCOUNT_USAGE = [
+  "Usage: agent-comms account export <file>",
+  "       agent-comms account import <file>",
+  "       agent-comms account invite [--ttl-minutes <n>] [--sign-key <file>]",
+  "       agent-comms account join [--public-key <file>] [--fingerprint <hex>] [--label <name>]",
+].join("\n");
+
+export interface AccountCliIo {
+  /** Reads a secret (a passphrase, an invite) without echoing it. */
+  readSecret: (prompt: string) => Promise<string>;
+  log: (line: string) => void;
+  env: Readonly<Record<string, string | undefined>>;
+  /** Starts a store on this machine's mesh for invite and join, which need one to reach the other machine. */
+  openStore: () => Promise<AccountCliStore>;
+}
+
+async function passphrase(
+  io: Readonly<AccountCliIo>,
+  confirm: boolean,
+): Promise<string> {
+  const fromEnv = io.env[ACCOUNT_PASSPHRASE_ENV];
+  if (fromEnv !== undefined) return fromEnv;
+  const first = await io.readSecret("Account bundle passphrase: ");
+  if (!confirm) return first;
+  const second = await io.readSecret("Repeat the passphrase: ");
+  if (first !== second) throw new Error("The passphrases do not match");
+  return first;
+}
+
+function principalOf(identity: Readonly<{ deviceId: Uint8Array }>): string {
+  return deviceIdToHex(Uint8Array.from(identity.deviceId));
+}
+
+/** Runs one `account` subcommand. Throws with a message fit to show the person on any failure: an unknown subcommand or option, a file that already exists (an export never overwrites), a weak or wrong passphrase, a file that is not a bundle, or an invite that is malformed or refused. */
+export async function runAccountCommand(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+  userIdentityOptions: Readonly<UserIdentityOptions> = {},
+): Promise<void> {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "invite") {
+    await inviteToAccount(rest, io);
+    return;
+  }
+  if (subcommand === "join") {
+    await joinAccount(rest, io);
+    return;
+  }
+  const [file, ...extra] = rest;
+  if (file === undefined || extra.length > 0) throw new Error(ACCOUNT_USAGE);
+  if (subcommand === "export") {
+    const identity = loadOrCreateUserIdentity(userIdentityOptions);
+    const bundle = sealAccountBundle(
+      readAccountContents(userIdentityOptions),
+      await passphrase(io, true),
+    );
+    fs.writeFileSync(file, `${bundle}\n`, {
+      encoding: "utf-8",
+      mode: BUNDLE_FILE_MODE,
+      flag: "wx",
+    });
+    io.log(
+      `Exported account ${principalOf(identity)} to ${file}. Anyone with this file and its passphrase holds the account; import it on your other machine with \`agent-comms account import ${file}\`, then delete it.`,
+    );
+    return;
+  }
+  if (subcommand === "import") {
+    const contents = openAccountBundle(
+      fs.readFileSync(file, "utf-8"),
+      await passphrase(io, false),
+    );
+    const { identity, replacedFile } = importAccountKey(
+      userIdentityOptions,
+      contents,
+    );
+    io.log(`This machine now holds account ${principalOf(identity)}.`);
+    if (replacedFile !== undefined) {
+      io.log(
+        `The account it held before was moved to ${replacedFile}; it is still the only key that can revoke what that account issued.`,
+      );
+    }
+    io.log("Restart running agent-comms bridges so they use it.");
+    return;
+  }
+  throw new Error(ACCOUNT_USAGE);
+}
+
+/** What one keypress does to a hidden line being typed. */
+export type HiddenLineStep =
+  | { kind: "typing"; value: string }
+  | { kind: "done"; value: string }
+  | { kind: "failed"; message: string };
+
+const END_OF_TEXT = "\u0003";
+const END_OF_TRANSMISSION = "\u0004";
+const BACKSPACE = "\b";
+const DELETE = "\u007f";
+/** Every character ordered before this one is a C0 control character, none of which a passphrase can hold. */
+const FIRST_PRINTABLE = " ";
+
+/** Applies one character typed at a hidden prompt to the line so far. Enter, or Ctrl-D on a line with something on it, ends the line; Ctrl-C, and Ctrl-D on an empty line, cancel it. Backspace and Delete remove the last character. An escape sequence (an arrow or function key) or any other control character is refused rather than kept, since it would end up in the value invisibly and could never be typed the same way again. */
+export function hiddenLineStep(
+  value: string,
+  character: string,
+): HiddenLineStep {
+  if (character === "\r" || character === "\n") return { kind: "done", value };
+  if (character === END_OF_TEXT)
+    return { kind: "failed", message: "Cancelled" };
+  if (character === END_OF_TRANSMISSION) {
+    return value === ""
+      ? { kind: "failed", message: "Cancelled: no input before end of input" }
+      : { kind: "done", value };
+  }
+  if (character === BACKSPACE || character === DELETE) {
+    // A terminal's backspace removes one visible character, which may be several code points.
+    const graphemes = Array.from(
+      new Intl.Segmenter().segment(value),
+      ({ segment }) => segment,
+    );
+    return { kind: "typing", value: graphemes.slice(0, -1).join("") };
+  }
+  // Escape, which starts every arrow and function key's sequence, is one of these.
+  if (character < FIRST_PRINTABLE) {
+    return {
+      kind: "failed",
+      message:
+        "Arrow keys, Escape and other control keys cannot be used at this prompt, since they would be kept in it invisibly; start again and type it plainly",
+    };
+  }
+  return { kind: "typing", value: value + character };
+}
+
+/** Reads one line from a terminal with echo off, keystroke by keystroke as hiddenLineStep describes. Throws when stdin is not a terminal, since there is nowhere to prompt; a bundle passphrase can then come from ACCOUNT_PASSPHRASE_ENV instead. */
+export async function readHiddenLine(prompt: string): Promise<string> {
+  const { stdin, stderr } = process;
+  if (!stdin.isTTY) {
+    throw new Error(
+      `No terminal to ask on (${prompt.trim()}); a bundle passphrase can be set in ${ACCOUNT_PASSPHRASE_ENV} instead`,
+    );
+  }
+  stderr.write(prompt);
+  stdin.setRawMode(true);
+  stdin.setEncoding("utf-8");
+  stdin.resume();
+  return new Promise((resolve, reject) => {
+    let value = "";
+    // Replaced once the listener exists, so the listener can detach itself.
+    let finish = (): void => undefined;
+    const onData = (chunk: string): void => {
+      for (const character of chunk) {
+        const step = hiddenLineStep(value, character);
+        if (step.kind === "typing") {
+          value = step.value;
+          continue;
+        }
+        finish();
+        if (step.kind === "done") resolve(step.value);
+        else reject(new Error(step.message));
+        return;
+      }
+    };
+    finish = (): void => {
+      stdin.off("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stderr.write("\n");
+    };
+    stdin.on("data", onData);
+  });
+}

package/src/account-join-cli.ts

@@ -0,0 +1,191 @@
+/**
+ * `agent-comms account invite` and `agent-comms account join` (agent-comms#344): joining a new machine to the account over the mesh (see core/account-join.ts for the flow). Each runs a store of its own for as long as the command runs. An invite is printed to this terminal only, and the command keeps its store up until the invite is redeemed or expires, since invites live only in the issuing store's memory. A join reads the invite at a prompt that does not echo, so it never sits in shell history.
+ */
+
+import * as fs from "node:fs";
+import type { AccountJoin } from "./core/account-join.js";
+import { createBridgeMesh } from "./core/bridge-mesh.js";
+import { createMeshErrorReporter } from "./core/error-reporting.js";
+import {
+  releaseIdentityLock,
+  type IdentitySlot,
+} from "./core/identity-store.js";
+import type { GenerateConnectionCodeOptions } from "./core/connection-code.js";
+import type { RedeemConnectionCodeOptions } from "./core/connection-code.js";
+import { ConnectionCodeSchema, type ConnectionCode } from "./core/types.js";
+import { ACCOUNT_USAGE, type AccountCliIo } from "./account-cli.js";
+
+/** A store started for one invite or join, and its shutdown. */
+export interface AccountCliStore {
+  account: Pick<AccountJoin, "invite" | "join">;
+  close: () => Promise<void>;
+}
+
+/** The identity slot harness these commands' own store runs under, apart from every bridge's. */
+const ACCOUNT_CLI_HARNESS = "account";
+
+/** Starts a store on this machine's mesh, holding the machine's account, with one hidden agent: that is what gives it a hub session once it trusts the other machine, and a hidden agent is reachable by device id without being listed. */
+export async function openMachineAccountStore(): Promise<AccountCliStore> {
+  const slot: IdentitySlot = {
+    harness: ACCOUNT_CLI_HARNESS,
+    cwd: process.cwd(),
+  };
+  const { store } = await createBridgeMesh(slot);
+  store.onError = createMeshErrorReporter();
+  await store.init();
+  const agent = await store.registerAgent({
+    name: ACCOUNT_CLI_HARNESS,
+    harness: ACCOUNT_CLI_HARNESS,
+    cwd: slot.cwd,
+    pid: process.pid,
+    visibility: "hidden",
+    tags: [],
+  });
+  return {
+    account: store.account,
+    close: async () => {
+      await store.setAgentOffline(agent.id);
+      await store.shutdown();
+      releaseIdentityLock(slot);
+    },
+  };
+}
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/** Parses `--name value` pairs, allowing only `allowed` names, each at most once. */
+function parseOptions(
+  args: readonly string[],
+  allowed: readonly string[],
+): Map<string, string> {
+  const options = new Map<string, string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const name = args[i];
+    const value = args[i + 1];
+    if (
+      name === undefined ||
+      !name.startsWith("--") ||
+      !allowed.includes(name.slice(2)) ||
+      options.has(name.slice(2)) ||
+      value === undefined
+    ) {
+      throw new Error(ACCOUNT_USAGE);
+    }
+    options.set(name.slice(2), value);
+  }
+  return options;
+}
+
+function ttlMsFrom(minutes: string | undefined): number | undefined {
+  if (minutes === undefined) return undefined;
+  const parsed = Number(minutes);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(
+      `--ttl-minutes must be a whole number of minutes above zero, not ${minutes}`,
+    );
+  }
+  return parsed * MS_PER_MINUTE;
+}
+
+async function signingOptions(
+  keyFile: string | undefined,
+  io: Readonly<AccountCliIo>,
+): Promise<
+  Pick<GenerateConnectionCodeOptions, "privateKeyArmored" | "passphrase">
+> {
+  if (keyFile === undefined) return {};
+  const privateKeyArmored = fs.readFileSync(keyFile, "utf-8");
+  const passphrase = await io.readSecret(
+    "PGP key passphrase (press Enter if it has none): ",
+  );
+  return passphrase === ""
+    ? { privateKeyArmored }
+    : { privateKeyArmored, passphrase };
+}
+
+/** Issues an invite, prints it, and returns once it has been redeemed or has expired. */
+export async function inviteToAccount(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+): Promise<void> {
+  const options = parseOptions(args, ["ttl-minutes", "sign-key"]);
+  const ttlMs = ttlMsFrom(options.get("ttl-minutes"));
+  const signing = await signingOptions(options.get("sign-key"), io);
+  const store = await io.openStore();
+  try {
+    const { code, settled } = await store.account.invite({
+      ...(ttlMs !== undefined && { ttlMs }),
+      ...signing,
+    });
+    io.log(
+      `Account invite, valid until ${code.expiresAt} and for one use. Whoever redeems it takes a full copy of this account, so give it only to your own new machine, out of band, and run \`agent-comms account join\` there. Keep this command running until then.`,
+    );
+    io.log(JSON.stringify(code));
+    const outcome = await settled;
+    io.log(
+      outcome === "redeemed"
+        ? "The invite was redeemed: the new machine now holds this account."
+        : "The invite expired unused.",
+    );
+  } finally {
+    await store.close();
+  }
+}
+
+const NOT_AN_INVITE =
+  "That is not an account invite: paste the whole line `agent-comms account invite` printed";
+
+function parseInvite(raw: string): ConnectionCode {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(NOT_AN_INVITE);
+  }
+  if (!ConnectionCodeSchema.is(parsed)) {
+    throw new Error(NOT_AN_INVITE);
+  }
+  return parsed;
+}
+
+function verifyingOptions(
+  options: ReadonlyMap<string, string>,
+): RedeemConnectionCodeOptions {
+  const keyFile = options.get("public-key");
+  const fingerprint = options.get("fingerprint");
+  return {
+    ...(keyFile !== undefined && {
+      publicKeyArmored: fs.readFileSync(keyFile, "utf-8"),
+    }),
+    ...(fingerprint !== undefined && { expectedFingerprint: fingerprint }),
+  };
+}
+
+/** Reads an invite at a prompt and makes this machine hold the account it came from. With --label, the issuing machine keeps the label as its own name for this one. */
+export async function joinAccount(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+): Promise<void> {
+  const options = parseOptions(args, ["public-key", "fingerprint", "label"]);
+  const label = options.get("label");
+  const joinOptions = {
+    ...verifyingOptions(options),
+    ...(label !== undefined && { label }),
+  };
+  const invite = parseInvite(await io.readSecret("Account invite: "));
+  const store = await io.openStore();
+  try {
+    const result = await store.account.join(invite, joinOptions);
+    io.log(`This machine now holds account ${result.principal}.`);
+    if (result.replacedFile !== undefined) {
+      io.log(
+        `The account it held before was moved to ${result.replacedFile}; it is still the only key that can revoke what that account issued.`,
+      );
+    }
+    io.log("Restart running agent-comms bridges so they use it.");
+  } finally {
+    await store.close();
+  }
+}

package/src/bridges/cc-peer/approval-commands.ts

@@ -0,0 +1,82 @@
+/**
+ * Lets a cc-peer session answer a room join or first-contact DM request. A session reached only through cc-peer (no agent-comms tool of its own) cannot call room_accept or room_reject, so the relayed request tells it exactly what to message back, and the relay runs the same tool action when that message arrives. The person at the session decides: only a message from that session's own socket ever reaches its relay.
+ */
+
+import { buildAction, formatDeliveryEvent } from "../../core/bridge.js";
+import type { CommsContext, CommsTool } from "../../core/tool.js";
+import type { DeliveryEvent } from "../../core/types.js";
+
+/** A device-id is a 64-character lowercase hex SHA-256 digest. */
+const DEVICE_ID_HEX = "[0-9a-f]{64}";
+
+/** `accept <room> <requester>` or `reject <room> <requester> [reason]`, the whole message and nothing else, so an ordinary message that merely mentions the word is never mistaken for a decision. */
+const APPROVAL_COMMAND = new RegExp(
+  `^\\s*(accept|reject)\\s+(\\S+)\\s+(${DEVICE_ID_HEX})(?:\\s+(\\S[\\s\\S]*?))?\\s*$`,
+  "i",
+);
+
+export type ApprovalCommand =
+  | { kind: "accept"; room: string; requesterId: string }
+  | { kind: "reject"; room: string; requesterId: string; reason?: string };
+
+/** The command a message body is, or undefined when it is not a well-formed one. */
+export function parseApprovalCommand(
+  body: string,
+): ApprovalCommand | undefined {
+  const match = APPROVAL_COMMAND.exec(body);
+  if (match === null) return undefined;
+  const [, verb, room, requesterId, reason] = match;
+  if (verb === undefined || room === undefined || requesterId === undefined) {
+    return undefined;
+  }
+  if (verb.toLowerCase() === "accept") {
+    return { kind: "accept", room, requesterId: requesterId.toLowerCase() };
+  }
+  return {
+    kind: "reject",
+    room,
+    requesterId: requesterId.toLowerCase(),
+    ...(reason !== undefined ? { reason } : {}),
+  };
+}
+
+/** Renders a delivery event for a cc-peer session. A join request carries the instructions for answering it through `peerName`, the peer the session should message; every other event renders as the shared formatter does. */
+export function formatCcPeerDelivery(
+  event: DeliveryEvent,
+  peerName: string,
+): string {
+  if (event.type !== "room_join_request") return formatDeliveryEvent(event);
+  return [
+    `${event.requesterId} is asking to join ${event.room}.`,
+    `To answer, send the peer "${peerName}" one of these messages:`,
+    `accept ${event.room} ${event.requesterId}`,
+    `reject ${event.room} ${event.requesterId} <optional reason>`,
+  ].join("\n");
+}
+
+export interface AnswerJoinRequestDeps {
+  tool: Pick<CommsTool, "handle">;
+  ctx: Readonly<CommsContext>;
+}
+
+/** Runs the room_accept or room_reject the command asks for as this session's own agent, and returns the tool's own text so the session learns what happened, including why a decision failed. */
+export async function answerJoinRequest(
+  deps: Readonly<AnswerJoinRequestDeps>,
+  command: Readonly<ApprovalCommand>,
+): Promise<string> {
+  const action =
+    command.kind === "accept"
+      ? buildAction({
+          action: "room_accept",
+          room: command.room,
+          requesterId: command.requesterId,
+        })
+      : buildAction({
+          action: "room_reject",
+          room: command.room,
+          requesterId: command.requesterId,
+          ...(command.reason !== undefined ? { reason: command.reason } : {}),
+        });
+  const result = await deps.tool.handle(deps.ctx, action);
+  return result.content;
+}