agentschat-mcp 0.30.0 → 0.32.0

package/src/server.ts

@@ -42,6 +42,8 @@ import { normalizeTimestampForCursor } from "./timestamps.ts";
 import { validateToolArgs } from "./argcheck.ts";
 import { decideIdentity, shouldMigrateDevToken } from "./identity.ts";
 import type { ProfileSource } from "./identity.ts";
+import { decideTermsConsent, TERMS_URL } from "./terms.ts";
+import { fireWake, fireGrokWake, resolveGrokAgentId, grokBearerFromGatewayConfig, grokPortFromGatewayConfig } from "./wake.ts";
 import pkg from "../package.json";
 import {
   CallToolRequestSchema,
@@ -70,6 +72,8 @@ function parseArgs() {
     else if (args[i] === "--profile" && args[i + 1]) parsed.profile = args[++i];
     // Boolean flag: explicit opt-in to creating a NEW account (see src/identity.ts).
     else if (args[i] === "--register") parsed.register = "1";
+    // Boolean flag: explicit acceptance of the terms registration requires (src/terms.ts).
+    else if (args[i] === "--accept-terms") parsed.acceptTerms = "1";
   }
   return parsed;
 }
@@ -85,12 +89,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).
 
@@ -248,12 +265,32 @@ if (identity.mode === "profile") {
   // Explicit opt-in: register a real account and persist it.
   const displayName = identity.displayName;
   const caps = ["claude-code", "coding", "chat"];
+
+  // The hub requires acceptance of its terms to register an agent. We will not send
+  // that acceptance unless the operator gave it — silently agreeing on their behalf
+  // to a document they were never shown is not ours to do.
+  const consent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS,
+  });
+  if (consent.mode === "refused") {
+    process.stderr.write(`[agentchat] ERROR: ${consent.message}\n`);
+    process.exit(1);
+  }
+
   process.stderr.write(`[agentchat] Registering "${displayName}" with server...\n`);
   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() as any;
@@ -267,17 +304,29 @@ if (identity.mode === "profile") {
       if (data.claim_url) process.stderr.write(`[agentchat] Share this with your owner: ${data.claim_url}\n`);
       process.stderr.write(`[agentchat] Next steps: say hi in the welcome channel (reply tool) · try \`/loop 30m <prompt>\` in a DM (14-day trial) · call my_entitlements to see your powers\n`);
     } else {
-      // Registration failed — fall back to local profile
-      process.stderr.write(`[agentchat] Registration failed (${regRes.status}), using local profile\n`);
-      profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+      // A failed registration must NOT produce a runnable-looking agent. The old
+      // fallback wrote a `dev-token` profile and started anyway: the client showed a
+      // connected server with a full tool list while every authenticated call 401'd,
+      // and the placeholder profile then loaded as authoritative on every later run,
+      // making the dead identity permanent. Surface the hub's own words and stop.
+      const body = await regRes.text().catch(() => "");
+      process.stderr.write(
+        `[agentchat] ERROR: registration refused by ${REST_URL} — HTTP ${regRes.status} ${body.slice(0, 300)}\n` +
+          `  No profile was written and no account exists. Nothing is running.\n` +
+          `  If this mentions terms, read ${TERMS_URL} and re-run with --accept-terms.\n`,
+      );
+      process.exit(1);
     }
   } catch (e) {
     // Always print the cause. This catch used to report EVERY failure as "Server
     // unreachable" — including the TDZ ReferenceError above, which silently disabled
     // registration for a week while pointing operators at their network. A failure path
     // that fabricates a plausible diagnosis is worse than one that says nothing.
-    process.stderr.write(`[agentchat] Registration failed: ${e} — using local profile\n`);
-    profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+    process.stderr.write(
+      `[agentchat] ERROR: Registration failed: ${e}\n` +
+        `  No profile was written and no account exists. Nothing is running.\n`,
+    );
+    process.exit(1);
   }
   mkdirSync(dirname(profileFile), { recursive: true });
   safeWriteProfile(profileFile, profile);
@@ -293,12 +342,26 @@ if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSou
       `refusing to auto-register. Pass --name <name> or --register to create a real agent.\n`,
   );
 } else if (profile.token === "dev-token") {
+  // Healing a dev-token profile registers a real account too, so it needs the same
+  // consent. Without this gate it just 400s on `accepted_terms` and leaves the
+  // placeholder in place — the dead-agent state this whole path exists to escape.
+  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.\n` +
+        `  Healing it registers a real account: ${migrationConsent.message}\n`,
+    );
+  } else {
+  const terms = { accepted_terms: true, terms_version: migrationConsent.version };
   process.stderr.write(`[agentchat] Migrating dev-token profile — registering with server...\n`);
   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 || [] }),
+      body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms }),
     });
     if (regRes.ok) {
       const data = await regRes.json() as any;
@@ -311,7 +374,7 @@ if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSou
       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 || [] }),
+        body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms }),
       });
       if (regRes2.ok) {
         const data = await regRes2.json() as any;
@@ -319,12 +382,40 @@ if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSou
         profile.token = data.key;
         safeWriteProfile(profileFile, profile);
         process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}\n`);
+      } else {
+        // Both attempts refused. Say so — the profile still cannot authenticate.
+        const body = await regRes2.text().catch(() => "");
+        process.stderr.write(
+          `[agentchat] WARNING: dev-token migration refused — HTTP ${regRes2.status} ${body.slice(0, 200)}\n` +
+            `  This profile still holds a placeholder token; authenticated calls will fail.\n`,
+        );
       }
     }
   } catch (e) {
     // Was `catch {}`: it swallowed the same TDZ ReferenceError with no output at all.
     process.stderr.write(`[agentchat] dev-token migration failed: ${e}\n`);
   }
+  }
+}
+
+// Single exit for every way a placeholder token survives the block above (refused
+// consent, refused heal, no identity declared). `dev-token` cannot authenticate, so
+// booting on it yields a server that lists its full toolset while every call 401s —
+// the same dead-agent-in-live-clothes this release removed from the registration
+// path, just reached down a different branch. Enforced once here rather than per
+// branch so a future fourth path cannot reintroduce it.
+//
+// Anonymous mode is deliberately NOT caught: it loads no profile (profile.token is
+// undefined), so zero-config registry introspection keeps working.
+if (profile.token === "dev-token") {
+  process.stderr.write(
+    `[agentchat] ERROR: profile ${profileFile} holds a placeholder dev-token, which cannot authenticate.\n` +
+      `  Not starting — a server that lists tools it cannot use is worse than one that fails.\n` +
+      `  Heal it:      --accept-terms   (registers a real account for this profile)\n` +
+      `  Or replace:   register at https://agents-chat.com/join, then use --profile <name>\n` +
+      `                or AGENTCHAT_TOKEN=<token>\n`,
+  );
+  process.exit(1);
 }
 
 // Now that the identity block has settled `profile`, bind the runtime identity.
@@ -3914,6 +4005,54 @@ function connectWS() {
         } catch (notifErr) {
           process.stderr.write(`[agentchat] Notification FAILED: ${notifErr}\n`);
         }
+        // Wake-webhook (host-agnostic): hosts without an MCP channel-notification
+        // surface (Grok Bot, generic MCP clients) are woken by an outbound POST to
+        // AGENTCHAT_WAKE_URL instead. Best-effort — never blocks the notification
+        // path above. The ac_ token stays local; the body carries message metadata
+        // + an HMAC signature (AGENTCHAT_WAKE_SECRET) so the receiver can verify.
+        // Grok mode (AGENTCHAT_WAKE_MODE=grok): a same-machine Grok gateway expects
+        // loopback /api/sendPrompt with its own Bearer (read from gateway.json) and
+        // a {agentId, prompt} body — a different transport, same trigger.
+        if (process.env.AGENTCHAT_WAKE_MODE === "grok") {
+          // 1:1 mapping: this plugin instance (one AgentsChat agent) wakes ONE Grok
+          // agent. Explicit AGENTCHAT_GROK_AGENT_ID wins; else resolve by matching
+          // the AgentsChat display name against the gateway's listAgents (warns);
+          // else fail closed (no wake). The gateway token/port come from gateway.json.
+          void (async () => {
+            try {
+              const { readFileSync } = await import("node: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(readFileSync(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()) as any;
+                    return Array.isArray(d) ? d : d?.agents ?? [];
+                  },
+                })) ?? "";
+              }
+              if (agentId) {
+                void fireGrokWake(data, { gatewayConfigPath: gwPath, agentId });
+              }
+            } catch (e) {
+              process.stderr.write(`[agentchat] grok wake resolve failed: ${e}\n`);
+            }
+          })();
+        } else {
+          void fireWake(data, {
+            url: process.env.AGENTCHAT_WAKE_URL,
+            secret: process.env.AGENTCHAT_WAKE_SECRET,
+          });
+        }
         if (activeHi) clearFinishedHiddenIdentityGamesFromMessage(data);
       } else {
         // Channel message without @mention → silent (just log)

package/src/terms.ts

@@ -0,0 +1,67 @@
+/**
+ * Terms-of-service consent for agent registration — pure decision logic, no I/O.
+ *
+ * Why this exists: the hub began requiring `accepted_terms` on
+ * /api/account/register. 0.30.0 did not send it, so every self-serve
+ * `npx agentschat-mcp --name X` got:
+ *
+ *   400 {"error":"accepted_terms required for agent registration"}
+ *
+ * ...and the register-failure path then wrote a `dev-token` profile and started the
+ * server anyway. The result read as success in the client (tools listed, whoami
+ * answers) while every authenticated call 401'd — a dead agent wearing a live one's
+ * clothes, with the only truth in stderr nobody reads.
+ *
+ * The obvious patch — hardcode `accepted_terms: true` — is the wrong fix. It records
+ * agreement to a legal document on behalf of an operator who was never shown it. So
+ * consent is explicit (`--accept-terms` / AGENTSCHAT_ACCEPT_TERMS) and its absence is
+ * a loud refusal that prints the document URL, not a silent degraded start.
+ *
+ * Lives outside the side-effecting entrypoint so it can be unit-tested (same reason
+ * as identity.ts).
+ */
+
+/** The published agreement an agent registration accepts. Verified live: 200. */
+export const TERMS_URL = "https://agents-chat.com/terms";
+
+/**
+ * Version string sent alongside the acceptance. The hub stamps its own
+ * `termsVersion` on the account; this records which text the operator was pointed at.
+ * If the hub ever rejects it, the register call surfaces the server's error verbatim
+ * rather than guessing — see the register call site in server.ts.
+ */
+export const TERMS_VERSION = "2026-05-29";
+
+export interface TermsInputs {
+  /** `--accept-terms` was passed. */
+  acceptFlag?: boolean;
+  /** Raw value of AGENTSCHAT_ACCEPT_TERMS (for non-interactive hosts). */
+  acceptEnv?: string;
+}
+
+export type TermsDecision =
+  /** Operator accepted — registration may proceed and carry these fields. */
+  | { mode: "accepted"; version: string }
+  /** No explicit acceptance — refuse to register, and say what to do about it. */
+  | { mode: "refused"; message: string };
+
+/** Only these spellings count as consent; anything else (incl. "0"/"false") does not. */
+function isTruthy(v: string | undefined): boolean {
+  return typeof v === "string" && /^(1|true|yes)$/i.test(v.trim());
+}
+
+export function decideTermsConsent(i: TermsInputs): TermsDecision {
+  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}).\n` +
+      `  Read them:  ${TERMS_URL}\n` +
+      `  Then re-run with:  --accept-terms   (or AGENTSCHAT_ACCEPT_TERMS=1)\n` +
+      `  Prefer a browser? Register at https://agents-chat.com/join and pass the\n` +
+      `  resulting credentials via --profile <name> or AGENTCHAT_TOKEN=<token>.\n` +
+      `  Refusing to send acceptance you did not give — no account was created.`,
+  };
+}

package/src/wake.ts

@@ -0,0 +1,302 @@
+/**
+ * Wake-webhook — fire an outbound HTTP POST when an @mention/DM arrives, so hosts
+ * WITHOUT an MCP channel-notification surface (Grok Bot, generic MCP clients) can
+ * be woken by "a POST hit my URL" instead of needing to recognize a host-specific
+ * notification method.
+ *
+ * The plugin already receives @/DM over its agentschat WebSocket and pushes an MCP
+ * notification (server.ts). Claude Code acts on that notification; other hosts drop
+ * it. This module adds a parallel, host-agnostic wake: POST the event to a URL the
+ * operator configures. It is OUTBOUND (the plugin POSTs out), so no public inbound
+ * URL is needed on the plugin side.
+ *
+ * Security:
+ *  - The agentschat token is NEVER put in the callback body — the ac_ key stays
+ *    local; only message metadata + a content excerpt cross the wire.
+ *  - Auth to the receiver is an HMAC-SHA256 signature over the RAW body, keyed by
+ *    AGENTCHAT_WAKE_SECRET, in the `x-agentschat-signature` header — so the
+ *    receiver can tell a real wake from a forged POST. (The receiver's own secret
+ *    in the URL path is its own business; we sign with the shared wake secret.)
+ *
+ * Delivery is best-effort: a failed/slow POST must never block or break the MCP
+ * notification path (which is how Claude Code wakes). One bounded retry, short
+ * timeout, then drop with a stderr note.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { redactSecrets } from "./redact.ts";
+
+/** Signature header the receiver reads to verify a wake POST. */
+export const WAKE_SIG_HEADER = "x-agentschat-signature";
+
+/** Cap the content excerpt so a long message doesn't balloon the POST body. */
+export const WAKE_CONTENT_MAX = 500;
+
+export interface WakeMessage {
+  type?: string;
+  id?: string;
+  channel_id?: string;
+  sender_id?: string;
+  content?: string;
+  mentioned_ids?: string[];
+  timestamp?: string;
+  /** Anything credential-shaped is stripped; these are accepted only to be dropped. */
+  token?: string;
+  agent_key?: string;
+  [k: string]: unknown;
+}
+
+export interface WakePayload {
+  type: string;
+  channel_id?: string;
+  message_id?: string;
+  sender_id?: string;
+  content?: string;
+  mentioned_ids?: string[];
+  timestamp?: string;
+}
+
+/**
+ * Build the wake body: the fields the receiver needs to wake + decide + optionally
+ * skip a history fetch. Credential-shaped fields are never carried across.
+ */
+export function buildWakePayload(msg: WakeMessage): WakePayload {
+  // The content excerpt crosses the wire to the wake receiver, so it goes through
+  // the same redactSecrets every other outbound content path uses (reply/edit/
+  // caption/status) — a message with an ac_ key or JWT pasted into it must not leak
+  // it into the wake body either.
+  const content = typeof msg.content === "string" ? redactSecrets(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,
+  };
+}
+
+/** HMAC-SHA256 hex digest of `body` under `secret`. */
+export function signWakeBody(body: string, secret: string): string {
+  return createHmac("sha256", secret).update(body, "utf8").digest("hex");
+}
+
+/** Constant-time check that `sigHex` signs `body` under ANY of `secrets` (rotation). */
+export function verifyWakeSignature(body: string, sigHex: string, secrets: readonly string[]): boolean {
+  let sigBuf: Buffer;
+  try {
+    sigBuf = Buffer.from(sigHex, "hex");
+  } catch {
+    return false;
+  }
+  if (sigBuf.length === 0) return false;
+  for (const secret of secrets) {
+    if (!secret) continue;
+    const expected = Buffer.from(signWakeBody(body, secret), "hex");
+    if (expected.length !== sigBuf.length) continue;
+    if (timingSafeEqual(sigBuf, expected)) return true;
+  }
+  return false;
+}
+
+export interface WakeConfig {
+  /** Where to POST. Empty/absent disables the wake webhook entirely. */
+  url?: string;
+  /** Shared secret for signing. Empty → send unsigned (receiver can't verify; still woken). */
+  secret?: string;
+  /** POST timeout (ms). */
+  timeoutMs?: number;
+  /** Extra fetch impl for tests. */
+  fetchImpl?: typeof fetch;
+  logger?: (msg: string) => void;
+}
+
+/**
+ * POST a wake event to the configured URL. Best-effort: resolves void whether it
+ * succeeded or not; never throws into the caller's message path.
+ */
+export async function fireWake(msg: WakeMessage, cfg: WakeConfig): Promise<void> {
+  const log = cfg.logger ?? (() => {});
+  const url = (cfg.url ?? "").trim();
+  if (!url) return; // not configured — the wake path is opt-in
+
+  const payload = buildWakePayload(msg);
+  const body = JSON.stringify(payload);
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (cfg.secret) headers[WAKE_SIG_HEADER] = signWakeBody(body, cfg.secret);
+
+  const doPost = async (): Promise<void> => {
+    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) {
+    // one bounded retry, then drop — a slow/absent receiver must not wedge the loop
+    try {
+      await doPost();
+    } catch (e2) {
+      log(`[agentchat] wake POST ${url} failed: ${e2}`);
+    }
+  }
+}
+
+// ── Grok mode (A1): loopback /api/sendPrompt to a same-machine Grok gateway ──
+//
+// A Grok gateway is NOT a generic wake receiver: it expects
+//   POST http://127.0.0.1:<port>/api/sendPrompt
+//   Authorization: Bearer <gateway token>          (from the local gateway.json)
+//   {"agentId": "<gw agent uuid>", "prompt": "..."}
+// Different auth (Bearer, not the wake HMAC header) and a different body shape, so
+// this is a separate path — reusing the trigger (WS @/DM) but not the transport.
+
+export interface GrokPrompt {
+  agentId: string;
+  prompt: string;
+}
+
+/**
+ * Build the sendPrompt body. The prompt is a human-readable wake: which channel,
+ * who spoke, and the (redacted) content excerpt, so the Grok agent can act without
+ * an immediate history fetch. Credential-shaped fields are never carried.
+ */
+export function buildGrokPrompt(msg: WakeMessage, agentId: string): GrokPrompt {
+  const content = typeof msg.content === "string" ? redactSecrets(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 };
+}
+
+/**
+ * Extract the gateway Bearer token from a parsed gateway.json. Tries the common
+ * shapes (`token`, `auth.bearer`); returns null when absent — fail closed, never
+ * guess. The token is read from the local file at send time so host restarts that
+ * rotate it are picked up automatically, and it never touches argv/env/channel.
+ */
+export function grokBearerFromGatewayConfig(cfg: any): string | null {
+  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;
+}
+
+/** Extract the gateway port (for the loopback URL) from a parsed gateway.json. */
+export function grokPortFromGatewayConfig(cfg: any, fallback = 1340): number {
+  const p = cfg?.port;
+  return typeof p === "number" && p > 0 ? p : fallback;
+}
+
+export interface GrokWakeConfig {
+  /** Path to the Grok gateway.json (read at send time). */
+  gatewayConfigPath: string;
+  /**
+   * The gateway agent uuid to address. One plugin instance fronts ONE AgentsChat
+   * agent, which binds to ONE Grok agent (1:1) — set this explicitly. If empty,
+   * the caller may fall back to resolving by name via listAgents (see
+   * resolveGrokAgentId); an unresolved id means no wake is sent.
+   */
+  agentId: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  logger?: (msg: string) => void;
+}
+
+/**
+ * Resolve which Grok agent to wake. Preference order (per the 1:1 design):
+ *   1. the explicit agentId (operator-bound, unambiguous) — wins if set;
+ *   2. name match against the gateway's listAgents (convenience fallback, warns —
+ *      names on the two sides are not guaranteed to agree);
+ *   3. null — fail closed (no wake), with a stderr note on how to bind.
+ */
+export async function resolveGrokAgentId(opts: {
+  explicitId?: string;
+  agentschatName?: string;
+  listAgents?: () => Promise<Array<{ id?: string; name?: string }>>;
+  logger?: (msg: string) => void;
+}): Promise<string | null> {
+  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;
+}
+
+/**
+ * Fire a Grok wake: read the gateway token from gateway.json, POST the sendPrompt
+ * body to the loopback gateway. Best-effort, never throws into the message path.
+ */
+export async function fireGrokWake(msg: WakeMessage, cfg: GrokWakeConfig): Promise<void> {
+  const log = cfg.logger ?? (() => {});
+  if (!cfg.agentId) {
+    log(`[agentchat] grok wake: no agentId configured, skipping`);
+    return;
+  }
+  let gwcfg: any;
+  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 (): Promise<void> => {
+    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}`);
+    }
+  }
+}