@vellumai/assistant 0.11.11-staging.4 → 0.12.0-dev.202609110918.dd3fa5e

package/AGENTS.md

@@ -87,6 +87,10 @@ The module-level dependency-injection pattern (`registerFooDeps()`) used by some
 
 Telemetry event types are defined by a platform-generated wire contract (`src/telemetry/telemetry-wire.generated.ts`) that `src/telemetry/types.ts` layers over, with pre-flush validation against it. Adding a new event type starts platform-side, not here. The mechanics, the drift guards, and the cross-repo ordering are documented next to the code they govern: see [`src/telemetry/AGENTS.md`](src/telemetry/AGENTS.md).
 
+## Daemon i18n
+
+User-facing copy the daemon generates as a hardcoded constant goes through `src/i18n/`. Persist the message key. Resolve with `t(key, locale)` at the HTTP/CLI/channel edge. Never persist a translated string, and never match stored display strings back to keys. See [`src/i18n/AGENTS.md`](src/i18n/AGENTS.md).
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/ARCHITECTURE.md

@@ -729,9 +729,9 @@ The assistant-side live voice module is intentionally bounded under `src/live-vo
 | `live-voice-archive.ts`         | Audio artifact creation/linking for user utterance and assistant response message IDs                                                                       |
 | `live-voice-metrics.ts`         | Per-session and per-turn latency snapshots emitted as `metrics` frames                                                                                      |
 
-Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming. For V1 latency-sensitive behavior, the selected `services.stt.provider` must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
+Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming, dialed with the provider the `liveVoice` STT role resolves to after managed-speech defaulting (`resolveEffectiveSpeechProviders`, see `config/managed-speech-defaults.ts`). For V1 latency-sensitive behavior, that provider must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
 
-Live voice TTS uses `streamLiveVoiceTtsAudio()` and the configured `services.tts.provider`. The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all four catalog providers: ElevenLabs, Fish Audio, Deepgram, and xAI) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
+Live voice TTS uses `streamLiveVoiceTtsAudio()` and the TTS provider that `resolveEffectiveSpeechProviders` settles on (the configured `services.tts.provider`, or the managed `vellum` provider when the configured one has no usable credentials). The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all five catalog providers: ElevenLabs, Fish Audio, Deepgram, xAI, and the managed Vellum provider) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
 
 The `voiceFrontDoor` prompt skips current-turn legacy and v3 memory retrieval, while prior frozen memory cards and static memory context remain available. The front-door rule escalates rather than guessing when required personal context is absent. The escalated leg runs the ordinary memory pipeline against the latest visible caller prompt before the quality model, with low selector effort. This keeps memory work off the front-door TTFT path without cross-leg speculative state.
 

package/Dockerfile

@@ -108,6 +108,7 @@ RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 COPY --link --from=builder /app /app
 
 # Copy source after installing dependencies for better layer caching.
+COPY packages/app-icons /app/packages/app-icons
 COPY packages/avatar-catalog /app/packages/avatar-catalog
 COPY packages/avatar-manifest /app/packages/avatar-manifest
 COPY packages/ces-client /app/packages/ces-client
@@ -122,6 +123,10 @@ COPY packages/twilio-client /app/packages/twilio-client
 
 COPY assistant /app/assistant
 
+# Resolve production workspace dependencies from the filesystem layout shipped
+# in the image.
+RUN bun run scripts/smoke-container-workspace-dependencies.ts
+
 # The repo-root .dockerignore decides which skills (and files) ship.
 COPY skills /app/skills
 

package/docs/architecture/turn-actor.md

@@ -60,6 +60,15 @@ and restore the prior value afterwards, each guarding the restore so a turn that
 started in between is not clobbered. They are supplying the acting actor for
 their run, and are covered by this contract.
 
+A queued message commits to a run at its drain, not at its enqueue. The drains
+(`drainSingleMessage` and `drainBatch` in `conversation-process.ts`) stamp the
+queued sender the way `processMessage` stamps its committing actor, and re-scope
+the resident history to them, so a turn drained behind another actor's turn
+runs as its sender everywhere the resting actor is read, not only in the
+per-turn snapshot. A steered drain skips the re-scope: its sender owned the
+turn it cut off, and the resident history may carry the in-memory repair of the
+abandoned `tool_use`.
+
 `call-controller` keeps its own `trustContext` on its own object and never reads
 the conversation's. It is outside this contract.
 

package/knip.json

@@ -15,6 +15,7 @@
   "ignore": ["src/config/preloaded-apps/**"],
   "ignoreDependencies": [
     "@microsoft/api-extractor",
+    "@vellumai/app-icons",
     "@vellumai/avatar-catalog",
     "@vellumai/avatar-manifest",
     "@vellumai/ces-client",

package/node_modules/@vellumai/app-icons/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/app-icons",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/app-icons/src/index.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  APP_ICON_NAMES,
+  bridgeEmojiAppIcon,
+  EMOJI_ICON_NAMES,
+  isAppIconName,
+  isEmojiAppIcon,
+  normalizeAppIcon,
+} from "./index.js";
+
+describe("APP_ICON_NAMES", () => {
+  test("is kebab-case and free of duplicates", () => {
+    expect(new Set(APP_ICON_NAMES).size).toBe(APP_ICON_NAMES.length);
+    for (const name of APP_ICON_NAMES) {
+      expect(name).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    }
+    expect(isAppIconName("calculator")).toBe(true);
+    expect(isAppIconName("not-an-icon")).toBe(false);
+  });
+
+  test("every emoji maps to a registry name", () => {
+    for (const name of Object.values(EMOJI_ICON_NAMES)) {
+      expect(isAppIconName(name)).toBe(true);
+    }
+  });
+});
+
+describe("isEmojiAppIcon", () => {
+  test("accepts an emoji, a sequence, and a keycap", () => {
+    expect(isEmojiAppIcon("☕")).toBe(true);
+    expect(isEmojiAppIcon("☕️")).toBe(true);
+    expect(isEmojiAppIcon("👨‍💻")).toBe(true);
+    expect(isEmojiAppIcon("1️⃣")).toBe(true);
+    expect(isEmojiAppIcon("👍🏽")).toBe(true);
+  });
+
+  test("rejects text, text around an emoji, and bare marks", () => {
+    expect(isEmojiAppIcon("coffee")).toBe(false);
+    expect(isEmojiAppIcon("coffee ☕")).toBe(false);
+    expect(isEmojiAppIcon("☕ coffee")).toBe(false);
+    expect(isEmojiAppIcon("\u200D")).toBe(false);
+    expect(isEmojiAppIcon("")).toBe(false);
+  });
+});
+
+describe("bridgeEmojiAppIcon", () => {
+  test("maps a known emoji to its name, with or without the selector", () => {
+    expect(bridgeEmojiAppIcon("🔢")).toBe("calculator");
+    expect(bridgeEmojiAppIcon("☕️")).toBe("coffee");
+  });
+
+  test("passes everything else through, prototype names included", () => {
+    expect(bridgeEmojiAppIcon("calculator")).toBe("calculator");
+    expect(bridgeEmojiAppIcon("1️⃣")).toBe("1️⃣");
+    expect(bridgeEmojiAppIcon("constructor")).toBe("constructor");
+    expect(bridgeEmojiAppIcon(undefined)).toBeUndefined();
+  });
+});
+
+describe("normalizeAppIcon", () => {
+  test("keeps a registry name, normalised to its kebab-case key", () => {
+    expect(normalizeAppIcon("calculator")).toBe("calculator");
+    expect(normalizeAppIcon(" Calculator ")).toBe("calculator");
+    expect(normalizeAppIcon("List-Todo")).toBe("list-todo");
+  });
+
+  test("maps a known emoji and keeps an unknown one", () => {
+    expect(normalizeAppIcon("☕")).toBe("coffee");
+    expect(normalizeAppIcon("🔢")).toBe("calculator");
+    expect(normalizeAppIcon("1️⃣")).toBe("1️⃣");
+  });
+
+  test("drops URLs, text around an emoji, unknown names, empties, non-strings", () => {
+    expect(normalizeAppIcon("https://example.com/icon.png")).toBeUndefined();
+    expect(normalizeAppIcon("http://x/y.svg")).toBeUndefined();
+    expect(normalizeAppIcon("coffee ☕")).toBeUndefined();
+    expect(normalizeAppIcon("not-an-icon")).toBeUndefined();
+    expect(normalizeAppIcon("constructor")).toBeUndefined();
+    expect(normalizeAppIcon("")).toBeUndefined();
+    expect(normalizeAppIcon("   ")).toBeUndefined();
+    expect(normalizeAppIcon(42)).toBeUndefined();
+    expect(normalizeAppIcon(undefined)).toBeUndefined();
+  });
+});

package/node_modules/@vellumai/app-icons/src/index.ts

@@ -0,0 +1,387 @@
+/**
+ * The icons an app can wear, shared by the assistant (which picks and stores
+ * one on an app's manifest) and the web client (which draws it).
+ *
+ * An app's `icon` is a Lucide kebab-case name from {@link APP_ICON_NAMES}.
+ * The assistant chooses it at `app_create`; the web client keeps the
+ * name-to-glyph map, typed against {@link AppIconName} so a name added here
+ * without a glyph there fails its typecheck. A manifest may also carry an
+ * emoji in place of a name; {@link EMOJI_ICON_NAMES} maps the common ones to
+ * the name each stands for, and both sides apply the map.
+ */
+
+export const APP_ICON_NAMES = [
+  "calculator",
+  "calendar",
+  "list-todo",
+  "list-checks",
+  "square-check",
+  "timer",
+  "clock",
+  "alarm-clock",
+  "notebook-pen",
+  "sticky-note",
+  "pencil",
+  "file-text",
+  "clipboard-list",
+  "bookmark",
+  "book",
+  "book-open",
+  "chart-bar",
+  "chart-line",
+  "chart-pie",
+  "table",
+  "square-kanban",
+  "database",
+  "gauge",
+  "activity",
+  "target",
+  "flag",
+  "trophy",
+  "wallet",
+  "dollar-sign",
+  "piggy-bank",
+  "credit-card",
+  "receipt",
+  "percent",
+  "shopping-cart",
+  "package",
+  "gift",
+  "ticket",
+  "mail",
+  "inbox",
+  "message-square",
+  "phone",
+  "bell",
+  "users",
+  "contact",
+  "music",
+  "headphones",
+  "mic",
+  "video",
+  "film",
+  "tv",
+  "play",
+  "image",
+  "camera",
+  "gamepad-2",
+  "puzzle",
+  "party-popper",
+  "smile",
+  "map",
+  "map-pin",
+  "compass",
+  "globe",
+  "plane",
+  "car",
+  "bus",
+  "bike",
+  "ship",
+  "truck",
+  "house",
+  "bed",
+  "briefcase",
+  "graduation-cap",
+  "languages",
+  "brain",
+  "lightbulb",
+  "heart",
+  "heart-pulse",
+  "dumbbell",
+  "pill",
+  "stethoscope",
+  "baby",
+  "paw-print",
+  "utensils",
+  "coffee",
+  "wine",
+  "beer",
+  "cake",
+  "apple",
+  "carrot",
+  "salad",
+  "egg",
+  "fish",
+  "cloud",
+  "sun",
+  "moon",
+  "umbrella",
+  "snowflake",
+  "thermometer",
+  "droplets",
+  "flame",
+  "leaf",
+  "mountain",
+  "code",
+  "terminal",
+  "cpu",
+  "bot",
+  "wifi",
+  "lock",
+  "key",
+  "shield",
+  "settings",
+  "wrench",
+  "plug",
+  "battery",
+  "search",
+  "link",
+  "hash",
+  "layers",
+  "folder-open",
+  "palette",
+  "pen-tool",
+  "ruler",
+  "scale",
+  "scissors",
+  "shirt",
+  "newspaper",
+  "repeat",
+  "shuffle",
+  "volume-2",
+  "speaker",
+  "star",
+  "sparkles",
+  "zap",
+  "rocket",
+  "home",
+] as const;
+
+export type AppIconName = (typeof APP_ICON_NAMES)[number];
+
+const APP_ICON_NAME_SET: ReadonlySet<string> = new Set(APP_ICON_NAMES);
+
+export function isAppIconName(value: string): value is AppIconName {
+  return APP_ICON_NAME_SET.has(value);
+}
+
+/**
+ * Emoji a manifest may carry as its icon, each mapped to the registry name
+ * it stands for. Keys carry no variation selector; the lookup strips it.
+ */
+export const EMOJI_ICON_NAMES: Readonly<Record<string, AppIconName>> = {
+  "🔢": "calculator",
+  "🧮": "calculator",
+  "📅": "calendar",
+  "🗓": "calendar",
+  "✅": "list-todo",
+  "☑": "list-checks",
+  "⏱": "timer",
+  "⏲": "timer",
+  "⏰": "alarm-clock",
+  "🕐": "clock",
+  "🕒": "clock",
+  "📝": "notebook-pen",
+  "🗒": "sticky-note",
+  "✏": "pencil",
+  "📄": "file-text",
+  "📋": "clipboard-list",
+  "🔖": "bookmark",
+  "📚": "book",
+  "📖": "book-open",
+  "📔": "notebook-pen",
+  "📊": "chart-bar",
+  "📈": "chart-line",
+  "📉": "chart-line",
+  "🥧": "chart-pie",
+  "🗄": "database",
+  "🎯": "target",
+  "🚩": "flag",
+  "🏆": "trophy",
+  "🏁": "flag",
+  "💰": "wallet",
+  "💵": "dollar-sign",
+  "💲": "dollar-sign",
+  "🐷": "piggy-bank",
+  "💳": "credit-card",
+  "🧾": "receipt",
+  "🛒": "shopping-cart",
+  "🛍": "shopping-cart",
+  "📦": "package",
+  "🎁": "gift",
+  "🎟": "ticket",
+  "🎫": "ticket",
+  "✉": "mail",
+  "📧": "mail",
+  "📨": "mail",
+  "📥": "inbox",
+  "💬": "message-square",
+  "🗨": "message-square",
+  "📞": "phone",
+  "☎": "phone",
+  "🔔": "bell",
+  "👥": "users",
+  "👤": "contact",
+  "🎵": "music",
+  "🎶": "music",
+  "🎧": "headphones",
+  "🎤": "mic",
+  "🎙": "mic",
+  "📹": "video",
+  "🎬": "film",
+  "🎥": "film",
+  "📺": "tv",
+  "▶": "play",
+  "🖼": "image",
+  "📷": "camera",
+  "📸": "camera",
+  "🎮": "gamepad-2",
+  "🕹": "gamepad-2",
+  "🧩": "puzzle",
+  "🎉": "party-popper",
+  "🎊": "party-popper",
+  "😀": "smile",
+  "🙂": "smile",
+  "🗺": "map",
+  "📍": "map-pin",
+  "🧭": "compass",
+  "🌍": "globe",
+  "🌎": "globe",
+  "🌏": "globe",
+  "✈": "plane",
+  "🚗": "car",
+  "🚌": "bus",
+  "🚲": "bike",
+  "🚢": "ship",
+  "🚚": "truck",
+  "🏠": "house",
+  "🏡": "house",
+  "🛏": "bed",
+  "💼": "briefcase",
+  "🎓": "graduation-cap",
+  "🌐": "languages",
+  "🧠": "brain",
+  "💡": "lightbulb",
+  "❤": "heart",
+  "💗": "heart-pulse",
+  "🏋": "dumbbell",
+  "💪": "dumbbell",
+  "💊": "pill",
+  "🩺": "stethoscope",
+  "👶": "baby",
+  "🐾": "paw-print",
+  "🐶": "paw-print",
+  "🐱": "paw-print",
+  "🍽": "utensils",
+  "🍴": "utensils",
+  "☕": "coffee",
+  "🍷": "wine",
+  "🍺": "beer",
+  "🍰": "cake",
+  "🎂": "cake",
+  "🍎": "apple",
+  "🥕": "carrot",
+  "🥗": "salad",
+  "🥚": "egg",
+  "🐟": "fish",
+  "☁": "cloud",
+  "🌤": "cloud",
+  "☀": "sun",
+  "🌞": "sun",
+  "🌙": "moon",
+  "☂": "umbrella",
+  "🌧": "umbrella",
+  "❄": "snowflake",
+  "🌡": "thermometer",
+  "💧": "droplets",
+  "🔥": "flame",
+  "🌱": "leaf",
+  "🍃": "leaf",
+  "🏔": "mountain",
+  "⛰": "mountain",
+  "💻": "code",
+  "👨‍💻": "code",
+  "🖥": "terminal",
+  "⌨": "terminal",
+  "🤖": "bot",
+  "📡": "wifi",
+  "🔒": "lock",
+  "🔐": "lock",
+  "🔑": "key",
+  "🛡": "shield",
+  "⚙": "settings",
+  "🔧": "wrench",
+  "🛠": "wrench",
+  "🔌": "plug",
+  "🔋": "battery",
+  "🔍": "search",
+  "🔎": "search",
+  "🔗": "link",
+  "#️⃣": "hash",
+  "📁": "folder-open",
+  "📂": "folder-open",
+  "🎨": "palette",
+  "🖌": "pen-tool",
+  "📏": "ruler",
+  "⚖": "scale",
+  "✂": "scissors",
+  "👕": "shirt",
+  "📰": "newspaper",
+  "🔁": "repeat",
+  "🔀": "shuffle",
+  "🔊": "volume-2",
+  "⭐": "star",
+  "🌟": "star",
+  "✨": "sparkles",
+  "⚡": "zap",
+  "🚀": "rocket",
+};
+
+const VARIATION_SELECTORS = /[\uFE0E\uFE0F]/gu;
+
+/* A value that is nothing but emoji: pictographs, emoji-presentation
+   characters, skin-tone modifiers, the joiner that composes a sequence, the
+   variation selectors, and keycap sequences (a digit, `#` or `*` with the
+   keycap mark). Anchored, so text with an emoji in it is not an emoji. */
+const EMOJI_ONLY =
+  /^(?:\p{Extended_Pictographic}|\p{Emoji_Presentation}|\p{Emoji_Modifier}|\u200D|\uFE0E|\uFE0F|[0-9#*]\uFE0F?\u20E3)+$/u;
+/* At least one glyph-bearing character, so a bare joiner or selector is not
+   an emoji either. */
+const EMOJI_GLYPH = /\p{Extended_Pictographic}|\p{Emoji_Presentation}|\u20E3/u;
+
+/** True when `value` is an emoji (or emoji sequence) and nothing else. */
+export function isEmojiAppIcon(value: string): boolean {
+  return EMOJI_ONLY.test(value) && EMOJI_GLYPH.test(value);
+}
+
+/**
+ * A stored icon as a client should read it: an emoji the map knows becomes
+ * its registry name, and anything else passes through untouched, so reading
+ * a manifest never loses an icon the map cannot place.
+ */
+export function bridgeEmojiAppIcon(
+  icon: string | undefined,
+): string | undefined {
+  if (!icon) {
+    return icon;
+  }
+  const key = icon.trim().replace(VARIATION_SELECTORS, "");
+  /* An own-property check: a bare index would find `constructor` and its
+     kin on the object's prototype. */
+  return Object.hasOwn(EMOJI_ICON_NAMES, key) ? EMOJI_ICON_NAMES[key] : icon;
+}
+
+/**
+ * The icon to persist on an app's manifest for a value the model passed: a
+ * registry name (any case) as its kebab-case key, an emoji as the name it
+ * maps to (or as itself when the map has none), and `undefined` for anything
+ * else. URLs and text around an emoji are dropped: they would render as raw
+ * strings, and an image icon is `app_generate_icon`'s job.
+ */
+export function normalizeAppIcon(raw: unknown): string | undefined {
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (trimmed === "" || /^https?:\/\//i.test(trimmed)) {
+    return undefined;
+  }
+  const name = trimmed.toLowerCase();
+  if (isAppIconName(name)) {
+    return name;
+  }
+  if (isEmojiAppIcon(trimmed)) {
+    return bridgeEmojiAppIcon(trimmed);
+  }
+  return undefined;
+}

package/node_modules/@vellumai/app-icons/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -1,8 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  botProviderForChannel,
   CHANNEL_BOT_PROVIDER,
   CHANNEL_IDS,
+  channelForBotProvider,
   isChannelBotProvider,
   isChannelUserIntegration,
   isChannelId,
@@ -41,6 +43,35 @@ describe("isChannelId", () => {
   });
 });
 
+describe("botProviderForChannel and channelForBotProvider", () => {
+  test("are inverses over every entry of the map", () => {
+    for (const [channelId, botProviderKey] of Object.entries(
+      CHANNEL_BOT_PROVIDER,
+    )) {
+      expect(botProviderForChannel(channelId)).toBe(botProviderKey);
+      expect(channelForBotProvider(botProviderKey)).toBe(
+        channelId as keyof typeof CHANNEL_BOT_PROVIDER,
+      );
+    }
+  });
+
+  test("answer nothing for a channel without a bot, a person's grant, or an unknown key", () => {
+    expect(botProviderForChannel("phone")).toBeUndefined();
+    expect(botProviderForChannel("vellum")).toBeUndefined();
+    expect(botProviderForChannel("not-a-channel")).toBeUndefined();
+    // `slack` is the person's integration standing beside the bot's key.
+    expect(channelForBotProvider("slack")).toBeUndefined();
+    expect(channelForBotProvider("google")).toBeUndefined();
+  });
+
+  test("never resolve an inherited object property as a channel or a key", () => {
+    for (const name of ["constructor", "toString", "__proto__"]) {
+      expect(botProviderForChannel(name)).toBeUndefined();
+      expect(channelForBotProvider(name)).toBeUndefined();
+    }
+  });
+});
+
 describe("isChannelUserIntegration", () => {
   test("names the grant standing beside a bot of the same brand", () => {
     expect(isChannelUserIntegration("slack")).toBe(true);

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

@@ -93,9 +93,34 @@ export const CHANNEL_BOT_PROVIDER = {
  * connected" question, for any provider key.
  */
 export function isChannelBotProvider(providerKey: string): boolean {
-  return (Object.values(CHANNEL_BOT_PROVIDER) as readonly string[]).includes(
-    providerKey,
-  );
+  return channelForBotProvider(providerKey) !== undefined;
+}
+
+/**
+ * The provider key holding a channel's bot credential, or `undefined` when
+ * the channel has none, or is not a channel at all. Walks the map's own
+ * entries, so an inherited object property name is never a channel.
+ */
+export function botProviderForChannel(channelId: string): string | undefined {
+  return Object.entries(CHANNEL_BOT_PROVIDER).find(
+    ([id]) => id === channelId,
+  )?.[1];
+}
+
+/**
+ * The channel whose bot credential a provider key holds, or `undefined` when
+ * the key is not a bot's. The inverse of `botProviderForChannel`, for a
+ * surface that has only the provider key in hand and needs to speak in the
+ * channel's vocabulary.
+ */
+export function channelForBotProvider(
+  providerKey: string,
+): keyof typeof CHANNEL_BOT_PROVIDER | undefined {
+  return (
+    Object.entries(CHANNEL_BOT_PROVIDER) as Array<
+      [keyof typeof CHANNEL_BOT_PROVIDER, string]
+    >
+  ).find(([, key]) => key === providerKey)?.[0];
 }
 
 /**