@vellumai/vellum-gateway 0.11.3 → 0.11.4-staging.2

package/ARCHITECTURE.md

@@ -60,16 +60,16 @@ Clients open WebSocket connections through the gateway to the daemon's real-time
 
 **Query parameters:**
 
-| Parameter    | Required | Description                                                                                                                                                                                               |
-| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mimeType`   | Yes      | MIME type of the audio being streamed (e.g. `audio/webm;codecs=opus`)                                                                                                                                     |
-| `provider`   | No       | Optional STT provider identifier (`deepgram`, `google-gemini`, `openai-whisper`, `xai`). Forwarded as compatibility metadata — the runtime resolves the transcriber from config, not from this parameter. |
-| `sampleRate` | No       | Sample rate in Hz (e.g. `16000`). Passed through to the daemon.                                                                                                                                           |
-| `token`      | No       | Edge JWT (alternative to `Authorization: Bearer` header for WS upgrades)                                                                                                                                  |
+| Parameter    | Required | Description                                                                                                                                                                                                                                                                              |
+| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mimeType`   | Yes      | MIME type of the audio being streamed (e.g. `audio/webm;codecs=opus`)                                                                                                                                                                                                                    |
+| `provider`   | No       | Optional STT provider identifier (any ID in the daemon's STT provider catalog, e.g. `deepgram`, `deepgram-flux`, `google-gemini`). Forwarded as compatibility metadata, and the gateway does not validate it: the runtime resolves the transcriber from config, not from this parameter. |
+| `sampleRate` | No       | Sample rate in Hz (e.g. `16000`). Passed through to the daemon.                                                                                                                                                                                                                          |
+| `token`      | No       | Edge JWT (alternative to `Authorization: Bearer` header for WS upgrades)                                                                                                                                                                                                                 |
 
 **Auth model:** STT streaming is an authenticated, assistant-scoped path. The client must present a valid edge JWT with an actor principal. Service tokens are rejected. When `runtimeProxyRequireAuth` is globally disabled (dev bypass), the upgrade proceeds without token validation.
 
-**Proxy behavior:** The gateway buffers up to 100 downstream messages while the upstream connection to the daemon is being established. If the buffer overflows, the downstream connection is closed with code 1008 (policy violation). Once the upstream connection opens, buffered messages are flushed in order. All subsequent messages are forwarded bidirectionally: client audio frames flow upstream, daemon transcript events (JSON text frames: `ready`, `partial`, `final`, `error`, `closed`) flow downstream. When either side closes, the other side is closed with the same code/reason.
+**Proxy behavior:** The gateway buffers up to 100 downstream messages while the upstream connection to the daemon is being established. If the buffer overflows, the downstream connection is closed with code 1008 (policy violation). Once the upstream connection opens, buffered messages are flushed in order. All subsequent messages are forwarded bidirectionally: client audio frames flow upstream, daemon session events (JSON text frames: `ready`, the transcript and turn-boundary events of the daemon's `SttStreamServerEvent` union, and `error` / `closed`) flow downstream. The gateway forwards these opaquely and needs no change when the daemon adds an event type. When either side closes, the other side is closed with the same code/reason.
 
 **Key source files:**
 

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

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];

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

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];

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

@@ -10,6 +10,8 @@
 
 import { z } from "zod";
 
+import type { TrustClass } from "./trust-verdict-contract.js";
+
 /**
  * Per-channel inbound admission policy — ordered from most-restrictive
  * (`no_one`, hard kill switch) to most-permissive (`strangers`, admits any
@@ -101,3 +103,35 @@ export function isAdmissionPolicy(value: unknown): value is AdmissionPolicy {
     (ADMISSION_POLICY_VALUES as readonly string[]).includes(value)
   );
 }
+
+/**
+ * Trust-class ordinal compared against {@link ADMISSION_FLOOR} to make the
+ * admission decision. Higher rank = more trusted. Blocked and revoked members
+ * never reach this comparison, short-circuiting to deny on member status, so
+ * they carry no rank.
+ */
+export const TRUST_CLASS_RANK: Record<TrustClass, number> = {
+  guardian: 4,
+  trusted_contact: 3,
+  unverified_contact: 2,
+  unknown: 1,
+};
+
+/**
+ * Whether a sender of this trust class clears a channel's admission floor.
+ *
+ * The two halves of the check live together because they are meaningless
+ * apart: this compares a table keyed by {@link TrustClass} against one keyed
+ * by {@link AdmissionPolicy}, and a floor added to one without a rank in the
+ * other silently admits or denies everyone.
+ *
+ * Both enforcement points read this. The runtime's admission stage answers for
+ * every channel it receives; the gateway answers for a channel it delivers
+ * somewhere other than the runtime, where there is no later stage to ask.
+ */
+export function meetsAdmissionFloor(
+  policy: AdmissionPolicy,
+  trustClass: TrustClass,
+): boolean {
+  return TRUST_CLASS_RANK[trustClass] >= ADMISSION_FLOOR[policy];
+}

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

@@ -71,6 +71,8 @@ export {
   isAdmissionPolicy,
   isAdmissionPolicyExemptChannel,
   isAdmissionPolicyHiddenChannel,
+  meetsAdmissionFloor,
+  TRUST_CLASS_RANK,
 } from "./admission-policy-contract.js";
 
 export type { AdmissionPolicy } from "./admission-policy-contract.js";

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

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];

package/openapi.json

@@ -388,6 +388,7 @@
                                 "description": { "type": "string" },
                                 "credential": { "type": "string" },
                                 "served": { "type": "boolean" },
+                                "deliversInbound": { "type": "boolean" },
                                 "verification": {
                                   "type": "object",
                                   "properties": {
@@ -406,7 +407,8 @@
                                 "handshake",
                                 "description",
                                 "credential",
-                                "served"
+                                "served",
+                                "deliversInbound"
                               ],
                               "additionalProperties": false
                             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.11.3",
+  "version": "0.11.4-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/log-redact.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, test } from "bun:test";
+
+import { logSerializers } from "../log-redact.js";
+
+const {
+  err: errSerializer,
+  req: reqSerializer,
+  res: resSerializer,
+} = logSerializers;
+
+// ---------------------------------------------------------------------------
+// Bearer token
+// ---------------------------------------------------------------------------
+
+describe("bearer token redaction", () => {
+  test("redacts a bearer token in a string value", () => {
+    const out = reqSerializer({
+      headers: { host: "api.example.com", accept: "Bearer eyJhbGci.abc.def" },
+    });
+    expect(JSON.stringify(out)).not.toContain("eyJhbGci");
+    expect(JSON.stringify(out)).toContain("Bearer [REDACTED]");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// API-key patterns - sourced from service-contracts (these were missing from
+// the old hardcoded gateway list and are the main motivation for this change)
+// ---------------------------------------------------------------------------
+
+describe("API key patterns from service-contracts", () => {
+  // Patterns that were MISSING from the old hardcoded gateway list
+  test("redacts a Linear API key (lin_api_...)", () => {
+    const key = "lin_api_" + "a".repeat(32);
+    const out = resSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Notion integration token (ntn_...)", () => {
+    const key = "ntn_" + "b".repeat(40);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts an OpenRouter API key (sk-or-v1-...)", () => {
+    const key = "sk-or-v1-" + "c".repeat(40);
+    const out = reqSerializer({ url: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a PyPI token (pypi-...)", () => {
+    const key = "pypi-" + "d".repeat(50);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Fireworks API key (fw_...)", () => {
+    const key = "fw_" + "e".repeat(32);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Perplexity API key (pplx-...)", () => {
+    const key = "pplx-" + "f".repeat(40);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Tavily API key (tvly-...)", () => {
+    const key = "tvly-" + "g".repeat(20);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Firecrawl API key (fc-...)", () => {
+    const key = "fc-" + "h".repeat(20);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Slack App token (xapp-...)", () => {
+    const key = "xapp-1-ABC12345-9876543210-abcdefghij1234567890";
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Mailgun API key (key-...)", () => {
+    const key = "key-" + "a".repeat(32);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts a Twilio API key (SK...)", () => {
+    const key = "SK" + "a1b2c3d4e5f6".repeat(3).slice(0, 32);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  // Patterns that were already in the old list (regression guard)
+  test("redacts an Anthropic API key (sk-ant-...)", () => {
+    const key = "sk-ant-" + "A".repeat(80);
+    const out = reqSerializer({ authorization: `Bearer ${key}` });
+    expect(JSON.stringify(out)).not.toContain(key);
+  });
+
+  test("redacts a GitHub token (ghp_...)", () => {
+    const key = "ghp_" + "Z".repeat(36);
+    const out = reqSerializer({ body: `token=${key}` });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts an OpenAI project key (sk-proj-...)", () => {
+    const key = "sk-proj-" + "X".repeat(40);
+    const out = reqSerializer({ body: key });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Sensitive headers - always fully redacted regardless of value
+// ---------------------------------------------------------------------------
+
+describe("sensitive header redaction", () => {
+  test("redacts authorization header", () => {
+    const out = reqSerializer({
+      headers: { authorization: "Bearer secret-token" },
+    });
+    expect((out as Record<string, unknown>).headers).toEqual({
+      authorization: "[REDACTED]",
+    });
+  });
+
+  test("redacts x-api-key header", () => {
+    const out = reqSerializer({ headers: { "x-api-key": "my-key-value" } });
+    expect((out as Record<string, unknown>).headers).toEqual({
+      "x-api-key": "[REDACTED]",
+    });
+  });
+
+  test("redacts x-vellum-velay-bridge-auth header", () => {
+    const out = reqSerializer({
+      headers: { "x-vellum-velay-bridge-auth": "bridge-secret-123" },
+    });
+    expect((out as Record<string, unknown>).headers).toEqual({
+      "x-vellum-velay-bridge-auth": "[REDACTED]",
+    });
+  });
+
+  test("redacts cookie and set-cookie headers", () => {
+    const out = reqSerializer({
+      headers: {
+        cookie: "session=abc123",
+        "set-cookie": "session=xyz; HttpOnly",
+      },
+    });
+    const headers = (out as Record<string, unknown>).headers as Record<
+      string,
+      unknown
+    >;
+    expect(headers.cookie).toBe("[REDACTED]");
+    expect(headers["set-cookie"]).toBe("[REDACTED]");
+  });
+
+  test("header name matching is case-insensitive", () => {
+    const out = reqSerializer({ headers: { Authorization: "token xyz" } });
+    const headers = (out as Record<string, unknown>).headers as Record<
+      string,
+      unknown
+    >;
+    expect(headers.Authorization).toBe("[REDACTED]");
+  });
+
+  test("non-sensitive headers pass through unchanged", () => {
+    const out = reqSerializer({
+      headers: { "content-type": "application/json" },
+    });
+    expect((out as Record<string, unknown>).headers).toEqual({
+      "content-type": "application/json",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Deep object / array traversal
+// ---------------------------------------------------------------------------
+
+describe("deep value redaction", () => {
+  test("redacts secrets nested inside an object", () => {
+    const key = "lin_api_" + "x".repeat(32);
+    const out = reqSerializer({ outer: { inner: { value: key } } });
+    expect(JSON.stringify(out)).not.toContain(key);
+    expect(JSON.stringify(out)).toContain("[REDACTED]");
+  });
+
+  test("redacts secrets inside an array", () => {
+    const key = "ghp_" + "Y".repeat(36);
+    const out = reqSerializer({ items: [key, "safe-value"] });
+    const items = (out as Record<string, unknown>).items as unknown[];
+    expect(items[0]).toBe("[REDACTED]");
+    expect(items[1]).toBe("safe-value");
+  });
+
+  test("stops recursing at depth 8 to prevent stack overflow", () => {
+    // Build an object 10 levels deep - beyond the depth cap it returns as-is
+    let deep: unknown = "leaf-value";
+    for (let i = 0; i < 10; i++) {
+      deep = { child: deep };
+    }
+    // Should not throw; the leaf may survive redaction past depth 8
+    expect(() => reqSerializer(deep)).not.toThrow();
+  });
+
+  test("non-object, non-string, non-array values pass through unchanged", () => {
+    const out = reqSerializer({ count: 42, flag: true, nothing: null });
+    expect(out).toEqual({ count: 42, flag: true, nothing: null });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error serializer
+// ---------------------------------------------------------------------------
+
+describe("err serializer", () => {
+  test("extracts name, message, stack from an Error", () => {
+    const err = new Error("something broke");
+    const out = errSerializer(err) as Record<string, unknown>;
+    expect(out.name).toBe("Error");
+    expect(out.message).toBe("something broke");
+    expect(typeof out.stack).toBe("string");
+  });
+
+  test("redacts a secret embedded in the error message", () => {
+    const key = "sk-ant-" + "B".repeat(80);
+    const err = new Error(`connection failed: auth=${key}`);
+    const out = errSerializer(err) as Record<string, unknown>;
+    expect(out.message as string).not.toContain(key);
+    expect(out.message as string).toContain("[REDACTED]");
+  });
+
+  test("walks the cause chain and redacts secrets in nested causes", () => {
+    const key = "ghp_" + "C".repeat(36);
+    const cause = new Error(`token=${key}`);
+    const err = new Error("outer error", { cause });
+    const out = errSerializer(err) as Record<string, unknown>;
+    const causeOut = out.cause as Record<string, unknown>;
+    expect(causeOut.message as string).not.toContain(key);
+    expect(causeOut.message as string).toContain("[REDACTED]");
+  });
+
+  test("preserves structured code property on errors", () => {
+    const err = Object.assign(new Error("auth failed"), {
+      code: "AUTH_EXPIRED",
+    });
+    const out = errSerializer(err) as Record<string, unknown>;
+    expect(out.code).toBe("AUTH_EXPIRED");
+  });
+
+  test("preserves extra enumerable properties", () => {
+    const err = Object.assign(new Error("oops"), { statusCode: 429 });
+    const out = errSerializer(err) as Record<string, unknown>;
+    expect(out.statusCode).toBe(429);
+  });
+
+  test("non-Error values pass through the err serializer unchanged", () => {
+    expect(errSerializer("a string")).toBe("a string");
+    expect(errSerializer(null)).toBeNull();
+    expect(errSerializer(42)).toBe(42);
+  });
+});

package/src/__tests__/telegram-webhook-manager.test.ts

@@ -481,6 +481,72 @@ describe("reconcileTelegramWebhook", () => {
     ]);
   });
 
+  test("prefers the managed callback route over the Velay ingress URL on platform pods", async () => {
+    const calls: string[] = [];
+    let registeredUrl: string | undefined;
+    process.env.IS_PLATFORM = "true";
+    // A platform pod always has an `ingress.publicBaseUrl`: the Velay tunnel
+    // client publishes one at boot. It must not win over the managed callback
+    // route — the Velay address dies with the tunnel, and the daemon's
+    // `hasWebhookRoutingConfigured` reports this pod as managed-callback mode.
+    const caches = makeCaches({
+      ingressUrl:
+        "https://velay.vellum.ai/11111111-2222-4333-8444-555555555555",
+      platformBaseUrl: "https://platform.example.com",
+      assistantApiKey: "ast-managed-key",
+      platformAssistantId: "11111111-2222-4333-8444-555555555555",
+    });
+
+    fetchMock = mock(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const url =
+          typeof input === "string"
+            ? input
+            : input instanceof URL
+              ? input.toString()
+              : input.url;
+        if (url.includes("/callback-routes/register/")) {
+          calls.push("registerCallbackRoute");
+          return new Response(
+            JSON.stringify({
+              callback_url:
+                "https://platform.example.com/v1/gateway/callbacks/11111111-2222-4333-8444-555555555555/webhooks/telegram/",
+            }),
+            { status: 201, headers: { "content-type": "application/json" } },
+          );
+        }
+        if (url.includes("/getWebhookInfo")) {
+          calls.push("getWebhookInfo");
+          return makeTelegramResponse({
+            url: "",
+            has_custom_certificate: false,
+            pending_update_count: 0,
+          });
+        }
+        if (url.includes("/setWebhook")) {
+          calls.push("setWebhook");
+          const body = init?.body
+            ? (JSON.parse(init.body as string) as { url?: string })
+            : undefined;
+          registeredUrl = body?.url;
+          return makeTelegramResponse(true);
+        }
+        return new Response("Not found", { status: 404 });
+      },
+    );
+
+    await reconcileTelegramWebhook(caches);
+
+    expect(calls).toEqual([
+      "registerCallbackRoute",
+      "getWebhookInfo",
+      "setWebhook",
+    ]);
+    expect(registeredUrl).toBe(
+      "https://platform.example.com/v1/gateway/callbacks/11111111-2222-4333-8444-555555555555/webhooks/telegram/",
+    );
+  });
+
   test("does not call Telegram when ingress is disabled but credentials are absent", async () => {
     fetchMock = mock(async () => new Response("", { status: 200 }));
 

package/src/channels/inbound-event.ts

@@ -10,7 +10,7 @@ import type { ChannelId } from "./types.js";
 
 export type InboundChannelId = Extract<
   ChannelId,
-  "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord"
+  "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin"
 >;
 
 interface InboundEventBase<C extends InboundChannelId> {
@@ -93,6 +93,14 @@ export type A2aInboundEvent = InboundEventBase<"a2a">;
  * `conversationExternalId` a private address.
  */
 export type DiscordInboundEvent = InboundEventBase<"discord">;
+/**
+ * Constructed by `plugin-inbound.ts` from a plugin's reply to a verified
+ * webhook delivery. One channel covers every plugin, so `conversationExternalId`
+ * and `actorExternalId` are both prefixed with the plugin's directory name and
+ * `source.chatType` carries whatever the plugin reported. Which plugin it was
+ * reaches the runtime on `sourceMetadata`, not here.
+ */
+export type PluginInboundEvent = InboundEventBase<"plugin">;
 
 export type GatewayInboundEvent =
   | TelegramInboundEvent
@@ -100,4 +108,5 @@ export type GatewayInboundEvent =
   | SlackInboundEvent
   | EmailInboundEvent
   | A2aInboundEvent
-  | DiscordInboundEvent;
+  | DiscordInboundEvent
+  | PluginInboundEvent;