@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/schema.ts

@@ -1,4 +1,11 @@
 import packageJson from "../package.json" with { type: "json" };
+import {
+  TWILIO_CONNECT_ACTION_WEBHOOK_PATH,
+  TWILIO_MEDIA_STREAM_WEBHOOK_PATH,
+  TWILIO_RELAY_WEBHOOK_PATH,
+  TWILIO_STATUS_WEBHOOK_PATH,
+  TWILIO_VOICE_WEBHOOK_PATH,
+} from "@vellumai/service-contracts/twilio-ingress";
 
 export function buildSchema(): Record<string, unknown> {
   return {
@@ -300,7 +307,7 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/webhooks/twilio/voice": {
+      [TWILIO_VOICE_WEBHOOK_PATH]: {
         post: {
           summary: "Twilio voice webhook",
           description:
@@ -358,7 +365,7 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/webhooks/twilio/status": {
+      [TWILIO_STATUS_WEBHOOK_PATH]: {
         post: {
           summary: "Twilio status webhook",
           description:
@@ -415,7 +422,7 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/webhooks/twilio/connect-action": {
+      [TWILIO_CONNECT_ACTION_WEBHOOK_PATH]: {
         post: {
           summary: "Twilio connect-action webhook",
           description:
@@ -472,6 +479,54 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/webhooks/twilio/voice-verify": {
+        post: {
+          summary: "Twilio voice verification callback",
+          description:
+            "Receives DTMF digits from Twilio <Gather> during gateway-owned voice verification. Validates the verification code, creates the guardian binding on success, and returns TwiML to either re-prompt or forward to the assistant for ConversationRelay setup.",
+          operationId: "twilioVoiceVerifyCallback",
+          security: [{ TwilioSignature: [] }],
+          parameters: [
+            {
+              name: "attempt",
+              in: "query",
+              required: false,
+              schema: { type: "integer", default: 0 },
+              description: "Zero-based attempt counter for retry tracking.",
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/x-www-form-urlencoded": {
+                schema: {
+                  type: "object",
+                  additionalProperties: { type: "string" },
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description:
+                "TwiML response — either a re-prompt <Gather>, a failure <Say>, or forwarded ConversationRelay setup.",
+              content: {
+                "text/xml": {
+                  schema: { type: "string" },
+                },
+              },
+            },
+            "403": {
+              description: "Twilio signature validation failed",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
       "/webhooks/whatsapp": {
         get: {
           summary: "WhatsApp webhook verification",
@@ -914,7 +969,7 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/webhooks/twilio/relay": {
+      [TWILIO_RELAY_WEBHOOK_PATH]: {
         get: {
           summary: "Twilio ConversationRelay WebSocket",
           description:
@@ -954,7 +1009,7 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/webhooks/twilio/media-stream": {
+      [TWILIO_MEDIA_STREAM_WEBHOOK_PATH]: {
         get: {
           summary: "Twilio Media Stream WebSocket",
           description:
@@ -1195,68 +1250,6 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/pairing/register": {
-        post: {
-          summary: "Register pairing code",
-          description:
-            "Authenticated gateway endpoint that registers a new pairing code for device linking via the assistant runtime.",
-          operationId: "pairingRegister",
-          security: [{ BearerAuth: [] }],
-          requestBody: {
-            required: true,
-            content: {
-              "application/json": {
-                schema: { type: "object", additionalProperties: true },
-              },
-            },
-          },
-          responses: {
-            "200": { description: "Pairing code registered" },
-            "400": { description: "Invalid request payload" },
-            "401": {
-              description: "Unauthorized — missing or invalid bearer token",
-            },
-            "502": { description: "Failed to reach assistant runtime" },
-          },
-        },
-      },
-      "/pairing/request": {
-        post: {
-          summary: "Request pairing",
-          description:
-            "Initiates a pairing request using a pairing code. Auth failures are tracked for rate limiting.",
-          operationId: "pairingRequest",
-          requestBody: {
-            required: true,
-            content: {
-              "application/json": {
-                schema: { type: "object", additionalProperties: true },
-              },
-            },
-          },
-          responses: {
-            "200": { description: "Pairing request accepted" },
-            "400": { description: "Invalid request payload" },
-            "401": { description: "Unauthorized" },
-            "403": { description: "Pairing code expired or invalid" },
-            "502": { description: "Failed to reach assistant runtime" },
-          },
-        },
-      },
-      "/pairing/status": {
-        get: {
-          summary: "Check pairing status",
-          description:
-            "Checks the current status of a pairing request. Auth failures are tracked for rate limiting.",
-          operationId: "pairingStatus",
-          responses: {
-            "200": { description: "Pairing status returned" },
-            "401": { description: "Unauthorized" },
-            "403": { description: "Pairing session not found" },
-            "502": { description: "Failed to reach assistant runtime" },
-          },
-        },
-      },
       "/v1/integrations/telegram/config": {
         get: {
           summary: "Get Telegram integration config",
@@ -1500,6 +1493,32 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/contacts/prompt/submit": {
+        post: {
+          summary: "Submit a contact address in response to a prompt",
+          description:
+            "Authenticated gateway endpoint that accepts a contact address submitted by the user in response to a contacts/prompt IPC request. Writes the contact, notifies the daemon to unblock the waiting CLI call.",
+          operationId: "contactsPromptSubmitPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Contact created and prompt resolved" },
+            "400": { description: "Invalid request payload" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "409": { description: "Channel already exists for this contact" },
+            "503": { description: "Bearer token not configured" },
+          },
+        },
+      },
       "/v1/contact-channels/{contactChannelId}": {
         patch: {
           summary: "Update a contact channel",
@@ -2153,33 +2172,6 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
-      "/v1/integrations/slack/channel/oauth-install": {
-        post: {
-          summary: "Slack OAuth install",
-          description:
-            "Scope-protected gateway endpoint that initiates the Slack OAuth loopback flow to capture bot and user tokens. This endpoint blocks while the user completes the Slack consent screen (up to 6 minutes). Requires a bearer token with `settings.write` scope.",
-          operationId: "slackChannelOAuthInstallPost",
-          security: [{ BearerAuth: [] }],
-          requestBody: {
-            required: false,
-            content: {
-              "application/json": {
-                schema: { type: "object", additionalProperties: true },
-              },
-            },
-          },
-          responses: {
-            "200": { description: "OAuth install completed successfully" },
-            "400": { description: "Invalid request payload" },
-            "401": {
-              description: "Unauthorized — missing or invalid bearer token",
-            },
-            "403": { description: "Insufficient scope" },
-            "502": { description: "Failed to reach assistant runtime" },
-            "504": { description: "Assistant runtime request timed out" },
-          },
-        },
-      },
       "/v1/oauth/providers": {
         get: {
           summary: "List OAuth providers",
@@ -2907,6 +2899,7 @@ export function buildSchema(): Record<string, unknown> {
                     properties: {
                       interactive: { type: "string" },
                       autonomous: { type: "string" },
+                      headless: { type: "string" },
                     },
                   },
                 },
@@ -2928,6 +2921,7 @@ export function buildSchema(): Record<string, unknown> {
                   properties: {
                     interactive: { type: "string" },
                     autonomous: { type: "string" },
+                    headless: { type: "string" },
                   },
                 },
               },
@@ -2943,6 +2937,7 @@ export function buildSchema(): Record<string, unknown> {
                     properties: {
                       interactive: { type: "string" },
                       autonomous: { type: "string" },
+                      headless: { type: "string" },
                     },
                   },
                 },
@@ -2976,6 +2971,7 @@ export function buildSchema(): Record<string, unknown> {
                     properties: {
                       interactive: { type: "string" },
                       autonomous: { type: "string" },
+                      headless: { type: "string" },
                     },
                   },
                 },
@@ -3005,6 +3001,7 @@ export function buildSchema(): Record<string, unknown> {
                   properties: {
                     interactive: { type: "string" },
                     autonomous: { type: "string" },
+                    headless: { type: "string" },
                   },
                 },
               },
@@ -3020,6 +3017,7 @@ export function buildSchema(): Record<string, unknown> {
                     properties: {
                       interactive: { type: "string" },
                       autonomous: { type: "string" },
+                      headless: { type: "string" },
                     },
                   },
                 },
@@ -3283,6 +3281,71 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/logs/tail": {
+        get: {
+          summary: "Tail gateway log entries",
+          description:
+            "Returns the last N structured log entries from the gateway's pino log files, " +
+            "with optional filtering by minimum level and module name.",
+          operationId: "gatewayLogsTail",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "n",
+              in: "query",
+              required: false,
+              schema: { type: "integer", minimum: 1, maximum: 1000, default: 10 },
+              description: "Number of log entries to return (1–1000, default: 10)",
+            },
+            {
+              name: "level",
+              in: "query",
+              required: false,
+              schema: {
+                type: "string",
+                enum: ["trace", "debug", "info", "warn", "error", "fatal"],
+                default: "info",
+              },
+              description: "Minimum pino level name (default: info)",
+            },
+            {
+              name: "module",
+              in: "query",
+              required: false,
+              schema: { type: "string" },
+              description: "Filter to exact pino module name",
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Log entries and truncation flag",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["lines", "truncated"],
+                    properties: {
+                      lines: {
+                        type: "array",
+                        items: { type: "object" },
+                        description: "Matching log entries in chronological order",
+                      },
+                      truncated: {
+                        type: "boolean",
+                        description: "True if earlier matching entries exist beyond n",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            "400": { description: "Invalid level parameter" },
+            "401": {
+              description: "Unauthorized — missing or invalid edge JWT",
+            },
+          },
+        },
+      },
       "/v1/trust-rules": {
         get: {
           summary: "List trust rules",
@@ -3716,7 +3779,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Kick off an async export-to-GCS job",
           description:
-            "Transparent proxy to the assistant daemon's `POST /v1/migrations/export-to-gcs` endpoint. The daemon schedules a background export job that streams the workspace backup to the supplied signed GCS upload URL and returns `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) so local/docker teleport works regardless of `runtimeProxyEnabled`.",
+            "Transparent proxy to the assistant daemon's `POST /v1/migrations/export-to-gcs` endpoint. The daemon schedules a background export job that streams the workspace backup to the supplied signed GCS upload URL and returns `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
           operationId: "migrationExportToGcs",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -3755,7 +3818,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Kick off an async import-from-GCS job",
           description:
-            "Transparent proxy to the assistant daemon's `POST /v1/migrations/import-from-gcs` endpoint. The daemon schedules a background import job that fetches a `.vbundle` archive at the supplied `bundle_url` and streams it through the importer, returning `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) so local/docker teleport works regardless of `runtimeProxyEnabled`.",
+            "Transparent proxy to the assistant daemon's `POST /v1/migrations/import-from-gcs` endpoint. The daemon schedules a background import job that fetches a `.vbundle` archive at the supplied `bundle_url` and streams it through the importer, returning `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
           operationId: "migrationImportFromGcs",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -3805,7 +3868,7 @@ export function buildSchema(): Record<string, unknown> {
         get: {
           summary: "Poll unified migration job status",
           description:
-            "Transparent proxy to the assistant daemon's `GET /v1/migrations/jobs/{job_id}` endpoint. Returns the current status of an async export-to-GCS or import-from-GCS job tracked by the daemon's migration job registry. Registered explicitly (not via the runtime-proxy catch-all) so local/docker teleport works regardless of `runtimeProxyEnabled`.",
+            "Transparent proxy to the assistant daemon's `GET /v1/migrations/jobs/{job_id}` endpoint. Returns the current status of an async export-to-GCS or import-from-GCS job tracked by the daemon's migration job registry. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
           operationId: "migrationJobStatus",
           security: [{ BearerAuth: [] }],
           parameters: [
@@ -3923,8 +3986,7 @@ export function buildSchema(): Record<string, unknown> {
                   properties: {
                     type: {
                       type: "string",
-                      description:
-                        "Email provider type (e.g. resend, mailgun)",
+                      description: "Email provider type (e.g. resend, mailgun)",
                     },
                     guardian_email: {
                       type: "string",
@@ -3938,7 +4000,8 @@ export function buildSchema(): Record<string, unknown> {
           },
           responses: {
             "200": {
-              description: "Guardian email channel verified and binding created",
+              description:
+                "Guardian email channel verified and binding created",
               content: {
                 "application/json": {
                   schema: {
@@ -3994,11 +4057,111 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/backups": {
+        get: {
+          summary: "List backup snapshots",
+          description:
+            "Lists local and offsite backup snapshots. The gateway owns the backup encryption key and performs all encrypt/decrypt operations.",
+          operationId: "backupsList",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Backup snapshots listed",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["local", "offsite"],
+                    properties: {
+                      local: {
+                        type: "object",
+                        required: ["directory", "snapshots"],
+                        properties: {
+                          directory: { type: "string" },
+                          snapshots: {
+                            type: "array",
+                            items: {
+                              $ref: "#/components/schemas/BackupSnapshot",
+                            },
+                          },
+                        },
+                      },
+                      offsite: {
+                        type: "array",
+                        items: {
+                          type: "object",
+                          required: ["directory", "encrypted", "snapshots"],
+                          properties: {
+                            directory: { type: "string" },
+                            encrypted: { type: "boolean" },
+                            snapshots: {
+                              type: "array",
+                              items: {
+                                $ref: "#/components/schemas/BackupSnapshot",
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "403": { description: "Insufficient scope" },
+            "500": { description: "Internal server error" },
+          },
+        },
+      },
+      "/v1/backups/create": {
+        post: {
+          summary: "Create backup snapshot",
+          description:
+            "Triggers a manual backup snapshot. The gateway exports a plaintext vbundle from the daemon, writes it locally, and encrypts + mirrors to offsite destinations.",
+          operationId: "backupsCreate",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Backup snapshot created",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["success", "local", "offsite", "duration_ms"],
+                    properties: {
+                      success: { type: "boolean" },
+                      local: {
+                        $ref: "#/components/schemas/BackupSnapshot",
+                      },
+                      offsite: {
+                        type: "array",
+                        items: { type: "object", additionalProperties: true },
+                      },
+                      duration_ms: { type: "number" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "403": { description: "Insufficient scope" },
+            "409": {
+              description: "A backup snapshot is already in progress",
+            },
+            "500": { description: "Internal server error" },
+          },
+        },
+      },
       "/{path}": {
         get: {
           summary: "Runtime proxy",
           description:
-            "Reverse-proxies requests to the assistant runtime when gateway.runtimeProxyEnabled is true in workspace config. Supports all HTTP methods. Returns 404 when the proxy is disabled.",
+            "Reverse-proxies requests to the assistant runtime. Supports all HTTP methods.",
           operationId: "runtimeProxyGet",
           security: [{ BearerAuth: [] }],
           parameters: [
@@ -4023,7 +4186,7 @@ export function buildSchema(): Record<string, unknown> {
               },
             },
             "404": {
-              description: "Runtime proxy not enabled",
+              description: "Route not found on upstream runtime",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/ErrorResponse" },
@@ -4059,8 +4222,7 @@ export function buildSchema(): Record<string, unknown> {
         },
         post: {
           summary: "Runtime proxy",
-          description:
-            "Reverse-proxies requests to the assistant runtime when gateway.runtimeProxyEnabled is true in workspace config.",
+          description: "Reverse-proxies requests to the assistant runtime.",
           operationId: "runtimeProxyPost",
           security: [{ BearerAuth: [] }],
           parameters: [
@@ -4114,6 +4276,17 @@ export function buildSchema(): Record<string, unknown> {
     },
     components: {
       schemas: {
+        BackupSnapshot: {
+          type: "object",
+          required: ["path", "filename", "created_at", "size_bytes", "encrypted"],
+          properties: {
+            path: { type: "string" },
+            filename: { type: "string" },
+            created_at: { type: "string", format: "date-time" },
+            size_bytes: { type: "integer" },
+            encrypted: { type: "boolean" },
+          },
+        },
         HealthResponse: {
           type: "object",
           required: ["status"],

package/src/slack/normalize.test.ts

@@ -492,7 +492,9 @@ describe("DM threading", () => {
     const result = normalizeSlackDirectMessage(event, "evt-dm-1", config);
 
     expect(result).not.toBeNull();
+    expect(result!.event.source.chatType).toBe("im");
     expect(result!.threadTs).toBeUndefined();
+    expect(result!.event.source.threadId).toBeUndefined();
   });
 
   it("threaded DM preserves threadTs", () => {
@@ -501,7 +503,9 @@ describe("DM threading", () => {
     const result = normalizeSlackDirectMessage(event, "evt-dm-2", config);
 
     expect(result).not.toBeNull();
+    expect(result!.event.source.chatType).toBe("im");
     expect(result!.threadTs).toBe("1700000000.000050");
+    expect(result!.event.source.threadId).toBe("1700000000.000050");
   });
 });
 
@@ -724,6 +728,39 @@ describe("attachment extraction in normalize functions", () => {
         expect(result!.slackFiles!.get("F030")!.id).toBe("F030");
       });
 
+      it("normalizes DM file_share mentions without stripping the bot mention", () => {
+        const config = makeConfig();
+        const event = makeDmEvent({
+          subtype: "file_share",
+          text: "<@UBOT> <@ULEO> shared this",
+          files: [
+            makeSlackFile({
+              id: "F032",
+              mimetype: "image/png",
+              name: "mention.png",
+            }),
+          ],
+        });
+        const result = normalizeSlackDirectMessage(
+          event,
+          "evt-fs-mentions-dm",
+          config,
+          "UBOT",
+          undefined,
+          { userLabels: { UBOT: "assistant", ULEO: "leo" } },
+        );
+
+        expect(result).not.toBeNull();
+        expect(result!.event.message.content).toBe(
+          "@assistant @leo shared this",
+        );
+        expect(result!.event.message.content).not.toContain("ULEO");
+        expect(result!.event.message.attachments).toHaveLength(1);
+        expect(result!.event.message.attachments![0].fileId).toBe("F032");
+        expect(result!.slackFiles).toBeDefined();
+        expect(result!.slackFiles!.get("F032")!.id).toBe("F032");
+      });
+
       it("normalizes DM with file_share subtype without files", () => {
         const config = makeConfig();
         const event = makeDmEvent({ subtype: "file_share" });
@@ -765,6 +802,43 @@ describe("attachment extraction in normalize functions", () => {
         expect(result!.slackFiles).toBeDefined();
       });
 
+      it("normalizes channel file_share mentions after stripping only the bot mention", () => {
+        const config = makeConfig();
+        const event = makeChannelEvent({
+          subtype: "file_share",
+          text: "<@UBOT> <@ULEO> shared this",
+          files: [
+            makeSlackFile({
+              id: "F033",
+              mimetype: "application/pdf",
+              name: "mention.pdf",
+            }),
+          ],
+        });
+        const result = normalizeSlackChannelMessage(
+          event,
+          "evt-fs-mentions-channel",
+          config,
+          "UBOT",
+          undefined,
+          { userLabels: { ULEO: "leo" } },
+        );
+
+        expect(result).not.toBeNull();
+        expect(result!.event.message.content).toBe("@leo shared this");
+        expect(result!.event.message.content).not.toContain("ULEO");
+        expect(result!.event.message.attachments).toHaveLength(1);
+        expect(result!.event.message.attachments![0]).toEqual({
+          type: "document",
+          fileId: "F033",
+          fileName: "mention.pdf",
+          mimeType: "application/pdf",
+          fileSize: 12345,
+        });
+        expect(result!.slackFiles).toBeDefined();
+        expect(result!.slackFiles!.get("F033")!.id).toBe("F033");
+      });
+
       it("normalizes channel message with file_share subtype without files", () => {
         const config = makeConfig();
         const event = makeChannelEvent({ subtype: "file_share" });
@@ -1157,6 +1231,30 @@ describe("normalizeSlackMessageDelete", () => {
     // DMs should not be tagged as channel chat even when inferred.
     expect(result!.event.source.chatType).toBeUndefined();
   });
+
+  it("returns null when previous_message author is the bot itself", () => {
+    // Slack echoes self-deletes back via Socket Mode. Without this filter,
+    // the bot's user ID flows through as the actor and triggers a spurious
+    // ingress access-request notification to the guardian.
+    const config = makeConfig();
+    const event = makeMessageDeletedEvent({
+      channel: "D789",
+      channel_type: "im",
+      previous_message: {
+        user: "UBOT",
+        text: "deleted bot message",
+        ts: "1700000000.000100",
+      },
+    });
+    const result = normalizeSlackMessageDelete(
+      event,
+      "evt-del-self",
+      config,
+      "UBOT",
+    );
+
+    expect(result).toBeNull();
+  });
 });
 
 // --- source.threadId propagation ---