@acnlabs/acn-cli 0.12.0 → 0.13.2

package/dist/index.js

@@ -1,16 +1,37 @@
 #!/usr/bin/env node
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // package.json
 var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@acnlabs/acn-cli",
-      version: "0.12.0",
+      version: "0.13.2",
       description: "Official CLI for ACN (Agent Collaboration Network) \u2014 zero-integration agent access",
       main: "dist/index.js",
       bin: {
@@ -48,10 +69,12 @@ var require_package = __commonJS({
         url: "https://github.com/acnlabs/ACN/issues"
       },
       dependencies: {
-        commander: "^12.0.0"
+        commander: "^12.0.0",
+        ws: "^8.18.0"
       },
       devDependencies: {
         "@types/node": "^20.0.0",
+        "@types/ws": "^8.5.10",
         tsup: "^8.0.0",
         typescript: "^5.0.0",
         vitest: "^3.0.5"
@@ -64,7 +87,7 @@ var require_package = __commonJS({
 });
 
 // src/index.ts
-var import_commander15 = require("commander");
+var import_commander16 = require("commander");
 
 // src/output.ts
 var jsonMode = false;
@@ -101,32 +124,91 @@ var import_path = require("path");
 var import_fs = require("fs");
 var CONFIG_DIR = (0, import_path.join)((0, import_os.homedir)(), ".acn");
 var CONFIG_FILE = (0, import_path.join)(CONFIG_DIR, "config.json");
-var DEFAULT_BASE_URL = "https://api.acnlabs.dev";
-function loadConfig() {
-  if (!(0, import_fs.existsSync)(CONFIG_FILE)) {
-    return { base_url: DEFAULT_BASE_URL };
+var REGION_BASE_URLS = {
+  global: "https://api.acnlabs.dev",
+  cn: "https://acn.acnlabs.cn"
+};
+var DEFAULT_BASE_URL = REGION_BASE_URLS.global;
+function normalizeBaseUrl(url) {
+  let u = url.trim().replace(/\/+$/, "");
+  u = u.replace(/\/api\/v1$/i, "");
+  return u.replace(/\/+$/, "");
+}
+function baseUrlForRegion(region) {
+  const key = region.trim().toLowerCase();
+  if (key === "global" || key === "cn") {
+    return REGION_BASE_URLS[key];
   }
+  throw new Error(`Unknown region "${region}". Valid: global | cn`);
+}
+function inferRegion(baseUrl) {
+  const u = normalizeBaseUrl(baseUrl);
+  if (u === REGION_BASE_URLS.global) return "global";
+  if (u === REGION_BASE_URLS.cn) return "cn";
+  return void 0;
+}
+function readConfigFile() {
+  if (!(0, import_fs.existsSync)(CONFIG_FILE)) return {};
   try {
     const raw = (0, import_fs.readFileSync)(CONFIG_FILE, "utf-8");
-    const parsed = JSON.parse(raw);
-    return {
-      base_url: parsed.base_url ?? DEFAULT_BASE_URL,
-      api_key: parsed.api_key,
-      agent_id: parsed.agent_id
-    };
+    return JSON.parse(raw);
   } catch {
-    return { base_url: DEFAULT_BASE_URL };
+    return {};
+  }
+}
+function resolveBaseUrl(overrides) {
+  if (overrides?.base_url) {
+    return normalizeBaseUrl(overrides.base_url);
+  }
+  if (overrides?.region) {
+    return baseUrlForRegion(overrides.region);
+  }
+  const env = process.env.ACN_BASE_URL?.trim();
+  if (env) {
+    return normalizeBaseUrl(env);
+  }
+  const file = readConfigFile();
+  if (file.base_url) {
+    return normalizeBaseUrl(file.base_url);
+  }
+  if (file.region) {
+    return baseUrlForRegion(file.region);
   }
+  return DEFAULT_BASE_URL;
+}
+function loadConfig() {
+  const file = readConfigFile();
+  const base_url = resolveBaseUrl();
+  return {
+    base_url,
+    api_key: file.api_key,
+    agent_id: file.agent_id,
+    region: inferRegion(base_url)
+  };
 }
 function saveConfig(updates) {
   if (!(0, import_fs.existsSync)(CONFIG_DIR)) {
     (0, import_fs.mkdirSync)(CONFIG_DIR, { recursive: true });
   }
-  const current = loadConfig();
+  const file = readConfigFile();
+  const current = {
+    base_url: file.base_url ? normalizeBaseUrl(file.base_url) : DEFAULT_BASE_URL,
+    api_key: file.api_key,
+    agent_id: file.agent_id,
+    region: file.region === "global" || file.region === "cn" ? file.region : void 0
+  };
   const next = { ...current, ...updates };
-  const clean = { base_url: next.base_url };
+  if (updates.region && !updates.base_url) {
+    next.base_url = baseUrlForRegion(updates.region);
+  }
+  if (updates.base_url && updates.region === void 0) {
+    next.region = inferRegion(updates.base_url);
+  }
+  const clean = { base_url: normalizeBaseUrl(next.base_url) };
   if (next.api_key !== void 0) clean.api_key = next.api_key;
   if (next.agent_id !== void 0) clean.agent_id = next.agent_id;
+  const region = next.region ?? inferRegion(clean.base_url);
+  if (region !== void 0) clean.region = region;
   (0, import_fs.writeFileSync)(CONFIG_FILE, JSON.stringify(clean, null, 2), "utf-8");
 }
 function getConfigPath() {
@@ -134,7 +216,7 @@ function getConfigPath() {
 }
 
 // src/commands/config.ts
-var VALID_KEYS = ["api-key", "agent-id", "base-url"];
+var VALID_KEYS = ["api-key", "agent-id", "base-url", "region"];
 var KEY_MAP = {
   "api-key": "api_key",
   "agent-id": "agent_id",
@@ -142,11 +224,25 @@ var KEY_MAP = {
 };
 function configCommand() {
   const cmd = new import_commander.Command("config").description("Manage local ACN configuration");
-  cmd.command("set <key> <value>").description(`Set a config value. Keys: ${VALID_KEYS.join(", ")}`).action((key, value) => {
+  cmd.command("set <key> <value>").description(
+    `Set a config value. Keys: ${VALID_KEYS.join(", ")}. region is global|cn (sets base-url). Env ACN_BASE_URL overrides base-url at runtime.`
+  ).action((key, value) => {
     if (!VALID_KEYS.includes(key)) {
       console.error(`Unknown key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`);
       process.exit(1);
     }
+    if (key === "region") {
+      try {
+        const base_url = baseUrlForRegion(value);
+        const region = value.trim().toLowerCase();
+        saveConfig({ region, base_url });
+        output({ key, value: region, base_url }, `Set region = ${region} (base-url = ${base_url})`);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+      return;
+    }
     saveConfig({ [KEY_MAP[key]]: value });
     output({ key, value }, `Set ${key} = ${value}`);
   });
@@ -156,19 +252,21 @@ function configCommand() {
       process.exit(1);
     }
     const config = loadConfig();
-    const val = config[KEY_MAP[key]];
+    const val = key === "region" ? config.region : config[KEY_MAP[key]];
     if (val === void 0) {
       console.error(`Key "${key}" is not set.`);
       process.exit(1);
     }
-    output({ key, value: val }, val);
+    output({ key, value: val }, String(val));
   });
   cmd.command("show").description("Show all config values").action(() => {
     const config = loadConfig();
     const path = getConfigPath();
+    const envOverride = process.env.ACN_BASE_URL?.trim() ? ` (ACN_BASE_URL override active)` : "";
     output(config, [
       `Config file: ${path}`,
-      `  base-url : ${config.base_url}`,
+      `  region   : ${config.region ?? "(custom / unknown)"}`,
+      `  base-url : ${config.base_url}${envOverride}`,
       `  api-key  : ${config.api_key ? maskKey(config.api_key) : "(not set)"}`,
       `  agent-id : ${config.agent_id ?? "(not set)"}`
     ].join("\n"));
@@ -205,8 +303,9 @@ function extractDetail(body) {
 }
 async function acnFetch(path, options = {}) {
   const config = loadConfig();
-  const { params, ...fetchOptions } = options;
-  const url = new URL(`${config.base_url}/api/v1${path}`);
+  const { params, baseUrl: baseUrlOverride, ...fetchOptions } = options;
+  const origin = baseUrlOverride ? normalizeBaseUrl(baseUrlOverride) : config.base_url;
+  const url = new URL(`${origin}/api/v1${path}`);
   if (params) {
     for (const [k, v] of Object.entries(params)) {
       if (v !== void 0) url.searchParams.set(k, String(v));
@@ -234,54 +333,98 @@ async function acnFetch(path, options = {}) {
   }
   return res.json();
 }
-function acnGet(path, params) {
-  return acnFetch(path, { method: "GET", params });
+function acnGet(path, params, opts) {
+  return acnFetch(path, { method: "GET", params, baseUrl: opts?.baseUrl });
 }
-function acnPost(path, body) {
+function acnPost(path, body, opts) {
   return acnFetch(path, {
     method: "POST",
-    body: body !== void 0 ? JSON.stringify(body) : void 0
+    body: body !== void 0 ? JSON.stringify(body) : void 0,
+    baseUrl: opts?.baseUrl
   });
 }
-function acnPatch(path, body) {
+function acnPatch(path, body, opts) {
   return acnFetch(path, {
     method: "PATCH",
-    body: body !== void 0 ? JSON.stringify(body) : void 0
+    body: body !== void 0 ? JSON.stringify(body) : void 0,
+    baseUrl: opts?.baseUrl
   });
 }
-function acnDelete(path) {
-  return acnFetch(path, { method: "DELETE" });
+function acnDelete(path, opts) {
+  return acnFetch(path, { method: "DELETE", baseUrl: opts?.baseUrl });
 }
 
 // src/commands/join.ts
 function joinCommand() {
-  return new import_commander2.Command("join").description("Register this agent with ACN and save credentials locally").requiredOption("-n, --name <name>", "Agent name").requiredOption("-t, --tags <tags>", "Comma-separated capability tags (e.g. coding,review)").option("-e, --endpoint <url>", "Public A2A endpoint URL of this agent").option("-d, --description <text>", "Agent description").action(async (opts) => {
-    const tags = opts.tags.split(",").map((s) => s.trim()).filter(Boolean);
-    const body = {
-      name: opts.name,
-      description: opts.description ?? `${opts.name} \u2014 registered via acn-cli`,
-      tags,
-      ...opts.endpoint ? { endpoint: opts.endpoint } : {}
-    };
-    try {
-      const res = await acnPost("/agents/join", body);
-      saveConfig({ api_key: res.api_key, agent_id: res.agent_id });
-      const claimLine = res.claim_url ? `
+  return new import_commander2.Command("join").description("Register this agent with ACN and save credentials locally").requiredOption("-n, --name <name>", "Agent name").requiredOption("-t, --tags <tags>", "Comma-separated capability tags (e.g. coding,review)").option("-e, --endpoint <url>", "Public A2A endpoint URL of this agent").option("-d, --description <text>", "Agent description").option(
+    "--relay",
+    "Receive messages in real time over an outbound WebSocket (run `acn listen`) instead of hosting a public endpoint. Registers in open/push mode with no delivery URL."
+  ).option(
+    "--region <region>",
+    "ACN deployment to join: global (api.acnlabs.dev) or cn (acn.acnlabs.cn). Pick by where the agent is hosted \u2014 not by user nationality."
+  ).option(
+    "--base-url <url>",
+    "Override ACN origin (no /api/v1). Overrides --region and ACN_BASE_URL for this join."
+  ).action(
+    async (opts) => {
+      if (opts.region && opts.baseUrl) {
+        console.error("Use either --region or --base-url, not both.");
+        process.exit(1);
+      }
+      if (opts.region) {
+        const r = opts.region.trim().toLowerCase();
+        if (r !== "global" && r !== "cn") {
+          console.error(`Unknown --region "${opts.region}". Valid: global | cn`);
+          process.exit(1);
+        }
+      }
+      const base_url = resolveBaseUrl({
+        base_url: opts.baseUrl,
+        region: opts.region
+      });
+      const region = opts.region?.trim().toLowerCase() === "cn" || opts.region?.trim().toLowerCase() === "global" ? opts.region.trim().toLowerCase() : inferRegion(base_url);
+      const tags = opts.tags.split(",").map((s) => s.trim()).filter(Boolean);
+      const body = {
+        name: opts.name,
+        description: opts.description ?? `${opts.name} \u2014 registered via acn-cli`,
+        tags,
+        ...opts.endpoint ? { endpoint: opts.endpoint } : {},
+        // ADR-0012 Mode B: relay delivery needs a push mode (open) so the
+        // gateway actually pushes inbound messages down the WebSocket; the
+        // server-side validator then waives the public-URL requirement.
+        ...opts.relay ? { delivery: "relay", communication_policy: { mode: "open" } } : {}
+      };
+      try {
+        const res = await acnPost("/agents/join", body, {
+          baseUrl: base_url
+        });
+        saveConfig({
+          api_key: res.api_key,
+          agent_id: res.agent_id,
+          base_url,
+          ...region ? { region } : {}
+        });
+        const claimLine = res.claim_url ? `
   Claim URL: ${res.claim_url}` : "";
-      const verifyLine = res.verification_code ? `
+        const verifyLine = res.verification_code ? `
   Verify   : ${res.verification_code}` : "";
-      output(res, [
-        `Registered successfully!`,
-        `  Agent ID : ${res.agent_id}`,
-        `  API Key  : ${res.api_key}`,
-        `  Status   : ${res.status}${claimLine}${verifyLine}`,
-        ``,
-        `Credentials saved to ~/.acn/config.json`
-      ].join("\n"));
-    } catch (err) {
-      handleError(err);
+        const regionLine = region ? `
+  Region   : ${region}` : "";
+        output(res, [
+          `Registered successfully!`,
+          `  Agent ID : ${res.agent_id}`,
+          `  API Key  : ${res.api_key}`,
+          `  ACN      : ${base_url}${regionLine}`,
+          `  Status   : ${res.status}${claimLine}${verifyLine}`,
+          ``,
+          `Credentials saved to ~/.acn/config.json`,
+          `Do not reuse this api_key against another region \u2014 re-join instead.`
+        ].join("\n"));
+      } catch (err) {
+        handleError(err);
+      }
     }
-  });
+  );
 }
 
 // src/commands/heartbeat.ts
@@ -1230,8 +1373,255 @@ ${formatPolicy(res)}`);
   return cmd;
 }
 
-// src/commands/session.ts
+// src/commands/listen.ts
 var import_commander10 = require("commander");
+var import_child_process = require("child_process");
+var import_ws = __toESM(require("ws"));
+var STRIP_HEADERS = /* @__PURE__ */ new Set([
+  "host",
+  "content-length",
+  "connection",
+  "transfer-encoding"
+]);
+function toWebsocketUrl(baseUrl, agentId) {
+  const u = new URL(baseUrl);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.pathname = `/ws/${agentId}`;
+  u.search = "";
+  return u.toString();
+}
+function decodeBody(frame) {
+  if (frame.body_encoding === "base64") {
+    return Buffer.from(frame.body ?? "", "base64");
+  }
+  return Buffer.from(frame.body ?? "", "utf-8");
+}
+function errorResponse(id, status, detail) {
+  return {
+    type: "a2a_response",
+    id,
+    status,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ error: detail })
+  };
+}
+async function dispatchA2aRequest(frame, opts, send, deps = {}) {
+  const bodyBuf = decodeBody(frame);
+  try {
+    if (opts.forward) {
+      await forwardToHttp(frame, bodyBuf, opts.forward, deps.fetchFn ?? fetch, send);
+      return;
+    }
+    if (opts.exec) {
+      send(await runExec(frame, bodyBuf, opts.exec, deps.spawnFn ?? import_child_process.spawn));
+      return;
+    }
+    send(errorResponse(frame.id, 500, "no handler configured"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    send(errorResponse(frame.id, 502, `handler failed: ${msg}`));
+  }
+}
+function buildForwardHeaders(frame) {
+  const headers = {};
+  for (const [k, v] of Object.entries(frame.headers ?? {})) {
+    if (!STRIP_HEADERS.has(k.toLowerCase())) headers[k] = v;
+  }
+  return headers;
+}
+async function forwardToHttp(frame, bodyBuf, base, fetchFn, send) {
+  const suffix = frame.path && frame.path !== "/" ? "/" + frame.path.replace(/^\//, "") : "";
+  const targetUrl = base.replace(/\/$/, "") + suffix;
+  const method = (frame.method ?? "POST").toUpperCase();
+  const init = { method, headers: buildForwardHeaders(frame) };
+  if (method !== "GET" && method !== "HEAD") {
+    init.body = bodyBuf;
+  }
+  const res = await fetchFn(targetUrl, init);
+  const contentType = res.headers.get("content-type") ?? "application/json";
+  if (contentType.includes("text/event-stream") && res.body) {
+    const reader = res.body.getReader();
+    let seq = 0;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value && value.length > 0) {
+          send({
+            type: "a2a_stream_chunk",
+            id: frame.id,
+            seq: seq++,
+            data: Buffer.from(value).toString("base64"),
+            data_encoding: "base64"
+          });
+        }
+      }
+      send({ type: "a2a_stream_end", id: frame.id, status: res.status });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      send({ type: "a2a_stream_end", id: frame.id, error: msg });
+    } finally {
+      reader.releaseLock();
+    }
+    return;
+  }
+  const respText = await res.text();
+  send({
+    type: "a2a_response",
+    id: frame.id,
+    status: res.status,
+    headers: { "content-type": contentType },
+    body: respText
+  });
+}
+function runExec(frame, bodyBuf, command, spawnFn) {
+  return new Promise((resolve) => {
+    const child = spawnFn(command, { shell: true });
+    const out = [];
+    const errOut = [];
+    child.stdout?.on("data", (d) => out.push(Buffer.from(d)));
+    child.stderr?.on("data", (d) => errOut.push(Buffer.from(d)));
+    child.on(
+      "error",
+      (e) => resolve(errorResponse(frame.id, 502, `exec error: ${e.message}`))
+    );
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(out).toString("utf-8");
+      if (code === 0) {
+        resolve({
+          type: "a2a_response",
+          id: frame.id,
+          status: 200,
+          headers: { "content-type": "application/json" },
+          body: stdout
+        });
+      } else {
+        const stderr = Buffer.concat(errOut).toString("utf-8");
+        resolve(
+          errorResponse(frame.id, 500, `exec exited ${code}: ${stderr.slice(0, 500)}`)
+        );
+      }
+    });
+    child.stdin?.end(bodyBuf);
+  });
+}
+function rawToString(data) {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString("utf-8");
+  if (Array.isArray(data)) return Buffer.concat(data).toString("utf-8");
+  return Buffer.from(data).toString("utf-8");
+}
+var KEEPALIVE_INTERVAL_MS = 3e4;
+var INITIAL_BACKOFF_MS = 1e3;
+var MAX_BACKOFF_MS = 3e4;
+function runListener(cfg) {
+  const wsUrl = toWebsocketUrl(cfg.baseUrl, cfg.agentId);
+  let backoff = INITIAL_BACKOFF_MS;
+  let stopped = false;
+  const connect = () => {
+    const ws = new import_ws.default(wsUrl, {
+      headers: { Authorization: `Bearer ${cfg.apiKey}` }
+    });
+    let keepalive;
+    ws.on("open", () => {
+      console.error(`[acn listen] connected as ${cfg.agentId} \u2192 ${wsUrl}`);
+      backoff = INITIAL_BACKOFF_MS;
+      keepalive = setInterval(() => {
+        if (ws.readyState === import_ws.default.OPEN) {
+          ws.send(JSON.stringify({ type: "ping" }));
+        }
+      }, KEEPALIVE_INTERVAL_MS);
+    });
+    ws.on("message", (data) => {
+      let frame;
+      try {
+        frame = JSON.parse(rawToString(data));
+      } catch {
+        return;
+      }
+      if (!frame || typeof frame !== "object") return;
+      const f = frame;
+      if (f.type === "a2a_request" && typeof f.id === "string") {
+        const send = (out) => {
+          if (ws.readyState === import_ws.default.OPEN) {
+            ws.send(JSON.stringify(out));
+          }
+        };
+        void dispatchA2aRequest(f, cfg, send);
+      }
+    });
+    ws.on("close", (code, reason) => {
+      if (keepalive) clearInterval(keepalive);
+      if (stopped) return;
+      if (code === 4401 || code === 4403 || code === 4429) {
+        console.error(
+          `[acn listen] fatal close (code ${code}): ${reason.toString() || "see api_key / agent_id"}`
+        );
+        process.exit(1);
+      }
+      console.error(
+        `[acn listen] disconnected (code ${code}); reconnecting in ${backoff / 1e3}s`
+      );
+      setTimeout(connect, backoff);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+    });
+    ws.on("error", (err) => {
+      console.error(`[acn listen] socket error: ${err.message}`);
+    });
+  };
+  process.on("SIGINT", () => {
+    stopped = true;
+    console.error("\n[acn listen] stopping");
+    process.exit(0);
+  });
+  connect();
+}
+function listenCommand() {
+  const cmd = new import_commander10.Command("listen").description(
+    "Hold an outbound connection to ACN and answer relayed A2A requests in real time (ADR-0012 Mode B). For agents with no public endpoint."
+  ).option(
+    "--forward <url>",
+    "Tunnel each relayed request to a local HTTP server (e.g. http://localhost:8080)"
+  ).option(
+    "--exec <command>",
+    "Run a shell command per request: body on stdin, stdout becomes the response"
+  ).option("-i, --agent-id <id>", "Agent ID (defaults to config)").action((opts) => {
+    const config = loadConfig();
+    const apiKey = config.api_key;
+    const agentId = opts.agentId ?? config.agent_id;
+    if (!apiKey) {
+      console.error(
+        "No API key found. Run `acn join` first or `acn config set api-key <key>`."
+      );
+      process.exit(1);
+    }
+    if (!agentId) {
+      console.error(
+        "No agent ID found. Run `acn join` first or `acn config set agent-id <id>`."
+      );
+      process.exit(1);
+    }
+    if (!opts.forward && !opts.exec) {
+      console.error("Provide a handler: --forward <url> or --exec <command>.");
+      process.exit(1);
+    }
+    if (opts.forward && opts.exec) {
+      console.error("Use only one handler: --forward or --exec, not both.");
+      process.exit(1);
+    }
+    runListener({
+      agentId,
+      apiKey,
+      baseUrl: config.base_url,
+      forward: opts.forward,
+      exec: opts.exec
+    });
+  });
+  return cmd;
+}
+
+// src/commands/session.ts
+var import_commander11 = require("commander");
 function requireAgentId3() {
   const config = loadConfig();
   if (!config.api_key) {
@@ -1276,7 +1666,7 @@ function formatEntry2(s, index) {
   return lines.join("\n");
 }
 function sessionCommand() {
-  const cmd = new import_commander10.Command("session").description(
+  const cmd = new import_commander11.Command("session").description(
     "Real-time session layer: bidirectional channel between two agents"
   );
   cmd.command("invite <target_agent_id>").description("Invite an agent to a real-time session").option("--ttl-seconds <s>", "Session TTL in seconds (60\u20131800, default 300)", parseInt).option("--metadata <json>", "Optional JSON object attached to the invitation (max 4KB)").action(
@@ -1354,7 +1744,7 @@ ${formatEntry2(res)}`);
 }
 
 // src/commands/subnet.ts
-var import_commander11 = require("commander");
+var import_commander12 = require("commander");
 function requireAgentId4() {
   const config = loadConfig();
   if (!config.api_key) {
@@ -1442,7 +1832,7 @@ function formatSubnet(s, index) {
   return lines.join("\n");
 }
 function subnetCommand() {
-  const cmd = new import_commander11.Command("subnet").description("Manage ACN subnets");
+  const cmd = new import_commander12.Command("subnet").description("Manage ACN subnets");
   cmd.command("list").description(
     "List subnets. Without --all/--parent shows only subnets you have joined."
   ).option("--all", "Show all public subnets on ACN (not just your own)").option(
@@ -1659,7 +2049,7 @@ ${JSON.stringify(res.agents, null, 2)}`);
       handleError(err);
     }
   });
-  const requests = new import_commander11.Command("requests").description(
+  const requests = new import_commander12.Command("requests").description(
     "Manage join-requests for a subnet (ADR-0004)"
   );
   requests.command("list <subnet_id>").description(
@@ -1801,7 +2191,7 @@ ${JSON.stringify(res.agents, null, 2)}`);
     }
   );
   cmd.addCommand(requests);
-  const invitations = new import_commander11.Command("invitations").description(
+  const invitations = new import_commander12.Command("invitations").description(
     "Manage invitations on a subnet (ADR-0004)"
   );
   invitations.command("send <subnet_id>").description(
@@ -1937,7 +2327,7 @@ ${JSON.stringify(res.agents, null, 2)}`);
     }
   );
   cmd.addCommand(invitations);
-  const allowlist = new import_commander11.Command("allowlist").description(
+  const allowlist = new import_commander12.Command("allowlist").description(
     "Manage a subnet allowlist (ADR-0004)"
   );
   allowlist.command("list <subnet_id>").description("Owner-only: list allowlist entries for a subnet.").option("--limit <n>", "Page size (1-500, default 100)", "100").option("--offset <n>", "Page offset (default 0)", "0").action(
@@ -2005,7 +2395,7 @@ ${JSON.stringify(res.agents, null, 2)}`);
     }
   );
   cmd.addCommand(allowlist);
-  const harness = new import_commander11.Command("harness").description("Manage Org Harness webhook for a subnet");
+  const harness = new import_commander12.Command("harness").description("Manage Org Harness webhook for a subnet");
   harness.command("set <subnet_id>").description("Register an Org Harness webhook on a subnet you own").requiredOption("--url <url>", "Harness webhook URL (HTTPS)").option("--secret <secret>", "HMAC-SHA256 signing secret (recommended)").action(async (subnetId, opts) => {
     const config = loadConfig();
     if (!config.api_key) {
@@ -2048,7 +2438,7 @@ ${JSON.stringify(res.agents, null, 2)}`);
 }
 
 // src/commands/follow.ts
-var import_commander12 = require("commander");
+var import_commander13 = require("commander");
 function requireAgentId5() {
   const config = loadConfig();
   if (!config.api_key) {
@@ -2071,7 +2461,7 @@ function formatAgent2(a, i) {
   ].join("\n");
 }
 function followCommand() {
-  const cmd = new import_commander12.Command("follow").description("Follow/unfollow agents and inspect follow graph");
+  const cmd = new import_commander13.Command("follow").description("Follow/unfollow agents and inspect follow graph");
   cmd.command("add <target_id>").description("Follow another agent").option("-i, --agent-id <id>", "Agent ID (defaults to config)").action(async (targetId, opts) => {
     const agentId = opts.agentId ?? requireAgentId5();
     try {
@@ -2162,7 +2552,7 @@ function followCommand() {
 }
 
 // src/commands/wallet.ts
-var import_commander13 = require("commander");
+var import_commander14 = require("commander");
 function requireAgentId6() {
   const config = loadConfig();
   if (!config.api_key) {
@@ -2205,7 +2595,7 @@ async function showWalletInfo(opts) {
   }
 }
 function walletCommand() {
-  const cmd = new import_commander13.Command("wallet").description("View and manage agent's wallet & payment info");
+  const cmd = new import_commander14.Command("wallet").description("View and manage agent's wallet & payment info");
   cmd.command("info", { isDefault: true }).description("Show wallet, payment methods, pricing, and ERC-8004 status").option("-i, --agent-id <id>", "Agent ID (defaults to config)").action(showWalletInfo);
   cmd.command("set-capability").description("Declare which payment methods, networks, and wallets you accept").requiredOption(
     "--methods <csv>",
@@ -2384,7 +2774,7 @@ function walletCommand() {
 }
 
 // src/commands/pay.ts
-var import_commander14 = require("commander");
+var import_commander15 = require("commander");
 function requireAgentId7() {
   const config = loadConfig();
   if (!config.api_key) {
@@ -2398,8 +2788,8 @@ function requireAgentId7() {
   return config.agent_id;
 }
 function payCommand() {
-  const cmd = new import_commander14.Command("pay").description("Manage payment tasks between agents");
-  const createCmd = new import_commander14.Command("create").description("Create a payment task to another agent");
+  const cmd = new import_commander15.Command("pay").description("Manage payment tasks between agents");
+  const createCmd = new import_commander15.Command("create").description("Create a payment task to another agent");
   createCmd.requiredOption("--to <agent>", "Recipient agent ID").requiredOption("--amount <n>", "Payment amount (positive number)").requiredOption("--currency <c>", "Currency code, e.g. USD, USDC").requiredOption("--method <m>", "Payment method, e.g. usdc, eth, platform_credits").requiredOption("--network <n>", "Network, e.g. ethereum, base, solana").option("--description <text>", "Free-text description for the payment task").option("--metadata <json>", "Additional metadata as JSON object").action(
     async (opts) => {
       const fromAgent = requireAgentId7();
@@ -2445,7 +2835,7 @@ function payCommand() {
       }
     }
   );
-  const confirmCmd = new import_commander14.Command("confirm").description(
+  const confirmCmd = new import_commander15.Command("confirm").description(
     "Confirm an external payment has been made (buyer only)"
   );
   confirmCmd.requiredOption("--task-id <id>", "Payment task ID to confirm").requiredOption(
@@ -2467,7 +2857,7 @@ function payCommand() {
       handleError(err);
     }
   });
-  const statusCmd = new import_commander14.Command("status").description(
+  const statusCmd = new import_commander15.Command("status").description(
     "Show payment tasks for the authenticated agent"
   );
   statusCmd.option("--status <s>", "Filter by status (e.g. created, payment_confirmed)").option("--limit <n>", "Max results (default 50)", "50").action(async (opts) => {
@@ -2490,7 +2880,7 @@ function payCommand() {
 
 // src/index.ts
 var { version } = require_package();
-var program = new import_commander15.Command();
+var program = new import_commander16.Command();
 program.name("acn").description("ACN CLI \u2014 Agent Collaboration Network command-line interface").version(version).option("--json", "Output raw JSON (useful for agent parsing)").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
   if (opts.json) setJsonMode(true);
@@ -2504,6 +2894,7 @@ program.addCommand(tasksCommand());
 program.addCommand(messageCommand());
 program.addCommand(notifyCommand());
 program.addCommand(inboxCommand());
+program.addCommand(listenCommand());
 program.addCommand(sessionCommand());
 program.addCommand(subnetCommand());
 program.addCommand(followCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acnlabs/acn-cli",
-  "version": "0.12.0",
+  "version": "0.13.2",
   "description": "Official CLI for ACN (Agent Collaboration Network) — zero-integration agent access",
   "main": "dist/index.js",
   "bin": {
@@ -38,10 +38,12 @@
     "url": "https://github.com/acnlabs/ACN/issues"
   },
   "dependencies": {
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.5"