@diegoaltoworks/chatter 0.60.0 → 0.62.0

package/README.md

@@ -9,7 +9,7 @@
 [![CI](https://github.com/diegoaltoworks/chatter/actions/workflows/ci.yml/badge.svg)](https://github.com/diegoaltoworks/chatter/actions/workflows/ci.yml)
 [![Demo](https://img.shields.io/badge/demo-chatter--demo-blue)](https://github.com/diegoaltoworks/chatter-demo)
 
-[Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Demo](#demo)
+[Features](#features) - [Quick Start](#quick-start) - [Documentation](#documentation) - [Demo](#demo)
 
 </div>
 
@@ -18,15 +18,15 @@
 - 🤖 **RAG-Powered**: Retrieval-Augmented Generation using OpenAI embeddings and Turso vector database
 - 🎨 **Customizable Widgets**: Pre-built chat components (ChatBot, Chat, ChatButton) with full styling control
 - 📝 **Markdown Rendering**: Assistant replies render Markdown (headings, lists, code blocks, links) safely with HTML escaping
-- 🔌 **OpenAI-Compatible API**: `POST /v1/chat/completions` (streaming + non-streaming) so any chat UI or SDK — [Deep Chat](https://deepchat.dev), [assistant-ui](https://www.assistant-ui.com), the OpenAI SDKs — can be the front end ([guide](./docs/integrations.md))
-- 🎛️ **Headless Mode**: Run the server as a pure API with `features: { headless: true }` — no built-in widget or demo pages
+- 🔌 **OpenAI-Compatible API**: `POST /v1/chat/completions` (streaming + non-streaming) so any chat UI or SDK - [Deep Chat](https://deepchat.dev), [assistant-ui](https://www.assistant-ui.com), the OpenAI SDKs - can be the front end ([guide](./docs/integrations.md))
+- 🎛️ **Headless Mode**: Run the server as a pure API with `features: { headless: true }` - no built-in widget or demo pages
 - 🔐 **Built-in API Key Management**: JWT-based API keys with CLI tool for easy creation
 - 🔑 **Authentication Ready**: Built-in support for JWT, Clerk, and custom auth providers
 - 📱 **Mobile Optimized**: Responsive design with iOS/Android-specific fixes
 - ⚡ **High Performance**: Built on Hono with streaming support
 - 🛡️ **Security First**: Rate limiting, CORS, referrer checking, and input guardrails
 - 💸 **Usage Metering**: Per-caller and global daily caps for paid features, multi-instance safe, via `@diegoaltoworks/chatter/usage` ([guide](./docs/usage.md))
-- 💬 **Channels**: Built-in WhatsApp and Telegram transports plus a Channel SPI for plugging in any other one — allowlist/mute gates, reply rate-limiting, and a shared inbound pipeline every channel reuses ([WhatsApp](./docs/channels.md), [Telegram](./docs/telegram.md), [build your own](./docs/build-a-channel.md))
+- 💬 **Channels**: Built-in WhatsApp, Telegram and Matrix transports plus a Channel SPI for plugging in any other one - allowlist/mute gates, reply rate-limiting, and a shared inbound pipeline every channel reuses ([WhatsApp](./docs/channels.md), [Telegram](./docs/telegram.md), [Matrix](./docs/matrix.md), [build your own](./docs/build-a-channel.md))
 - 🧩 **Flows**: Multi-turn, schema-driven slot-filling for structured conversations, with hybrid keyword + LLM intent matching ([guide](./docs/flows.md))
 - 🖼️ **Images**: On-demand generation and editing with cache-before-spend ordering and optional Cloudinary upload ([guide](./docs/images.md))
 - 🎭 **Personas**: Windowed, per-contact prompt layers and named greetings from a JSON registry ([guide](./docs/personas.md))
@@ -56,26 +56,26 @@ const app = await createServer({
 Bun.serve({ port: 8181, fetch: app.fetch });
 
 # Create API key for clients
-npx chatter create-apikey --name "my-app" --expires-in 365d
+npx chatter --name "my-app" --expires-in 365d
 ```
 
 **Requirements:** OpenAI API key, Turso database, and Bun >= 1.2 or Node >= 24. See [Requirements Guide](./docs/requirements.md) for setup instructions.
 
 ### Runtime
 
-The package runs on **Bun or Node** (>= 24 — it is built and published for both,
+The package runs on **Bun or Node** (>= 24 - it is built and published for both,
 and CI loads the built bundles under each). Two things differ:
 
-- **Serving the app** — `Bun.serve({ port: 8181, fetch: app.fetch })` on Bun;
+- **Serving the app** - `Bun.serve({ port: 8181, fetch: app.fetch })` on Bun;
   `serve({ port: 8181, fetch: app.fetch })` from [`@hono/node-server`](https://github.com/honojs/node-server) on Node.
-- **Static assets** — serving the widget files (`/chatter.js`, `/chatter.css`)
+- **Static assets** - serving the widget files (`/chatter.js`, `/chatter.css`)
   and a `publicDir` needs a runtime adapter, picked automatically. On Node that
   adapter is `@hono/node-server`, an optional peer dependency: without it,
   `/chatter.js` and `/chatter.css` 404 and the server logs an actionable
   error naming the missing package. Install it, or run with
   `features: { headless: true }` if the server should serve no files.
 
-Everything else — the chat pipeline, RAG, channels, the OpenAI-compatible API —
+Everything else - the chat pipeline, RAG, channels, the OpenAI-compatible API -
 is runtime-neutral. Development and the quality gates run on Bun.
 
 ## Examples
@@ -90,7 +90,7 @@ is runtime-neutral. Development and the quality gates run on Bun.
 
 ## Documentation
 
-Complete guides for setup, deployment, and integration — see
+Complete guides for setup, deployment, and integration - see
 [docs/index.md](./docs/index.md) for the full, ordered walkthrough:
 
 - **[Architecture](./docs/ARCHITECTURE.md)** - Load-bearing invariants, each linked to the test that enforces it
@@ -103,6 +103,7 @@ Complete guides for setup, deployment, and integration — see
 - **[WhatsApp Channel](./docs/channels.md)** - Link a WhatsApp number as a transport
 - **[Building a Channel](./docs/build-a-channel.md)** - Plug in a new transport
 - **[Telegram Channel](./docs/telegram.md)** - Run a bot on the official Bot API, no extra dependency
+- **[Matrix Channel](./docs/matrix.md)** - Run a bot on the client-server API, no extra dependency (unencrypted rooms only)
 - **[Flows](./docs/flows.md)** - Multi-turn, schema-driven slot-filling flows
 - **[Images](./docs/images.md)** - Generate and cache images on demand
 - **[Conversation History](./docs/history.md)** - Structural, host-replaceable multi-turn context
@@ -110,8 +111,23 @@ Complete guides for setup, deployment, and integration — see
 - **[Deployment](./docs/deployment.md)** - Google Cloud Run, Fly.io, Railway, VPS
 - **[Packaging](./docs/packaging.md)** - The subpath contract and the release chain
 - **[Testing](./docs/testing.md)** - Comprehensive testing guide
-- **[Sprint Review](./docs/sprint-review.md)** - Cross-module & security-invariant audit
 - **[FAQs](./docs/faqs.md)** - Troubleshooting and common questions
+- **Architecture Decisions** - The ADRs behind the shape of the codebase:
+  [0001, brain and sockets split](./docs/decisions/0001-brain-and-sockets-split.md),
+  [0002, no LangChain in core](./docs/decisions/0002-no-langchain-in-core.md),
+  [0003, slot-filling is brain territory](./docs/decisions/0003-slot-filling-is-brain-territory.md),
+  [0004, main-protection keeps only non-fast-forward and deletion protections](./docs/decisions/0004-main-protection-stays-non-fast-forward-only.md)
+- **Patterns** - Worked "how do I add X" guides:
+  [adding a capability](./docs/patterns/adding-a-capability.md),
+  [adding a store](./docs/patterns/adding-a-store.md),
+  [adding a retriever](./docs/patterns/adding-a-retriever.md),
+  [exemplars](./docs/patterns/exemplars.md)
+
+### Archive
+
+- **[Cross-Module Review](./docs/sprint-review.md)** - A dated, point-in-time
+  audit (v0.40) of cross-module paths and security invariants, not a
+  standing guarantee about the current codebase.
 
 ## Demo
 
@@ -120,7 +136,7 @@ Complete guides for setup, deployment, and integration — see
 The [chatter-demo](https://github.com/diegoaltoworks/chatter-demo) repository contains a complete, production-ready implementation showing:
 
 - Full server setup with custom configuration
-- 8 live demo implementations (Widget/React × Button/Inline × Public/Private)
+- 8 live demo implementations (Widget/React x Button/Inline x Public/Private)
 - Clerk authentication integration
 - Deployment configuration for Google Cloud Run
 - Knowledge base and prompt customization
@@ -156,7 +172,7 @@ See [Client Setup Guide](./docs/client.md) for detailed integration examples, th
 
 ## MCP Server Integration
 
-Use Chatter as a Model Context Protocol (MCP) server to expose your chatbot to Claude Desktop, VS Code extensions, and other MCP-compatible tools. `@modelcontextprotocol/sdk` and `zod` are optional peer dependencies scoped to this subpath — install them to use it: `bun add @modelcontextprotocol/sdk zod`.
+Use Chatter as a Model Context Protocol (MCP) server to expose your chatbot to Claude Desktop, VS Code extensions, and other MCP-compatible tools. `@modelcontextprotocol/sdk` and `zod` are optional peer dependencies scoped to this subpath - install them to use it: `bun add @modelcontextprotocol/sdk zod`.
 
 **Basic Setup:**
 ```typescript
@@ -199,7 +215,8 @@ const server = await createMCPServer({
   // ... other config ...
   toolRateLimit: 30,  // Max 30 requests per minute per tool (optional)
   logging: {
-    console: true,  // JSON logs to stdout (default: true)
+    console: true,   // JSON `mcp_chat` events via the logger, stderr (default: true)
+    content: false,  // also log the conversation itself (default: false)
     onChat: async (event) => {
       // Custom logging - includes conversation tracking and cost data
       console.log('Chat event:', {
@@ -230,6 +247,14 @@ const server = await createMCPServer({
 });
 ```
 
+The default `mcp_chat` console event carries metadata only: tool name,
+conversation id, message and context counts, duration and token cost. Set
+`logging.content: true` plus `logLevel: "debug"` to also get an
+`mcp_chat_content` event with the user message, history, retrieved context and
+answer. `onChat` always receives the full event, since the host decides where
+it lands. Content is scrubbed of credentials wherever it is emitted. See
+[docs/server.md](docs/server.md#logging).
+
 **Claude Desktop Configuration:**
 
 Add to your `claude_desktop_config.json`:
@@ -264,13 +289,13 @@ Both tools:
 
 **Features:**
 - **Conversation ID Tracking**: Pass `conversationId` parameter to maintain session continuity across tool calls
-- **Cost Tracking**: Every response includes token usage (prompt/completion/total). Add `openai: { pricing: { promptPer1M, completionPer1M } }` to also get an estimated USD cost — without it, `estimatedCost` is `null` rather than guessing at a price for the wrong model
+- **Cost Tracking**: Every response includes token usage (prompt/completion/total). Add `openai: { pricing: { promptPer1M, completionPer1M } }` to also get an estimated USD cost - without it, `estimatedCost` is `null` rather than guessing at a price for the wrong model
 - **Rate Limiting**: Optional per-tool rate limiting (requests per minute) to control API usage
 - **Observability**: Comprehensive logging with conversation tracking and cost data
 
 ## Plugins
 
-### Talker — Voice Calls & SMS
+### Talker - Voice Calls, SMS & WhatsApp
 
 Add phone call and SMS support to your Chatter bot with [Talker](https://github.com/diegoaltoworks/talker):
 
@@ -293,7 +318,21 @@ const app = await createServer({
 });
 ```
 
-One server, one port — web chat, phone calls, and SMS. See the [Talker README](https://github.com/diegoaltoworks/talker) for full documentation.
+One server, one port - web chat, phone calls, and SMS. See the [Talker README](https://github.com/diegoaltoworks/talker) for full documentation.
+
+### Two ways to do WhatsApp
+
+Chatter's own [WhatsApp channel](./docs/channels.md) and Talker's Twilio
+integration both reach WhatsApp, through very different paths - pick based on
+what you're building:
+
+| | This repo's [WhatsApp channel](./docs/channels.md) | Talker's Twilio WhatsApp |
+| --- | --- | --- |
+| WhatsApp access | Unofficial, via [Baileys](https://github.com/WhiskeySockets/Baileys) - a linked-device client, not the WhatsApp Business API | Sanctioned path, via Twilio's WhatsApp Business API integration |
+| Cost | Free besides hosting | Twilio usage-based pricing |
+| Risk | Real risk of the linked number being banned - use a number you can afford to lose | Runs through WhatsApp's own approved channel |
+| Setup | Link a number by QR code or pairing code, no third party | Twilio account and WhatsApp Business API approval |
+| Best for | Prototyping, personal or low-stakes bots | Production, customer-facing deployments |
 
 ## License
 

package/dist/auth/secretStrength.d.ts

@@ -4,5 +4,5 @@
  * forgery or WhatsApp account takeover — so a short or empty value fails
  * fast with an actionable error instead of quietly producing a weak key.
  */
-export declare function assertStrongSecret(secret: string | undefined, label: string): void;
+export declare function assertStrongSecret(secret: string | undefined, label: string): asserts secret is string;
 //# sourceMappingURL=secretStrength.d.ts.map

package/dist/auth/secretStrength.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secretStrength.d.ts","sourceRoot":"","sources":["../../src/auth/secretStrength.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAUlF"}
+{"version":3,"file":"secretStrength.d.ts","sourceRoot":"","sources":["../../src/auth/secretStrength.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,IAAI,MAAM,CAU1B"}

package/dist/bin/create-apikey.js

@@ -125,58 +125,75 @@ var ApiKeyManager = class {
   }
 };
 
-// bin/create-apikey.ts
-async function main() {
-  const args = process.argv.slice(2);
+// bin/create-apikey-args.ts
+function parseArgs(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--name" && args[i + 1]) {
-      options.name = args[i + 1];
-      i++;
-    } else if (args[i] === "--expires-in" && args[i + 1]) {
-      options.expiresIn = args[i + 1];
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      return { ok: true, help: true };
+    }
+    if (arg === "--name" || arg === "--expires-in") {
+      const value = args[i + 1];
+      if (value === void 0 || value.startsWith("-")) {
+        return { ok: false, error: `${arg} requires a value` };
+      }
+      if (arg === "--name") options.name = value;
+      else options.expiresIn = value;
       i++;
-    } else if (args[i] === "--help" || args[i] === "-h") {
-      console.log(`
+      continue;
+    }
+    return { ok: false, error: `Unknown argument: ${arg}` };
+  }
+  return { ok: true, help: false, ...options };
+}
+
+// bin/create-apikey.ts
+var HELP_TEXT = `
 Chatter API Key Generator
 
 Usage:
-  npx chatter create-apikey [options]
+  npx chatter [options]
 
 Options:
   --name <name>          Name/label for the API key (default: "api-key")
   --expires-in <time>    Expiration time (default: "365d")
                          Formats: s=seconds, m=minutes, h=hours, d=days, M=months, y=years
                          Examples: 30d, 12h, 1y, 6M
+  --help, -h             Show this help.
 
 Environment:
   CHATTER_SECRET         Required. Secret key for signing JWT tokens
 
 Examples:
-  npx chatter create-apikey --name "mobile-app" --expires-in 365d
-  npx chatter create-apikey --name "test-key" --expires-in 1h
-      `);
-      process.exit(0);
-    }
-  }
-  const secret = process.env.CHATTER_SECRET;
-  if (!secret) {
-    console.error("\u274C Error: CHATTER_SECRET environment variable is not set");
-    console.error("\n   Please set it before running this command:");
-    console.error("   export CHATTER_SECRET=your-secret-key-here");
-    console.error("\n   Or prefix the command:");
-    console.error("   CHATTER_SECRET=your-secret npx chatter create-apikey\n");
+  npx chatter --name "mobile-app" --expires-in 365d
+  npx chatter --name "test-key" --expires-in 1h
+`;
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    console.error(`\u274C ${parsed.error}`);
+    console.log(HELP_TEXT);
     process.exit(1);
   }
+  if (parsed.help) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+  const secret = process.env.CHATTER_SECRET;
   try {
     assertStrongSecret(secret, "CHATTER_SECRET");
   } catch (error) {
     console.error(`\u274C ${error.message}`);
+    console.error("\n   Set it before running this command:");
+    console.error("   export CHATTER_SECRET=your-secret-key-here");
+    console.error("\n   Or prefix the command:");
+    console.error("   CHATTER_SECRET=your-secret npx chatter\n");
     process.exit(1);
   }
   const manager = new ApiKeyManager(secret);
-  const keyName = options.name || "api-key";
-  const expiresIn = options.expiresIn || "365d";
+  const keyName = parsed.name || "api-key";
+  const expiresIn = parsed.expiresIn || "365d";
   try {
     const apiKey = await manager.create({
       name: keyName,
@@ -199,12 +216,12 @@ Examples:
 `);
     console.log("   Usage:");
     console.log("   curl -X POST https://your-bot.example.com/api/public/chat \\");
-    console.log(`     -H "x-api-key: ${apiKey.slice(0, 50)}..." \\`);
+    console.log(`     -H "x-api-key: ${apiKey}" \\`);
     console.log('     -H "Content-Type: application/json" \\');
     console.log(`     -d '{"message": "Hello"}'`);
     console.log("");
   } catch (error) {
-    console.error("\u274C Error creating API key:", error);
+    console.error(`\u274C Error creating API key: ${error.message}`);
     process.exit(1);
   }
 }

package/dist/bin/wa-pair.js

@@ -108,27 +108,55 @@ function ensureAuthSchema(client) {
   }
   return ready;
 }
-async function useTursoAuthState(db2, secret, sessionId2, runtime) {
-  await ensureAuthSchema(db2);
+function createTursoWaAuthKV(db2) {
+  return {
+    async read(id) {
+      await ensureAuthSchema(db2);
+      const result = await db2.execute({
+        sql: "SELECT value FROM wa_auth WHERE id = ?",
+        args: [id]
+      });
+      const row = result.rows[0];
+      return row ? row.value : null;
+    },
+    async write(id, value) {
+      await ensureAuthSchema(db2);
+      await db2.execute({
+        sql: "INSERT OR REPLACE INTO wa_auth (id, value) VALUES (?, ?)",
+        args: [id, value]
+      });
+    },
+    async remove(id) {
+      await ensureAuthSchema(db2);
+      await db2.execute({ sql: "DELETE FROM wa_auth WHERE id = ?", args: [id] });
+    },
+    // Mirrors isAuthRowForSession - keep the two in sync.
+    async clear(sessionId2) {
+      await ensureAuthSchema(db2);
+      if (sessionId2 === "default") {
+        await db2.execute("DELETE FROM wa_auth WHERE id NOT LIKE 's:%'");
+      } else {
+        await db2.execute({
+          sql: "DELETE FROM wa_auth WHERE id LIKE ?",
+          args: [`s:${sessionId2}/%`]
+        });
+      }
+    }
+  };
+}
+async function useAuthState(store, secret, sessionId2, runtime) {
   const rowId = (id) => sessionId2 === "default" ? id : `s:${sessionId2}/${id}`;
   async function read(id) {
-    const result = await db2.execute({
-      sql: "SELECT value FROM wa_auth WHERE id = ?",
-      args: [rowId(id)]
-    });
-    const row = result.rows[0];
-    if (!row) return null;
-    return JSON.parse(await decrypt(row.value, secret), runtime.bufferJSON.reviver);
+    const value = await store.read(rowId(id));
+    if (value === null) return null;
+    return JSON.parse(await decrypt(value, secret), runtime.bufferJSON.reviver);
   }
   async function write(id, value) {
     const payload = await encrypt(JSON.stringify(value, runtime.bufferJSON.replacer), secret);
-    await db2.execute({
-      sql: "INSERT OR REPLACE INTO wa_auth (id, value) VALUES (?, ?)",
-      args: [rowId(id), payload]
-    });
+    await store.write(rowId(id), payload);
   }
   async function remove(id) {
-    await db2.execute({ sql: "DELETE FROM wa_auth WHERE id = ?", args: [rowId(id)] });
+    await store.remove(rowId(id));
   }
   const creds = await read("creds") ?? runtime.initAuthCreds();
   return {
@@ -165,18 +193,13 @@ async function useTursoAuthState(db2, secret, sessionId2, runtime) {
       }
     },
     saveCreds: () => write("creds", creds),
-    clear: async () => {
-      if (sessionId2 === "default") {
-        await db2.execute("DELETE FROM wa_auth WHERE id NOT LIKE 's:%'");
-      } else {
-        await db2.execute({
-          sql: "DELETE FROM wa_auth WHERE id LIKE ?",
-          args: [`s:${sessionId2}/%`]
-        });
-      }
-    }
+    // Scoped to THIS session - never nuke a sibling number's pairing.
+    clear: () => store.clear(sessionId2)
   };
 }
+async function useTursoAuthState(db2, secret, sessionId2, runtime) {
+  return useAuthState(createTursoWaAuthKV(db2), secret, sessionId2, runtime);
+}
 
 // src/channels/whatsapp/baileys.ts
 function wrapMissingBaileysError(cause) {
@@ -196,6 +219,11 @@ function loadBaileys() {
   return cached;
 }
 
+// src/channels/backoff.ts
+function exponentialBackoffMs(baseMs, maxMs, n) {
+  return Math.min(baseMs * 2 ** Math.max(0, Math.min(n, 20)), maxMs);
+}
+
 // src/channels/whatsapp/pairing.ts
 var RESTART_REQUIRED_STATUS = 515;
 var MAX_PAIRING_RECONNECTS = 12;
@@ -206,9 +234,10 @@ var REGISTERED_CONFIRM_TIMEOUT_MS = 15e3;
 var REGISTERED_CONFIRM_POLL_MS = 500;
 function pairingReconnectDelayMs(statusCode, attempt) {
   if (statusCode === RESTART_REQUIRED_STATUS) return RESTART_REQUIRED_DELAY_MS;
-  return Math.min(
-    PAIRING_RECONNECT_DELAY_MS * 2 ** Math.max(0, attempt - 1),
-    PAIRING_RECONNECT_MAX_DELAY_MS
+  return exponentialBackoffMs(
+    PAIRING_RECONNECT_DELAY_MS,
+    PAIRING_RECONNECT_MAX_DELAY_MS,
+    attempt - 1
   );
 }
 function decidePairingClose(input) {
@@ -395,14 +424,46 @@ function resolveQrGenerate(mod) {
   return void 0;
 }
 
-// bin/wa-pair.ts
-var args = process.argv.slice(2);
-function flagValue(name) {
-  const index = args.indexOf(name);
-  return index >= 0 ? args[index + 1] : void 0;
+// bin/wa-pair-args.ts
+function parseArgs(args) {
+  let sessionId2;
+  let codeValue;
+  let reset2 = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      return { ok: true, help: true };
+    }
+    if (arg === "--reset") {
+      reset2 = true;
+      continue;
+    }
+    if (arg === "--code") {
+      const value = args[i + 1];
+      if (value === void 0 || value.startsWith("-")) {
+        return { ok: false, error: "--code requires a phone number, e.g. --code 447700900123" };
+      }
+      codeValue = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return { ok: false, error: `Unknown argument: ${arg}` };
+    }
+    if (sessionId2 !== void 0) {
+      return { ok: false, error: `Unexpected extra argument: ${arg}` };
+    }
+    sessionId2 = arg;
+  }
+  const phoneNumber2 = codeValue === void 0 ? void 0 : codeValue.replace(/[^0-9]/g, "");
+  if (codeValue !== void 0 && !phoneNumber2) {
+    return { ok: false, error: "--code requires a phone number, e.g. --code 447700900123" };
+  }
+  return { ok: true, help: false, sessionId: sessionId2 ?? "default", phoneNumber: phoneNumber2, reset: reset2 };
 }
-if (args.includes("--help") || args.includes("-h")) {
-  console.log(`
+
+// bin/wa-pair.ts
+var HELP_TEXT = `
 WhatsApp pairing CLI
 
 Usage:
@@ -416,21 +477,23 @@ Options:
   --code <phoneNumber>    Pair via pairing code instead of QR (digits only,
                            e.g. 447700900123). For headless setups.
   --reset                 Wipe the stored session first, then pair fresh.
-  --help, -h               Show this help.
+  --help, -h              Show this help.
 
 Environment:
-  TURSO_URL, TURSO_AUTH_TOKEN   Required. The database auth state is stored in.
+  TURSO_URL, TURSO_AUTH_TOKEN   Required. The database the auth state is stored in.
   WA_SESSION_SECRET             Required. Encrypts the stored session at rest.
-`);
-  process.exit(0);
-}
-var sessionId = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--code") ?? "default";
-if (args.includes("--code") && !flagValue("--code")) {
-  console.error("\u274C --code requires a phone number, e.g. --code 447700900123");
+`;
+var parsed = parseArgs(process.argv.slice(2));
+if (!parsed.ok) {
+  console.error(`\u274C ${parsed.error}`);
+  console.log(HELP_TEXT);
   process.exit(1);
 }
-var phoneNumber = flagValue("--code")?.replace(/[^0-9]/g, "");
-var reset = args.includes("--reset");
+if (parsed.help) {
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+var { sessionId, phoneNumber, reset } = parsed;
 var sessionSecret = process.env.WA_SESSION_SECRET;
 try {
   assertStrongSecret(sessionSecret, "WA_SESSION_SECRET");
@@ -442,9 +505,13 @@ if (!process.env.TURSO_URL) {
   console.error("\u274C TURSO_URL is required.");
   process.exit(1);
 }
+if (!process.env.TURSO_AUTH_TOKEN) {
+  console.error("\u274C TURSO_AUTH_TOKEN is required.");
+  process.exit(1);
+}
 var db = (0, import_client.createClient)({
   url: process.env.TURSO_URL,
-  authToken: process.env.TURSO_AUTH_TOKEN || ""
+  authToken: process.env.TURSO_AUTH_TOKEN
 });
 var printedQrFallbackHelp = false;
 function printQrFallback(qr) {
@@ -561,6 +628,6 @@ async function start() {
   process.exit(0);
 }
 start().catch((error) => {
-  console.error("\u274C Unexpected error:", error);
+  console.error(`\u274C Unexpected error: ${error.message}`);
   process.exit(1);
 });

package/dist/channels/backoff.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Exponential backoff with a cap: `base * 2^n`, `n` clamped to `[0, 20]` so
+ * the exponent never overflows long before `max` would bind anyway. Every
+ * poll/sync/reconnect loop in `src/channels/` computes its retry delay this
+ * way (`./telegram/poll.ts`, `./matrix/sync.ts`, `./whatsapp/channel.ts`,
+ * `./whatsapp/pairing.ts`); only `base`, `max`, and what `n` counts
+ * (failures seen vs. attempts made) differ between them.
+ */
+export declare function exponentialBackoffMs(baseMs: number, maxMs: number, n: number): number;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/channels/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/channels/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErF"}

package/dist/channels/gates.d.ts

@@ -95,14 +95,21 @@ export declare function underReplyRateLimit(msg: Pick<ChannelMessage, "chatId" |
     group: (chatId: string) => boolean;
 }): boolean;
 /**
- * Every session's own identities ever seen, keyed by session id. A
- * multi-session deployment (e.g. two linked numbers in one process) gives
- * each session only its own identity from its transport — a message that
- * actually came from a *different* session's identity looks like a
- * stranger, not "us", and the two sessions can ping-pong replies at each
- * other indefinitely. Callers populate this directly (`registry.set(sessionId, ids)`)
- * as each session's identities become known, typically on connect and kept
- * in sync as they change.
+ * Every session's own identities ever seen, keyed by session id.
+ *
+ * The failure this exists to prevent: link two numbers to one process (a
+ * common WhatsApp setup — a "support" and a "sales" line sharing a server),
+ * and each session's transport only tells that session its own identity. A
+ * message from the OTHER linked number's session then looks like a
+ * stranger, not "us" — the bot answers it, the other session sees THAT
+ * reply as a new stranger message and answers it back, and the two numbers
+ * ping-pong replies at each other indefinitely, burning the rate limit and
+ * spamming both chats until someone notices and kills the process. Sharing
+ * one registry across every session (rather than each session checking only
+ * its own identity) is what lets session A recognise session B's identity
+ * as "us" too, and stop the loop before it starts. Callers populate this
+ * directly (`registry.set(sessionId, ids)`) as each session's identities
+ * become known, typically on connect and kept in sync as they change.
  *
  * Entries are NOT expected to be removed when a session disconnects: a
  * session's own identity is still "us" while it reconnects, and losing that

package/dist/channels/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../src/channels/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,sHAAsH;IACtH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kIAAkI;IAClI,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,cAAc,CAAC,GAC9C,OAAO,CAQT;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAUjG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,MAAiB;UAcR,MAAM,GAAG,OAAO;;EAiBrC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,iBAAiB,CAAC,EACvD,QAAQ,EAAE;IAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,GAChF,OAAO,CAET;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE5D,qHAAqH;AACrH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC,EACjD,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAET"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../src/channels/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,sHAAsH;IACtH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kIAAkI;IAClI,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,cAAc,CAAC,GAC9C,OAAO,CAQT;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAUjG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,MAAiB;UAcR,MAAM,GAAG,OAAO;;EAiBrC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,iBAAiB,CAAC,EACvD,QAAQ,EAAE;IAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,GAChF,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE5D,qHAAqH;AACrH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC,EACjD,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAET"}

package/dist/channels/index.d.ts

@@ -42,7 +42,7 @@ export interface Channel {
     stop?(): void | Promise<void>;
 }
 export * from "./gates";
-export { createInboundPipeline, type InboundPipeline, type InboundPipelineConfig, type InboundPipelineDeps, type InboundPipelineOutcome, type InboundReplySender, type InboundTurn, } from "./pipeline";
+export { createInboundPipeline, type InboundPipeline, type InboundPipelineConfig, type InboundPipelineDeps, type InboundPipelineOutcome, type InboundReplySender, type InboundTurn, resolveBrainHooks, } from "./pipeline";
 export type { ChannelSender, ChannelSenderRegistry } from "./senders";
 export { createSenderRegistry } from "./senders";
 //# sourceMappingURL=index.d.ts.map

package/dist/channels/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,MAAM,WAAW,OAAO;IACtB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,MAAM,WAAW,OAAO;IACtB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}