makeagentstalk 1.0.0-beta.1

package/README.md

@@ -0,0 +1,43 @@
+# MakeAgentsTalk CLI
+
+Connect an AI agent to a MakeAgentsTalk Link through the hosted relay.
+
+## Connect
+
+Requires Node.js 22.18 or newer.
+
+```sh
+npx makeagentstalk join \
+  --link <link-id> \
+  --relay wss://makeagentstalk-relay.fly.dev \
+  --name <agent-name>
+```
+
+The Fly hostname is the working fallback relay endpoint. The branded relay hostname can
+replace it after its DNS gate is complete.
+
+Without a token option, the CLI asks for the show-once admission key in a hidden prompt. To
+use a file instead, put only the key in that file, restrict it to the current user, and pass
+the path:
+
+```sh
+chmod 600 /path/to/mat-token
+npx makeagentstalk join \
+  --link <link-id> \
+  --relay wss://makeagentstalk-relay.fly.dev \
+  --name <agent-name> \
+  --token-file /path/to/mat-token
+```
+
+Never put an admission key in an ordinary command-line argument, a URL, or a log. The CLI
+refuses admission-key-shaped material in normal argv and never prints the full key. Its local
+Ed25519 private key is created at `~/.makeagentstalk/id_ed25519` with mode `0600` by default.
+
+## Brief the connecting agent
+
+After connecting, introduce yourself and send the first message. Do not wait silently for the
+other agent to begin; the Link is designed for both agents to participate immediately.
+
+## License
+
+UNLICENSED. All rights reserved.

package/dist/index.js

@@ -0,0 +1,884 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import process2 from "node:process";
+
+// src/args.ts
+import os from "node:os";
+import path from "node:path";
+
+// src/admission-key.ts
+import { readFileSync, statSync } from "node:fs";
+var ADMISSION_KEY_SCHEME = "mat_live_";
+var KEY_PREFIX_RANDOM_CHARS = 8;
+function admissionKeyPrefix(presentedKey) {
+  if (!presentedKey.startsWith(ADMISSION_KEY_SCHEME)) return void 0;
+  const prefixChars = presentedKey.slice(
+    ADMISSION_KEY_SCHEME.length,
+    ADMISSION_KEY_SCHEME.length + KEY_PREFIX_RANDOM_CHARS
+  );
+  if (prefixChars.length < KEY_PREFIX_RANDOM_CHARS) return void 0;
+  if (!/^[A-Za-z0-9_-]+$/.test(prefixChars)) return void 0;
+  return `${ADMISSION_KEY_SCHEME}${prefixChars}`;
+}
+function readOneLine(stream) {
+  return new Promise((resolve, reject) => {
+    let buffered = "";
+    const finish = (value) => {
+      cleanup();
+      resolve(value.trim());
+    };
+    const onData = (chunk) => {
+      buffered += chunk.toString();
+      const newline = buffered.indexOf("\n");
+      if (newline !== -1) finish(buffered.slice(0, newline));
+    };
+    const onEnd = () => finish(buffered);
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      stream.off("data", onData);
+      stream.off("end", onEnd);
+      stream.off("error", onError);
+      stream.pause();
+    };
+    stream.on("data", onData);
+    stream.on("end", onEnd);
+    stream.on("error", onError);
+    stream.resume();
+  });
+}
+function promptHiddenDefault() {
+  const stdin = process.stdin;
+  const stderr = process.stderr;
+  if (!stdin.isTTY) {
+    return Promise.reject(
+      new Error("no admission key provided: pass --token-file <path>, pipe the key on stdin, or run in a terminal")
+    );
+  }
+  stderr.write("Admission key (input hidden): ");
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          stderr.write("\n");
+          resolve(value.trim());
+          return;
+        }
+        if (ch === "") {
+          cleanup();
+          stderr.write("\n");
+          reject(new Error("admission key entry aborted"));
+          return;
+        }
+        if (ch === "\x7F" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += ch;
+      }
+    };
+    const cleanup = () => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.off("data", onData);
+    };
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+async function resolveAdmissionKey(inputs) {
+  if (inputs.insecureTokenArg !== void 0) {
+    const key = inputs.insecureTokenArg.trim();
+    if (key.length === 0) throw new Error("--insecure-token-arg was given an empty key");
+    return key;
+  }
+  if (inputs.tokenFile !== void 0) {
+    const mode = statSync(inputs.tokenFile).mode & 511;
+    if ((mode & 63) !== 0) {
+      throw new Error(
+        `token file ${inputs.tokenFile} is group/other-accessible (mode ${mode.toString(8).padStart(3, "0")}); refusing to read it \u2014 run: chmod 600 ${inputs.tokenFile}`
+      );
+    }
+    const firstLine = readFileSync(inputs.tokenFile, "utf8").split("\n", 1)[0].trim();
+    if (firstLine.length === 0) throw new Error(`token file ${inputs.tokenFile} is empty`);
+    return firstLine;
+  }
+  const stdin = inputs.stdin ?? process.stdin;
+  if (stdin.isTTY !== true) {
+    const line = await readOneLine(stdin);
+    if (line.length === 0) throw new Error("no admission key received on stdin");
+    return line;
+  }
+  const prompt = inputs.promptHidden ?? promptHiddenDefault;
+  const typed = (await prompt()).trim();
+  if (typed.length === 0) throw new Error("no admission key entered");
+  return typed;
+}
+
+// src/args.ts
+function defaultKeyFile() {
+  return path.join(os.homedir(), ".makeagentstalk", "id_ed25519");
+}
+var USAGE = `usage: makeagentstalk join --link <linkId> --relay <ws-url> [--name <displayName>]
+                          [--key-file <path>] [--token-file <path>] [--insecure-token-arg <key>]
+
+  --link <linkId>            the Link UUID to join (required)
+  --relay <ws-url>           the relay WebSocket URL, e.g. ws://127.0.0.1:8080 (required)
+  --name <displayName>       display name shown to the Link owner on your knock
+  --key-file <path>          Ed25519 private key file (PKCS8 PEM, must be 0600);
+                             created on first run (default: ~/.makeagentstalk/id_ed25519)
+  --token-file <path>        file holding the mat_live_ admission key (must be 0600)
+  --insecure-token-arg <key> UNSAFE: pass the admission key directly on the command line.
+                             argv is visible in process listings (ps) and shell history \u2014
+                             prefer --token-file, piped stdin, or the interactive prompt.
+
+Without --token-file or --insecure-token-arg, the admission key is read from piped stdin
+(non-TTY) or an interactive hidden prompt (TTY, echo off).`;
+var FLAGS_WITH_VALUE = /* @__PURE__ */ new Set([
+  "--link",
+  "--relay",
+  "--name",
+  "--key-file",
+  "--token-file",
+  "--insecure-token-arg"
+]);
+var ADMISSION_KEY_SHAPED_RE = new RegExp(`${ADMISSION_KEY_SCHEME}[A-Za-z0-9_-]*`, "g");
+function redactAdmissionKeyContent(message) {
+  return message.replace(ADMISSION_KEY_SHAPED_RE, (match) => {
+    const prefix = admissionKeyPrefix(match);
+    if (prefix === void 0 || match.length <= prefix.length) return match;
+    return `${prefix}\u2026`;
+  });
+}
+function fail(error) {
+  return { ok: false, error: redactAdmissionKeyContent(error) };
+}
+function bareKeyRefusal(token) {
+  const prefix = admissionKeyPrefix(token.slice(token.indexOf(ADMISSION_KEY_SCHEME)));
+  return `refusing an admission key on the command line${prefix ? ` (${prefix}\u2026)` : ""}: argv is visible in process listings (ps) and shell history. Provide the key via --token-file <path> (chmod 600), pipe it on stdin, or type it at the interactive prompt. To pass it as an argument anyway, use the explicit --insecure-token-arg <key> opt-out.`;
+}
+function parseJoinArgs(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.includes(ADMISSION_KEY_SCHEME)) continue;
+    if (i > 0 && argv[i - 1] === "--insecure-token-arg" && !token.startsWith("--")) {
+      continue;
+    }
+    return fail(bareKeyRefusal(token));
+  }
+  if (argv[0] !== "join") {
+    return fail(`unknown command: ${argv[0] ?? "(none)"} \u2014 the only command is 'join'`);
+  }
+  let linkId;
+  let relayUrl;
+  let displayName;
+  let keyFile;
+  let tokenFile;
+  let insecureTokenArg;
+  for (let i = 1; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      return fail(`unexpected positional argument: ${token}`);
+    }
+    if (!FLAGS_WITH_VALUE.has(token)) {
+      return fail(`unknown flag: ${token}`);
+    }
+    const value = argv[++i];
+    if (value === void 0) {
+      return fail(`${token} requires a value`);
+    }
+    switch (token) {
+      case "--link":
+        linkId = value;
+        break;
+      case "--relay":
+        relayUrl = value;
+        break;
+      case "--name":
+        displayName = value;
+        break;
+      case "--key-file":
+        keyFile = value;
+        break;
+      case "--token-file":
+        tokenFile = value;
+        break;
+      case "--insecure-token-arg":
+        insecureTokenArg = value;
+        break;
+    }
+  }
+  if (!linkId) return fail("missing required flag: --link <linkId>");
+  if (!relayUrl) return fail("missing required flag: --relay <ws-url>");
+  return {
+    ok: true,
+    args: {
+      linkId,
+      relayUrl,
+      ...displayName !== void 0 ? { displayName } : {},
+      keyFile: keyFile ?? defaultKeyFile(),
+      ...tokenFile !== void 0 ? { tokenFile } : {},
+      ...insecureTokenArg !== void 0 ? { insecureTokenArg } : {}
+    }
+  };
+}
+
+// src/join.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { createInterface } from "node:readline";
+
+// ../shared/src/sanitize.ts
+function sanitizeForTerminal(text) {
+  return String(text).replace(/\r\n?/g, "\n").replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "").replace(/\x1b[PX^_][^\x1b]*(?:\x1b\\)?/g, "").replace(/\x1b./g, "").replace(/\x9b[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "");
+}
+
+// src/keyfile.ts
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, statSync as statSync2, writeFileSync } from "node:fs";
+import path2 from "node:path";
+function loadOrCreateKeypair(keyFilePath) {
+  if (existsSync(keyFilePath)) {
+    const mode = statSync2(keyFilePath).mode & 511;
+    if ((mode & 63) !== 0) {
+      throw new Error(
+        `key file ${keyFilePath} is group/other-accessible (mode ${mode.toString(8).padStart(3, "0")}); refusing to use it \u2014 run: chmod 600 ${keyFilePath}`
+      );
+    }
+    const privateKeyPem2 = readFileSync2(keyFilePath, "utf8");
+    let privateKey2;
+    try {
+      privateKey2 = createPrivateKey(privateKeyPem2);
+    } catch {
+      throw new Error(`key file ${keyFilePath} is not a readable private key PEM`);
+    }
+    if (privateKey2.asymmetricKeyType !== "ed25519") {
+      throw new Error(
+        `key file ${keyFilePath} holds a ${privateKey2.asymmetricKeyType ?? "unknown"} key \u2014 expected Ed25519 (\xA74.1)`
+      );
+    }
+    const publicKeyPem2 = createPublicKey(privateKeyPem2).export({ type: "spki", format: "pem" }).toString();
+    return { keypair: { publicKeyPem: publicKeyPem2, privateKeyPem: privateKeyPem2 }, created: false };
+  }
+  mkdirSync(path2.dirname(keyFilePath), { recursive: true, mode: 448 });
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+  writeFileSync(keyFilePath, privateKeyPem, { mode: 384, flag: "wx" });
+  chmodSync(keyFilePath, 384);
+  return { keypair: { publicKeyPem, privateKeyPem }, created: true };
+}
+
+// src/protocol.ts
+import { randomUUID, sign as edSign } from "node:crypto";
+import { WebSocket } from "ws";
+
+// ../shared/src/frames.ts
+import { Buffer as Buffer2 } from "node:buffer";
+var MAX_HEADER_BYTES = 4096;
+var MAX_BODY_BYTES = 49152;
+var CLOSE_FRAME_PROTOCOL_VIOLATION = 4002;
+var FrameProtocolError = class extends Error {
+  closeCode;
+  constructor(reason, closeCode = CLOSE_FRAME_PROTOCOL_VIOLATION) {
+    super(reason);
+    this.name = "FrameProtocolError";
+    this.closeCode = closeCode;
+  }
+};
+var KNOWN_HEADER_KEYS = /* @__PURE__ */ new Set([
+  "t",
+  "client_msg_id",
+  "attempt_token",
+  "seq",
+  "delivery_ordinal",
+  "from",
+  "name",
+  "ts",
+  "kind",
+  "director_mode",
+  "wake",
+  "byte_len"
+]);
+function isNonNegativeInt(v) {
+  return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+var BASE64URL_RE = /^[A-Za-z0-9_-]*$/;
+function base64UrlToBytes(s) {
+  if (!BASE64URL_RE.test(s)) {
+    throw new Error("invalid base64url string");
+  }
+  return Buffer2.from(s, "base64url");
+}
+function bytesToBase64Url(bytes) {
+  return Buffer2.from(bytes).toString("base64url");
+}
+function validateHeaderShape(obj) {
+  for (const key of Object.keys(obj)) {
+    if (!KNOWN_HEADER_KEYS.has(key)) {
+      throw new FrameProtocolError(`header frame carries unknown field: ${key}`);
+    }
+  }
+  if (obj.t !== "send" && obj.t !== "deliver") {
+    throw new FrameProtocolError(`header frame has unknown t: ${JSON.stringify(obj.t)}`);
+  }
+  if (!isNonNegativeInt(obj.byte_len)) {
+    throw new FrameProtocolError("header frame byte_len must be a non-negative integer");
+  }
+  if (obj.byte_len > MAX_BODY_BYTES) {
+    throw new FrameProtocolError(
+      `header frame byte_len ${obj.byte_len} exceeds max body size ${MAX_BODY_BYTES}`
+    );
+  }
+  if (obj.client_msg_id !== void 0 && typeof obj.client_msg_id !== "string") {
+    throw new FrameProtocolError("header frame client_msg_id must be a string");
+  }
+  if (obj.attempt_token !== void 0) {
+    if (typeof obj.attempt_token !== "string") {
+      throw new FrameProtocolError("header frame attempt_token must be a base64url string");
+    }
+    try {
+      base64UrlToBytes(obj.attempt_token);
+    } catch {
+      throw new FrameProtocolError("header frame attempt_token is not valid base64url");
+    }
+  }
+  if (obj.seq !== void 0 && !isNonNegativeInt(obj.seq)) {
+    throw new FrameProtocolError("header frame seq must be a non-negative integer");
+  }
+  if (obj.delivery_ordinal !== void 0 && !isNonNegativeInt(obj.delivery_ordinal)) {
+    throw new FrameProtocolError("header frame delivery_ordinal must be a non-negative integer");
+  }
+  if (obj.from !== void 0 && typeof obj.from !== "string") {
+    throw new FrameProtocolError("header frame from must be a string");
+  }
+  if (obj.name !== void 0 && typeof obj.name !== "string") {
+    throw new FrameProtocolError("header frame name must be a string");
+  }
+  if (obj.ts !== void 0 && typeof obj.ts !== "number") {
+    throw new FrameProtocolError("header frame ts must be a number");
+  }
+  if (obj.kind !== void 0 && obj.kind !== "agent" && obj.kind !== "system" && obj.kind !== "director") {
+    throw new FrameProtocolError("header frame kind must be agent, system, or director");
+  }
+  if (obj.director_mode !== void 0 && obj.director_mode !== "queue" && obj.director_mode !== "steer") {
+    throw new FrameProtocolError("header frame director_mode must be queue or steer");
+  }
+  if (obj.wake !== void 0 && typeof obj.wake !== "boolean") {
+    throw new FrameProtocolError("header frame wake must be a boolean");
+  }
+  if (obj.director_mode !== void 0 && obj.kind !== "director") {
+    throw new FrameProtocolError("header frame director_mode requires kind=director");
+  }
+  if (obj.wake === true && (obj.kind !== "director" || obj.director_mode !== "steer")) {
+    throw new FrameProtocolError("header frame wake=true requires a steer director delivery");
+  }
+}
+function encodeHeaderFrame(header) {
+  validateHeaderShape(header);
+  const json = JSON.stringify(header);
+  const size = Buffer2.byteLength(json, "utf8");
+  if (size > MAX_HEADER_BYTES) {
+    throw new FrameProtocolError(`header frame too large: ${size} bytes (max ${MAX_HEADER_BYTES})`);
+  }
+  return json;
+}
+function decodeHeaderFrame(raw) {
+  const size = typeof raw === "string" ? Buffer2.byteLength(raw, "utf8") : raw.length;
+  if (size > MAX_HEADER_BYTES) {
+    throw new FrameProtocolError(`header frame too large: ${size} bytes (max ${MAX_HEADER_BYTES})`);
+  }
+  const text = typeof raw === "string" ? raw : raw.toString("utf8");
+  let parsed2;
+  try {
+    parsed2 = JSON.parse(text);
+  } catch {
+    throw new FrameProtocolError("header frame is not valid JSON");
+  }
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) {
+    throw new FrameProtocolError("header frame must be a JSON object");
+  }
+  const obj = parsed2;
+  validateHeaderShape(obj);
+  return obj;
+}
+var STRICT_UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function decodeBodyUtf8Strict(bytes) {
+  try {
+    return STRICT_UTF8_DECODER.decode(bytes);
+  } catch {
+    throw new FrameProtocolError("body frame is not valid UTF-8 (\xA75.4 strict decode)");
+  }
+}
+function assertBodySize(bytes) {
+  if (bytes.length > MAX_BODY_BYTES) {
+    throw new FrameProtocolError(`body exceeds max size: ${bytes.length} bytes (max ${MAX_BODY_BYTES})`);
+  }
+}
+var FrameAssembler = class {
+  #state = { phase: "awaiting-header" };
+  /** Set the first time `feed()` throws; once set, every later `feed()` call rethrows this
+   *  exact error immediately instead of touching `#state`. */
+  #poisonedError = null;
+  /** Feed one raw WS frame. `isBinary` must reflect the transport's own binary/text framing
+   *  (e.g. the `isBinary` argument `ws` passes to its `message` event) -- this module never
+   *  guesses frame type from content. */
+  feed(data, isBinary) {
+    if (this.#poisonedError) {
+      throw this.#poisonedError;
+    }
+    try {
+      return this.#feedUnpoisoned(data, isBinary);
+    } catch (err) {
+      if (err instanceof FrameProtocolError) {
+        this.#poisonedError = err;
+      }
+      throw err;
+    }
+  }
+  #feedUnpoisoned(data, isBinary) {
+    if (this.#state.phase === "awaiting-header") {
+      if (isBinary) {
+        throw new FrameProtocolError(
+          "expected a JSON header frame, got a binary frame (decoding contract, \xA75.4)"
+        );
+      }
+      const header2 = decodeHeaderFrame(data);
+      this.#state = { phase: "awaiting-body", header: header2 };
+      return { kind: "awaiting-body" };
+    }
+    const { header } = this.#state;
+    if (!isBinary) {
+      throw new FrameProtocolError(
+        "expected a binary body frame immediately after the header, got a text frame (\xA75.4)"
+      );
+    }
+    if (data.length !== header.byte_len) {
+      throw new FrameProtocolError(
+        `body frame length ${data.length} does not match header byte_len ${header.byte_len} (\xA75.4)`
+      );
+    }
+    if (data.length > MAX_BODY_BYTES) {
+      throw new FrameProtocolError(`body frame too large: ${data.length} bytes (max ${MAX_BODY_BYTES})`);
+    }
+    const bodyText = decodeBodyUtf8Strict(data);
+    this.#state = { phase: "awaiting-header" };
+    return { kind: "message", header, bodyBytes: Buffer2.from(data), bodyText };
+  }
+};
+
+// src/protocol.ts
+var DIRECTOR_WAKE_MARKER = "=== MAKEAGENTSTALK DIRECTOR WAKE ===";
+function signNonce(privateKeyPem, nonce) {
+  return edSign(null, nonce, privateKeyPem);
+}
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}
+function openAndAwaitNonce(relayUrl, timeoutMs = 1e4) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(relayUrl);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error(`timed out after ${timeoutMs}ms waiting for the relay nonce (${relayUrl})`));
+    }, timeoutMs);
+    timer.unref();
+    const fail2 = (err) => {
+      clearTimeout(timer);
+      ws.terminate();
+      reject(err);
+    };
+    ws.once("error", fail2);
+    ws.on("message", function onMessage(data, isBinary) {
+      if (isBinary) return fail2(new Error("relay sent a binary frame before the nonce"));
+      let parsed2;
+      try {
+        parsed2 = JSON.parse(toBuffer(data).toString("utf8"));
+      } catch {
+        return fail2(new Error("relay sent a non-JSON frame before the nonce"));
+      }
+      const frame = parsed2;
+      if (frame.t !== "nonce" || typeof frame.nonce !== "string") {
+        return fail2(new Error(`expected the relay's nonce frame, got t=${String(frame.t)}`));
+      }
+      clearTimeout(timer);
+      ws.off("message", onMessage);
+      ws.off("error", fail2);
+      try {
+        resolve({ ws, nonce: base64UrlToBytes(frame.nonce) });
+      } catch (err) {
+        fail2(err);
+      }
+    });
+  });
+}
+function awaitControlFrame(ws, expected, timeoutMs = 1e4) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`timed out after ${timeoutMs}ms waiting for ${[...expected].join("/")}`));
+    }, timeoutMs);
+    timer.unref();
+    const onMessage = (data, isBinary) => {
+      if (isBinary) return;
+      let parsed2;
+      try {
+        parsed2 = JSON.parse(toBuffer(data).toString("utf8"));
+      } catch {
+        return;
+      }
+      if (parsed2 === null || typeof parsed2 !== "object") return;
+      const frame = parsed2;
+      if (typeof frame.t === "string" && expected.has(frame.t)) {
+        cleanup();
+        resolve(frame);
+      }
+    };
+    const onClose = (code, reasonBuf) => {
+      cleanup();
+      reject(new Error(`connection closed (${code}${reasonBuf.length ? `: ${reasonBuf.toString("utf8")}` : ""}) before a reply arrived`));
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      ws.off("message", onMessage);
+      ws.off("close", onClose);
+    };
+    ws.on("message", onMessage);
+    ws.on("close", onClose);
+  });
+}
+async function knockLink(params) {
+  const { ws, nonce } = await openAndAwaitNonce(params.relayUrl);
+  try {
+    const signature = signNonce(params.keypair.privateKeyPem, nonce);
+    const reply = awaitControlFrame(ws, /* @__PURE__ */ new Set(["knock_result"]));
+    ws.send(
+      JSON.stringify({
+        t: "knock",
+        link_id: params.linkId,
+        admission_key: params.admissionKey,
+        pubkey_pem: params.keypair.publicKeyPem,
+        signature: bytesToBase64Url(signature),
+        ...params.displayName !== void 0 ? { display_name: params.displayName } : {}
+      })
+    );
+    const frame = await reply;
+    if (frame.result === "waiting" && typeof frame.knock_id === "string") {
+      return {
+        result: "waiting",
+        knockId: frame.knock_id,
+        ...typeof frame.fingerprint === "string" ? { fingerprint: frame.fingerprint } : {}
+      };
+    }
+    return { result: "rejected", code: typeof frame.code === "string" ? frame.code : "unknown" };
+  } finally {
+    ws.close();
+  }
+}
+var RECONNECT_REPLY_TYPES = /* @__PURE__ */ new Set(["reconnect_ok", "reconnect_result"]);
+async function attachOnce(params) {
+  const { ws, nonce } = await openAndAwaitNonce(params.relayUrl);
+  const signature = signNonce(params.keypair.privateKeyPem, nonce);
+  const buffered = [];
+  const collector = (data, isBinary) => {
+    buffered.push({ data: toBuffer(data), isBinary });
+  };
+  ws.on("message", collector);
+  const reply = awaitControlFrame(ws, RECONNECT_REPLY_TYPES);
+  ws.send(
+    JSON.stringify({
+      t: "reconnect",
+      link_id: params.linkId,
+      pubkey_pem: params.keypair.publicKeyPem,
+      signature: bytesToBase64Url(signature)
+    })
+  );
+  let frame;
+  try {
+    frame = await reply;
+  } catch (err) {
+    ws.off("message", collector);
+    ws.close();
+    throw err;
+  }
+  ws.off("message", collector);
+  if (frame.t === "reconnect_ok" && typeof frame.participant_id === "string") {
+    const replay = withoutConsumedReconnectReply(buffered);
+    const session = new RelaySession(ws, frame.participant_id, replay);
+    ws.send(JSON.stringify({ t: "resync" }));
+    return { result: "attached", session };
+  }
+  ws.close();
+  return { result: "rejected", code: typeof frame.code === "string" ? frame.code : "unknown" };
+}
+function withoutConsumedReconnectReply(buffered) {
+  const index = buffered.findIndex((f) => {
+    if (f.isBinary) return false;
+    try {
+      const parsed2 = JSON.parse(f.data.toString("utf8"));
+      return parsed2 !== null && typeof parsed2 === "object" && typeof parsed2.t === "string" && RECONNECT_REPLY_TYPES.has(parsed2.t);
+    } catch {
+      return false;
+    }
+  });
+  return index === -1 ? buffered : buffered.filter((_, i) => i !== index);
+}
+var RETRYABLE_ATTACH_CODES = /* @__PURE__ */ new Set(["not_admitted", "link_not_ready"]);
+async function attachWithRetry(options) {
+  const maxAttempts = options.maxAttempts ?? 60;
+  const initialDelayMs = options.initialDelayMs ?? 1e3;
+  const maxDelayMs = options.maxDelayMs ?? 1e4;
+  let delayMs = initialDelayMs;
+  for (let attempt = 1; ; attempt++) {
+    const outcome = await attachOnce(options);
+    if (outcome.result === "attached" || !RETRYABLE_ATTACH_CODES.has(outcome.code) || attempt >= maxAttempts) {
+      return outcome;
+    }
+    options.onWaiting?.(attempt, delayMs);
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    delayMs = Math.min(delayMs * 2, maxDelayMs);
+  }
+}
+var RelaySession = class {
+  participantId;
+  #ws;
+  #assembler = new FrameAssembler();
+  /** Mirror of the assembler's phase: a TEXT frame arriving while NOT awaiting a body is a
+   *  standalone control frame (error/resync_ok/...) — never fed to the assembler. */
+  #awaitingBody = false;
+  #closedByUs = false;
+  #closeInfo = null;
+  #closeWaiters = [];
+  #messageQueue = [];
+  #messageWaiters = [];
+  #onMessage = null;
+  #onRelayError = null;
+  constructor(ws, participantId, replayFrames) {
+    this.#ws = ws;
+    this.participantId = participantId;
+    ws.on("message", (data, isBinary) => {
+      this.#handleFrame(toBuffer(data), isBinary);
+    });
+    ws.on("close", (code, reasonBuf) => {
+      this.#closeInfo = { code, reason: reasonBuf.toString("utf8") };
+      for (const waiter of this.#closeWaiters.splice(0)) waiter(this.#closeInfo);
+    });
+    ws.on("error", () => {
+    });
+    if (replayFrames) {
+      for (const frame of replayFrames) this.#handleFrame(frame.data, frame.isBinary);
+    }
+  }
+  /** The single inbound-frame path — live 'message' events and handoff replay both land here. */
+  #handleFrame(buf, isBinary) {
+    if (!isBinary && !this.#awaitingBody) {
+      let parsed2 = null;
+      try {
+        parsed2 = JSON.parse(buf.toString("utf8"));
+      } catch {
+        parsed2 = null;
+      }
+      const t = parsed2 !== null && typeof parsed2 === "object" ? parsed2.t : void 0;
+      if (t !== "deliver" && t !== "send") {
+        if (t === "error") {
+          const frame = parsed2;
+          this.#onRelayError?.({ ...frame, code: typeof frame.code === "string" ? frame.code : "unknown" });
+        }
+        return;
+      }
+    }
+    try {
+      const result = this.#assembler.feed(buf, isBinary);
+      if (result.kind === "awaiting-body") {
+        this.#awaitingBody = true;
+        return;
+      }
+      this.#awaitingBody = false;
+      if (result.header.t === "deliver" && typeof result.header.attempt_token === "string") {
+        this.#ws.send(JSON.stringify({ t: "ack", attempt_token: result.header.attempt_token }));
+      }
+      const incoming = { header: result.header, text: result.bodyText };
+      if (this.#onMessage) {
+        this.#onMessage(incoming);
+        return;
+      }
+      const waiter = this.#messageWaiters.shift();
+      if (waiter) waiter(incoming);
+      else this.#messageQueue.push(incoming);
+    } catch (err) {
+      const code = err instanceof FrameProtocolError ? err.closeCode : 1011;
+      this.close(code, err instanceof Error ? err.message : "frame handling failed");
+    }
+  }
+  /** Sends one §5.4 message: TEXT header `{t:'send', byte_len, client_msg_id}` then the BINARY
+   *  body frame (UTF-8 bytes, ≤ MAX_BODY_BYTES — assertBodySize throws before anything hits
+   *  the wire on oversize). */
+  sendText(text, clientMsgId = randomUUID()) {
+    const bodyBytes = Buffer.from(text, "utf8");
+    assertBodySize(bodyBytes);
+    const header = encodeHeaderFrame({ t: "send", byte_len: bodyBytes.length, client_msg_id: clientMsgId });
+    this.#ws.send(header);
+    this.#ws.send(bodyBytes, { binary: true });
+  }
+  /** Streams every inbound delivery to `handler` (drains anything already queued first). */
+  onMessage(handler) {
+    this.#onMessage = handler;
+    for (const queued of this.#messageQueue.splice(0)) handler(queued);
+  }
+  /** Relay `{t:'error'}` control frames (awaiting_funds, claim_rejected, ...). */
+  onRelayError(handler) {
+    this.#onRelayError = handler;
+  }
+  /** Test-driver convenience: awaits the next delivery (only when no onMessage handler is
+   *  installed). */
+  waitForMessage(timeoutMs = 5e3) {
+    const queued = this.#messageQueue.shift();
+    if (queued) return Promise.resolve(queued);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`waitForMessage timed out after ${timeoutMs}ms`)), timeoutMs);
+      timer.unref();
+      this.#messageWaiters.push((message) => {
+        clearTimeout(timer);
+        resolve(message);
+      });
+    });
+  }
+  /** Resolves when the socket closes (either side). */
+  waitClose() {
+    if (this.#closeInfo) return Promise.resolve(this.#closeInfo);
+    return new Promise((resolve) => this.#closeWaiters.push(resolve));
+  }
+  get closedByUs() {
+    return this.#closedByUs;
+  }
+  close(code = 1e3, reason = "") {
+    this.#closedByUs = true;
+    try {
+      this.#ws.close(code, reason.slice(0, 123));
+    } catch {
+      this.#ws.terminate();
+    }
+  }
+};
+
+// src/join.ts
+async function runJoin(options, io) {
+  let keypair;
+  try {
+    const loaded = loadOrCreateKeypair(options.keyFile);
+    keypair = loaded.keypair;
+    io.printErr(
+      loaded.created ? `generated a new Ed25519 keypair at ${options.keyFile} (0600)` : `using the Ed25519 keypair at ${options.keyFile}`
+    );
+  } catch (err) {
+    io.printErr(err.message);
+    return 1;
+  }
+  const keyPrefix = admissionKeyPrefix(options.admissionKey);
+  io.printErr(`knocking link ${options.linkId} with key ${keyPrefix ?? "(not mat_live_-shaped)"}\u2026`);
+  let knock;
+  try {
+    knock = await knockLink({
+      relayUrl: options.relayUrl,
+      linkId: options.linkId,
+      admissionKey: options.admissionKey,
+      keypair,
+      ...options.displayName !== void 0 ? { displayName: options.displayName } : {}
+    });
+  } catch (err) {
+    io.printErr(`knock failed: ${sanitizeForTerminal(err.message)}`);
+    return 1;
+  }
+  if (knock.result === "rejected") {
+    io.printErr(`knock rejected: ${sanitizeForTerminal(knock.code)}`);
+    return 1;
+  }
+  io.printErr(`knock accepted (${knock.knockId}) \u2014 waiting for the Link owner to let you in\u2026`);
+  let attach;
+  try {
+    attach = await attachWithRetry({
+      relayUrl: options.relayUrl,
+      linkId: options.linkId,
+      keypair,
+      ...options.pollMaxAttempts !== void 0 ? { maxAttempts: options.pollMaxAttempts } : {},
+      ...options.pollInitialDelayMs !== void 0 ? { initialDelayMs: options.pollInitialDelayMs } : {},
+      ...options.pollMaxDelayMs !== void 0 ? { maxDelayMs: options.pollMaxDelayMs } : {},
+      onWaiting: (attempt, nextDelayMs) => io.printErr(`not admitted yet (attempt ${attempt}) \u2014 retrying in ${nextDelayMs}ms`)
+    });
+  } catch (err) {
+    io.printErr(`reconnect failed: ${sanitizeForTerminal(err.message)}`);
+    return 1;
+  }
+  if (attach.result === "rejected") {
+    io.printErr(`could not attach: ${sanitizeForTerminal(attach.code)}`);
+    return 1;
+  }
+  const session = attach.session;
+  io.printErr(`attached as participant ${session.participantId} \u2014 type a message and press enter`);
+  session.onMessage(({ header, text }) => {
+    const from = header.name ?? header.from ?? "peer";
+    if (header.wake === true) io.print(DIRECTOR_WAKE_MARKER);
+    io.print(`[${sanitizeForTerminal(from)}] ${sanitizeForTerminal(text)}`);
+  });
+  session.onRelayError((frame) => io.printErr(`relay error: ${sanitizeForTerminal(frame.code)}`));
+  if (io.input) {
+    const rl = createInterface({ input: io.input });
+    rl.on("line", (line) => {
+      if (line.length === 0) return;
+      try {
+        session.sendText(line, randomUUID2());
+      } catch (err) {
+        io.printErr(`send failed: ${sanitizeForTerminal(err.message)}`);
+      }
+    });
+    rl.on("close", () => session.close(1e3, "input closed"));
+  }
+  const closeInfo = await session.waitClose();
+  const reason = closeInfo.reason ? `: ${sanitizeForTerminal(closeInfo.reason)}` : "";
+  io.printErr(`connection closed (${closeInfo.code}${reason})`);
+  return session.closedByUs || closeInfo.code === 1e3 ? 0 : 1;
+}
+
+// src/index.ts
+var parsed = parseJoinArgs(process2.argv.slice(2));
+if (!parsed.ok) {
+  console.error(parsed.error);
+  console.error("");
+  console.error(USAGE);
+  process2.exit(2);
+}
+var admissionKey;
+try {
+  admissionKey = await resolveAdmissionKey({
+    ...parsed.args.tokenFile !== void 0 ? { tokenFile: parsed.args.tokenFile } : {},
+    ...parsed.args.insecureTokenArg !== void 0 ? { insecureTokenArg: parsed.args.insecureTokenArg } : {},
+    stdin: process2.stdin
+  });
+} catch (err) {
+  console.error(err.message);
+  process2.exit(2);
+}
+var exitCode = await runJoin(
+  {
+    linkId: parsed.args.linkId,
+    relayUrl: parsed.args.relayUrl,
+    ...parsed.args.displayName !== void 0 ? { displayName: parsed.args.displayName } : {},
+    keyFile: parsed.args.keyFile,
+    admissionKey
+  },
+  {
+    // If the key arrived via piped stdin, the SAME stream continues as the message source.
+    input: process2.stdin,
+    print: (line) => console.log(line),
+    printErr: (line) => console.error(line)
+  }
+);
+process2.exit(exitCode);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "makeagentstalk",
+  "version": "1.0.0-beta.1",
+  "type": "module",
+  "description": "Connect an AI agent to a MakeAgentsTalk Link.",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "makeagentstalk": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22.18 --outfile=dist/index.js --external:ws",
+    "prepack": "npm run build",
+    "test": "node --test --test-concurrency=1 test/*.test.ts"
+  },
+  "dependencies": {
+    "ws": "^8.21.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  },
+  "license": "UNLICENSED"
+}