@vellumai/assistant 0.7.1 → 0.7.2

package/docs/plugins.md

@@ -66,7 +66,7 @@ skill can omit middleware entirely.
 
 ## Where plugins live
 
-The assistant scans `~/.vellum/plugins/*` at startup. Any subdirectory
+The assistant scans `<workspaceDir>/plugins/*` at startup. Any subdirectory
 containing `register.js` or `register.ts` is dynamic-imported once. The
 loader lives in
 [`assistant/src/plugins/user-loader.ts`](../src/plugins/user-loader.ts) and
@@ -78,9 +78,8 @@ has three key properties:
 - **Per-plugin isolation.** If one plugin throws at import time, the error
   is logged with the plugin directory and the loader moves on. Other
   plugins still load. One broken plugin cannot brick the assistant.
-- **Per-instance.** The scan runs under `vellumRoot()`, which honors the
-  multi-instance `BASE_DATA_DIR` override. Each assistant instance loads
-  its own plugin set.
+- **Per-instance.** The scan runs under `vellumRoot()`. Each assistant
+  instance loads its own plugin set.
 
 The loader runs after first-party plugin registrations and before
 `bootstrapPlugins()` invokes every plugin's `init()`.
@@ -105,7 +104,7 @@ export interface PluginManifest {
 
 | Field                | Required | Purpose                                                                                                                                                                                                                                                                                                        |
 | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`               | yes      | Unique plugin identifier. Duplicate names fail registration. Used as the directory under `~/.vellum/plugins-data/<name>/` and the attribution tag in logs.                                                                                                                                                     |
+| `name`               | yes      | Unique plugin identifier. Duplicate names fail registration. Used as the directory under `<workspaceDir>/plugins-data/<name>/` and the attribution tag in logs.                                                                                                                                                     |
 | `version`            | yes      | Plugin's own semver. Informational — the registry does not compare it.                                                                                                                                                                                                                                         |
 | `provides`           | no       | Reserved for future cross-plugin composition and not currently consumed by the assistant. Plugin authors may set this field, but no runtime code reads it yet — it is declared here so future cross-plugin work can land without a manifest version bump. Do not rely on it for any runtime behavior today.    |
 | `requires`           | yes      | Must include `pluginRuntime: "v1"` at minimum. The registry checks every entry against `ASSISTANT_API_VERSIONS` and refuses to register plugins that ask for a capability or version the assistant does not expose.                                                                                            |
@@ -487,7 +486,7 @@ export interface PluginInitContext {
   config: unknown; // parsed config (or raw if no validator)
   credentials: Record<string, string>; // resolved credentials from requiresCredential
   logger: unknown; // pino child logger, tagged { plugin: <name> }
-  pluginStorageDir: string; // ~/.vellum/plugins-data/<name>/ (created by bootstrap)
+  pluginStorageDir: string; // <workspaceDir>/plugins-data/<name>/ (created by bootstrap)
   assistantVersion: string; // assistant semver
   apiVersions: Record<string, string[]>; // ASSISTANT_API_VERSIONS, for runtime checks
 }
@@ -657,7 +656,7 @@ The registry's internal state is not mutable at runtime. `init()` and
 `onShutdown()` hooks are fired exactly once per assistant boot.
 
 If you need hot reload for development, symlink your plugin directory
-into `~/.vellum/plugins/` so edits propagate, and automate the restart
+into `<workspaceDir>/plugins/` so edits propagate, and automate the restart
 loop externally.
 
 ## Troubleshooting
@@ -748,8 +747,7 @@ tail -f ~/.vellum/daemon.log \
 
 ### Plugin not loading at all
 
-- Confirm the directory is under `~/.vellum/plugins/` (or the per-instance
-  equivalent under `$BASE_DATA_DIR/.vellum/plugins/`).
+- Confirm the directory is under `<workspaceDir>/plugins/`.
 - Confirm it has a `register.ts` or `register.js` at the top level.
 - Check the assistant's stderr for a line like
   `loaded user plugin (side-effect import completed)` or

package/knip.json

@@ -13,6 +13,7 @@
     "@vellumai/gateway-client",
     "@vellumai/service-contracts",
     "@vellumai/slack-text",
+    "@vellumai/twilio-client",
     "@resvg/resvg-js-darwin-arm64",
     "@resvg/resvg-js-darwin-x64",
     "@vellumai/skill-host-contracts",

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -17,6 +17,7 @@ export {
 
 export {
   ipcCall,
+  IpcCallError,
   PersistentIpcClient,
 } from "./ipc-client.js";
 

package/node_modules/@vellumai/gateway-client/src/ipc-client.ts

@@ -13,6 +13,38 @@ import { connect, type Socket } from "node:net";
 import type { IpcRequest, IpcResponse, Logger } from "./types.js";
 import { noopLogger } from "./types.js";
 
+// ---------------------------------------------------------------------------
+// Error surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Error class thrown by `PersistentIpcClient.call` when the daemon returns
+ * a structured error envelope (i.e. `RouteError`-derived). Mirrors the HTTP
+ * adapter's `error.details` shape so IPC callers can branch on `errorCode`
+ * or recover machine-readable `errorDetails` (e.g. `version_incompatible`).
+ */
+export class IpcCallError extends Error {
+  readonly statusCode?: number;
+  readonly errorCode?: string;
+  readonly errorDetails?: unknown;
+
+  constructor(
+    message: string,
+    fields: {
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    } = {},
+  ) {
+    super(message);
+    this.name = "IpcCallError";
+    if (fields.statusCode !== undefined) this.statusCode = fields.statusCode;
+    if (fields.errorCode !== undefined) this.errorCode = fields.errorCode;
+    if (fields.errorDetails !== undefined)
+      this.errorDetails = fields.errorDetails;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -294,7 +326,13 @@ export class PersistentIpcClient {
             this.pending.delete(msg.id);
             clearTimeout(entry.timer);
             if (msg.error) {
-              entry.reject(new Error(msg.error));
+              entry.reject(
+                new IpcCallError(msg.error, {
+                  statusCode: msg.statusCode,
+                  errorCode: msg.errorCode,
+                  errorDetails: msg.errorDetails,
+                }),
+              );
             } else {
               entry.resolve(msg.result);
             }

package/node_modules/@vellumai/gateway-client/src/types.ts

@@ -105,6 +105,17 @@ export interface IpcResponse {
   id: string;
   result?: unknown;
   error?: string;
+  /** HTTP-style status code mirrored from `RouteError.statusCode`. */
+  statusCode?: number;
+  /** Machine-readable error code (e.g. "UNPROCESSABLE_ENTITY"). */
+  errorCode?: string;
+  /**
+   * Structured error payload mirroring `RouteError.details` — present only
+   * when the originating error carried a `details` field. Mirrors the HTTP
+   * adapter's `error.details` envelope so IPC clients can recover the same
+   * machine-readable context as HTTP clients.
+   */
+  errorDetails?: unknown;
 }
 
 // ---------------------------------------------------------------------------

package/node_modules/@vellumai/service-contracts/package.json

@@ -7,6 +7,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
+    "./ingress": "./src/ingress.ts",
+    "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",
     "./handles": "./src/handles.ts",
     "./grants": "./src/grants.ts",

package/node_modules/@vellumai/service-contracts/src/__tests__/contracts.test.ts

@@ -33,6 +33,8 @@ describe("package independence", () => {
     "../transport.ts",
     "../credential-rpc.ts",
     "../trust-rules.ts",
+    "../ingress.ts",
+    "../twilio-ingress.ts",
     "../error.ts",
   ];
 
@@ -219,6 +221,7 @@ describe("ToolResponseBaseSchema", () => {
       result: { html: "<html></html>" },
     });
     expect(result.success).toBe(true);
+    if (!result.success) throw new Error("Expected successful response");
     expect(result.result).toEqual({ html: "<html></html>" });
   });
 
@@ -238,6 +241,7 @@ describe("ToolResponseBaseSchema", () => {
       },
     });
     expect(result.success).toBe(false);
+    if (result.success) throw new Error("Expected failed response");
     expect(result.error.code).toBe("TOOL_FAILED");
   });
 

package/node_modules/@vellumai/service-contracts/src/__tests__/ingress.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  normalizeHttpPublicBaseUrl,
+  normalizePublicBaseUrl,
+} from "../ingress.js";
+import {
+  buildTwilioConnectActionUrl,
+  buildTwilioMediaStreamUrl,
+  buildTwilioPhoneNumberWebhookUrls,
+  buildTwilioRelayUrl,
+  buildTwilioVoiceWebhookUrl,
+  resolveTwilioPublicBaseUrl,
+} from "../twilio-ingress.js";
+
+describe("normalizePublicBaseUrl", () => {
+  test("trims whitespace and trailing slashes", () => {
+    expect(normalizePublicBaseUrl(" https://example.test/path/// ")).toBe(
+      "https://example.test/path",
+    );
+  });
+
+  test("rejects non-string and empty values", () => {
+    expect(normalizePublicBaseUrl(undefined)).toBeUndefined();
+    expect(normalizePublicBaseUrl("   ")).toBeUndefined();
+  });
+});
+
+describe("normalizeHttpPublicBaseUrl", () => {
+  test("normalizes valid HTTP and HTTPS URLs", () => {
+    expect(normalizeHttpPublicBaseUrl(" HTTPS://EXAMPLE.TEST/twilio ")).toBe(
+      "https://example.test/twilio",
+    );
+    expect(normalizeHttpPublicBaseUrl("https://example.test/twilio///")).toBe(
+      "https://example.test/twilio",
+    );
+    expect(normalizeHttpPublicBaseUrl("https://example.test")).toBe(
+      "https://example.test/",
+    );
+  });
+
+  test("rejects non-HTTP URLs and malformed values", () => {
+    expect(normalizeHttpPublicBaseUrl("ftp://example.test")).toBeUndefined();
+    expect(normalizeHttpPublicBaseUrl("notaurl")).toBeUndefined();
+    expect(normalizeHttpPublicBaseUrl("")).toBeUndefined();
+  });
+
+  test("rejects query strings and fragments instead of mutating them", () => {
+    expect(
+      normalizeHttpPublicBaseUrl("https://example.test/twilio?token=abc/"),
+    ).toBeUndefined();
+    expect(
+      normalizeHttpPublicBaseUrl("https://example.test/twilio#section/"),
+    ).toBeUndefined();
+    expect(
+      normalizeHttpPublicBaseUrl("https://example.test/twilio?"),
+    ).toBeUndefined();
+    expect(
+      normalizeHttpPublicBaseUrl("https://example.test/twilio#"),
+    ).toBeUndefined();
+  });
+});
+
+describe("Twilio ingress helpers", () => {
+  test("resolves public base URL with fallback", () => {
+    expect(
+      resolveTwilioPublicBaseUrl({
+        publicBaseUrl: " https://twilio.example.test/twilio/ ",
+      }),
+    ).toBe("https://twilio.example.test/twilio");
+    expect(
+      resolveTwilioPublicBaseUrl({
+        publicBaseUrl: " ",
+      }),
+    ).toBeUndefined();
+    expect(
+      resolveTwilioPublicBaseUrl({
+        publicBaseUrl: " ",
+      }, "https://fallback.example.test/"),
+    ).toBe("https://fallback.example.test");
+    expect(
+      resolveTwilioPublicBaseUrl({}, "https://fallback.example.test/"),
+    ).toBe("https://fallback.example.test");
+  });
+
+  test("builds Twilio webhook and WebSocket URLs from one base URL", () => {
+    expect(buildTwilioVoiceWebhookUrl("https://example.test")).toBe(
+      "https://example.test/webhooks/twilio/voice",
+    );
+    expect(buildTwilioVoiceWebhookUrl("https://example.test", "call-123")).toBe(
+      "https://example.test/webhooks/twilio/voice?callSessionId=call-123",
+    );
+    expect(buildTwilioConnectActionUrl("https://example.test")).toBe(
+      "https://example.test/webhooks/twilio/connect-action",
+    );
+    expect(buildTwilioRelayUrl("https://example.test")).toBe(
+      "wss://example.test/webhooks/twilio/relay",
+    );
+    expect(buildTwilioMediaStreamUrl("http://example.test")).toBe(
+      "ws://example.test/webhooks/twilio/media-stream",
+    );
+    expect(buildTwilioPhoneNumberWebhookUrls("https://example.test")).toEqual({
+      statusCallbackUrl: "https://example.test/webhooks/twilio/status",
+      voiceUrl: "https://example.test/webhooks/twilio/voice",
+    });
+  });
+});

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -6,9 +6,11 @@
  *
  *   - `@vellumai/service-contracts/credential-rpc`  — transport, RPC, handles, grants, rendering, error
  *   - `@vellumai/service-contracts/trust-rules`     — trust-rule types and parsing helpers
+ *   - `@vellumai/service-contracts/twilio-ingress`  — shared Twilio ingress config constants
+ *   - `@vellumai/service-contracts/ingress`         — shared public ingress URL helpers
  *
  * Fine-grained subpaths are also available for low-friction migration:
- *   `./rpc`, `./handles`, `./grants`, `./rendering`, `./error`, `./trust-rules`
+ *   `./rpc`, `./handles`, `./grants`, `./rendering`, `./error`, `./trust-rules`, `./ingress`, `./twilio-ingress`
  *
  * Neutral wire-protocol contracts for communication between the assistant
  * daemon and the Credential Execution Service (CES). This package is
@@ -23,3 +25,5 @@ export * from "./grants.js";
 export * from "./rpc.js";
 export * from "./rendering.js";
 export * from "./trust-rules.js";
+export * from "./ingress.js";
+export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -0,0 +1,24 @@
+export function normalizePublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  if (/[?#]/.test(trimmed)) return undefined;
+
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return undefined;
+    }
+    if (!url.hostname) return undefined;
+    url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}

package/node_modules/@vellumai/service-contracts/src/twilio-ingress.ts

@@ -0,0 +1,84 @@
+import { normalizePublicBaseUrl } from "./ingress.js";
+
+export const TWILIO_VOICE_WEBHOOK_PATH = "/webhooks/twilio/voice";
+export const TWILIO_STATUS_WEBHOOK_PATH = "/webhooks/twilio/status";
+export const TWILIO_CONNECT_ACTION_WEBHOOK_PATH =
+  "/webhooks/twilio/connect-action";
+export const TWILIO_RELAY_WEBHOOK_PATH = "/webhooks/twilio/relay";
+export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
+
+/**
+ * Sentinel placeholder embedded in TwiML by the assistant where the real
+ * public base URL should go. The gateway replaces `wss://__VELLUM_PUBLIC_BASE_URL__/…`
+ * with the actual public URL (from Velay registration, config, or the
+ * `X-Vellum-Ingress-URL` header) before returning TwiML to Twilio.
+ *
+ * The placeholder uses `https://` so that `buildTwilioRelayUrl` /
+ * `buildTwilioMediaStreamUrl` can apply the standard `http→ws` scheme
+ * conversion, producing `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
+ */
+export const TWILIO_PUBLIC_BASE_URL_PLACEHOLDER =
+  "https://__VELLUM_PUBLIC_BASE_URL__";
+
+/**
+ * The WebSocket-scheme form of the placeholder that appears in TwiML after
+ * the `http→ws` scheme conversion applied by the URL builders.
+ */
+export const TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER =
+  "wss://__VELLUM_PUBLIC_BASE_URL__";
+
+export { normalizePublicBaseUrl } from "./ingress.js";
+
+export type TwilioPhoneNumberWebhookUrls = {
+  statusCallbackUrl: string;
+  voiceUrl: string;
+};
+
+export function resolveTwilioPublicBaseUrl(
+  ingress: { publicBaseUrl?: unknown } | undefined,
+  fallbackPublicBaseUrl?: unknown,
+): string | undefined {
+  const publicBaseUrl = normalizePublicBaseUrl(ingress?.publicBaseUrl);
+  if (publicBaseUrl) return publicBaseUrl;
+
+  return normalizePublicBaseUrl(fallbackPublicBaseUrl);
+}
+
+export function buildTwilioVoiceWebhookUrl(
+  baseUrl: string,
+  callSessionId?: string,
+): string {
+  if (callSessionId) {
+    return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}?callSessionId=${callSessionId}`;
+  }
+  return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioStatusWebhookUrl(baseUrl: string): string {
+  return `${baseUrl}${TWILIO_STATUS_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioConnectActionUrl(baseUrl: string): string {
+  return `${baseUrl}${TWILIO_CONNECT_ACTION_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioRelayUrl(baseUrl: string): string {
+  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_RELAY_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioMediaStreamUrl(baseUrl: string): string {
+  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_MEDIA_STREAM_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioPhoneNumberWebhookUrls(
+  baseUrl: string,
+): TwilioPhoneNumberWebhookUrls {
+  return {
+    statusCallbackUrl: buildTwilioStatusWebhookUrl(baseUrl),
+    voiceUrl: buildTwilioVoiceWebhookUrl(baseUrl),
+  };
+}
+
+function toTwilioWebSocketBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/^http(s?)/, "ws$1");
+}

package/node_modules/@vellumai/skill-host-contracts/src/assistant-event.ts

@@ -84,3 +84,12 @@ export function formatSseFrame(event: AssistantEvent): string {
 export function formatSseHeartbeat(): string {
   return ": heartbeat\n\n";
 }
+
+/**
+ * Format a keep-alive as both an SSE comment (for proxy keepalive) and a
+ * data-bearing event (so fetch-based SSE clients that cannot observe comment
+ * lines can still detect heartbeats for disconnect watchdogs).
+ */
+export function formatSseHeartbeatWithData(): string {
+  return `${formatSseHeartbeat()}event: assistant_event\ndata: ${JSON.stringify({ type: "heartbeat" })}\n\n`;
+}

package/node_modules/@vellumai/twilio-client/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/twilio-client",
+      "devDependencies": {
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/node_modules/@vellumai/twilio-client/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/twilio-client",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/twilio-client/src/__tests__/twilio-client.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import {
+  lookupIncomingPhoneNumberSid,
+  twilioAuthHeader,
+  twilioBaseUrl,
+  TwilioRestError,
+  updatePhoneNumberWebhooks,
+  type TwilioFetch,
+} from "../index.js";
+
+const ACCOUNT_SID = "AC123";
+const AUTH_TOKEN = "auth-token";
+const PHONE_NUMBER = "+15550100";
+const PHONE_NUMBER_SID = "PN123";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "Content-Type": "application/json" },
+    status,
+  });
+}
+
+describe("twilioAuthHeader", () => {
+  test("returns a Basic auth header", () => {
+    expect(twilioAuthHeader("AC_test_sid", "test_token")).toBe(
+      "Basic " + Buffer.from("AC_test_sid:test_token").toString("base64"),
+    );
+  });
+});
+
+describe("twilioBaseUrl", () => {
+  test("constructs the account-scoped REST API URL", () => {
+    expect(twilioBaseUrl("AC_abc123")).toBe(
+      "https://api.twilio.com/2010-04-01/Accounts/AC_abc123",
+    );
+  });
+});
+
+describe("lookupIncomingPhoneNumberSid", () => {
+  test("returns the matching incoming phone number SID", async () => {
+    const fetchImpl = mock<TwilioFetch>(async () =>
+      jsonResponse({
+        incoming_phone_numbers: [
+          { phone_number: "+15550199", sid: "PN_OTHER" },
+          { phone_number: PHONE_NUMBER, sid: PHONE_NUMBER_SID },
+        ],
+      }),
+    );
+
+    await expect(
+      lookupIncomingPhoneNumberSid({
+        accountSid: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        fetchImpl,
+        phoneNumber: PHONE_NUMBER,
+      }),
+    ).resolves.toBe(PHONE_NUMBER_SID);
+  });
+
+  test("throws TwilioRestError for lookup failures", async () => {
+    const fetchImpl = mock<TwilioFetch>(
+      async () => new Response("unavailable", { status: 503 }),
+    );
+
+    await expect(
+      lookupIncomingPhoneNumberSid({
+        accountSid: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        fetchImpl,
+        phoneNumber: PHONE_NUMBER,
+      }),
+    ).rejects.toBeInstanceOf(TwilioRestError);
+  });
+});
+
+describe("updatePhoneNumberWebhooks", () => {
+  test("looks up the SID and posts voice webhook settings", async () => {
+    const calls: Array<{ input: string | URL | Request; init?: RequestInit }> =
+      [];
+    const fetchImpl = mock<TwilioFetch>(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        calls.push({ input, init });
+        if (calls.length === 1) {
+          return jsonResponse({
+            incoming_phone_numbers: [
+              { phone_number: PHONE_NUMBER, sid: PHONE_NUMBER_SID },
+            ],
+          });
+        }
+        return jsonResponse({});
+      },
+    );
+
+    await updatePhoneNumberWebhooks({
+      accountSid: ACCOUNT_SID,
+      authToken: AUTH_TOKEN,
+      fetchImpl,
+      phoneNumber: PHONE_NUMBER,
+      webhooks: {
+        statusCallbackUrl: "https://example.test/webhooks/twilio/status",
+        voiceUrl: "https://example.test/webhooks/twilio/voice",
+      },
+    });
+
+    expect(calls).toHaveLength(2);
+    expect(String(calls[0].input)).toContain(
+      `/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers.json?PhoneNumber=%2B15550100`,
+    );
+    expect(String(calls[1].input)).toContain(
+      `/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers/${PHONE_NUMBER_SID}.json`,
+    );
+    expect(calls[1].init?.method).toBe("POST");
+    expect(calls[1].init?.headers).toEqual({
+      Authorization:
+        "Basic " +
+        Buffer.from(`${ACCOUNT_SID}:${AUTH_TOKEN}`).toString("base64"),
+      "Content-Type": "application/x-www-form-urlencoded",
+    });
+    const body = new URLSearchParams(String(calls[1].init?.body));
+    expect(body.get("VoiceUrl")).toBe(
+      "https://example.test/webhooks/twilio/voice",
+    );
+    expect(body.get("StatusCallback")).toBe(
+      "https://example.test/webhooks/twilio/status",
+    );
+  });
+});