@vellumai/vellum-gateway 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",

package/src/__tests__/config.test.ts

@@ -11,6 +11,7 @@ describe("config: hardcoded defaults", () => {
     expect(config.maxWebhookPayloadBytes).toBe(1024 * 1024);
     expect(config.maxAttachmentBytes).toEqual({
       telegram: 20 * 1024 * 1024,
+      telegramOutbound: 50 * 1024 * 1024,
       slack: 100 * 1024 * 1024,
       whatsapp: 16 * 1024 * 1024,
       default: 100 * 1024 * 1024,

package/src/__tests__/route-schema-guard.test.ts

@@ -111,6 +111,9 @@ function regexToOpenApiPath(escaped: string): string | null {
     return `{param${paramIndex}}`;
   });
 
+  // Strip optional trailing slash (`/?`) — common in route regexes
+  path = path.replace(/\/\?$/, "");
+
   // If there are remaining regex constructs we can't convert, skip
   if (/[\\()\[\].*+?{}|^$]/.test(path.replace(/\{param\d+\}/g, ""))) {
     return null;

package/src/__tests__/schema.test.ts

@@ -64,6 +64,11 @@ describe("/schema route", () => {
     expect(body.paths["/v1/integrations/telegram/config"]).toBeDefined();
     expect(body.paths["/v1/integrations/telegram/commands"]).toBeDefined();
     expect(body.paths["/v1/integrations/telegram/setup"]).toBeDefined();
+    expect(body.paths["/v1/oauth/apps"]).toBeDefined();
+    expect(body.paths["/v1/oauth/apps/{appId}"]).toBeDefined();
+    expect(body.paths["/v1/oauth/apps/{appId}/connections"]).toBeDefined();
+    expect(body.paths["/v1/oauth/connections/{connectionId}"]).toBeDefined();
+    expect(body.paths["/v1/oauth/apps/{appId}/connect"]).toBeDefined();
     expect(body.paths["/v1/contacts"]).toBeDefined();
     expect(body.paths["/v1/contacts/merge"]).toBeDefined();
     expect(body.paths["/v1/contact-channels/{contactChannelId}"]).toBeDefined();
@@ -131,6 +136,17 @@ describe("buildSchema()", () => {
     expect(schemaNames).toContain("TelegramDocument");
     expect(schemaNames).toContain("TelegramDeliverRequest");
     expect(schemaNames).toContain("RuntimeAttachmentMeta");
+
+    const oauthConnection = components.schemas.OAuthConnectionSummary as {
+      properties?: Record<string, unknown>;
+    };
+    expect(oauthConnection.properties?.granted_scopes).toEqual({
+      type: "array",
+      items: { type: "string" },
+    });
+    expect(oauthConnection.properties?.has_refresh_token).toEqual({
+      type: "boolean",
+    });
   });
 
   test("returns a JSON-serializable object", () => {

package/src/config.ts

@@ -137,7 +137,8 @@ export function loadConfig(): GatewayConfig {
     gatewayInternalBaseUrl,
     logFile,
     maxAttachmentBytes: {
-      telegram: 20 * 1024 * 1024, // Telegram Bot API getFile limit
+      telegram: 20 * 1024 * 1024, // Telegram Bot API getFile (download) limit
+      telegramOutbound: 50 * 1024 * 1024, // Telegram Bot API sendDocument (upload) limit
       slack: 100 * 1024 * 1024, // Slack standard plan
       whatsapp: 16 * 1024 * 1024, // WhatsApp Business API limit
       default: 100 * 1024 * 1024, // Fallback; capped by runtime MAX_UPLOAD_BYTES (100 MB)

package/src/feature-flag-registry.json

@@ -25,6 +25,14 @@
       "description": "Show the Contacts tab in Settings for viewing and managing contacts",
       "defaultEnabled": true
     },
+    {
+      "id": "custom-inference-provider",
+      "scope": "macos",
+      "key": "custom_inference_provider_enabled",
+      "label": "Custom Inference Provider",
+      "description": "Allow selecting a specific LLM provider and model for inference in Your Own mode",
+      "defaultEnabled": false
+    },
     {
       "id": "email-channel",
       "scope": "assistant",

package/src/http/router.ts

@@ -160,11 +160,17 @@ function matchRoute(
   if (route.method && route.method !== method) return null;
 
   if (typeof route.path === "string") {
-    if (pathname !== route.path) return null;
+    // Normalize trailing slashes so "/v1/foo/" matches "/v1/foo"
+    const normalized =
+      pathname.length > 1 && pathname.endsWith("/")
+        ? pathname.slice(0, -1)
+        : pathname;
+    if (normalized !== route.path) return null;
     return { params: [] };
   }
 
-  // Regex path
+  // Regex path — use original pathname since regex routes may
+  // explicitly include trailing slashes in their patterns.
   const match = pathname.match(route.path);
   if (!match) return null;
   return { params: match.slice(1) };

package/src/http/routes/oauth-apps-proxy.ts

@@ -0,0 +1,129 @@
+/**
+ * Gateway proxy endpoints for OAuth app and connection management routes.
+ *
+ * These routes remain available even when the broad runtime proxy is
+ * disabled, so skills and clients can use gateway URLs exclusively.
+ */
+
+import { mintServiceToken } from "../../auth/token-exchange.js";
+import type { GatewayConfig } from "../../config.js";
+import { fetchImpl } from "../../fetch.js";
+import { getLogger } from "../../logger.js";
+import { stripHopByHop } from "../../util/strip-hop-by-hop.js";
+
+const log = getLogger("oauth-apps-proxy");
+
+export function createOAuthAppsProxyHandler(config: GatewayConfig) {
+  async function proxyToRuntime(
+    req: Request,
+    upstreamPath: string,
+    upstreamSearch: string,
+  ): Promise<Response> {
+    const start = performance.now();
+    const upstream = `${config.assistantRuntimeBaseUrl}${upstreamPath}${upstreamSearch}`;
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    reqHeaders.delete("authorization");
+
+    reqHeaders.set("authorization", `Bearer ${mintServiceToken()}`);
+
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : null;
+    if (bodyBuffer !== null) {
+      reqHeaders.set("content-length", String(bodyBuffer.byteLength));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(
+        new DOMException(
+          "The operation was aborted due to timeout",
+          "TimeoutError",
+        ),
+      );
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetchImpl(upstream, {
+        method: req.method,
+        headers: reqHeaders,
+        body: bodyBuffer,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error(
+          { path: upstreamPath, duration },
+          "OAuth apps proxy upstream timed out",
+        );
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error(
+        { err, path: upstreamPath, duration },
+        "OAuth apps proxy upstream connection failed",
+      );
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      log.warn(
+        { path: upstreamPath, status: response.status, duration },
+        "OAuth apps proxy upstream error",
+      );
+      return new Response(body, {
+        status: response.status,
+        headers: resHeaders,
+      });
+    }
+
+    log.info(
+      { path: upstreamPath, status: response.status, duration },
+      "OAuth apps proxy completed",
+    );
+    return new Response(response.body, {
+      status: response.status,
+      headers: resHeaders,
+    });
+  }
+
+  return {
+    async handleListApps(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/oauth/apps", new URL(req.url).search);
+    },
+
+    async handleCreateApp(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/oauth/apps", "");
+    },
+
+    async handleDeleteApp(req: Request, appId: string): Promise<Response> {
+      return proxyToRuntime(req, `/v1/oauth/apps/${appId}`, "");
+    },
+
+    async handleListConnections(
+      req: Request,
+      appId: string,
+    ): Promise<Response> {
+      return proxyToRuntime(req, `/v1/oauth/apps/${appId}/connections`, "");
+    },
+
+    async handleDeleteConnection(
+      req: Request,
+      connectionId: string,
+    ): Promise<Response> {
+      return proxyToRuntime(req, `/v1/oauth/connections/${connectionId}`, "");
+    },
+
+    async handleConnect(req: Request, appId: string): Promise<Response> {
+      return proxyToRuntime(req, `/v1/oauth/apps/${appId}/connect`, "");
+    },
+  };
+}

package/src/index.ts

@@ -50,6 +50,7 @@ import { createTelegramControlPlaneProxyHandler } from "./http/routes/telegram-c
 import { createContactsControlPlaneProxyHandler } from "./http/routes/contacts-control-plane-proxy.js";
 import { createTwilioControlPlaneProxyHandler } from "./http/routes/twilio-control-plane-proxy.js";
 import { createSlackControlPlaneProxyHandler } from "./http/routes/slack-control-plane-proxy.js";
+import { createOAuthAppsProxyHandler } from "./http/routes/oauth-apps-proxy.js";
 import { createChannelReadinessProxyHandler } from "./http/routes/channel-readiness-proxy.js";
 import { createRuntimeHealthProxyHandler } from "./http/routes/runtime-health-proxy.js";
 import { createBrainGraphProxyHandler } from "./http/routes/brain-graph-proxy.js";
@@ -266,6 +267,7 @@ async function main() {
     createContactsControlPlaneProxyHandler(config);
   const twilioControlPlaneProxy = createTwilioControlPlaneProxyHandler(config);
   const slackControlPlaneProxy = createSlackControlPlaneProxyHandler(config);
+  const oauthAppsProxy = createOAuthAppsProxyHandler(config);
   const channelReadinessProxy = createChannelReadinessProxyHandler(config);
   const runtimeHealthProxy = createRuntimeHealthProxyHandler(config);
   const brainGraphProxy = createBrainGraphProxyHandler(config);
@@ -649,6 +651,46 @@ async function main() {
       handler: (req) => slackControlPlaneProxy.handleShareToSlack(req),
     },
 
+    // ── OAuth apps ──
+    {
+      path: "/v1/oauth/apps",
+      method: "GET",
+      auth: "edge",
+      handler: (req) => oauthAppsProxy.handleListApps(req),
+    },
+    {
+      path: "/v1/oauth/apps",
+      method: "POST",
+      auth: "edge",
+      handler: (req) => oauthAppsProxy.handleCreateApp(req),
+    },
+    {
+      path: /^\/v1\/oauth\/apps\/([^/]+)\/?$/,
+      method: "DELETE",
+      auth: "edge",
+      handler: (req, params) => oauthAppsProxy.handleDeleteApp(req, params[0]),
+    },
+    {
+      path: /^\/v1\/oauth\/apps\/([^/]+)\/connections\/?$/,
+      method: "GET",
+      auth: "edge",
+      handler: (req, params) =>
+        oauthAppsProxy.handleListConnections(req, params[0]),
+    },
+    {
+      path: /^\/v1\/oauth\/connections\/([^/]+)\/?$/,
+      method: "DELETE",
+      auth: "edge",
+      handler: (req, params) =>
+        oauthAppsProxy.handleDeleteConnection(req, params[0]),
+    },
+    {
+      path: /^\/v1\/oauth\/apps\/([^/]+)\/connect\/?$/,
+      method: "POST",
+      auth: "edge",
+      handler: (req, params) => oauthAppsProxy.handleConnect(req, params[0]),
+    },
+
     // ── Channel readiness ──
     {
       path: "/v1/channels/readiness",

package/src/runtime/client.ts

@@ -310,47 +310,61 @@ export type UploadAttachmentResponse = {
   id: string;
 };
 
-export async function downloadAttachmentContent(
+/**
+ * Internal helper that fetches raw attachment content without interacting
+ * with the circuit breaker. Used by downloadAttachment's hydration path
+ * which already owns the breaker lifecycle for the compound operation.
+ */
+async function fetchAttachmentContentRaw(
   config: GatewayConfig,
   attachmentId: string,
 ): Promise<Buffer> {
-  cbBeforeRequest();
-
-  const url = `${config.assistantRuntimeBaseUrl}/v1/attachments/${encodeURIComponent(attachmentId)}/content`;
+  const url = `${
+    config.assistantRuntimeBaseUrl
+  }/v1/attachments/${encodeURIComponent(attachmentId)}/content`;
 
-  let response: Response;
-  try {
-    response = await fetchImpl(url, {
-      method: "GET",
-      headers: runtimeServiceHeaders(config),
-      signal: AbortSignal.timeout(config.runtimeTimeoutMs),
-    });
-  } catch (err) {
-    cbOnFailure();
-    throw err;
-  }
+  const response = await fetchImpl(url, {
+    method: "GET",
+    headers: runtimeServiceHeaders(config),
+    signal: AbortSignal.timeout(config.runtimeTimeoutMs),
+  });
 
   if (!response.ok) {
     const body = await response.text();
-    if (response.status >= 500) cbOnFailure();
-    else cbOnSuccess();
     throw new Error(
       `Attachment content download failed (${response.status}): ${body}`,
     );
   }
 
-  cbOnSuccess();
   const arrayBuffer = await response.arrayBuffer();
   return Buffer.from(arrayBuffer);
 }
 
+export async function downloadAttachmentContent(
+  config: GatewayConfig,
+  attachmentId: string,
+): Promise<Buffer> {
+  cbBeforeRequest();
+
+  try {
+    const buffer = await fetchAttachmentContentRaw(config, attachmentId);
+    cbOnSuccess();
+    return buffer;
+  } catch (err) {
+    cbOnFailure();
+    throw err;
+  }
+}
+
 export async function downloadAttachment(
   config: GatewayConfig,
   attachmentId: string,
 ): Promise<HydratedAttachmentPayload> {
   cbBeforeRequest();
 
-  const url = `${config.assistantRuntimeBaseUrl}/v1/attachments/${encodeURIComponent(attachmentId)}`;
+  const url = `${
+    config.assistantRuntimeBaseUrl
+  }/v1/attachments/${encodeURIComponent(attachmentId)}`;
 
   let response: Response;
   try {
@@ -375,15 +389,24 @@ export async function downloadAttachment(
 
   // Transparently hydrate file-backed attachments: fetch the binary content
   // from the dedicated /content endpoint and inline it as base64.
-  // Note: we defer cbOnSuccess() until after hydration so that a recurring
-  // pattern of metadata-200 + content-5xx correctly accumulates breaker
-  // failures instead of resetting the counter on every metadata success.
-  if (payload.fileBacked && !payload.data) {
-    const contentBuffer = await downloadAttachmentContent(config, attachmentId);
-    payload.data = contentBuffer.toString("base64");
+  // We use the raw helper (no nested circuit breaker) so the compound
+  // metadata+content operation is treated as a single breaker unit.
+  // If content fetch fails, cbOnFailure() fires for the whole operation.
+  if (payload.fileBacked && payload.data == null) {
+    try {
+      const contentBuffer = await fetchAttachmentContentRaw(
+        config,
+        attachmentId,
+      );
+      payload.data = contentBuffer.toString("base64");
+    } catch (err) {
+      cbOnFailure();
+      throw err;
+    }
   }
 
-  if (!payload.data) {
+  // Use == null to allow empty string (valid base64 for zero-byte attachments)
+  if (payload.data == null) {
     throw new Error(`Attachment ${attachmentId} has no data after hydration`);
   }
 

package/src/schema.ts

@@ -1615,6 +1615,226 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/oauth/apps": {
+        get: {
+          summary: "List OAuth apps",
+          description:
+            "Authenticated gateway endpoint that lists configured OAuth apps for a provider by proxying to the assistant runtime.",
+          operationId: "oauthAppsList",
+          parameters: [
+            {
+              name: "provider_key",
+              in: "query",
+              required: true,
+              schema: { type: "string" },
+              description:
+                "OAuth provider key to filter by, for example `integration:google`.",
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth apps returned",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/OAuthAppListResponse",
+                  },
+                },
+              },
+            },
+            "400": { description: "Missing or invalid provider_key query parameter" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+        post: {
+          summary: "Create OAuth app",
+          description:
+            "Authenticated gateway endpoint that creates or updates a user-managed OAuth app by proxying to the assistant runtime.",
+          operationId: "oauthAppsCreate",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/OAuthAppCreateRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "OAuth app created",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/OAuthAppCreateResponse",
+                  },
+                },
+              },
+            },
+            "400": { description: "Invalid request payload" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth provider not found" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/oauth/apps/{appId}": {
+        delete: {
+          summary: "Delete OAuth app",
+          description:
+            "Authenticated gateway endpoint that deletes a user-managed OAuth app and disconnects its linked accounts by proxying to the assistant runtime.",
+          operationId: "oauthAppsDelete",
+          parameters: [
+            {
+              name: "appId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth app deleted",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/OkResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth app not found" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/oauth/apps/{appId}/connections": {
+        get: {
+          summary: "List OAuth app connections",
+          description:
+            "Authenticated gateway endpoint that lists linked accounts for a specific OAuth app by proxying to the assistant runtime.",
+          operationId: "oauthAppConnectionsList",
+          parameters: [
+            {
+              name: "appId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth app connections returned",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/OAuthConnectionListResponse",
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth app not found" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/oauth/connections/{connectionId}": {
+        delete: {
+          summary: "Delete OAuth connection",
+          description:
+            "Authenticated gateway endpoint that disconnects a linked OAuth account by proxying to the assistant runtime.",
+          operationId: "oauthConnectionDelete",
+          parameters: [
+            {
+              name: "connectionId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth connection deleted",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/OkResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth connection not found" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/oauth/apps/{appId}/connect": {
+        post: {
+          summary: "Start OAuth app connect flow",
+          description:
+            "Authenticated gateway endpoint that starts an OAuth authorization flow for a specific app by proxying to the assistant runtime.",
+          operationId: "oauthAppConnect",
+          parameters: [
+            {
+              name: "appId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: false,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/OAuthConnectRequest" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "OAuth connect flow started",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/OAuthConnectResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth app not found" },
+            "500": { description: "Failed to start OAuth flow" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
       "/v1/channels/readiness": {
         get: {
           summary: "Get channel readiness",
@@ -2263,6 +2483,117 @@ export function buildSchema(): Record<string, unknown> {
             error: { type: "string" },
           },
         },
+        OkResponse: {
+          type: "object",
+          required: ["ok"],
+          properties: {
+            ok: { type: "boolean" },
+          },
+        },
+        OAuthAppSummary: {
+          type: "object",
+          required: [
+            "id",
+            "provider_key",
+            "client_id",
+            "created_at",
+            "updated_at",
+          ],
+          properties: {
+            id: { type: "string" },
+            provider_key: { type: "string" },
+            client_id: { type: "string" },
+            created_at: { type: "integer" },
+            updated_at: { type: "integer" },
+          },
+        },
+        OAuthAppListResponse: {
+          type: "object",
+          required: ["apps"],
+          properties: {
+            apps: {
+              type: "array",
+              items: { $ref: "#/components/schemas/OAuthAppSummary" },
+            },
+          },
+        },
+        OAuthAppCreateRequest: {
+          type: "object",
+          required: ["provider_key", "client_id", "client_secret"],
+          properties: {
+            provider_key: { type: "string" },
+            client_id: { type: "string" },
+            client_secret: { type: "string" },
+          },
+        },
+        OAuthAppCreateResponse: {
+          type: "object",
+          required: ["app"],
+          properties: {
+            app: { $ref: "#/components/schemas/OAuthAppSummary" },
+          },
+        },
+        OAuthConnectionSummary: {
+          type: "object",
+          required: [
+            "id",
+            "provider_key",
+            "account_info",
+            "granted_scopes",
+            "status",
+            "has_refresh_token",
+            "expires_at",
+            "created_at",
+            "updated_at",
+          ],
+          properties: {
+            id: { type: "string" },
+            provider_key: { type: "string" },
+            account_info: { type: ["string", "null"] },
+            granted_scopes: {
+              type: "array",
+              items: { type: "string" },
+            },
+            status: { type: "string" },
+            has_refresh_token: { type: "boolean" },
+            expires_at: { type: ["integer", "null"] },
+            created_at: { type: "integer" },
+            updated_at: { type: "integer" },
+          },
+        },
+        OAuthConnectionListResponse: {
+          type: "object",
+          required: ["connections"],
+          properties: {
+            connections: {
+              type: "array",
+              items: { $ref: "#/components/schemas/OAuthConnectionSummary" },
+            },
+          },
+        },
+        OAuthConnectRequest: {
+          type: "object",
+          properties: {
+            scopes: {
+              type: "array",
+              items: { type: "string" },
+            },
+          },
+        },
+        OAuthConnectDeferredResponse: {
+          type: "object",
+          required: ["auth_url", "state"],
+          properties: {
+            auth_url: { type: "string" },
+            state: { type: "string" },
+          },
+        },
+        OAuthConnectResponse: {
+          oneOf: [
+            { $ref: "#/components/schemas/OAuthConnectDeferredResponse" },
+            { $ref: "#/components/schemas/OkResponse" },
+          ],
+        },
         TelegramOk: {
           type: "object",
           required: ["ok"],

package/src/telegram/send.ts

@@ -82,10 +82,12 @@ export async function sendTelegramAttachments(
 
   for (const meta of attachments) {
     // When size is known upfront, skip oversized attachments before downloading.
+    // Use the outbound limit (sendDocument supports 50 MB) rather than the
+    // inbound getFile limit (20 MB).
     if (
       meta.sizeBytes !== undefined &&
       meta.sizeBytes >
-        (config.maxAttachmentBytes.telegram ??
+        (config.maxAttachmentBytes.telegramOutbound ??
           config.maxAttachmentBytes.default)
     ) {
       log.warn(
@@ -111,7 +113,7 @@ export async function sendTelegramAttachments(
       // Check size after hydration for ID-only payloads where size was unknown.
       if (
         sizeBytes >
-        (config.maxAttachmentBytes.telegram ??
+        (config.maxAttachmentBytes.telegramOutbound ??
           config.maxAttachmentBytes.default)
       ) {
         log.warn(