niahere 0.3.0 → 0.3.1

package/src/channels/phone/index.ts

@@ -1,8 +1,10 @@
 /**
  * Phone channel — voice calling via Twilio + OpenAI Realtime.
  *
- * Boots an HTTP+WebSocket server inside the daemon. Twilio reaches it
- * through a public tunnel (cloudflared in our setup). Two surfaces:
+ * Registers HTTP + WebSocket routes on the shared TwilioWebhookServer
+ * (which other Twilio channels — sms, whatsapp — also use). The server
+ * handles signature validation, dedup, and rate-limit middleware so this
+ * file only owns voice-specific logic:
  *
  *   - Inbound: caller dials our Twilio number; we return TwiML that opens
  *     a Media Stream back to us; the stream is bridged to OpenAI Realtime.
@@ -11,33 +13,30 @@
  *     with a per-call goal seeded into the realtime session.
  *
  * Submodules:
- *   - twilio.ts        — REST + webhook signature helpers
- *   - twiml.ts         — TwiML XML builders
- *   - relay.ts         — Twilio Media Stream <-> OpenAI Realtime bridge
- *   - instructions.ts  — system-prompt builders for inbound/outbound
- *   - tools.ts         — function-calling tools exposed to the realtime model
- *   - consult.ts       — escape hatch to Claude for memory-aware reasoning
+ *   - ../twilio/server.ts  — shared HTTP+WS server
+ *   - ../twilio/rest.ts    — Twilio REST API helpers (placeCall, etc.)
+ *   - twiml.ts             — TwiML XML builders
+ *   - relay.ts             — Twilio Media Stream <-> OpenAI Realtime bridge
+ *   - instructions.ts      — system-prompt builders for inbound/outbound
+ *   - tools.ts             — function-calling tools exposed to the realtime model
+ *   - consult.ts           — escape hatch to Claude for memory-aware reasoning
  */
-import type { Server, ServerWebSocket } from "bun";
-import type { Channel, PhoneConfig } from "../../types";
+import type { ServerWebSocket } from "bun";
+import type { Channel, PhoneConfig, TwilioConfig } from "../../types";
 import { getConfig } from "../../utils/config";
 import { log } from "../../utils/log";
 import { getChannel } from "../registry";
 import { Session, Message } from "../../db/models";
 import { runMigrations } from "../../db/migrate";
 
-import { placeCall as twilioPlaceCall, validateTwilioSignature } from "./twilio";
+import { getTwilioServer, type WsConnectionData } from "../twilio/server";
+import { placeCall as twilioPlaceCall } from "../twilio/rest";
 import { streamTwiML, sayAndHangupTwiML, rejectTwiML } from "./twiml";
 import { createRelay, type CallContext, type RelayHandle, type RelayResult } from "./relay";
 import { buildInboundInstructions, buildOutboundInstructions } from "./instructions";
 import { buildPhoneTools } from "./tools";
 
-interface WsData {
-  streamSid: string | null;
-}
-
 interface PendingCall {
-  /** Context written when the call is initiated; consumed by the WS upgrade. */
   context: Omit<CallContext, "streamSid" | "tools">;
   startedAt: number;
 }
@@ -64,97 +63,68 @@ function defer<T>(): Deferred<T> {
 const DEFAULT_MAX_MINUTES = 10;
 const HARD_MAX_MINUTES = 30;
 
+const WS_PATH = "/twilio/voice/stream";
+
 class PhoneChannel implements Channel {
   name = "phone";
-  private server: Server<WsData> | null = null;
-  private readonly cfg: PhoneConfig;
-  /** Calls placed/answered but whose Media Stream hasn't connected yet. */
+  private readonly phone: PhoneConfig;
+  private readonly twilio: TwilioConfig;
   private readonly pending = new Map<string, PendingCall>();
-  /** Active relays, keyed by streamSid (assigned on Twilio "start" event). */
+  /** Active relays keyed by streamSid. */
   private readonly active = new Map<string, ActiveCall>();
-  /** Per-callSid completion deferreds. Resolved when the call's transcript is persisted. */
+  /** Per-callSid completion deferreds; resolved after persistCall. */
   private readonly completions = new Map<string, Deferred<RelayResult>>();
 
-  constructor(cfg: PhoneConfig) {
-    this.cfg = cfg;
+  constructor(phone: PhoneConfig, twilio: TwilioConfig) {
+    this.phone = phone;
+    this.twilio = twilio;
   }
 
-  // --- Channel lifecycle ---
-
   async start(): Promise<void> {
     await runMigrations();
-    const self = this;
-
-    this.server = Bun.serve<WsData, never>({
-      port: this.cfg.port,
-      async fetch(req, server) {
-        const path = new URL(req.url).pathname;
-
-        if (path === "/healthz") return new Response("ok", { status: 200 });
-
-        if (path === "/twilio/voice/stream") {
-          const ok = server.upgrade(req, { data: { streamSid: null } });
-          return ok ? undefined : new Response("expected websocket", { status: 400 });
-        }
-        if (path === "/twilio/voice/incoming" && req.method === "POST") {
-          return await self.handleIncoming(req);
-        }
-        if (path === "/twilio/voice/outbound" && req.method === "POST") {
-          return await self.handleOutboundTwiml(req);
-        }
-        if (path === "/twilio/voice/status" && req.method === "POST") {
-          return await self.handleStatus(req);
-        }
-        return new Response("not found", { status: 404 });
-      },
-      websocket: {
-        message(ws, message) {
-          const data = typeof message === "string" ? message : new TextDecoder().decode(message);
-          const sid = ws.data.streamSid;
-          if (sid) {
-            const active = self.active.get(sid);
-            if (active) {
-              active.handle.onTwilioMessage(data);
-              return;
-            }
-          }
-          self.bootstrapWsMessage(ws, data).catch((err) => {
-            log.error({ err }, "phone: ws bootstrap failed");
-            try {
-              ws.close();
-            } catch {}
-          });
-        },
-        close(ws) {
-          const sid = ws.data.streamSid;
-          if (!sid) return;
-          const active = self.active.get(sid);
-          if (active) active.handle.onTwilioClose();
-        },
-      },
+
+    const server = getTwilioServer();
+    server.configure({
+      port: this.twilio.port,
+      publicBaseUrl: this.twilio.public_base_url,
+      signingToken: this.twilio.auth_token || this.twilio.secret,
     });
 
+    server.registerHttp("/twilio/voice/incoming", (req, ctx) => this.handleIncoming(req, ctx.params));
+    server.registerHttp("/twilio/voice/outbound", (req, ctx) => this.handleOutboundTwiml(req, ctx.params));
+    server.registerHttp("/twilio/voice/status", (req, ctx) => this.handleStatus(ctx.params), {
+      dedupOn: "CallSid",
+    });
+
+    server.registerWs(WS_PATH, {
+      onMessage: (ws, data) => this.onWsMessage(ws, data),
+      onClose: (ws) => this.onWsClose(ws),
+    });
+
+    // Owner number must never be rate-limited (e.g. urgent rapid retries).
+    if (this.twilio.owner_number) server.exemptFromRateLimit(this.twilio.owner_number);
+
+    await server.start();
+
     log.info(
       {
-        port: this.cfg.port,
-        publicBaseUrl: this.cfg.public_base_url,
-        from: this.cfg.from_number,
-        owner: this.cfg.owner_number,
-        realtimeModel: this.cfg.realtime_model,
-        voice: this.cfg.voice,
+        port: this.twilio.port,
+        publicBaseUrl: this.twilio.public_base_url,
+        from: this.phone.from_number,
+        owner: this.twilio.owner_number,
+        realtimeModel: this.phone.realtime_model,
+        voice: this.phone.voice,
       },
       "phone channel started",
     );
   }
 
   async stop(): Promise<void> {
-    if (this.server) {
-      this.server.stop(true);
-      this.server = null;
-    }
     for (const active of this.active.values()) active.handle.onTwilioClose();
     this.active.clear();
     this.pending.clear();
+    // The shared server is stopped by the daemon's channel teardown — leaving
+    // it running here would block SMS/WhatsApp if they're also bound to it.
   }
 
   // --- Outbound entrypoint (used by the place_call MCP tool and CLI test) ---
@@ -174,10 +144,6 @@ class PhoneChannel implements Channel {
       opts.maxMinutes && opts.maxMinutes > 0 ? Math.min(opts.maxMinutes, HARD_MAX_MINUTES) : DEFAULT_MAX_MINUTES;
     const instructions = buildOutboundInstructions(opts.goal, opts.context);
 
-    // Twilio always includes `CallSid` in the form body of the TwiML
-    // webhook, so we don't need to encode it in the URL path — one static
-    // endpoint handles every outbound call, and we look up context by the
-    // CallSid Twilio sends us back.
     const result = await twilioPlaceCall({
       ...creds,
       to: opts.number,
@@ -205,21 +171,14 @@ class PhoneChannel implements Channel {
     return result;
   }
 
-  /**
-   * Wait for an in-flight call to finish. Resolves with the final transcript
-   * once the call has been persisted; returns null if the callSid is unknown.
-   */
   async awaitCallCompletion(callSid: string): Promise<RelayResult | null> {
     const deferred = this.completions.get(callSid);
     return deferred ? deferred.promise : null;
   }
 
-  // --- HTTP handlers ---
-
-  private async handleIncoming(req: Request): Promise<Response> {
-    const { params } = await readForm(req);
-    if (!this.verifySignature(req, params)) return forbidden();
+  // --- HTTP handlers (signature already validated by the shared server) ---
 
+  private async handleIncoming(_req: Request, params: Record<string, string>): Promise<Response> {
     const callSid = params.CallSid || "";
     const from = params.From || "";
     const { label, allowed } = this.classifyCaller(from);
@@ -254,10 +213,7 @@ class PhoneChannel implements Channel {
     return twimlResponse(streamTwiML(this.buildWssUrl(), { callSid, direction: "inbound" }));
   }
 
-  private async handleOutboundTwiml(req: Request): Promise<Response> {
-    const { params } = await readForm(req);
-    if (!this.verifySignature(req, params)) return forbidden();
-
+  private async handleOutboundTwiml(_req: Request, params: Record<string, string>): Promise<Response> {
     const callSid = params.CallSid || "";
     const pending = this.pending.get(callSid);
     if (!pending) {
@@ -270,9 +226,7 @@ class PhoneChannel implements Channel {
     return twimlResponse(streamTwiML(this.buildWssUrl(), { callSid, direction: "outbound" }));
   }
 
-  private async handleStatus(req: Request): Promise<Response> {
-    const { params } = await readForm(req);
-    if (!this.verifySignature(req, params)) return forbidden();
+  private handleStatus(params: Record<string, string>): Response {
     log.info(
       {
         callSid: params.CallSid,
@@ -285,16 +239,40 @@ class PhoneChannel implements Channel {
     return new Response("", { status: 204 });
   }
 
-  // --- WebSocket bootstrap ---
+  // --- WebSocket plumbing (delegated by shared server to this channel) ---
+
+  private onWsMessage(ws: ServerWebSocket<WsConnectionData>, data: string): void {
+    const sid = (ws.data.channel as { streamSid?: string }).streamSid;
+    if (sid) {
+      const active = this.active.get(sid);
+      if (active) {
+        active.handle.onTwilioMessage(data);
+        return;
+      }
+    }
+    this.bootstrapWsMessage(ws, data).catch((err) => {
+      log.error({ err }, "phone: ws bootstrap failed");
+      try {
+        ws.close();
+      } catch {}
+    });
+  }
 
-  private async bootstrapWsMessage(ws: ServerWebSocket<WsData>, data: string): Promise<void> {
+  private onWsClose(ws: ServerWebSocket<WsConnectionData>): void {
+    const sid = (ws.data.channel as { streamSid?: string }).streamSid;
+    if (!sid) return;
+    const active = this.active.get(sid);
+    if (active) active.handle.onTwilioClose();
+  }
+
+  private async bootstrapWsMessage(ws: ServerWebSocket<WsConnectionData>, data: string): Promise<void> {
     let msg: any;
     try {
       msg = JSON.parse(data);
     } catch {
       return;
     }
-    if (msg.event === "connected") return; // first frame, no streamSid yet
+    if (msg.event === "connected") return;
 
     if (msg.event !== "start") {
       log.warn({ event: msg.event }, "phone: unexpected first ws event");
@@ -321,16 +299,16 @@ class PhoneChannel implements Channel {
 
     const handle = createRelay({
       twilioWs: ws,
-      openAiKey: this.cfg.openai_api_key!,
-      model: this.cfg.realtime_model,
-      voice: this.cfg.voice,
+      openAiKey: this.phone.openai_api_key!,
+      model: this.phone.realtime_model,
+      voice: this.phone.voice,
       context,
     });
 
-    ws.data.streamSid = streamSid;
+    (ws.data.channel as { streamSid?: string }).streamSid = streamSid;
     this.active.set(streamSid, { handle, context, startedAt: pending.startedAt });
 
-    handle.onTwilioMessage(data); // forward the "start" event itself
+    handle.onTwilioMessage(data);
 
     handle.completion
       .then((result) => this.persistCall(context, pending.startedAt, result))
@@ -341,50 +319,36 @@ class PhoneChannel implements Channel {
   // --- Helpers ---
 
   private canStartRealtime(): boolean {
-    return Boolean(this.cfg.openai_api_key && this.cfg.public_base_url);
+    return Boolean(this.phone.openai_api_key && this.twilio.public_base_url);
   }
 
   private buildWssUrl(): string {
-    const base = this.cfg.public_base_url!.replace(/^http/, "ws");
-    return `${base}/twilio/voice/stream`;
+    return getTwilioServer().buildWssUrl(WS_PATH);
   }
 
   private classifyCaller(from: string): { label: string; allowed: boolean } {
-    if (from && from === this.cfg.owner_number) return { label: "Aman", allowed: true };
-    if (from && this.cfg.allowlist.includes(from)) return { label: from, allowed: true };
+    if (from && from === this.twilio.owner_number) return { label: "Aman", allowed: true };
+    if (from && this.twilio.allowlist.includes(from)) return { label: from, allowed: true };
     return { label: from || "unknown", allowed: false };
   }
 
-  private verifySignature(req: Request, params: Record<string, string>): boolean {
-    // X-Twilio-Signature is HMAC-SHA1 with the account's Auth Token. When an
-    // API Key (SK…) + Secret is used for REST auth, the Auth Token is a
-    // separate value — set as TWILIO_AUTH_TOKEN. We fall back to TWILIO_SECRET
-    // so the simple "Account SID + Auth Token" pairing also works.
-    const signingToken = this.cfg.twilio_auth_token || this.cfg.twilio_secret;
-    if (!signingToken) return false;
-    const signature = req.headers.get("X-Twilio-Signature") || "";
-    const fullUrl = this.cfg.public_base_url ? `${this.cfg.public_base_url}${new URL(req.url).pathname}` : req.url;
-    return validateTwilioSignature({ authToken: signingToken, fullUrl, params, signature });
-  }
-
-  private requireCreds(): { accountSid: string; authToken: string } {
-    const sid = this.cfg.twilio_sid;
-    const secret = this.cfg.twilio_secret;
-    if (!sid || !secret)
-      throw new Error("phone: channels.phone.twilio_sid and twilio_secret not set (config.yaml or env)");
-    return { accountSid: sid, authToken: secret };
+  private requireCreds(): { accountSid: string; authSid: string; authSecret: string } {
+    const sid = this.twilio.sid;
+    const secret = this.twilio.secret;
+    if (!sid || !secret) throw new Error("twilio: sid and secret not set (channels.twilio.* in config.yaml or env)");
+    return { accountSid: sid, authSid: sid, authSecret: secret };
   }
 
   private requirePublicBaseUrl(): string {
-    if (!this.cfg.public_base_url)
-      throw new Error("phone: channels.phone.public_base_url not set (config.yaml or PUBLIC_BASE_URL env)");
-    return this.cfg.public_base_url;
+    if (!this.twilio.public_base_url)
+      throw new Error("twilio: public_base_url not set (channels.twilio.public_base_url or PUBLIC_BASE_URL env)");
+    return this.twilio.public_base_url;
   }
 
   private requireFromNumber(): string {
-    if (!this.cfg.from_number)
-      throw new Error("phone: channels.phone.from_number not set (config.yaml or PHONE_FROM_NUMBER env)");
-    return this.cfg.from_number;
+    if (!this.phone.from_number)
+      throw new Error("phone: from_number not set (channels.phone.from_number or PHONE_FROM_NUMBER env)");
+    return this.phone.from_number;
   }
 
   private async persistCall(context: CallContext, startedAt: number, result: RelayResult): Promise<void> {
@@ -432,34 +396,22 @@ class PhoneChannel implements Channel {
 
 // --- Pure helpers ---
 
-async function readForm(req: Request): Promise<{ params: Record<string, string> }> {
-  const body = await req.text();
-  const params: Record<string, string> = {};
-  const usp = new URLSearchParams(body);
-  for (const [k, v] of usp) params[k] = v;
-  return { params };
-}
-
 function twimlResponse(xml: string): Response {
   return new Response(xml, { status: 200, headers: { "Content-Type": "text/xml" } });
 }
 
-function forbidden(): Response {
-  return new Response("invalid signature", { status: 403 });
-}
-
 // --- Factory ---
 
 let _instance: PhoneChannel | null = null;
 
 export function createPhoneChannel(): PhoneChannel | null {
-  const cfg = getConfig().channels.phone;
-  if (!cfg.twilio_sid || !cfg.twilio_secret || !cfg.from_number) return null;
-  _instance = new PhoneChannel(cfg);
+  const { twilio, phone } = getConfig().channels;
+  if (!phone.enabled) return null;
+  if (!twilio.sid || !twilio.secret || !phone.from_number) return null;
+  _instance = new PhoneChannel(phone, twilio);
   return _instance;
 }
 
-/** Used by the place_call MCP tool and CLI test entrypoint. Null if not running. */
 export function getPhoneChannel(): PhoneChannel | null {
   return _instance;
 }

package/src/channels/sms.ts

@@ -0,0 +1,189 @@
+/**
+ * SMS channel via Twilio.
+ *
+ * Same Twilio number as voice (channels.phone.from_number by default,
+ * overridable via channels.sms.from_number). Inbound webhook →
+ * chat engine → REST reply. Reuses the shared TwilioWebhookServer for
+ * routing, signature validation, dedup, and rate-limiting.
+ *
+ * Use case: cellular-only-no-data reachability — Aman can text Nia from
+ * patchy zones (Ladakh highways, basements, etc.) where Telegram /
+ * WhatsApp / voice over data won't work but SMS over SS7 still does.
+ *
+ * Note: outbound from US Twilio long codes to Indian mobile numbers has
+ * variable deliverability under TRAI scrubbing rules. Test empirically;
+ * if outbound fails, the inbound leg (Aman → Nia) is more reliable.
+ */
+import { createChatEngine } from "../chat/engine";
+import { getMcpServers } from "../mcp";
+import { Session } from "../db/models";
+import { runMigrations } from "../db/migrate";
+import type { Channel, ChatState, PhoneConfig, SmsConfig, TwilioConfig } from "../types";
+import { getConfig } from "../utils/config";
+import { log } from "../utils/log";
+import { sendMessage as twilioSendMessage } from "./twilio/rest";
+import { getTwilioServer } from "./twilio/server";
+
+const EMPTY_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response></Response>';
+
+class SmsChannel implements Channel {
+  name = "sms";
+  private readonly twilio: TwilioConfig;
+  private readonly sms: SmsConfig;
+  /** Cached resolved "from" number: sms.from_number || phone.from_number */
+  private readonly fromNumber: string;
+  private readonly chats = new Map<string, ChatState>();
+
+  constructor(twilio: TwilioConfig, sms: SmsConfig, fromNumber: string) {
+    this.twilio = twilio;
+    this.sms = sms;
+    this.fromNumber = fromNumber;
+  }
+
+  async start(): Promise<void> {
+    await runMigrations();
+
+    const server = getTwilioServer();
+    server.configure({
+      port: this.twilio.port,
+      publicBaseUrl: this.twilio.public_base_url,
+      signingToken: this.twilio.auth_token || this.twilio.secret,
+    });
+
+    server.registerHttp("/twilio/sms/incoming", (_req, ctx) => this.handleInbound(ctx.params), {
+      dedupOn: "MessageSid",
+      rateLimitOn: "From",
+    });
+    server.registerHttp("/twilio/sms/status", (_req, ctx) => this.handleStatus(ctx.params), {
+      dedupOn: "MessageSid",
+    });
+
+    if (this.twilio.owner_number) server.exemptFromRateLimit(this.twilio.owner_number);
+
+    await server.start();
+
+    log.info(
+      {
+        from: this.fromNumber,
+        owner: this.twilio.owner_number,
+        publicBaseUrl: this.twilio.public_base_url,
+      },
+      "sms channel started",
+    );
+  }
+
+  async stop(): Promise<void> {
+    for (const state of this.chats.values()) state.engine.close();
+    this.chats.clear();
+  }
+
+  /** Outbound to the owner — used by send_message MCP tool. */
+  async sendMessage(text: string): Promise<void> {
+    if (!this.twilio.owner_number) throw new Error("sms: owner_number not set");
+    await this.sendTo(this.twilio.owner_number, text);
+  }
+
+  // --- Inbound webhook ---
+
+  private async handleInbound(params: Record<string, string>): Promise<Response> {
+    const from = params.From || "";
+    const body = params.Body || "";
+
+    if (!this.isAllowed(from)) {
+      log.warn({ from }, "sms: rejecting non-allowlisted sender");
+      return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
+    }
+
+    const state = await this.getState(from);
+    // Ack the webhook immediately; reply via REST asynchronously to avoid
+    // Twilio's ~15s webhook timeout when the engine takes longer.
+    state.lock = state.lock.then(
+      async () => {
+        try {
+          const { result } = await state.engine.send(body);
+          const reply = result.trim() || "(no response)";
+          await this.sendTo(from, reply);
+        } catch (err) {
+          log.error({ err, from }, "sms: engine error");
+          await this.sendTo(from, `[error] ${err instanceof Error ? err.message : String(err)}`).catch(() => {});
+        }
+      },
+      (err) => log.error({ err, from }, "sms: lock chain error"),
+    );
+
+    return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
+  }
+
+  private handleStatus(params: Record<string, string>): Response {
+    log.info(
+      {
+        messageSid: params.MessageSid,
+        status: params.MessageStatus,
+        errorCode: params.ErrorCode,
+        to: params.To,
+      },
+      "sms: delivery status",
+    );
+    return new Response("", { status: 204 });
+  }
+
+  // --- Outbound ---
+
+  private async sendTo(remoteE164: string, body: string): Promise<void> {
+    if (!this.twilio.sid || !this.twilio.secret) {
+      log.warn("sms: twilio sid/secret missing, cannot send");
+      return;
+    }
+    try {
+      const res = await twilioSendMessage({
+        accountSid: this.twilio.sid,
+        authSid: this.twilio.sid,
+        authSecret: this.twilio.secret,
+        to: remoteE164,
+        from: this.fromNumber,
+        body,
+        statusCallbackUrl: this.twilio.public_base_url ? `${this.twilio.public_base_url}/twilio/sms/status` : undefined,
+      });
+      log.info({ to: remoteE164, sid: res.messageSid, status: res.status }, "sms: sent");
+    } catch (err) {
+      log.error({ err, to: remoteE164 }, "sms: send failed");
+    }
+  }
+
+  // --- Helpers ---
+
+  private isAllowed(remoteE164: string): boolean {
+    if (this.twilio.owner_number && remoteE164 === this.twilio.owner_number) return true;
+    return this.twilio.allowlist.includes(remoteE164);
+  }
+
+  private async getState(remoteE164: string): Promise<ChatState> {
+    let state = this.chats.get(remoteE164);
+    if (state) return state;
+    const prefix = `sms-${remoteE164}`;
+    const idx = await Session.getLatestRoomIndex(prefix);
+    const room = `${prefix}-${idx}`;
+    log.info({ remoteE164, room }, "sms: creating chat engine");
+    const engine = await createChatEngine({
+      room,
+      channel: "sms",
+      resume: true,
+      mcpServers: getMcpServers(),
+    });
+    state = { engine, roomIndex: idx, lock: Promise.resolve() };
+    this.chats.set(remoteE164, state);
+    return state;
+  }
+}
+
+export function createSmsChannel(): SmsChannel | null {
+  const { twilio, sms, phone } = getConfig().channels;
+  if (!sms.enabled) return null;
+  if (!twilio.sid || !twilio.secret) return null;
+  // sms.from_number falls back to phone.from_number (same number for voice + SMS).
+  const fromNumber = sms.from_number ?? phone.from_number;
+  if (!fromNumber) return null;
+  return new SmsChannel(twilio, sms, fromNumber);
+}
+
+export type { SmsChannel };

package/src/channels/twilio/dedup.ts

@@ -0,0 +1,36 @@
+/**
+ * Time-bounded set for deduplicating webhook deliveries.
+ *
+ * Twilio retries webhooks on 5xx/timeouts, so the same MessageSid /
+ * CallSid can arrive multiple times. We track recently-seen IDs and
+ * drop duplicates, expiring entries after `ttlMs`.
+ */
+export class Dedup {
+  private readonly seen = new Map<string, number>();
+
+  constructor(
+    private readonly ttlMs: number = 10 * 60 * 1000,
+    private readonly maxEntries: number = 5000,
+  ) {}
+
+  /** Returns true if this id was already seen recently; false (and records it) otherwise. */
+  check(id: string): boolean {
+    const now = Date.now();
+    const cutoff = now - this.ttlMs;
+    const seenAt = this.seen.get(id);
+    if (seenAt !== undefined && seenAt > cutoff) return true;
+    this.seen.set(id, now);
+    if (this.seen.size > this.maxEntries) this.prune(cutoff);
+    return false;
+  }
+
+  private prune(cutoff: number): void {
+    for (const [k, v] of this.seen) {
+      if (v <= cutoff) this.seen.delete(k);
+    }
+  }
+
+  size(): number {
+    return this.seen.size;
+  }
+}