@vellumai/assistant 0.12.0-staging.1 → 0.12.0

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];
 }
 
 /**

package/node_modules/@vellumai/gateway-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);