@vellumai/vellum-gateway 0.7.1 → 0.7.3

package/AGENTS.md

@@ -37,6 +37,10 @@ In Docker mode, the gateway is the sole owner of trust rule storage. Trust files
 
 The assistant reads and writes trust rules via the gateway's HTTP trust API instead of accessing the filesystem directly. This ensures the security boundary is enforced at the container level — even if the assistant container is compromised, it cannot tamper with trust rules without going through the gateway's API.
 
+### Backup Encryption Key
+
+The backup encryption key (`backup.key`) lives in `GATEWAY_SECURITY_DIR` and is never exposed to the assistant daemon or workspace. The gateway owns all backup encryption/decryption — the assistant produces plaintext vbundles via `/v1/migrations/export`, and the gateway encrypts them for offsite storage. The assistant cannot read the key via `file_read` or any other tool. This is a security boundary: even if the assistant is prompt-injected, backup encryption remains intact.
+
 ### Credential Access in Docker Mode
 
 In Docker mode, the gateway accesses stored credentials via the CES HTTP API (`CES_CREDENTIAL_URL`), authenticated with `CES_SERVICE_TOKEN`. The gateway does not have direct filesystem access to credential encryption keys (`keys.enc`, `store.key`), which reside on the CES security volume.

package/ARCHITECTURE.md

@@ -280,9 +280,10 @@ Channel bindings follow a three-phase lifecycle:
 
 The public URL where the gateway is reachable is configured via:
 
-| Source                                     | Description                                                                  |
-| ------------------------------------------ | ---------------------------------------------------------------------------- |
-| `ingress.publicBaseUrl` (workspace config) | Set via Settings UI > Public Ingress, or directly in workspace `config.json` |
+| Source                                              | Description                                                                                                                                             |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ingress.publicBaseUrl` (workspace config)          | Canonical public ingress URL for Telegram webhooks, OAuth callbacks, email callbacks, generic JSON webhooks, Twilio webhooks, and Twilio WebSocket URLs |
+| `ingress.publicBaseUrlManagedBy` (workspace config) | Ownership marker used when Velay published `ingress.publicBaseUrl`; lets the gateway clear stale Velay-managed URLs without disturbing manual URLs      |
 
 ### Tunnel-Agnostic Setup
 
@@ -291,7 +292,34 @@ To expose the gateway for external callbacks during local development:
 1. **Start your tunnel** service (ngrok, Cloudflare Tunnel, or any similar tool), pointing it at the local gateway: `http://127.0.0.1:7830`
 2. **Set the public URL** provided by the tunnel as `ingress.publicBaseUrl` in the Settings UI (Public Ingress section)
 
-The assistant runtime reads this URL via the centralized `public-ingress-urls.ts` module and uses it to construct all webhook and callback URLs automatically (Twilio voice/status/relay webhooks, Telegram webhooks, OAuth redirect URIs, etc.).
+The assistant runtime reads this URL via the centralized `public-ingress-urls.ts` module and uses it to construct webhook and callback URLs automatically. Ngrok and custom tunnels remain supported for every ingress surface, including Twilio fallback.
+
+### Velay Twilio Ingress
+
+Velay is a platform-managed tunnel for assistant-hosted HTTP and WebSocket traffic. When it is active, Velay publishes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`.
+
+When `VELAY_BASE_URL` is present in the gateway environment, the gateway starts `VelayTunnelClient`. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. The gateway writes that URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
+
+Velay forwards both HTTP request frames and WebSocket frames into the local gateway loopback listener:
+
+```text
+Public Velay HTTPS/WSS URL
+  → Velay tunnel session
+  → Gateway Velay bridge
+  → Gateway loopback listener (http://127.0.0.1:<GATEWAY_PORT>)
+  → Existing gateway route handlers
+```
+
+The HTTP bridge can carry normal JSON requests and health checks, so it is useful for local bridge smoke tests. Velay-managed `ingress.publicBaseUrl` changes are tagged with `publicBaseUrlManagedBy` so gateway side effects can skip unrelated webhook reconciliation while still refreshing Twilio phone-number webhooks.
+
+Local platform smoke-test flow:
+
+1. In `vellum-assistant-platform`, run `vel up velay`.
+2. Ensure vembda passes the environment-appropriate `VELAY_BASE_URL` into assistant gateway containers.
+3. Re-hatch or restart the assistant so the gateway receives the new environment.
+4. Confirm gateway logs show `Velay tunnel connected` and `Velay tunnel registered`.
+5. Verify HTTP forwarding by requesting `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/healthz` and `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/schema`. When validating a JSON webhook route under active development, POST a small JSON body through the same Velay public URL and confirm it reaches the loopback gateway.
+6. Verify Twilio WebSocket forwarding with a synthetic local WebSocket client against `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/webhooks/twilio/relay?callSessionId=...&token=...`, then with a real Twilio call after the gateway has registered with Velay.
 
 ### URL Builders
 
@@ -300,10 +328,10 @@ All public-facing URLs are constructed by `assistant/src/inbound/public-ingress-
 | Function                       | URL Pattern                                                                                                                                                      |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `getPublicBaseUrl()`           | Resolves the canonical base URL from `ingress.publicBaseUrl` in workspace config or module-level state (assistant-side; the gateway reads via `ConfigFileCache`) |
-| `getTwilioVoiceWebhookUrl()`   | `${base}/webhooks/twilio/voice?callSessionId=...`                                                                                                                |
-| `getTwilioStatusCallbackUrl()` | `${base}/webhooks/twilio/status`                                                                                                                                 |
-| `getTwilioConnectActionUrl()`  | `${base}/webhooks/twilio/connect-action`                                                                                                                         |
-| `getTwilioRelayUrl()`          | `ws(s)://.../webhooks/twilio/relay`                                                                                                                              |
+| `getTwilioVoiceWebhookUrl()`   | `${base}/webhooks/twilio/voice?callSessionId=...`, using `ingress.publicBaseUrl`                                                                                 |
+| `getTwilioStatusCallbackUrl()` | `${base}/webhooks/twilio/status`, using `ingress.publicBaseUrl`                                                                                                  |
+| `getTwilioConnectActionUrl()`  | `${base}/webhooks/twilio/connect-action`, using `ingress.publicBaseUrl`                                                                                          |
+| `getTwilioRelayUrl()`          | `ws(s)://.../webhooks/twilio/relay`, using `ingress.publicBaseUrl`                                                                                               |
 | `getOAuthCallbackUrl()`        | `${base}/webhooks/oauth/callback`                                                                                                                                |
 | `getTelegramWebhookUrl()`      | `${base}/webhooks/telegram`                                                                                                                                      |
 
@@ -702,7 +730,7 @@ The Slack channel enables inbound and outbound messaging via Slack's Socket Mode
 
 1. Every Socket Mode envelope is ACKed immediately by echoing `{ envelope_id }` back on the WebSocket — this is required by Slack regardless of whether the event is processed.
 2. Only `events_api` envelopes with `app_mention` events are processed in MVP. Other envelope types (slash commands, interactive payloads) are ACKed but ignored.
-3. Events are deduplicated by `event_id` using an in-memory `Map<string, number>` with a 24-hour TTL. A periodic cleanup sweep runs every hour to evict expired entries.
+3. Events are deduplicated by a compound key in the SQLite-backed `slack_seen_events` table: every event records its Slack `event_id`, and message-shaped events additionally record `msg:${channel}:${ts}` so the live and reconnect-replay paths dedup symmetrically. Entries TTL out after 24h; a periodic cleanup sweep evicts expired rows.
 4. The `normalizeSlackAppMention()` function strips leading bot-mention tokens (`<@U...>`) from the message text and produces a `GatewayInboundEvent` with `sourceChannel: "slack"`, using the Slack channel ID as `conversationExternalId` and the sender's user ID as `actorExternalId`.
 5. Routing uses the standard `resolveAssistant()` chain (conversation_id -> actor_id -> default/reject). Events that cannot be routed are dropped.
 6. The normalized event is forwarded to the runtime via `POST /v1/channels/inbound` with a `replyCallbackUrl` pointing to `/deliver/slack`.
@@ -729,13 +757,24 @@ Both tokens are stored in secure storage (`credential/slack_channel/app_token`,
 
 The Socket Mode client auto-reconnects on any WebSocket close or error. The backoff schedule is: `min(1000 * 2^attempt, 30000)` + random jitter. After a successful connection, the attempt counter resets. Slack-initiated disconnects (envelope `type: "disconnect"`) trigger an immediate reconnect with no backoff.
 
+**Reconnect catch-up:**
+
+Slack [does not buffer Socket Mode events](https://api.slack.com/apis/socket-mode#events) for disconnected clients, so any @mention or DM that arrives during a reconnect window is lost on the wire. The client recovers these by maintaining a persistent high-watermark (`slack_last_seen_ts`) of the latest accepted event timestamp and, on every WebSocket `open`, fetching a bounded slice of [`conversations.history`](https://api.slack.com/methods/conversations.history) and [`conversations.replies`](https://api.slack.com/methods/conversations.replies) since that watermark. Recovered messages are wrapped in synthetic Socket Mode envelopes and dispatched through the same `processEventPayload` path as live events, so filter, dedup, normalize, and routing logic stay in one place.
+
+Catch-up is scoped to channels the gateway can reasonably reach: routing entries with a Slack-shaped conversation ID (`C…` / `D…` / `G…`), tracked active threads (`slack_active_threads`), and previously-seen DM channels (`contact_channels` rows of type `slack`). It is bounded by max-lookback (1h), per-channel limit (50), and concurrency (4); on a 429 the cycle aborts immediately and resumes on the next reconnect. Brand-new mentions in unrouted, never-engaged channels remain unrecoverable here — the daemon's existing inbound-triggered Slack backfill (`triggerSlackThreadBackfillIfNeeded` and `tryBackfillSlackDmIfCold`) hydrates context once the next live event arrives.
+
+**General principle — stateful-stream transports require catch-up-on-reconnect:**
+
+Any persistent-stream transport that does not buffer events for disconnected clients (Slack Socket Mode, similar WebSocket gateways) must combine the WebSocket with a HTTP catch-up path on reconnect. A persisted high-watermark + bounded replay through the shared event pipeline is the standard pattern; without it, every transient disconnect silently drops events.
+
 **Key modules:**
 
-| Module                                     | Purpose                                                                      |
-| ------------------------------------------ | ---------------------------------------------------------------------------- |
-| `gateway/src/slack/socket-mode.ts`         | `SlackSocketModeClient` — WebSocket lifecycle, ACK, dedup, auto-reconnect    |
-| `gateway/src/slack/normalize.ts`           | `normalizeSlackAppMention()` — event normalization and bot-mention stripping |
-| `gateway/src/http/routes/slack-deliver.ts` | `/deliver/slack` — outbound message delivery via `chat.postMessage`          |
+| Module                                     | Purpose                                                                                       |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `gateway/src/slack/socket-mode.ts`         | `SlackSocketModeClient` — WebSocket lifecycle, ACK, dedup, auto-reconnect, reconnect catch-up |
+| `gateway/src/slack/slack-web.ts`           | `conversations.history` / `conversations.replies` helpers for reconnect catch-up              |
+| `gateway/src/slack/normalize.ts`           | `normalizeSlackAppMention()` — event normalization and bot-mention stripping                  |
+| `gateway/src/http/routes/slack-deliver.ts` | `/deliver/slack` — outbound message delivery via `chat.postMessage`                           |
 
 **Limitations (MVP):** Text-only — attachments are rejected. Only `app_mention` events are processed (direct messages to the bot are not handled). Rich approval UI (inline buttons) is not supported.
 
@@ -1038,10 +1077,12 @@ In gateway-fronted deployments, the TwiML WebSocket URL (returned by the voice w
 
 Signature validation is **fail-closed**: if the Twilio auth token is not configured, all webhook requests are rejected with `403`. Missing or invalid `X-Twilio-Signature` headers are also rejected with `403`. Payload size is capped by `maxWebhookPayloadBytes` (checked via both `Content-Length` header and actual body size).
 
-**Webhook base URL resolution:** The base URL used when constructing all public ingress URLs (Twilio webhooks, OAuth callbacks, Telegram webhooks, etc.) is resolved by `public-ingress-urls.ts`:
+**Webhook base URL resolution:** Public ingress URL construction is centralized in `public-ingress-urls.ts`:
 
-1. `ingress.publicBaseUrl` in workspace config (set via Settings UI > Public Ingress)
-2. Module-level state in the assistant (set by config handlers when tunnels start/stop)
+- Twilio voice/status/connect-action/relay/media-stream URLs use `ingress.publicBaseUrl`.
+- Velay registration publishes its public assistant URL to `ingress.publicBaseUrl` with `ingress.publicBaseUrlManagedBy: "velay"`.
+- Telegram webhooks, OAuth callbacks, email callbacks, and normal JSON webhook URLs also use `ingress.publicBaseUrl`; Velay-managed URL changes are tagged so unrelated reconciliation can be skipped when appropriate.
+- Module-level assistant state remains a fallback for legacy tunnel start/stop flows.
 
 All webhook paths (`/webhooks/twilio/voice`, `/webhooks/twilio/status`, `/webhooks/telegram`, `/webhooks/oauth/callback`, etc.) are appended automatically.
 

package/Dockerfile

@@ -13,6 +13,7 @@ COPY packages/assistant-client ./packages/assistant-client
 COPY packages/ces-client ./packages/ces-client
 COPY packages/service-contracts ./packages/service-contracts
 COPY packages/slack-text ./packages/slack-text
+COPY packages/twilio-client ./packages/twilio-client
 
 # Install deps for shared packages that have their own file: dependencies.
 RUN cd /app/packages/ces-client && bun install --frozen-lockfile

package/README.md

@@ -26,11 +26,11 @@ bun run dev
 
 ## Configuration
 
-| Variable                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Variable                  | Required | Default | Description                                                                                                                                                                                                                                                                         |
+| ------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `TELEGRAM_BOT_TOKEN`      | No       | —       | Bot token from @BotFather (Telegram disabled when unset). When not set as an env var, the gateway reads from the assistant's secure credential store: CES HTTP API first (when `CES_CREDENTIAL_URL` is configured), then the encrypted file store (`~/.vellum/protected/keys.enc`). |
-| `TELEGRAM_WEBHOOK_SECRET` | No       | —       | Secret for verifying webhook requests (Telegram disabled when unset). Same credential reader fallback behavior as `TELEGRAM_BOT_TOKEN`.                                                                                                                                            |
-| `GATEWAY_PORT`            | No       | `7830`  | Port for the gateway HTTP server                                                                                                                                                                                                                                                                                                                                                       |
+| `TELEGRAM_WEBHOOK_SECRET` | No       | —       | Secret for verifying webhook requests (Telegram disabled when unset). Same credential reader fallback behavior as `TELEGRAM_BOT_TOKEN`.                                                                                                                                             |
+| `GATEWAY_PORT`            | No       | `7830`  | Port for the gateway HTTP server                                                                                                                                                                                                                                                    |
 
 Most gateway behavior is now configured via hardcoded defaults or workspace config (`~/.vellum/workspace/config.json`) rather than environment variables. Channel operational settings (Telegram API base URL, timeouts, deliver auth bypass flags, runtime base URL, routing, proxy settings, attachment limits, shutdown drain) are managed via `workspace/config.json` through `ConfigFileCache`. See the channel-specific sections in `ARCHITECTURE.md` for details.
 
@@ -176,7 +176,7 @@ The gateway serves as the single public ingress point for all external callbacks
 
 ### Tunnel Setup
 
-To receive external callbacks during local development, point a tunnel service at the local gateway (default `http://127.0.0.1:7830`) and configure the resulting public URL:
+To receive external callbacks during local development, point a tunnel service at the local gateway (default `http://127.0.0.1:7830`) and configure the resulting public URL. Ngrok, Cloudflare Tunnel, and other custom HTTPS/WSS tunnels remain supported.
 
 #### Test Gateway Source Changes Locally (No Release Needed)
 
@@ -210,6 +210,47 @@ In local tunnel setups, updating `ingress.publicBaseUrl` in Settings is typicall
 
 The assistant runtime uses this URL to construct all webhook and OAuth callback URLs automatically.
 
+### Velay for Twilio Testing
+
+Velay is a managed ingress transport for assistant-hosted HTTP and WebSocket traffic. When Velay registration succeeds, the gateway writes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`. Twilio URL builders use that public base URL for voice, status, relay, and media-stream endpoints.
+
+Use Velay when testing Twilio voice webhooks or Twilio WebSocket upgrades through the platform-managed tunnel:
+
+1. In `vellum-assistant-platform`, start the local Velay service:
+
+   ```bash
+   vel up velay
+   ```
+
+2. Ensure vembda injects the Velay endpoint into assistant gateway containers. For local Docker-hosted assistants, the gateway container must dial the Velay service running on the host:
+
+   ```bash
+   VELAY_BASE_URL=http://host.docker.internal:8501
+   ```
+
+   Hosted environments should use their environment's deployed Velay URL instead.
+
+3. Re-hatch or restart the assistant so the gateway process receives `VELAY_BASE_URL`.
+4. Confirm the gateway logs include `Velay tunnel connected` followed by `Velay tunnel registered`. Registration publishes the returned Velay URL to `ingress.publicBaseUrl`.
+
+For an HTTP bridge smoke test, send a request to the registered Velay public URL and confirm it reaches the loopback gateway, for example:
+
+```bash
+curl -i "$VELAY_PUBLIC_BASE_URL/<assistant-id>/healthz"
+curl -i "$VELAY_PUBLIC_BASE_URL/<assistant-id>/schema"
+```
+
+When testing a JSON webhook route under active development, POST a small JSON body through the same Velay public URL and confirm the gateway logs or handler response show the request reached the loopback listener.
+
+For a synthetic Twilio WebSocket smoke test, connect a local WebSocket client to the Velay public URL using one of the gateway Twilio WebSocket paths, such as:
+
+```bash
+bun -e 'const ws = new WebSocket(process.argv[1]); ws.onopen = () => { console.log("open"); ws.close(); }; ws.onerror = (event) => console.error(event);' \
+  "wss://<velay-host>/<assistant-id>/webhooks/twilio/relay?callSessionId=session-123&token=<edge-token>"
+```
+
+For a real Twilio call, expose local Velay with a public HTTPS/WSS tunnel and configure the platform Velay service with that origin as `VELAY_PUBLIC_BASE_URL`. After the assistant re-registers, Twilio should fetch `/webhooks/twilio/voice` and open `/webhooks/twilio/relay` or `/webhooks/twilio/media-stream/...` through the Velay URL. Use ngrok or another custom tunnel in `ingress.publicBaseUrl` only for local/self-hosted workflows that are not routed through Velay.
+
 ## Ingress Boundary Guarantees
 
 The gateway is the **sole public ingress point** for all external webhooks. The assistant runtime never directly accepts public webhook traffic — all Twilio and Telegram webhook routes on the runtime return `410 GATEWAY_ONLY` when accessed directly.

package/bun.lock

@@ -9,6 +9,7 @@
         "@vellumai/ces-client": "file:../packages/ces-client",
         "@vellumai/service-contracts": "file:../packages/service-contracts",
         "@vellumai/slack-text": "file:../packages/slack-text",
+        "@vellumai/twilio-client": "file:../packages/twilio-client",
         "drizzle-kit": "0.30.6",
         "drizzle-orm": "0.45.2",
         "file-type": "21.3.0",
@@ -212,6 +213,8 @@
 
     "@vellumai/slack-text": ["@vellumai/slack-text@file:../packages/slack-text", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
 
+    "@vellumai/twilio-client": ["@vellumai/twilio-client@file:../packages/twilio-client", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
+
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
@@ -352,7 +355,7 @@
 
     "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="],
 
-    "minimatch": ["minimatch@10.2.4", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg=="],
+    "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="],
 
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
@@ -494,7 +497,7 @@
 
     "@vellumai/ces-client/@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
 
-    "@vellumai/ces-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
+    "@vellumai/ces-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", {}],
 
     "@vellumai/ces-client/typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
 
@@ -504,6 +507,8 @@
 
     "@vellumai/slack-text/@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
 
+    "@vellumai/twilio-client/@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "gel/which": ["which@4.0.0", "", { "dependencies": { "isexe": "^3.1.1" }, "bin": { "node-which": "bin/which.js" } }, "sha512-GlaYyEb07DPxYCKhKzplCWBJtvxZcZMrL+4UkrTSJHHPyZU4mYYTv3qaOe77H7EODLSSopAUFAc6W8U4yqvscg=="],
@@ -566,6 +571,8 @@
 
     "@vellumai/slack-text/@types/bun/bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
 
+    "@vellumai/twilio-client/@types/bun/bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
     "gel/which/isexe": ["isexe@3.1.5", "", {}, "sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w=="],
 
     "@typescript-eslint/typescript-estree/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],

package/knip.json

@@ -5,6 +5,7 @@
     "@vellumai/assistant-client",
     "@vellumai/ces-client",
     "@vellumai/service-contracts",
-    "@vellumai/slack-text"
+    "@vellumai/slack-text",
+    "@vellumai/twilio-client"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -28,6 +28,7 @@
     "@vellumai/ces-client": "file:../packages/ces-client",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/slack-text": "file:../packages/slack-text",
+    "@vellumai/twilio-client": "file:../packages/twilio-client",
     "drizzle-kit": "0.30.6",
     "drizzle-orm": "0.45.2",
     "file-type": "21.3.0",

package/src/__tests__/auto-approve-thresholds.test.ts

@@ -52,6 +52,7 @@ describe("auto-approve thresholds", () => {
       expect(data).toEqual({
         interactive: "medium",
         autonomous: "low",
+        headless: "none",
       });
     });
 
@@ -59,16 +60,15 @@ describe("auto-approve thresholds", () => {
       const putHandler = createGlobalThresholdPutHandler();
       const getHandler = createGlobalThresholdGetHandler();
 
-      // First PUT to set values
       await putHandler(makeRequest({ interactive: "none" }));
 
-      // GET should reflect the update
       const res = await getHandler(makeRequest(undefined, "GET"));
       expect(res.status).toBe(200);
       const data = await res.json();
       expect(data).toEqual({
         interactive: "none",
         autonomous: "low",
+        headless: "none",
       });
     });
   });
@@ -83,6 +83,7 @@ describe("auto-approve thresholds", () => {
       expect(data).toEqual({
         interactive: "none",
         autonomous: "low",
+        headless: "none",
       });
     });
 
@@ -105,6 +106,7 @@ describe("auto-approve thresholds", () => {
       expect(data).toEqual({
         interactive: "high",
         autonomous: "low",
+        headless: "none",
       });
     });
 
@@ -160,7 +162,6 @@ describe("auto-approve thresholds", () => {
     test("upserts correctly — first write creates, second write updates", async () => {
       const handler = createGlobalThresholdPutHandler();
 
-      // First write — creates the row
       const res1 = await handler(
         makeRequest({ interactive: "none", autonomous: "low" }),
       );
@@ -169,17 +170,16 @@ describe("auto-approve thresholds", () => {
       expect(data1).toEqual({
         interactive: "none",
         autonomous: "low",
+        headless: "none",
       });
 
-      // Second write — updates the existing row
-      const res2 = await handler(
-        makeRequest({ autonomous: "medium" }),
-      );
+      const res2 = await handler(makeRequest({ autonomous: "medium" }));
       expect(res2.status).toBe(200);
       const data2 = await res2.json();
       expect(data2).toEqual({
         interactive: "none",
         autonomous: "medium",
+        headless: "none",
       });
     });
 
@@ -187,42 +187,69 @@ describe("auto-approve thresholds", () => {
       const handler = createGlobalThresholdPutHandler();
 
       const res = await handler(
-        makeRequest({
-          interactive: "medium",
-          autonomous: "low",
-        }),
+        makeRequest({ interactive: "medium", autonomous: "low" }),
       );
       expect(res.status).toBe(200);
       const data = await res.json();
       expect(data).toEqual({
         interactive: "medium",
         autonomous: "low",
+        headless: "none",
       });
     });
 
     test("empty object preserves existing values when row exists", async () => {
       const putHandler = createGlobalThresholdPutHandler();
 
-      // First: set non-default values
-      await putHandler(
-        makeRequest({
-          interactive: "medium",
-          autonomous: "low",
-        }),
-      );
+      await putHandler(makeRequest({ interactive: "medium", autonomous: "low" }));
 
-      // Then PUT empty object — existing values should be preserved
       const res = await putHandler(makeRequest({}));
       expect(res.status).toBe(200);
       const data = await res.json();
       expect(data).toEqual({
         interactive: "medium",
         autonomous: "low",
+        headless: "none",
+      });
+    });
+
+    // ── headless field ────────────────────────────────────────────────────────
+
+    test("can set headless threshold", async () => {
+      const handler = createGlobalThresholdPutHandler();
+
+      const res = await handler(makeRequest({ headless: "low" }));
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data).toEqual({
+        interactive: "medium",
+        autonomous: "low",
+        headless: "low",
       });
     });
 
-    // Note: "empty PUT inserts schema defaults when no row" is covered by
-    // the GET handler test suite. The PUT tests run after prior PUTs leave
-    // a row in the DB (bun test reuse), so we test preserve-existing above.
+    test("returns 400 for invalid headless value", async () => {
+      const handler = createGlobalThresholdPutHandler();
+
+      const res = await handler(makeRequest({ headless: "extreme" }));
+      expect(res.status).toBe(400);
+      const data = await res.json();
+      expect(data.error).toContain("headless");
+      expect(data.error).toContain("none, low, medium, high");
+    });
+
+    test("headless is preserved when other fields are updated", async () => {
+      const handler = createGlobalThresholdPutHandler();
+
+      // Explicitly set headless to a non-default value
+      await handler(makeRequest({ headless: "low" }));
+
+      // Update only interactive — headless should remain "low"
+      const res = await handler(makeRequest({ interactive: "high" }));
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.headless).toBe("low");
+      expect(data.interactive).toBe("high");
+    });
   });
 });

package/src/__tests__/config-file-watcher.test.ts

@@ -0,0 +1,181 @@
+import { existsSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  ConfigFileWatcher,
+  type ConfigChangeEvent,
+} from "../config-file-watcher.js";
+import {
+  isOnlyVelayPublicBaseUrlChange,
+  shouldSyncTwilioPhoneWebhooksAfterConfigChange,
+} from "../twilio/webhook-sync-trigger.js";
+import { testWorkspaceDir } from "./test-preload.js";
+
+const configPath = join(testWorkspaceDir, "config.json");
+
+function writeConfig(data: Record<string, unknown>): void {
+  writeFileSync(configPath, JSON.stringify(data), "utf-8");
+}
+
+function pollOnce(watcher: ConfigFileWatcher): void {
+  (
+    watcher as unknown as {
+      pollOnce: () => void;
+    }
+  ).pollOnce();
+}
+
+function makeEvent(
+  changedKeys: string[],
+  changedFields: Record<string, string[]>,
+): ConfigChangeEvent {
+  return {
+    data: {},
+    changedKeys: new Set(changedKeys),
+    changedFields: new Map(
+      Object.entries(changedFields).map(([section, fields]) => [
+        section,
+        new Set(fields),
+      ]),
+    ),
+  };
+}
+
+afterEach(() => {
+  try {
+    if (existsSync(configPath)) unlinkSync(configPath);
+  } catch {
+    // best-effort cleanup
+  }
+});
+
+describe("ConfigFileWatcher", () => {
+  test("reports shallow ingress fields changed by Velay-managed URL writes", () => {
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://public.example.test",
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://velay.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedKeys).toEqual(new Set(["ingress"]));
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl", "publicBaseUrlManagedBy"]),
+    );
+  });
+
+  test("reports Twilio-only fields when Velay creates ingress from scratch", () => {
+    writeConfig({
+      gateway: {
+        runtimeProxyRequireAuth: false,
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      gateway: {
+        runtimeProxyRequireAuth: false,
+      },
+      ingress: {
+        publicBaseUrl: "https://velay.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedKeys).toEqual(new Set(["ingress"]));
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl", "publicBaseUrlManagedBy"]),
+    );
+  });
+
+  test("detects public base URL changes", () => {
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://old-public.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://new-public.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl"]),
+    );
+  });
+});
+
+describe("Twilio webhook sync config-change triggers", () => {
+  test("syncs when generic public ingress changes without a Twilio override", () => {
+    const event = makeEvent(["ingress"], { ingress: ["publicBaseUrl"] });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(false);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("syncs when Velay-managed public ingress changes", () => {
+    const event = makeEvent(["ingress"], {
+      ingress: ["publicBaseUrl", "publicBaseUrlManagedBy"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(true);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("does not sync when only the Velay manager marker changes", () => {
+    const event = makeEvent(["ingress"], {
+      ingress: ["publicBaseUrlManagedBy"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(true);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(false);
+  });
+
+  test("syncs when Twilio phone configuration becomes available", () => {
+    const event = makeEvent(["twilio"], {
+      twilio: ["phoneNumber", "accountSid"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(false);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("does not sync when unrelated Twilio configuration changes", () => {
+    const event = makeEvent(["twilio"], {
+      twilio: ["assistantPhoneNumbers"],
+    });
+
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(false);
+  });
+});