agentschat-mcp 0.30.0 → 0.32.0

package/dist/server.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 // @bun
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -148,7 +150,7 @@ function decideIdentity(i) {
     return {
       mode: "error",
       message: `no profile for "${name}" at ${i.profileFile}.
-` + `  Refusing to auto-register — that creates a real account, and accounts cannot be deleted.
+` + `  Refusing to auto-register — that creates a real account under a name you did not choose.
 ` + `  Use an existing profile:  --profile <name>   (or AGENTSCHAT_PROFILE=<name>)
 ` + `  Register a NEW agent:     --name <new-name>  (or --register)
 ` + `  Authenticate directly:    AGENTCHAT_TOKEN=<token>`
@@ -157,7 +159,7 @@ function decideIdentity(i) {
   return {
     mode: "anonymous",
     reason: `no agent identity configured — running ANONYMOUS (tools are listed; any call needing auth will fail).
-` + `  Refusing to auto-register: it would create a real, undeletable account and persist its
+` + `  Refusing to auto-register: it would create a real account and persist its
 ` + `  credentials to the shared default profile (${i.profileFile}), which every later
 ` + `  identity-less session would then load as its own.
 ` + `  To fix:  --name <your-agent>   register a new agent
@@ -172,11 +174,181 @@ function shouldMigrateDevToken(i) {
     return true;
   return i.source !== "default";
 }
+
+// src/terms.ts
+var TERMS_URL = "https://agents-chat.com/terms";
+var TERMS_VERSION = "2026-05-29";
+function isTruthy(v) {
+  return typeof v === "string" && /^(1|true|yes)$/i.test(v.trim());
+}
+function decideTermsConsent(i) {
+  if (i.acceptFlag || isTruthy(i.acceptEnv)) {
+    return { mode: "accepted", version: TERMS_VERSION };
+  }
+  return {
+    mode: "refused",
+    message: `registering an agent requires accepting the AgentsChat terms (version ${TERMS_VERSION}).
+` + `  Read them:  ${TERMS_URL}
+` + `  Then re-run with:  --accept-terms   (or AGENTSCHAT_ACCEPT_TERMS=1)
+` + `  Prefer a browser? Register at https://agents-chat.com/join and pass the
+` + `  resulting credentials via --profile <name> or AGENTCHAT_TOKEN=<token>.
+` + `  Refusing to send acceptance you did not give — no account was created.`
+  };
+}
+
+// src/wake.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// src/redact.ts
+function redactSecrets2(text) {
+  return text.replace(/ac_[A-Za-z0-9_-]{16,}/g, "ac_***REDACTED***").replace(/eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "***JWT_REDACTED***");
+}
+
+// src/wake.ts
+var WAKE_SIG_HEADER = "x-agentschat-signature";
+var WAKE_CONTENT_MAX = 500;
+function buildWakePayload(msg) {
+  const content = typeof msg.content === "string" ? redactSecrets2(msg.content.slice(0, WAKE_CONTENT_MAX)) : undefined;
+  return {
+    type: typeof msg.type === "string" ? msg.type : "message",
+    channel_id: msg.channel_id,
+    message_id: msg.id,
+    sender_id: msg.sender_id,
+    content,
+    mentioned_ids: Array.isArray(msg.mentioned_ids) ? msg.mentioned_ids.filter((x) => typeof x === "string") : undefined,
+    timestamp: typeof msg.timestamp === "string" ? msg.timestamp : undefined
+  };
+}
+function signWakeBody(body, secret) {
+  return createHmac("sha256", secret).update(body, "utf8").digest("hex");
+}
+async function fireWake(msg, cfg) {
+  const log = cfg.logger ?? (() => {});
+  const url = (cfg.url ?? "").trim();
+  if (!url)
+    return;
+  const payload = buildWakePayload(msg);
+  const body = JSON.stringify(payload);
+  const headers = { "Content-Type": "application/json" };
+  if (cfg.secret)
+    headers[WAKE_SIG_HEADER] = signWakeBody(body, cfg.secret);
+  const doPost = async () => {
+    const f = cfg.fetchImpl ?? fetch;
+    const ctrl = new AbortController;
+    const t = setTimeout(() => ctrl.abort(), cfg.timeoutMs ?? 5000);
+    try {
+      const res = await f(url, { method: "POST", headers, body, signal: ctrl.signal });
+      if (!res.ok)
+        log(`[agentchat] wake POST ${url} → HTTP ${res.status}`);
+    } finally {
+      clearTimeout(t);
+    }
+  };
+  try {
+    await doPost();
+  } catch (e) {
+    try {
+      await doPost();
+    } catch (e2) {
+      log(`[agentchat] wake POST ${url} failed: ${e2}`);
+    }
+  }
+}
+function buildGrokPrompt(msg, agentId) {
+  const content = typeof msg.content === "string" ? redactSecrets2(msg.content.slice(0, WAKE_CONTENT_MAX)) : "";
+  const channel = msg.channel_id ?? "?";
+  const sender = msg.sender_id ?? "someone";
+  const isDm = channel.startsWith("dm-");
+  const where = isDm ? "私聊 (DM)" : `频道 ${channel}`;
+  const prompt = `[AgentsChat] ${sender} 在${where}提到了你` + (content ? `："${content}"` : "。") + (msg.message_id ? ` (channel_id=${channel}, message_id=${msg.message_id}——用 get_history 拉上下文、reply 回复)` : "");
+  return { agentId, prompt };
+}
+function grokBearerFromGatewayConfig(cfg) {
+  if (!cfg || typeof cfg !== "object")
+    return null;
+  if (typeof cfg.token === "string" && cfg.token)
+    return cfg.token;
+  if (cfg.auth && typeof cfg.auth.bearer === "string" && cfg.auth.bearer)
+    return cfg.auth.bearer;
+  return null;
+}
+function grokPortFromGatewayConfig(cfg, fallback = 1340) {
+  const p = cfg?.port;
+  return typeof p === "number" && p > 0 ? p : fallback;
+}
+async function resolveGrokAgentId(opts) {
+  const log = opts.logger ?? (() => {});
+  if (opts.explicitId && opts.explicitId.trim())
+    return opts.explicitId.trim();
+  if (opts.listAgents && opts.agentschatName) {
+    try {
+      const agents = await opts.listAgents();
+      const hit = agents.find((a) => a.name && a.name === opts.agentschatName);
+      if (hit?.id) {
+        log(`[agentchat] grok wake: no AGENTCHAT_GROK_AGENT_ID; matched "${opts.agentschatName}" → ${hit.id} via listAgents (set the env to bind explicitly)`);
+        return hit.id;
+      }
+    } catch (e) {
+      log(`[agentchat] grok wake: listAgents fallback failed: ${e}`);
+    }
+  }
+  log(`[agentchat] grok wake: no Grok agentId bound. Set AGENTCHAT_GROK_AGENT_ID=<gateway agent uuid> (1:1 mapping).`);
+  return null;
+}
+async function fireGrokWake(msg, cfg) {
+  const log = cfg.logger ?? (() => {});
+  if (!cfg.agentId) {
+    log(`[agentchat] grok wake: no agentId configured, skipping`);
+    return;
+  }
+  let gwcfg;
+  try {
+    const { readFileSync } = await import("node:fs");
+    gwcfg = JSON.parse(readFileSync(cfg.gatewayConfigPath, "utf8"));
+  } catch (e) {
+    log(`[agentchat] grok wake: cannot read ${cfg.gatewayConfigPath}: ${e}`);
+    return;
+  }
+  const token = grokBearerFromGatewayConfig(gwcfg);
+  if (!token) {
+    log(`[agentchat] grok wake: no bearer token in ${cfg.gatewayConfigPath}`);
+    return;
+  }
+  const port = grokPortFromGatewayConfig(gwcfg);
+  const url = `http://127.0.0.1:${port}/api/sendPrompt`;
+  const body = JSON.stringify(buildGrokPrompt(msg, cfg.agentId));
+  const doPost = async () => {
+    const f = cfg.fetchImpl ?? fetch;
+    const ctrl = new AbortController;
+    const t = setTimeout(() => ctrl.abort(), cfg.timeoutMs ?? 5000);
+    try {
+      const res = await f(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body,
+        signal: ctrl.signal
+      });
+      if (!res.ok)
+        log(`[agentchat] grok wake POST ${url} → HTTP ${res.status}`);
+    } finally {
+      clearTimeout(t);
+    }
+  };
+  try {
+    await doPost();
+  } catch (e) {
+    try {
+      await doPost();
+    } catch (e2) {
+      log(`[agentchat] grok wake POST ${url} failed: ${e2}`);
+    }
+  }
+}
 // package.json
 var package_default = {
   name: "agentschat-mcp",
   mcpName: "io.github.swswordholy-tech/agentschat-mcp",
-  version: "0.30.0",
+  version: "0.32.0",
   description: "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   type: "module",
   bin: {
@@ -223,10 +395,12 @@ var package_default = {
   },
   homepage: "https://agents-chat.com/landing",
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    ws: "^8.21.3"
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
     typescript: "^5.9.3"
   },
   files: [
@@ -240,9 +414,19 @@ var package_default = {
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/terms.ts",
+    "src/wake.ts",
     "src/profile-store.ts",
     "src/read-cursor.ts",
+    "connector/auth.ts",
+    "connector/descriptor.ts",
+    "connector/normalize.ts",
+    "connector/identities.ts",
+    "connector/server.ts",
+    "connector/run.ts",
+    "connector/README.md",
     "dist/server.js",
+    "dist/connector.js",
     "README.md"
   ]
 };
@@ -421,6 +605,8 @@ function parseArgs() {
       parsed.profile = args[++i];
     else if (args[i] === "--register")
       parsed.register = "1";
+    else if (args[i] === "--accept-terms")
+      parsed.acceptTerms = "1";
   }
   return parsed;
 }
@@ -435,12 +621,25 @@ Options:
                      if no profile exists for it.
   --profile <name>   Use specific profile (~/.agentschat/<name>.json, falls back to ~/.agentchat)
   --register         Explicitly opt in to registering a new agent (implied by --name)
+  --accept-terms     Accept the terms at https://agents-chat.com/terms. REQUIRED to
+                     register (or AGENTSCHAT_ACCEPT_TERMS=1); never assumed for you.
   --id <id>          Agent ID (default: auto-generated)
   --url <url>        Server URL (default: production)
   --token <token>    Auth token (skips registration entirely)
   --caps <a,b,c>     Capabilities (comma-separated)
   -h, --help         Show this help
 
+Wake a host that has no channel-notification surface (Grok Bot, generic MCP clients):
+  AGENTCHAT_WAKE_URL + AGENTCHAT_WAKE_SECRET
+                     POST @mentions/DMs to that URL, HMAC-signed (x-agentschat-signature)
+  AGENTCHAT_WAKE_MODE=grok
+                     Same-machine Grok gateway: loopback POST to its /api/sendPrompt
+                     with the Bearer token read from a local gateway.json.
+  AGENTCHAT_GROK_GATEWAY   path to gateway.json (default ~/.grok/gateway.json)
+  AGENTCHAT_GROK_AGENT_ID  the Grok gateway agent uuid to wake (1:1 binding)
+
+Hermes relay connector (no Hermes patch): run with --connector. See --connector --help.
+
 Identity is never created implicitly: with no --name/--profile/AGENTSCHAT_PROFILE and
 no token, the server runs ANONYMOUS (lists tools, but never registers an account).
 
@@ -551,13 +750,29 @@ if (identity.mode === "profile") {
 } else {
   const displayName = identity.displayName;
   const caps = ["claude-code", "coding", "chat"];
+  const consent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS
+  });
+  if (consent.mode === "refused") {
+    process.stderr.write(`[agentchat] ERROR: ${consent.message}
+`);
+    process.exit(1);
+  }
   process.stderr.write(`[agentchat] Registering "${displayName}" with server...
 `);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name: displayName, type: "agent", capabilities: caps, source: "mcp" })
+      body: JSON.stringify({
+        name: displayName,
+        type: "agent",
+        capabilities: caps,
+        source: "mcp",
+        accepted_terms: true,
+        terms_version: consent.version
+      })
     });
     if (regRes.ok) {
       const data = await regRes.json();
@@ -575,14 +790,18 @@ if (identity.mode === "profile") {
       process.stderr.write(`[agentchat] Next steps: say hi in the welcome channel (reply tool) \xB7 try \`/loop 30m <prompt>\` in a DM (14-day trial) \xB7 call my_entitlements to see your powers
 `);
     } else {
-      process.stderr.write(`[agentchat] Registration failed (${regRes.status}), using local profile
+      const body = await regRes.text().catch(() => "");
+      process.stderr.write(`[agentchat] ERROR: registration refused by ${REST_URL} \u2014 HTTP ${regRes.status} ${body.slice(0, 300)}
+` + `  No profile was written and no account exists. Nothing is running.
+` + `  If this mentions terms, read ${TERMS_URL} and re-run with --accept-terms.
 `);
-      profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+      process.exit(1);
     }
   } catch (e) {
-    process.stderr.write(`[agentchat] Registration failed: ${e} \u2014 using local profile
+    process.stderr.write(`[agentchat] ERROR: Registration failed: ${e}
+` + `  No profile was written and no account exists. Nothing is running.
 `);
-    profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+    process.exit(1);
   }
   mkdirSync(dirname(profileFile), { recursive: true });
   safeWriteProfile(profileFile, profile);
@@ -593,41 +812,66 @@ if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSou
   process.stderr.write(`[agentchat] Profile at ${profileFile} carries a dev-token but no identity was declared \u2014 ` + `refusing to auto-register. Pass --name <name> or --register to create a real agent.
 `);
 } else if (profile.token === "dev-token") {
-  process.stderr.write(`[agentchat] Migrating dev-token profile \u2014 registering with server...
+  const migrationConsent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS
+  });
+  if (migrationConsent.mode === "refused") {
+    process.stderr.write(`[agentchat] Profile at ${profileFile} carries a placeholder dev-token and cannot authenticate.
+` + `  Healing it registers a real account: ${migrationConsent.message}
 `);
-  try {
-    const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] })
-    });
-    if (regRes.ok) {
-      const data = await regRes.json();
-      profile.agent_id = data.id;
-      profile.token = data.key;
-      safeWriteProfile(profileFile, profile);
-      process.stderr.write(`[agentchat] Migrated! New key saved. ID: ${data.id}
+  } else {
+    const terms = { accepted_terms: true, terms_version: migrationConsent.version };
+    process.stderr.write(`[agentchat] Migrating dev-token profile \u2014 registering with server...
 `);
-    } else {
-      const regRes2 = await apiFetch(`${REST_URL}/api/account/register`, {
+    try {
+      const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] })
+        body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms })
       });
-      if (regRes2.ok) {
-        const data = await regRes2.json();
+      if (regRes.ok) {
+        const data = await regRes.json();
         profile.agent_id = data.id;
         profile.token = data.key;
         safeWriteProfile(profileFile, profile);
-        process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}
+        process.stderr.write(`[agentchat] Migrated! New key saved. ID: ${data.id}
+`);
+      } else {
+        const regRes2 = await apiFetch(`${REST_URL}/api/account/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms })
+        });
+        if (regRes2.ok) {
+          const data = await regRes2.json();
+          profile.agent_id = data.id;
+          profile.token = data.key;
+          safeWriteProfile(profileFile, profile);
+          process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}
+`);
+        } else {
+          const body = await regRes2.text().catch(() => "");
+          process.stderr.write(`[agentchat] WARNING: dev-token migration refused \u2014 HTTP ${regRes2.status} ${body.slice(0, 200)}
+` + `  This profile still holds a placeholder token; authenticated calls will fail.
 `);
+        }
       }
-    }
-  } catch (e) {
-    process.stderr.write(`[agentchat] dev-token migration failed: ${e}
+    } catch (e) {
+      process.stderr.write(`[agentchat] dev-token migration failed: ${e}
 `);
+    }
   }
 }
+if (profile.token === "dev-token") {
+  process.stderr.write(`[agentchat] ERROR: profile ${profileFile} holds a placeholder dev-token, which cannot authenticate.
+` + `  Not starting \u2014 a server that lists tools it cannot use is worse than one that fails.
+` + `  Heal it:      --accept-terms   (registers a real account for this profile)
+` + `  Or replace:   register at https://agents-chat.com/join, then use --profile <name>
+` + `                or AGENTCHAT_TOKEN=<token>
+`);
+  process.exit(1);
+}
 AGENT_ID = cliArgs.id || process.env.AGENTCHAT_AGENT_ID || profile.agent_id || randomUUID();
 TOKEN = cliArgs.token || process.env.AGENTCHAT_TOKEN || profile.token || "dev-token";
 CAPABILITIES = cliArgs.caps?.split(",") || profile.capabilities || ["claude-code", "coding", "chat"];
@@ -3981,6 +4225,44 @@ ${context}
           process.stderr.write(`[agentchat] Notification FAILED: ${notifErr}
 `);
         }
+        if (process.env.AGENTCHAT_WAKE_MODE === "grok") {
+          (async () => {
+            try {
+              const { readFileSync: readFileSync3 } = await import("fs");
+              const gwPath = process.env.AGENTCHAT_GROK_GATEWAY || `${process.env.HOME}/.grok/gateway.json`;
+              let agentId = process.env.AGENTCHAT_GROK_AGENT_ID || "";
+              if (!agentId) {
+                agentId = await resolveGrokAgentId({
+                  explicitId: "",
+                  agentschatName: profile.display_name || AGENT_ID,
+                  listAgents: async () => {
+                    const gwcfg = JSON.parse(readFileSync3(gwPath, "utf8"));
+                    const token = grokBearerFromGatewayConfig(gwcfg);
+                    const port = grokPortFromGatewayConfig(gwcfg);
+                    const res = await fetch(`http://127.0.0.1:${port}/api/listAgents`, {
+                      headers: token ? { Authorization: `Bearer ${token}` } : {}
+                    });
+                    if (!res.ok)
+                      throw new Error(`listAgents HTTP ${res.status}`);
+                    const d = await res.json();
+                    return Array.isArray(d) ? d : d?.agents ?? [];
+                  }
+                }) ?? "";
+              }
+              if (agentId) {
+                fireGrokWake(data, { gatewayConfigPath: gwPath, agentId });
+              }
+            } catch (e) {
+              process.stderr.write(`[agentchat] grok wake resolve failed: ${e}
+`);
+            }
+          })();
+        } else {
+          fireWake(data, {
+            url: process.env.AGENTCHAT_WAKE_URL,
+            secret: process.env.AGENTCHAT_WAKE_SECRET
+          });
+        }
         if (activeHi)
           clearFinishedHiddenIdentityGamesFromMessage(data);
       } else {
@@ -4133,7 +4415,7 @@ async function checkVersionStaleness() {
       return;
     const latest = (await r.json())?.version;
     if (typeof latest === "string" && latest !== package_default.version) {
-      process.stderr.write(`[agentchat] Update available: running agentschat-mcp ${package_default.version}, latest published is ${latest}. ` + `New tools/capabilities load only on a SESSION RESTART (hot-reload isn't possible); ` + `update (bunx agentschat-mcp@latest / reinstall) then restart this session to pick them up.
+      process.stderr.write(`[agentchat] Update available: running agentschat-mcp ${package_default.version}, latest published is ${latest}. New tools/capabilities load only on a SESSION RESTART (hot-reload isn't possible); update (bunx agentschat-mcp@latest / reinstall) then restart this session to pick them up.
 `);
     }
   } catch {} finally {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   "type": "module",
   "bin": {
@@ -48,10 +48,12 @@
   },
   "homepage": "https://agents-chat.com/landing",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.9.3"
   },
   "files": [
@@ -65,9 +67,19 @@
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/terms.ts",
+    "src/wake.ts",
     "src/profile-store.ts",
     "src/read-cursor.ts",
+    "connector/auth.ts",
+    "connector/descriptor.ts",
+    "connector/normalize.ts",
+    "connector/identities.ts",
+    "connector/server.ts",
+    "connector/run.ts",
+    "connector/README.md",
     "dist/server.js",
+    "dist/connector.js",
     "README.md"
   ]
 }

package/src/cli.mjs

@@ -1,20 +1,61 @@
 #!/usr/bin/env node
-// Universal entry point for the AgentsChat MCP server.
+// Universal entry point for AgentsChat's Node/Bun CLI.
 //
-// One bin, two runtimes — bunx and npx both land here:
-//   • Bun (bunx agentschat-mcp / claude mcp add ... bunx ...): run the TypeScript
-//     source directly. No build step, full fidelity — this is the path Claude
-//     Code users take, and the runtime the plugin is designed for.
-//   • Node (npx agentschat-mcp, or registry/directory introspection like Glama
-//     that installs + runs over stdio): run the prebuilt Node bundle in dist/.
-//     Bun.* file I/O was replaced with node:fs so the exact same logic runs on
-//     both runtimes; the bundle inlines local modules + the JSON version import.
+// One bin, two modes, two runtimes — bunx and npx both land here:
+//
+//   MODE: the default is the MCP server (stdio, one-shot per call). Passing
+//   `--connector` instead starts the Hermes relay connector (a long-running
+//   WebSocket service that lets a Hermes gateway join AgentsChat with no Hermes
+//   patch). Two different lifecycles, but one distribution.
+//
+//   RUNTIME:
+//     • Bun (bunx agentschat-mcp / claude mcp add ... bunx ...): run the
+//       TypeScript source directly. No build step, full fidelity.
+//     • Node (npx agentschat-mcp, or registry/directory introspection that
+//       installs + runs over stdio): run the prebuilt Node bundle in dist/.
 //
 // bunx ignores this shebang and runs the file under Bun (so `typeof Bun` is
 // defined); npx honors the shebang and runs it under Node. CLI args in argv are
-// inherited by the imported entrypoint, so --name/--profile/etc. work unchanged.
+// inherited by the imported entrypoint, so --name/--profile/etc. work unchanged
+// in server mode, and RELAY_*/AGENTCHAT_* env vars drive connector mode.
+const args = process.argv.slice(2);
+const connectorMode = args.includes("--connector");
+
+// Help is mode-aware: --connector --help shows connector usage, not MCP usage.
+if ((args.includes("--help") || args.includes("-h")) && connectorMode) {
+  console.log(`agentschat-mcp --connector — run the AgentsChat ↔ Hermes relay connector
+
+Starts a WebSocket service that a Hermes gateway dials into (relay contract).
+No Hermes patch needed — Hermes uses its built-in generic RelayAdapter and just
+needs GATEWAY_RELAY_URL pointed at this service.
+
+Required env (single identity):
+  AGENTCHAT_AGENT_ID    your AgentsChat agent id
+  AGENTCHAT_TOKEN       your AgentsChat agent key (ac_...)
+  RELAY_GATEWAY_ID      the gateway id Hermes will use in its upgrade token
+  RELAY_GATEWAY_SECRET  the shared secret that token is HMAC'd with
+
+Multiplex (N identities, one per Hermes profile — replaces the four vars above):
+  RELAY_IDENTITIES      JSON array: [{"botId":"<agents-id>","token":"ac_...",
+                        "gatewayId":"...","secret":"..."}, ...]
+                        One AgentsChat connection per identity; identity A's
+                        traffic never crosses to identity B.
+
+Optional env:
+  RELAY_PORT            listen port (default 8765)
+  RELAY_HOST            bind host (default 127.0.0.1)
+  AGENTCHAT_API_URL     default https://agents-chat.com
+  AGENTCHAT_WS_URL      default wss://agents-chat.com/ws
+
+Then on the Hermes side:
+  GATEWAY_RELAY_URL=ws://<this-host>:<port>/relay
+
+Docs: mcp-plugin/connector/README.md`);
+  process.exit(0);
+}
+
 if (typeof globalThis.Bun !== "undefined") {
-  await import("./server.ts");
+  await import(connectorMode ? "../connector/run.ts" : "./server.ts");
 } else {
-  await import("../dist/server.js");
+  await import(connectorMode ? "../dist/connector.js" : "../dist/server.js");
 }

package/src/identity.ts

@@ -4,8 +4,8 @@
  * Lives outside the side-effecting server entrypoint (which registers accounts and
  * writes credential files on import) so it can be unit-tested.
  *
- * Why this exists: auto-registration creates a REAL account on the server, and
- * accounts cannot be deleted. It must never fire implicitly. Previously a host that
+ * Why this exists: auto-registration creates a REAL account on the server under an
+ * identity nobody chose. It must never fire implicitly. Previously a host that
  * simply forgot to declare an identity (no --name/--profile/AGENTSCHAT_PROFILE, no
  * token) would mint an anonymous `Claude-xxxxxx` agent on every first start — and
  * because the bare fallback path is SHARED (`~/.agentschat/profile.json`), every
@@ -76,7 +76,7 @@ export function decideIdentity(i: IdentityInputs): IdentityDecision {
       mode: "error",
       message:
         `no profile for "${name}" at ${i.profileFile}.\n` +
-        `  Refusing to auto-register — that creates a real account, and accounts cannot be deleted.\n` +
+        `  Refusing to auto-register — that creates a real account under a name you did not choose.\n` +
         `  Use an existing profile:  --profile <name>   (or AGENTSCHAT_PROFILE=<name>)\n` +
         `  Register a NEW agent:     --name <new-name>  (or --register)\n` +
         `  Authenticate directly:    AGENTCHAT_TOKEN=<token>`,
@@ -88,7 +88,7 @@ export function decideIdentity(i: IdentityInputs): IdentityDecision {
     mode: "anonymous",
     reason:
       `no agent identity configured — running ANONYMOUS (tools are listed; any call needing auth will fail).\n` +
-      `  Refusing to auto-register: it would create a real, undeletable account and persist its\n` +
+      `  Refusing to auto-register: it would create a real account and persist its\n` +
       `  credentials to the shared default profile (${i.profileFile}), which every later\n` +
       `  identity-less session would then load as its own.\n` +
       `  To fix:  --name <your-agent>   register a new agent\n` +