@vellumai/vellum-gateway 0.3.3 → 0.3.5

package/README.md

@@ -138,7 +138,7 @@ These fields are forwarded to the runtime in the `/channels/inbound` payload alo
 
 **Normalization constraints:** Only DM-only (`private` chat type) callback queries are processed. Group and channel callbacks are dropped and acknowledged with `answerCallbackQuery` so the Telegram button spinner clears. Callback queries with no `data` field or no associated `message` are also dropped.
 
-**Stale callback blocking:** When the runtime receives `callbackData` that does not match any pending approval (e.g., a button from an old prompt), it returns `stale_ignored` and does not process the payload as a regular message. This is enforced regardless of whether the callback has non-empty content. The gateway acknowledges all callback queries via `answerCallbackQuery` to clear the button spinner.
+**Stale callback blocking:** When the runtime receives `callbackData` that does not match any pending approval (e.g., a button from an old prompt), it returns `stale_ignored` and does not process the payload as a regular message. This is enforced regardless of whether the callback has non-empty content. The gateway sends a best-effort `answerCallbackQuery` acknowledgment for normalized callback updates (including stale, rejected, and forward-failure paths) so the button spinner clears promptly. Transient forwarding failures may still return `500` so Telegram retries update delivery.
 
 ## Approval Buttons and Inline Keyboard
 
@@ -370,7 +370,7 @@ See [`benchmarking/gateway/README.md`](../benchmarking/gateway/README.md) for lo
 | Symptom | Cause | Resolution |
 |---------|-------|------------|
 | `/guardian_verify` command gets no reply | The verification message did not reach the runtime, or the challenge expired | Ensure the gateway is running, the bot token is valid, and the Telegram webhook is registered. Challenges expire after 10 minutes -- generate a new one via the desktop UI. |
-| Non-guardian actions auto-denied with "no guardian configured" | No guardian binding exists for the channel and `CHANNEL_APPROVALS_ENABLED=true` on the runtime. The system is fail-closed when guardian enforcement is active. | Set up a guardian by running the verification flow from the desktop UI, and ensure `CHANNEL_APPROVALS_ENABLED=true` is set on the runtime. |
+| Non-guardian actions auto-denied with "no guardian configured" | No guardian binding exists for the channel. The runtime is fail-closed for unverified channels. | Set up a guardian by running the verification flow from the desktop UI. |
 | Approval prompt not delivered to guardian | The `replyCallbackUrl` may be unreachable, or the guardian's chat ID is stale | Verify `GATEWAY_INTERNAL_BASE_URL` is set correctly (especially in containerized deployments). Re-verify the guardian if the chat ID has changed. |
 | Guardian approval expired | The 30-minute TTL elapsed without a decision. A proactive sweep (every 60s) auto-denied the approval and notified both the requester and guardian. | The non-guardian user must re-trigger the action. |
 | "Only the verified guardian can approve or deny" | A non-guardian sender attempted to respond to a guardian approval prompt | Only the guardian whose `externalUserId` matches the approval request can approve or deny. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",

package/src/__tests__/config.test.ts

@@ -1,5 +1,7 @@
-import { writeFileSync, unlinkSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, unlinkSync } from "node:fs";
 import { describe, test, expect } from "bun:test";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { loadConfig } from "../config.js";
 
 const BASE_ENV = {
@@ -31,6 +33,7 @@ function withEnv(overrides: Record<string, string | undefined>, fn: () => void)
     "GATEWAY_MAX_ATTACHMENT_CONCURRENCY",
     "GATEWAY_TELEGRAM_DELIVER_AUTH_BYPASS",
     "VELLUM_HTTP_TOKEN_PATH",
+    "BASE_DATA_DIR",
   ];
 
   for (const key of allKeys) {
@@ -259,3 +262,35 @@ describe("config: runtime bearer token", () => {
     );
   });
 });
+
+describe("config: twilio assistant phone number mapping", () => {
+  test("loads assistantPhoneNumbers from workspace config on startup", () => {
+    const testBaseDir = mkdtempSync(join(tmpdir(), "gateway-config-test-"));
+    try {
+      const workspaceDir = join(testBaseDir, ".vellum", "workspace");
+      mkdirSync(workspaceDir, { recursive: true });
+      writeFileSync(
+        join(workspaceDir, "config.json"),
+        JSON.stringify({
+          sms: {
+            phoneNumber: "+15550001111",
+            assistantPhoneNumbers: {
+              "asst-alpha": "+15550002222",
+              "asst-beta": "+15550003333",
+            },
+          },
+        }),
+      );
+
+      withEnv({ BASE_DATA_DIR: testBaseDir }, () => {
+        const config = loadConfig();
+        expect(config.assistantPhoneNumbers).toEqual({
+          "asst-alpha": "+15550002222",
+          "asst-beta": "+15550003333",
+        });
+      });
+    } finally {
+      rmSync(testBaseDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/credential-reader.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach, mock, spyOn } from "bun:test";
+import { describe, test, expect, beforeEach, afterEach, mock } from "bun:test";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -35,10 +35,7 @@ mock.module("node:child_process", () => {
 
 import {
   readTelegramCredentials,
-  readCredential,
   readKeychainCredential,
-  getMetadataPath,
-  getRootDir,
 } from "../credential-reader.js";
 
 // ---------------------------------------------------------------------------

package/src/__tests__/dedup-cache.test.ts

@@ -62,21 +62,48 @@ describe("DedupCache", () => {
     expect(cache.size).toBe(2);
   });
 
-  test("reserve returns true for unseen update_id and creates processing entry", () => {
-    expect(cache.reserve(50)).toBe(true);
+  test("reserve returns 'reserved' for unseen update_id and creates processing entry", () => {
+    expect(cache.reserve(50)).toBe("reserved");
     expect(cache.size).toBe(1);
     // get() returns undefined for processing entries (not yet finalized)
     expect(cache.get(50)).toBeUndefined();
   });
 
-  test("reserve returns false for already-reserved update_id", () => {
+  test("reserve returns 'duplicate' for already-reserved update_id", () => {
     cache.reserve(60);
-    expect(cache.reserve(60)).toBe(false);
+    expect(cache.reserve(60)).toBe("duplicate");
   });
 
-  test("reserve returns false for already-cached update_id", () => {
+  test("reserve returns 'duplicate' for already-cached update_id still in cache", () => {
+    // set() advances the high-water mark, but the cache entry is checked
+    // first — since it's still within TTL, reserve() returns "duplicate"
     cache.set(70, '{"done":true}', 200);
-    expect(cache.reserve(70)).toBe(false);
+    expect(cache.reserve(70)).toBe("duplicate");
+  });
+
+  test("reserve returns 'already_processed' for finalized update_id after TTL expires", () => {
+    const shortCache = new DedupCache(1, 100);
+    shortCache.set(70, '{"done":true}', 200);
+
+    // Wait for the TTL entry to expire
+    const start = Date.now();
+    while (Date.now() - start < 5) {
+      // busy-wait
+    }
+
+    // Cache entry expired, but high-water mark still blocks replay
+    expect(shortCache.reserve(70)).toBe("already_processed");
+  });
+
+  test("reserve returns 'duplicate' for in-cache entry above high-water mark", () => {
+    // reserve() without set() doesn't advance the high-water mark,
+    // so a second reserve() for the same ID returns "duplicate"
+    cache.reserve(71);
+    cache.set(71, '{"done":true}', 200);
+    // Now reserve a higher ID (which won't be finalized)
+    cache.reserve(72);
+    // 72 is above high-water mark (71) but already in cache
+    expect(cache.reserve(72)).toBe("duplicate");
   });
 
   test("get returns undefined while entry is still processing", () => {
@@ -99,12 +126,12 @@ describe("DedupCache", () => {
 
   test("unreserve allows re-reservation after processing failure", () => {
     cache.reserve(85);
-    expect(cache.reserve(85)).toBe(false);
+    expect(cache.reserve(85)).toBe("duplicate");
     // Simulate processing failure — unreserve so Telegram can retry
     cache.unreserve(85);
     expect(cache.size).toBe(0);
     // Now re-reserve should succeed
-    expect(cache.reserve(85)).toBe(true);
+    expect(cache.reserve(85)).toBe("reserved");
   });
 
   test("unreserve does not remove finalized entries", () => {
@@ -123,7 +150,65 @@ describe("DedupCache", () => {
       // busy-wait for expiry
     }
 
-    expect(shortCache.reserve(90)).toBe(true);
+    expect(shortCache.reserve(90)).toBe("reserved");
+  });
+
+  test("high-water mark rejects update_ids at or below the max finalized", () => {
+    cache.reserve(100);
+    cache.set(100, '{"ok":true}', 200);
+
+    // update_id below the high-water mark is permanently rejected
+    expect(cache.reserve(99)).toBe("already_processed");
+    // same update_id is still in cache — returns "duplicate" (cache checked first)
+    expect(cache.reserve(100)).toBe("duplicate");
+    // update_id above the high-water mark is accepted
+    expect(cache.reserve(101)).toBe("reserved");
+  });
+
+  test("high-water mark persists after cache TTL expires", () => {
+    const shortCache = new DedupCache(1, 100);
+    shortCache.reserve(50);
+    shortCache.set(50, '{"ok":true}', 200);
+
+    // Wait for the TTL entry to expire
+    const start = Date.now();
+    while (Date.now() - start < 5) {
+      // busy-wait
+    }
+
+    // TTL entry is gone, but high-water mark still blocks replay
+    expect(shortCache.get(50)).toBeUndefined();
+    expect(shortCache.reserve(50)).toBe("already_processed");
+    expect(shortCache.reserve(49)).toBe("already_processed");
+    // Higher ID still works
+    expect(shortCache.reserve(51)).toBe("reserved");
+  });
+
+  test("high-water mark advances to the max across non-sequential sets", () => {
+    cache.set(200, "a", 200);
+    cache.set(100, "b", 200);
+    cache.set(150, "c", 200);
+
+    // High-water mark should be 200 (the max), not 150 (the last set)
+    expect(cache.reserve(199)).toBe("already_processed");
+    // 200 is still in the cache — returns "duplicate" (cache checked first)
+    expect(cache.reserve(200)).toBe("duplicate");
+    expect(cache.reserve(201)).toBe("reserved");
+  });
+
+  test("in-flight entry returns 'duplicate' even when high-water mark has advanced past it", () => {
+    // Simulate concurrent processing: reserve 101, then 102 finalizes first
+    cache.reserve(101);
+    cache.reserve(102);
+    cache.set(102, '{"ok":true}', 200); // advances high-water mark to 102
+
+    // 101 is still in-flight (reserved but not finalized). A retry for 101
+    // should return "duplicate" (not "already_processed") so the caller
+    // returns 503 and Telegram retries, rather than returning 200 which
+    // would suppress retries if the original 101 handler fails.
+    expect(cache.reserve(101)).toBe("duplicate");
+    // get() still returns undefined because 101 is in processing state
+    expect(cache.get(101)).toBeUndefined();
   });
 });
 

package/src/config.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { getLogger, type LogFileConfig } from "./logger.js";
+import { getRootDir, readKeychainCredential, readCredential, readTwilioCredentials } from "./credential-reader.js";
 
 const log = getLogger("config");
 
@@ -247,9 +248,40 @@ export function loadConfig(): GatewayConfig {
     );
   }
 
-  const twilioAuthToken = process.env.TWILIO_AUTH_TOKEN || undefined;
-  const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID || undefined;
-  const twilioPhoneNumber = process.env.TWILIO_PHONE_NUMBER || undefined;
+  // Twilio credentials: env var > credential store (keychain / encrypted file)
+  const twilioCreds = readTwilioCredentials();
+  const twilioAuthToken = process.env.TWILIO_AUTH_TOKEN || twilioCreds?.authToken || undefined;
+  const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID || twilioCreds?.accountSid || undefined;
+
+  // Phone number: env var > config file sms.phoneNumber > credential store
+  let twilioPhoneNumber: string | undefined = process.env.TWILIO_PHONE_NUMBER || undefined;
+  let assistantPhoneNumbers: Record<string, string> | undefined;
+  try {
+    const cfgPath = join(getRootDir(), "workspace", "config.json");
+    const raw = readFileSync(cfgPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (!twilioPhoneNumber && data?.sms?.phoneNumber && typeof data.sms.phoneNumber === "string") {
+      twilioPhoneNumber = data.sms.phoneNumber;
+    }
+    const rawMapping = data?.sms?.assistantPhoneNumbers;
+    if (rawMapping && typeof rawMapping === "object" && !Array.isArray(rawMapping)) {
+      const normalized: Record<string, string> = {};
+      for (const [assistantId, phoneNumber] of Object.entries(rawMapping as Record<string, unknown>)) {
+        if (typeof phoneNumber === "string" && phoneNumber.trim().length > 0) {
+          normalized[assistantId] = phoneNumber;
+        }
+      }
+      assistantPhoneNumbers = normalized;
+    }
+  } catch {
+    // config file may not exist yet
+  }
+  if (!twilioPhoneNumber) {
+    twilioPhoneNumber =
+      readKeychainCredential("credential:twilio:phone_number")
+      || readCredential("credential:twilio:phone_number")
+      || undefined;
+  }
 
   const smsDeliverAuthBypassRaw = process.env.GATEWAY_SMS_DELIVER_AUTH_BYPASS;
   if (
@@ -292,6 +324,7 @@ export function loadConfig(): GatewayConfig {
       hasTwilioAuthToken: !!twilioAuthToken,
       hasTwilioAccountSid: !!twilioAccountSid,
       hasTwilioPhoneNumber: !!twilioPhoneNumber,
+      assistantPhoneNumberCount: assistantPhoneNumbers ? Object.keys(assistantPhoneNumbers).length : 0,
       smsDeliverAuthBypass,
       ingressPublicBaseUrl,
     },
@@ -327,6 +360,7 @@ export function loadConfig(): GatewayConfig {
     twilioAuthToken,
     twilioAccountSid,
     twilioPhoneNumber,
+    assistantPhoneNumbers,
     smsDeliverAuthBypass,
     ingressPublicBaseUrl,
     unmappedPolicy,

package/src/dedup-cache.ts

@@ -2,6 +2,8 @@ import { getLogger } from "./logger.js";
 
 const log = getLogger("dedup-cache");
 
+export type ReserveResult = "reserved" | "duplicate" | "already_processed";
+
 interface CacheEntry {
   body: string;
   status: number;
@@ -19,6 +21,14 @@ export class DedupCache {
   private cache = new Map<number, CacheEntry>();
   private readonly ttlMs: number;
   private readonly maxSize: number;
+  /**
+   * Monotonic high-water mark: the highest update_id that has been fully
+   * processed (finalized via set()). Any update_id at or below this value
+   * is rejected permanently, even after the TTL cache evicts the entry.
+   * This closes the replay window that existed when entries expired from
+   * the TTL cache.
+   */
+  private highWaterMark = -Infinity;
 
   constructor(ttlMs = 5 * 60_000, maxSize = 10_000) {
     this.ttlMs = ttlMs;
@@ -45,21 +55,33 @@ export class DedupCache {
    * Checks whether this update_id is already reserved or cached.
    * If not, immediately reserves it with a "processing" sentinel so that
    * concurrent retries are blocked before the handler finishes.
-   * Returns true if a new reservation was created (caller should proceed),
-   * false if the update_id was already present (caller should short-circuit).
    *
-   * While the entry is in the "processing" state, {@link get} returns
-   * `undefined` so callers can distinguish an in-flight request from a
-   * finalized cache hit and respond accordingly (e.g. 503 Retry-After).
+   * Returns:
+   * - `'reserved'` — new reservation created, caller should proceed
+   * - `'duplicate'` — update_id is already in the cache (in-flight or finalized)
+   * - `'already_processed'` — update_id is at or below the high-water mark
+   *   (fully processed, TTL entry may have expired)
    */
-  reserve(updateId: number): boolean {
+  reserve(updateId: number): ReserveResult {
+    // Check existing cache entries FIRST — an active (non-expired) entry
+    // takes priority over the high-water mark. This prevents a race where
+    // a higher update_id finalizes first (advancing the high-water mark)
+    // while a lower update_id is still in-flight: without this ordering,
+    // the in-flight entry would be reported as "already_processed" instead
+    // of "duplicate", causing the caller to return 200 and suppress retries.
     const existing = this.cache.get(updateId);
     if (existing && Date.now() <= existing.expiresAt) {
-      return false;
+      return "duplicate";
     }
     // Clean up expired entry if present
     if (existing) this.cache.delete(updateId);
 
+    // Reject any update_id at or below the high-water mark — these have
+    // already been fully processed and are replay attempts.
+    if (updateId <= this.highWaterMark) {
+      return "already_processed";
+    }
+
     // Evict if at capacity
     if (this.cache.size >= this.maxSize) {
       this.evictExpired();
@@ -77,7 +99,7 @@ export class DedupCache {
       expiresAt: Date.now() + this.ttlMs,
       processing: true,
     });
-    return true;
+    return "reserved";
   }
 
   /** Remove a reserved entry so Telegram can retry. */
@@ -88,8 +110,14 @@ export class DedupCache {
     }
   }
 
-  /** Store a response for the given update_id. */
+  /** Store a response for the given update_id and advance the high-water mark. */
   set(updateId: number, body: string, status: number): void {
+    // Advance monotonic high-water mark so this update_id (and all lower
+    // ones) are permanently rejected even after the TTL cache evicts them.
+    if (updateId > this.highWaterMark) {
+      this.highWaterMark = updateId;
+    }
+
     // Evict expired entries if we're at capacity
     if (this.cache.size >= this.maxSize) {
       this.evictExpired();

package/src/http/routes/runtime-proxy.ts

@@ -118,14 +118,21 @@ export function createRuntimeProxyHandler(config: GatewayConfig) {
       controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
     }, config.runtimeTimeoutMs);
 
+    // Buffer the request body instead of streaming req.body to avoid
+    // Content-Length mismatches when Bun re-sends a ReadableStream, which
+    // can cause the upstream to reject the request with a bare 400.
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : null;
+    if (bodyBuffer !== null) {
+      reqHeaders.set("content-length", String(bodyBuffer.byteLength));
+    }
+
     let response: Response;
     try {
       response = await fetch(upstream, {
         method: req.method,
         headers: reqHeaders,
-        body: req.body,
-        // @ts-expect-error Bun supports duplex on Request
-        duplex: "half",
+        body: bodyBuffer,
         signal: controller.signal,
       });
       clearTimeout(timeoutId);

package/src/http/routes/sms-deliver.test.ts

@@ -64,9 +64,9 @@ afterEach(() => {
   globalThis.fetch = originalFetch;
 });
 
-function mockTwilioApi() {
+function mockTwilioApi(overrides?: Record<string, unknown>) {
   globalThis.fetch = mock(async () => {
-    return new Response(JSON.stringify({ sid: "SM-sent" }), {
+    return new Response(JSON.stringify({ sid: "SM-sent", status: "queued", error_code: null, error_message: null, ...overrides }), {
       status: 201,
       headers: { "content-type": "application/json" },
     });
@@ -271,4 +271,156 @@ describe("/deliver/sms", () => {
     expect(sentParams.get("To")).toBe("+15559876543");
     expect(sentParams.get("Body")).toBe("Test SMS body");
   });
+
+  it("uses assistant-specific From number when assistantId mapping exists", async () => {
+    const fetchCalls: Array<{ url: string; init: RequestInit }> = [];
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr, init: init ?? {} });
+      return new Response(JSON.stringify({ sid: "SM-sent" }), {
+        status: 201,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const handler = createSmsDeliverHandler(
+      makeConfig({
+        runtimeProxyBearerToken: undefined,
+        smsDeliverAuthBypass: true,
+        assistantPhoneNumbers: { "ast-alpha": "+15550001111" },
+      }),
+    );
+    const req = makeRequest({
+      to: "+15559876543",
+      text: "assistant scoped",
+      assistantId: "ast-alpha",
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    expect(fetchCalls).toHaveLength(1);
+    const sentBody = fetchCalls[0].init.body as string;
+    const sentParams = new URLSearchParams(sentBody);
+    expect(sentParams.get("From")).toBe("+15550001111");
+  });
+
+  it("falls back to global From number when assistant mapping is missing", async () => {
+    const fetchCalls: Array<{ url: string; init: RequestInit }> = [];
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr, init: init ?? {} });
+      return new Response(JSON.stringify({ sid: "SM-sent" }), {
+        status: 201,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const handler = createSmsDeliverHandler(
+      makeConfig({
+        runtimeProxyBearerToken: undefined,
+        smsDeliverAuthBypass: true,
+        assistantPhoneNumbers: { "ast-beta": "+15550002222" },
+      }),
+    );
+    const req = makeRequest({
+      to: "+15559876543",
+      text: "fallback",
+      assistantId: "ast-alpha",
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    expect(fetchCalls).toHaveLength(1);
+    const sentBody = fetchCalls[0].init.body as string;
+    const sentParams = new URLSearchParams(sentBody);
+    expect(sentParams.get("From")).toBe("+15551234567");
+  });
+
+  it("attachment-only request (no text) uses fallback text", async () => {
+    const fetchCalls: Array<{ url: string; init: RequestInit }> = [];
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr, init: init ?? {} });
+      return new Response(JSON.stringify({ sid: "SM-sent" }), {
+        status: 201,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const handler = createSmsDeliverHandler(
+      makeConfig({ runtimeProxyBearerToken: undefined, smsDeliverAuthBypass: true }),
+    );
+    const req = makeRequest({
+      to: "+15559876543",
+      attachments: [{ url: "https://example.com/image.png" }],
+    });
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+
+    // Verify the Twilio Messages API was called
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toContain("AC-test-sid/Messages.json");
+
+    // Verify the Body parameter contains the fallback text
+    const sentBody = fetchCalls[0].init.body as string;
+    const sentParams = new URLSearchParams(sentBody);
+    expect(sentParams.get("Body")).toBe(
+      "I have a media attachment to share, but SMS currently supports text only.",
+    );
+  });
+
+  it("returns enriched Twilio acceptance details in response", async () => {
+    mockTwilioApi({ sid: "SM-enrich-test", status: "queued", error_code: null, error_message: null });
+    const handler = createSmsDeliverHandler(
+      makeConfig({ runtimeProxyBearerToken: undefined, smsDeliverAuthBypass: true }),
+    );
+    const req = makeRequest({ to: "+15559876543", text: "enriched" });
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+    expect(body.messageSid).toBe("SM-enrich-test");
+    expect(body.status).toBe("queued");
+    expect(body.errorCode).toBeNull();
+    expect(body.errorMessage).toBeNull();
+  });
+
+  it("returns Twilio error details in response when error_code is present", async () => {
+    mockTwilioApi({ sid: "SM-err-test", status: "failed", error_code: 30003, error_message: "Unreachable" });
+    const handler = createSmsDeliverHandler(
+      makeConfig({ runtimeProxyBearerToken: undefined, smsDeliverAuthBypass: true }),
+    );
+    const req = makeRequest({ to: "+15559876543", text: "fail test" });
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+    expect(body.messageSid).toBe("SM-err-test");
+    expect(body.status).toBe("failed");
+    expect(body.errorCode).toBe("30003");
+    expect(body.errorMessage).toBe("Unreachable");
+  });
+
+  it("returns 503 when no From number is available", async () => {
+    const handler = createSmsDeliverHandler(
+      makeConfig({
+        runtimeProxyBearerToken: undefined,
+        smsDeliverAuthBypass: true,
+        twilioPhoneNumber: undefined,
+        assistantPhoneNumbers: undefined,
+      }),
+    );
+    const req = makeRequest({
+      to: "+15559876543",
+      text: "no from",
+      assistantId: "ast-alpha",
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(503);
+    const body = await res.json();
+    expect(body.error).toBe("SMS integration not configured");
+  });
 });