@vellumai/vellum-gateway 0.12.3-staging.1 → 0.12.3

package/AGENTS.md

@@ -221,7 +221,7 @@ Two orthogonal axes, do not conflate them:
 - **Admission** (above) — _who gets in the door_. `TRUST_CLASS_RANK` vs `ADMISSION_FLOOR`, enforced across gateway + runtime.
 - **Capabilities** — _what an actor may do once admitted_. Resolved in the runtime, never on the gateway.
 
-**Trust classes** (`TrustClass` in `assistant/src/runtime/trust-class.ts`, re-exported from `actor-trust-resolver.ts`) are the _role_, ranked by `TRUST_CLASS_RANK`:
+**Trust classes** (`TrustClass` in `packages/gateway-client/src/trust-verdict-contract.ts`; the daemon imports it and never redeclares it) are the _role_, ranked by `TRUST_CLASS_RANK`:
 
 | Class                | Rank | Meaning                                                                  |
 | -------------------- | ---- | ------------------------------------------------------------------------ |

package/ARCHITECTURE.md

@@ -282,7 +282,7 @@ Channel bindings follow a three-phase lifecycle:
 
 1. **Bind** — An inbound message from an external channel (e.g., Telegram chat) arrives at the gateway, which normalizes it and forwards it to the runtime's `/v1/channels/inbound` endpoint. The runtime creates or reuses a conversation, establishing the channel binding (`sourceChannel` metadata on the conversation).
 
-2. **Route**: Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Slack and Telegram are thread-scoped: a message that arrives in a Slack thread (including every message in a Slack agent DM, which Slack always delivers in a thread) or a Telegram topic resolves to that thread's own conversation, keyed on the chat plus the thread id (`assistant/src/persistence/delivery-crud.ts`, `buildScopedConversationKey`); a thread-less message resolves to the chat's base conversation. Replies from the assistant are delivered back through the gateway's `/deliver/telegram` endpoint. The desktop client filters out channel-bound conversations during conversation restoration (`ConversationRestorer`) so they never appear in the desktop conversation list.
+2. **Route**: Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Slack and Telegram are thread-scoped: a message that arrives in a Slack thread (including every message in a Slack agent DM, which Slack always delivers in a thread) or a Telegram topic resolves to that thread's own conversation, keyed on the chat plus the thread id (`assistant/src/persistence/delivery-crud.ts`, `buildScopedConversationKey`); a thread-less message resolves to the chat's base conversation. Replies from the assistant go out through the daemon's channel transport for that channel (`assistant/src/messaging/providers`), which calls the provider's API directly; they never pass back through the gateway. The desktop client filters out channel-bound conversations during conversation restoration (`ConversationRestorer`) so they never appear in the desktop conversation list.
 
 3. **Rebind** — If a message arrives on an external chat whose conversation was previously deleted, the channel inbound handler treats it as a new conversation and establishes a fresh binding. The external chat ID is reused, but the conversation is new.
 
@@ -371,18 +371,18 @@ Telegram messages follow three paths through the system:
 Inbound (user → assistant):
   Telegram → Gateway POST /webhooks/telegram → verify secret → normalize → route
     → Runtime POST /v1/assistants/:id/channels/inbound
-    (replyCallbackUrl = ${gatewayInternalBaseUrl}/deliver/telegram)
+    (replyCallbackUrl = ${gatewayInternalBaseUrl}/deliver/telegram[?threadId=<topic>])
 
 Outbound reply (assistant → user, triggered by inbound):
-  Runtime callback → Gateway POST /deliver/telegram (bearer auth) → Telegram sendMessage/sendPhoto/sendDocument/sendChatAction
+  Daemon Telegram transport → Telegram Bot API sendMessage/sendPhoto/sendDocument/sendChatAction
 
-Outbound proactive (assistant → user, initiated by messaging provider):
-  Runtime messaging provider → Gateway POST /deliver/telegram (bearer auth) → Telegram sendMessage/sendChatAction
+Outbound proactive (assistant → user, messaging tool or POST /v1/channels/send):
+  Daemon Telegram transport → Telegram Bot API sendMessage
 ```
 
-The `replyCallbackUrl` included in the inbound forward is built from the `gatewayInternalBaseUrl` config field, which is always derived from `GATEWAY_PORT` as `http://127.0.0.1:${GATEWAY_PORT}` (default port `7830`). Both the hostname (`127.0.0.1`) and port derivation are hardcoded in `gateway/src/config.ts`, so the gateway and runtime must be co-located (same host, `--network host`, or Docker Compose with shared networking) for callbacks to reach the gateway. Separate-host deployments are not currently supported.
+The gateway does not serve `/deliver/telegram`. The `replyCallbackUrl` it attaches to the inbound forward is an addressing token: the daemon resolves its path to the channel's transport (`channelForCallback` in `assistant/src/messaging/providers/callback-routing.ts`) and reads per-channel parameters from its query (the Telegram transport reads `threadId` to reply into the same topic). The daemon never dials the URL's host and port, which come from `gatewayInternalBaseUrl` (`http://127.0.0.1:${GATEWAY_PORT}`, `gateway/src/config.ts`). The gateway's own replies to invite and verification codes it intercepts at ingress go out the same way: `deliverVerificationReply` (`gateway/src/verification/reply-delivery.ts`) hands the reply and the inbound message's callback URL to the daemon's IPC-only `deliver_gateway_reply` method, which resolves the transport from that URL as it does for any reply. The gateway never sends those replies to a provider itself. The daemon's Telegram transport (`assistant/src/messaging/providers/telegram-bot/`) reads the bot token from credential storage and calls the Bot API itself.
 
-The `/deliver/telegram` endpoint requires bearer auth unconditionally (fail-closed). If no bearer token is configured and the dev-only bypass flag (`telegram.deliverAuthBypass` in `workspace/config.json`) is not set, the endpoint returns 503 rather than allowing unauthenticated access. The bypass requires `APP_VERSION=0.0.0-dev`.
+The gateway sends to Telegram on its own only for notices it composes while handling the webhook, before or instead of a runtime turn: the `/start` acknowledgement, the "not fully set up" routing-rejection notice, a setup-hiccup notice when the forward fails, and the denial text the runtime returns when ingress ACL rejects the sender. These go through `sendTelegramReply` in `gateway/src/telegram/send.ts`.
 
 **Bot-account limitations:** The Telegram Bot API only supports sending messages to chats that have previously interacted with the bot. Bots cannot enumerate chats, read message history, or search messages. A future MTProto user-account session track may lift some of these restrictions.
 
@@ -403,8 +403,7 @@ The run transitions to `NeedsConfirmation` when the agent loop emits a `confirma
 ```
 Runtime detects needs_confirmation
   → runtime builds approval prompt + UI metadata
-  → POST /deliver/telegram with `approval` payload
-  → gateway renders inline keyboard (buttons: Approve once, Approve always, Reject)
+  → daemon Telegram transport sends the prompt with an inline keyboard (buttons: Approve once, Approve always, Reject)
   → user clicks button → Telegram callback_query
   → gateway normalizes callback_query into inbound event (callbackData field)
   → runtime parses callback data (format: apr:<requestId>:<action>)
@@ -431,19 +430,19 @@ Runtime detects needs_confirmation
 
 **Key modules:**
 
-| Module                                                  | Purpose                                                                                                                                                                 |
-| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assistant/src/runtime/approval-conversation-turn.ts`   | Conversational approval turn engine: LLM-based intent classification (structured output) for pending approval follow-ups, with fail-closed safety                       |
-| `assistant/src/runtime/approval-message-composer.ts`    | Centralized approval message composition: layered source selection (assistant preface → deterministic fallback) for all approval/guardian/verification user-facing copy |
-| `assistant/src/runtime/channel-approvals.ts`            | Orchestration: detect pending confirmations, build prompts (including guardian-aware prompts), apply decisions, plain-text fallback selection                           |
-| `assistant/src/runtime/channel-approval-types.ts`       | Shared types: actions, prompts, UI metadata, decisions                                                                                                                  |
-| `assistant/src/runtime/routes/channel-routes.ts`        | Integration point: approval interception, actor role resolution, guardian approval routing, deliver-once guard, fail-closed prompt delivery                             |
-| `assistant/src/runtime/channel-verification-service.ts` | Guardian binding lookups: `isGuardian()`, `getGuardianBinding()`                                                                                                        |
-| `assistant/src/memory/delivery-channels.ts`             | `claimRunDelivery()` — in-memory deliver-once guard for terminal reply idempotency                                                                                      |
-| `assistant/src/channels/gateway-guardian-requests.ts`   | Typed daemon client for the gateway-owned `guardian_requests` lifecycle (`guardian_requests_create` / `_decide` / `_list_expired_pending` / `_expire`)                  |
-| `assistant/src/runtime/gateway-client.ts`               | `deliverApprovalPrompt()` — sends approval payload to gateway                                                                                                           |
-| `gateway/src/telegram/send.ts`                          | `buildInlineKeyboard()` — renders approval actions as Telegram inline buttons                                                                                           |
-| `gateway/src/telegram/normalize.ts`                     | `callback_query` normalization into `GatewayInboundEvent` (private chats, groups, and supergroups; drops callbacks without data)                                        |
+| Module                                                   | Purpose                                                                                                                                                                 |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/runtime/approval-conversation-turn.ts`    | Conversational approval turn engine: LLM-based intent classification (structured output) for pending approval follow-ups, with fail-closed safety                       |
+| `assistant/src/runtime/approval-message-composer.ts`     | Centralized approval message composition: layered source selection (assistant preface → deterministic fallback) for all approval/guardian/verification user-facing copy |
+| `assistant/src/runtime/channel-approvals.ts`             | Orchestration: detect pending confirmations, build prompts (including guardian-aware prompts), apply decisions, plain-text fallback selection                           |
+| `assistant/src/runtime/channel-approval-types.ts`        | Shared types: actions, prompts, UI metadata, decisions                                                                                                                  |
+| `assistant/src/runtime/routes/channel-routes.ts`         | Integration point: approval interception, actor role resolution, guardian approval routing, deliver-once guard, fail-closed prompt delivery                             |
+| `assistant/src/runtime/channel-verification-service.ts`  | Guardian binding lookups: `isGuardian()`, `getGuardianBinding()`                                                                                                        |
+| `assistant/src/memory/delivery-channels.ts`              | `claimRunDelivery()`: in-memory deliver-once guard for terminal reply idempotency                                                                                       |
+| `assistant/src/channels/gateway-guardian-requests.ts`    | Typed daemon client for the gateway-owned `guardian_requests` lifecycle (`guardian_requests_create` / `_decide` / `_list_expired_pending` / `_expire`)                  |
+| `assistant/src/runtime/gateway-client.ts`                | `deliverApprovalPrompt()`: hands the approval prompt to the channel transport the callback URL names                                                                    |
+| `assistant/src/messaging/providers/telegram-bot/send.ts` | `buildInlineKeyboard()`: renders approval actions as Telegram inline buttons                                                                                            |
+| `gateway/src/telegram/normalize.ts`                      | `callback_query` normalization into `GatewayInboundEvent` (private chats, groups, and supergroups; drops callbacks without data)                                        |
 
 ### Approval Message Composer
 
@@ -562,19 +561,19 @@ sequenceDiagram
     GW->>Daemon: POST /v1/channels/inbound (JWT auth)
     Daemon->>Daemon: Detect non-guardian, set forcePromptSideEffects
     Daemon->>Daemon: Tool needs confirmation → create GuardianApprovalRequest
-    Daemon->>GW: POST /deliver/telegram (approval prompt + inline keyboard)
-    GW->>Guardian: sendMessage (approval prompt)
-    Daemon->>GW: POST /deliver/telegram (requester notification)
-    GW-->>NG: "Waiting for guardian approval..."
+    Daemon->>TG: sendMessage via Telegram transport (approval prompt + inline keyboard)
+    TG-->>Guardian: Approval prompt
+    Daemon->>TG: sendMessage via Telegram transport (requester notification)
+    TG-->>NG: "Waiting for guardian approval..."
     Guardian->>TG: Approve / Deny (callback_query or text)
     TG->>GW: POST /webhooks/telegram (callback_query)
     GW->>Daemon: POST /v1/channels/inbound (JWT auth)
     Daemon->>Daemon: Validate guardian identity, update approval decision
     Daemon->>Daemon: Apply decision to pending run
-    Daemon->>GW: POST /deliver/telegram (outcome notification)
-    GW-->>NG: "Guardian approved/denied your request"
-    Daemon->>GW: POST /deliver/telegram (confirmation)
-    GW-->>Guardian: Confirmation of decision
+    Daemon->>TG: sendMessage via Telegram transport (outcome notification)
+    TG-->>NG: "Guardian approved/denied your request"
+    Daemon->>TG: sendMessage via Telegram transport (confirmation)
+    TG-->>Guardian: Confirmation of decision
 ```
 
 Approval state lives in the gateway's `guardian_requests` table (kind `tool_approval`), with per-surface card deliveries in `guardian_request_deliveries`. Each request records the requester, guardian, tool name, risk level, and decision outcome; decisions commit atomically via the gateway's `guardian_requests_decide` IPC route.
@@ -732,14 +731,11 @@ The Slack channel enables inbound and outbound messaging via Slack's Socket Mode
 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`.
+6. The normalized event is forwarded to the runtime via `POST /v1/channels/inbound` with a `replyCallbackUrl` of `/deliver/slack?channel=<id>`, plus `threadTs` for a threaded message or `messageTs` for a thread-less message.
 
-**Egress** (`POST /deliver/slack`):
+**Egress:**
 
-1. The runtime calls the gateway's `/deliver/slack` endpoint with `{ chatId, text }` or `{ to, text }` (alias). The `chatId` field maps to the Slack channel ID where the reply should be posted.
-2. The gateway authenticates the request via bearer token (same fail-closed model as other deliver endpoints).
-3. The gateway posts the message via `POST https://slack.com/api/chat.postMessage` using the bot token.
-4. Threading is supported via a `threadTs` query parameter on the deliver URL. When present, replies are posted as thread replies to the specified message timestamp.
+The gateway does not serve `/deliver/slack`; for the daemon the callback URL only addresses the reply (the gateway's intercepted-code replies reach the same transport through the daemon, see Telegram Messaging Flow). The daemon's Slack transport (`assistant/src/messaging/providers/slack/`) calls the Slack Web API itself with the bot token: `chat.postMessage` and `chat.update` for whole messages, and `chat.startStream` / `chat.appendStream` / `chat.stopStream` for streamed replies. It reads `threadTs` from the callback URL to reply in the thread and `messageTs` to anchor the busy indicator on a thread-less message.
 
 **Credential management:**
 
@@ -773,7 +769,7 @@ Any persistent-stream transport that does not buffer events for disconnected cli
 | `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/message-normalizer.ts` | Normalizers per event family (`normalizeSlackAppMention()`, DM, group DM, channel message) with bot-mention stripping |
-| `gateway/src/index.ts`                    | `/deliver/slack` route: outbound message delivery via `chat.postMessage`, thread and message ts on the callback URL   |
+| `gateway/src/index.ts`                    | Builds the `/deliver/slack` callback URL (channel, thread ts, message ts) the daemon's Slack transport replies to     |
 
 **What the ingress does not do:** it never forwards the bot's own posts to the daemon (except a deletion of one, which the daemon records), and it never reads history on the daemon's behalf beyond the bounded reconnect catch-up above; the daemon's inbound-triggered backfill hydrates context.
 
@@ -846,7 +842,7 @@ sequenceDiagram
         Ctrl->>CallStore: createPendingQuestion()
         Ctrl->>GuardianDispatch: dispatchGuardianQuestion()
         GuardianDispatch->>Mac: notification_conversation_created SSE
-        GuardianDispatch->>TG: POST /deliver/{channel}
+        GuardianDispatch->>TG: sendMessage via notification pipeline
         Note over Mac,TG: First channel to respond wins
         Mac/TG->>Routes: guardian answer
         Routes->>CallDomain: answerCall()

package/README.md

@@ -58,19 +58,6 @@ For manual setup (or reference), register the webhook with Telegram using the `s
 
 See the [Telegram Bot API docs](https://core.telegram.org/bots/api#setwebhook) for the full API reference.
 
-## Telegram Deliver Endpoint Security
-
-The `/deliver/telegram` endpoint requires bearer auth by default (fail-closed). The security behavior is:
-
-| Condition                                                                                 | Result                     |
-| ----------------------------------------------------------------------------------------- | -------------------------- |
-| Bearer token configured + valid `Authorization` header                                    | Request allowed            |
-| Bearer token configured + missing/invalid `Authorization` header                          | 401 Unauthorized           |
-| No bearer token configured + `telegram.deliverAuthBypass=true` in `workspace/config.json` | Request allowed (dev-only) |
-| No bearer token configured + bypass not set                                               | 503 Service Not Configured |
-
-This ensures that misconfiguration cannot expose an unauthenticated public message-send surface. In production, ensure JWT authentication is properly configured. The `telegram.deliverAuthBypass` config flag (in `workspace/config.json`) is intended for local development only and requires `APP_VERSION=0.0.0-dev`.
-
 ## Voice Ingress — Inbound Calls (Twilio)
 
 The `/webhooks/twilio/voice` endpoint handles both outbound and inbound voice calls. For **outbound** calls (initiated by the assistant via `call_start`), the voice webhook URL includes a `callSessionId` query parameter that identifies the pre-created session. For **inbound** calls (someone dialing the assistant's Twilio phone number), no `callSessionId` is present — the gateway resolves the target assistant and the runtime creates a session on the fly.
@@ -112,9 +99,9 @@ These fields are forwarded to the runtime in the `/channels/inbound` payload alo
 
 ## Approval Buttons and Inline Keyboard
 
-The `/deliver/telegram` endpoint accepts an optional `approval` field in the request body. When present, the gateway renders Telegram inline keyboard buttons below the message text.
+The gateway does not send approval prompts. The assistant's Telegram transport (`assistant/src/messaging/providers/telegram-bot/`) sends them to the Bot API directly, and when the reply payload carries an `approval` field it renders Telegram inline keyboard buttons below the message text. The gateway's part is the return trip: it normalizes the button press (`callback_query`) and forwards it as described above.
 
-**Approval payload shape:**
+**Approval reply payload shape:**
 
 ```json
 {
@@ -134,7 +121,7 @@ The `/deliver/telegram` endpoint accepts an optional `approval` field in the req
 
 **Inline keyboard format:** Each action is rendered as a single-button row. The callback data uses the compact format `apr:<requestId>:<action>` (e.g., `apr:request-uuid:approve_once`) so the runtime can parse it back when the button is clicked.
 
-**Fallback behavior:** For non-rich channels that do not support inline keyboards, the runtime substitutes the `plainTextFallback` string for the structured `promptText` before calling the delivery endpoint. The fallback includes plain-text instructions so the user can respond via text. The `supportsInlineOptions` channel capability (`channelSupportsInlineOptions()`) in the runtime determines which format to use. Free-text responses are classified by the conversational approval engine.
+**Fallback behavior:** For non-rich channels that do not support inline keyboards, the runtime substitutes the `plainTextFallback` string for the structured `promptText` before handing the prompt to the channel transport. The fallback includes plain-text instructions so the user can respond via text. The `supportsInlineOptions` channel capability (`channelSupportsInlineOptions()`) in the runtime determines which format to use. Free-text responses are classified by the conversational approval engine.
 
 ## Public Ingress Routes
 
@@ -145,7 +132,6 @@ Control-plane routes are listed with their flat paths. Clients emit assistant-sc
 | Route                                                 | Method          | Description                                                                                                                                   |
 | ----------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/webhooks/telegram`                                  | POST            | Telegram bot webhook (validated via `TELEGRAM_WEBHOOK_SECRET`)                                                                                |
-| `/deliver/telegram`                                   | POST            | Internal endpoint for the assistant runtime to deliver outbound messages/attachments to Telegram chats                                        |
 | `/webhooks/twilio/voice`                              | POST            | Twilio voice webhook (validated via HMAC-SHA1 signature)                                                                                      |
 | `/webhooks/twilio/status`                             | POST            | Twilio status callback (validated via HMAC-SHA1 signature)                                                                                    |
 | `/webhooks/twilio/media-stream/:callSessionId/:token` | WS              | Twilio Media Streams WebSocket (bidirectional proxy to runtime; handshake metadata in URL path segments)                                      |
@@ -304,15 +290,13 @@ curl -i -X POST http://localhost:7830/webhooks/telegram
 
 ## Outbound Attachments (Telegram)
 
-When the assistant includes attachments in a reply, the gateway downloads each attachment from the runtime API and delivers it to the Telegram chat:
+The gateway does not send attachments. When a reply carries attachments, the assistant's Telegram transport (`assistant/src/messaging/providers/telegram-bot/`) reads each one from the assistant's attachment store and uploads it to the Bot API itself:
 
-- **Images** (`image/*` MIME types) are sent via `sendPhoto` (multipart form upload).
-- **Other files** are sent via `sendDocument` (multipart form upload).
-- **Oversized** attachments (exceeding the hardcoded max attachment size, default 20 MB) are skipped and included in the partial-failure notice.
-- **Partial failures** are handled gracefully: each attachment is attempted independently. If any fail, a single summary notice is sent to the chat listing the undelivered filenames.
-- **Concurrency** is controlled by a hardcoded max concurrency limit (default 3).
+- **Images** (`image/jpeg`, `image/png`, `image/gif`, `image/webp`) within the Bot API's 10 MB photo upload limit are sent via `sendPhoto`; **larger images and other files** via `sendDocument`.
+- **Oversized** attachments (over the 50 MB `sendDocument` limit) are skipped.
+- **Partial failures**: each attachment is attempted on its own, and if any fail, one summary notice lists the undelivered filenames.
 
-Text and attachments are sent separately — the text reply goes first via `sendMessage`, then each attachment follows.
+The text reply goes first via `sendMessage`, then each attachment follows in order.
 
 ## Health & Readiness Probes
 
@@ -385,10 +369,24 @@ See [`benchmarking/gateway/README.md`](../benchmarking/gateway/README.md) for lo
 
 ### Guardian-Specific Troubleshooting
 
-| Symptom                                                        | Cause                                                                                                                                              | Resolution                                                                                                                                                                                                                            |
-| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Guardian verification code reply gets no response              | 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. 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_PORT` is correct and the gateway is reachable at `http://127.0.0.1:<GATEWAY_PORT>` from the runtime (requires co-located networking 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 `actorExternalId` matches the approval request can approve or deny.                                                                                                                                           |
+| Symptom                                                        | Cause                                                                                                                                              | Resolution                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Guardian verification code reply gets no response              | The code never reached the gateway, the challenge expired, or the assistant could not send the gateway's reply                                     | Ensure the gateway is running, the bot token is valid, and the Telegram webhook is registered. Search the gateway log for `Verification reply`: a reply the assistant could not send does not undo the verification, so check the binding with the `channel-verification-sessions status` CLI command. 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. 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 assistant's channel transport could not send it (for example a missing or invalid bot token), or the guardian's chat ID is stale               | Check the assistant log for the transport's delivery error and confirm the channel's bot token is configured. For a channel with a transport the assistant never dials the `replyCallbackUrl`, so gateway reachability is not the cause. 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 `actorExternalId` matches the approval request can approve or deny.                                                                                                                                                                                                                                                                                         |
+
+### Binary virtual desktop tunnel
+
+The gateway advertises `X-Vellum-Velay-Binary-WebSocket: 1` when registering.
+It uses binary tunnel messages only when Velay sends `binary_messages: true`
+on a `/v1/desktop/stream` open frame. The envelope is byte `0x01`, 32 lowercase
+ASCII hex connection-ID bytes, then the unchanged payload (including empty
+payloads). Control and text messages remain JSON. Other routes and older relays
+retain JSON/base64 framing. Deploy Velay support before updating gateways;
+older gateways can continue using the upgraded relay.
+
+Malformed tunnel messages retain the existing log-and-ignore behavior. Raw binary
+frames addressed to streams without desktop negotiation are ignored, preserving
+other active streams on the shared tunnel.

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

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/integration-categories.ts

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

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

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/integration-categories.ts

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

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

@@ -43,6 +43,26 @@ export type GatewayLogsTailRouteParams = z.infer<
   typeof GatewayLogsTailRouteParamsSchema
 >;
 
+/**
+ * `gateway_debug_export`: a consistent copy of the gateway database plus its
+ * recent log files, as one gzipped tar, for a debug bundle. No params.
+ */
+export const GatewayDebugExportIpcParamsSchema = z
+  .object({})
+  .strict()
+  .default({});
+
+export const GatewayDebugExportIpcResponseSchema = z.object({
+  ok: z.literal(true),
+  /** `tar.gz` bytes, base64. Contains gateway.sqlite and gateway-logs/. */
+  archive_base64: z.string(),
+  size_bytes: z.number().int().nonnegative(),
+});
+
+export type GatewayDebugExportIpcResponse = z.infer<
+  typeof GatewayDebugExportIpcResponseSchema
+>;
+
 export const GatewayLogsTailIpcResponseSchema = z.object({
   lines: z.array(z.record(z.string(), z.unknown())),
   truncated: z.boolean(),

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

@@ -24,13 +24,15 @@ export {
   PersistentIpcClient,
 } from "./ipc-client.js";
 
-// Outbound delivery contract (daemon → gateway) — Zod schemas + derived types
+// Outbound delivery contract: Zod schemas + derived types
 export {
   ApprovalActionOptionSchema,
   ApprovalUIMetadataSchema,
   AttachmentMetadataSchema,
   ChannelDeliveryResultSchema,
   ChannelReplyPayloadSchema,
+  DELIVER_GATEWAY_REPLY_IPC_METHOD,
+  GatewayReplyRequestSchema,
   MessageAudienceSchema,
   PermissionRequestDetailsSchema,
   StreamOpSchema,
@@ -45,6 +47,7 @@ export type {
   AttachmentMetadata,
   ChannelDeliveryResult,
   ChannelReplyPayload,
+  GatewayReplyRequest,
   MessageAudience,
   PermissionRequestDetails,
   StreamOp,

package/node_modules/@vellumai/gateway-client/src/outbound-contract.ts

@@ -1,13 +1,17 @@
 /**
- * Daemon → gateway outbound delivery contract.
+ * Outbound channel delivery contract.
  *
- * Zod schemas defining the wire format for channel replies delivered from
- * the daemon to the gateway via `POST /deliver/{channel}`. Both services
- * import from here so the contract is enforced at compile time.
+ * Zod schemas for a reply to a channel chat. The daemon constructs these
+ * payloads in `deliverChannelReply()` and `deliverApprovalPrompt()` and hands
+ * them to the channel transport its callback URL names
+ * (`messaging/providers`). `/deliver/{channel}` is only that callback URL's
+ * addressing form: no service serves it. A callback URL no
+ * transport owns (a managed callback carrying a `callback_token`) is POSTed
+ * over HTTP by `http-delivery.ts` instead.
  *
- * The daemon constructs these payloads in `deliverChannelReply()` and
- * `deliverApprovalPrompt()`; the gateway validates and dispatches them
- * to the target channel provider.
+ * The gateway sends through the same transports, never to a provider itself:
+ * a reply it composes for a message it answered at ingress goes to the daemon
+ * as a {@link GatewayReplyRequest}.
  */
 
 import type { KnownBlock } from "@slack/types";
@@ -279,6 +283,33 @@ export const ChannelReplyPayloadSchema = z.object({
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;
 
+// ---------------------------------------------------------------------------
+// Gateway reply: gateway to daemon
+// ---------------------------------------------------------------------------
+
+/**
+ * Daemon IPC method that delivers a {@link GatewayReplyRequest}. IPC-only:
+ * it has no HTTP route.
+ */
+export const DELIVER_GATEWAY_REPLY_IPC_METHOD = "deliver_gateway_reply";
+
+/**
+ * A text reply the gateway composed for an inbound message it answered
+ * itself (a verification code, an invite redemption), which the daemon
+ * delivers through the channel transport `callbackUrl` names. The callback
+ * URL is the one the inbound message carried, so the reply lands in the chat
+ * and thread the person wrote from.
+ */
+export const GatewayReplyRequestSchema = ChannelReplyPayloadSchema.pick({
+  chatId: true,
+  assistantId: true,
+}).extend({
+  callbackUrl: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export type GatewayReplyRequest = z.infer<typeof GatewayReplyRequestSchema>;
+
 // ---------------------------------------------------------------------------
 // Channel delivery result — gateway response
 // ---------------------------------------------------------------------------

package/node_modules/@vellumai/gateway-client/src/trust-verdict-contract.ts

@@ -3,9 +3,8 @@
  *
  * The gateway resolves this verdict from its ACL DB and stamps it onto the
  * inbound payload's `sourceMetadata`; the runtime consumes it. Keeping the
- * type here avoids the runtime importing from `gateway/src` and lets the
- * daemon's `trustClass` union (`actor-trust-resolver.ts`) converge on this
- * one source of truth.
+ * type here avoids the runtime importing from `gateway/src`, and the daemon
+ * imports {@link TrustClass} from here rather than declaring its own.
  *
  * This contract carries ACL + identity keys + minimal labels only — never
  * info fields (notes, userFile, contactType). `status` / `policy` / `type`
@@ -19,9 +18,9 @@ import { z } from "zod";
 import { AdmissionPolicySchema } from "./admission-policy-contract.js";
 
 /**
- * Verification-purpose trust classification. Mirrors the daemon's
- * `TrustClass` union (`actor-trust-resolver.ts`), ordered most- to
- * least-trusted.
+ * Trust classification of an inbound actor, ordered most- to least-trusted.
+ * The one declaration of the vocabulary: the gateway classifies with it and
+ * the daemon derives capabilities from it.
  */
 export const TRUST_CLASS_VALUES = [
   "guardian",

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

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/integration-categories.ts

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}