@vellumai/cli 0.11.10 → 0.11.11-staging.2

package/node_modules/@vellumai/avatar-manifest/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./accent": "./src/accent.ts"
+    "./accent": "./src/accent.ts",
+    "./notification-avatar": "./src/notification-avatar.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+  NOTIFICATION_AVATAR_INSET,
+  NOTIFICATION_AVATAR_MAX_BYTES,
+  NOTIFICATION_AVATAR_MAX_LOCAL_BYTES,
+  NOTIFICATION_AVATAR_SIZE,
+  NOTIFICATION_AVATAR_SPEC_VERSION,
+  notificationAvatarDiscHex,
+  notificationAvatarGeometry,
+  notificationAvatarSvg,
+} from "../notification-avatar.js";
+
+function allAttributes(tag: string, svg: string): Record<string, string>[] {
+  return [...svg.matchAll(new RegExp(`<${tag}\\s([^>]*)/>`, "g"))].map(
+    (match) => {
+      const out: Record<string, string> = {};
+      for (const [, name, value] of match[1]!.matchAll(
+        /([\w:-]+)="([^"]*)"/g,
+      )) {
+        out[name!] = value!;
+      }
+      return out;
+    },
+  );
+}
+
+function attributes(tag: string, svg: string): Record<string, string> {
+  const all = allAttributes(tag, svg);
+  expect(all.length).toBeGreaterThan(0);
+  return all[0]!;
+}
+
+function countOf(tag: string, svg: string): number {
+  return svg.split(`<${tag}`).length - 1;
+}
+
+const PNG_BASE64 = "iVBORw0KGgo=";
+
+describe("notificationAvatarDiscHex", () => {
+  test("mixes the accent into white", () => {
+    expect(notificationAvatarDiscHex("#E9642F")).toBe("#FCE9E2");
+    expect(notificationAvatarDiscHex("#4C9B50")).toBe("#E6F1E7");
+  });
+
+  test("is case insensitive and always returns uppercase #RRGGBB", () => {
+    expect(notificationAvatarDiscHex("#e9642f")).toBe("#FCE9E2");
+  });
+
+  test("keeps white white and lifts black to near white", () => {
+    expect(notificationAvatarDiscHex("#FFFFFF")).toBe("#FFFFFF");
+    expect(notificationAvatarDiscHex("#000000")).toBe("#DBDBDB");
+  });
+
+  test.each([
+    ["null", null],
+    ["short form", "#abc"],
+    ["no hash", "e9642f"],
+    ["garbage", "not a colour"],
+    ["empty", ""],
+  ])("falls back to the neutral disc for %s", (_label, value) => {
+    expect(notificationAvatarDiscHex(value as string | null)).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarSvg", () => {
+  test("draws one disc and one inset avatar at the default size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(countOf("svg", svg)).toBe(1);
+    expect(countOf("image", svg)).toBe(1);
+
+    expect(svg.startsWith("<svg ")).toBe(true);
+    expect(svg).toContain(`width="256" height="256"`);
+    expect(svg).toContain(`viewBox="0 0 256 256"`);
+
+    const circle = attributes("circle", svg);
+    expect(circle).toMatchObject({ cx: "128", cy: "128", r: "128" });
+    expect(circle.fill).toBe("#FCE9E2");
+
+    const inset = NOTIFICATION_AVATAR_SIZE * NOTIFICATION_AVATAR_INSET;
+    const inner = NOTIFICATION_AVATAR_SIZE - 2 * inset;
+    const image = attributes("image", svg);
+    expect(Number(image.x)).toBeCloseTo(inset, 3);
+    expect(Number(image.y)).toBeCloseTo(inset, 3);
+    expect(Number(image.width)).toBeCloseTo(inner, 3);
+    expect(Number(image.height)).toBeCloseTo(inner, 3);
+    expect(image.href).toBe(`data:image/png;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("cover-crops a non-square raster and clips it to the disc", () => {
+    // The builder never sees the source dimensions, so what makes a 1024x512
+    // upload fill the square instead of letterboxing is the pair of attributes
+    // asserted here.
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.preserveAspectRatio).toBe("xMidYMid slice");
+
+    const clipRef = image["clip-path"]!;
+    const clipId = clipRef.match(/^url\(#([\w-]+)\)$/)?.[1];
+    expect(clipId).toBeTruthy();
+    expect(svg).toContain(`<clipPath id="${clipId}">`);
+
+    // The clip circle carries the disc geometry and nothing else, so the
+    // painted disc and the boundary can never drift apart.
+    const [disc, clip] = allAttributes("circle", svg);
+    expect(clip).toEqual({ cx: "128", cy: "128", r: "128" });
+    expect(disc).toMatchObject({ cx: "128", cy: "128", r: "128" });
+  });
+
+  test("scales the geometry to a custom size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+      size: 100,
+    });
+
+    expect(svg).toContain(`width="100" height="100"`);
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: "50",
+      cy: "50",
+      r: "50",
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: "11",
+      y: "11",
+      width: "78",
+      height: "78",
+    });
+  });
+
+  test("carries a non-PNG inner raster with its own media type", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      innerMediaType: "image/jpeg",
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.href).toBe(`data:image/jpeg;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("paints the fallback disc when there is no accent", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+    });
+    expect(attributes("circle", svg).fill).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarGeometry", () => {
+  test("derives the disc, the border and the avatar edge from the size", () => {
+    expect(notificationAvatarGeometry(100)).toEqual({
+      radius: 50,
+      offset: 11,
+      inner: 78,
+    });
+  });
+
+  test("measures the default size when given none", () => {
+    expect(notificationAvatarGeometry()).toEqual(
+      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    );
+  });
+
+  test("is the geometry the SVG is drawn with", () => {
+    const size = 100;
+    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+      size,
+    });
+
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: String(radius),
+      cy: String(radius),
+      r: String(radius),
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: String(offset),
+      y: String(offset),
+      width: String(inner),
+      height: String(inner),
+    });
+  });
+});
+
+describe("the transport contract", () => {
+  test("caps a notification PNG at 128 KB for the platform sync", () => {
+    expect(NOTIFICATION_AVATAR_MAX_BYTES).toBe(128 * 1024);
+  });
+
+  test("gives the local desktop path a looser cap of its own", () => {
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBe(512 * 1024);
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBeGreaterThan(
+      NOTIFICATION_AVATAR_MAX_BYTES,
+    );
+  });
+
+  test("stamps the drawing with a spec version", () => {
+    expect(Number.isInteger(NOTIFICATION_AVATAR_SPEC_VERSION)).toBe(true);
+    expect(NOTIFICATION_AVATAR_SPEC_VERSION).toBeGreaterThan(0);
+  });
+});

package/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -0,0 +1,139 @@
+/**
+ * The notification avatar: the assistant's avatar centered on an accent-tinted
+ * disc, the icon a native notification shows as the sender.
+ *
+ * The disc is inscribed in the square, so the four corners stay transparent.
+ * That is deliberate: iOS, Android, and the Windows toast logo slot all
+ * circle-crop what they are handed, and a square of colour behind the disc
+ * would only show through as a ring on any surface that does not crop. The
+ * disc itself is fully opaque, and so is everything inside it.
+ *
+ * Every platform draws the same picture with a different rasterizer (resvg in
+ * the daemon, a canvas in the desktop renderer), so the geometry and the disc
+ * colour live here once. Pure arithmetic and string building, no decoder and
+ * no node builtins, so a browser can call it too.
+ */
+
+import { isAvatarAccentHex } from "./accent.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+export const NOTIFICATION_AVATAR_INSET = 0.11;
+
+/** The disc when the assistant has no accent. */
+export const NOTIFICATION_AVATAR_FALLBACK_DISC_HEX = "#ECEFEA";
+
+/** How much of the accent survives the mix into white. */
+const ACCENT_MIX = 0.14;
+
+/**
+ * Largest notification PNG the platform sync ships, in bytes. It bounds the
+ * `notification_avatar_base64` field of the PATCH that uploads the disc, which
+ * is what APNs and FCM later hand their clients a URL and a hash for. A
+ * photographic avatar is quantised (or dropped) to fit.
+ */
+export const NOTIFICATION_AVATAR_MAX_BYTES = 128 * 1024;
+
+/**
+ * Largest notification PNG the local desktop path carries, in bytes. The
+ * renderer composites the disc, hands it to the Electron host over IPC and the
+ * host caches it on disk, so nothing crosses a push transport and a
+ * photographic avatar that renders past the sync cap still shows.
+ */
+export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
+
+/**
+ * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
+ * a disc rendered by an older spec even when the avatar itself is unchanged.
+ */
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+
+/** The id the inner raster's clip path is referenced by inside the document. */
+const CLIP_ID = "notification-avatar-disc";
+
+/**
+ * The disc fill for an accent: the accent mixed into white, so the avatar reads
+ * against it at notification size. Uppercase `#RRGGBB`; the neutral fallback
+ * when there is no accent or the value is not a hex.
+ */
+export function notificationAvatarDiscHex(accentHex: string | null): string {
+  if (!isAvatarAccentHex(accentHex)) {
+    return NOTIFICATION_AVATAR_FALLBACK_DISC_HEX;
+  }
+  const rgb = parseInt(accentHex.slice(1), 16);
+  const mixed = (shift: number) => {
+    const channel = (rgb >> shift) & 0xff;
+    return Math.round(255 + (channel - 255) * ACCENT_MIX)
+      .toString(16)
+      .padStart(2, "0");
+  };
+  return `#${mixed(16)}${mixed(8)}${mixed(0)}`.toUpperCase();
+}
+
+/** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
+export type NotificationAvatarMediaType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif";
+
+/**
+ * The three measurements the drawing derives from the edge: the disc's radius,
+ * which is also its centre; the free border around the avatar; and the
+ * avatar's own edge. Every rasterizer reads them from here, so the daemon's
+ * SVG and the desktop canvas cannot drift.
+ */
+export function notificationAvatarGeometry(
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = size * NOTIFICATION_AVATAR_INSET;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  /** The avatar raster to draw inside the disc, base64 with no data prefix. */
+  innerPngBase64: string;
+  /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
+  innerMediaType?: NotificationAvatarMediaType;
+  accentHex: string | null;
+  size?: number;
+}
+
+/** Trims the float noise a fractional inset leaves in the coordinates. */
+function px(value: number): string {
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * The notification avatar as an SVG document: a filled disc with the avatar
+ * drawn inset into it.
+ *
+ * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
+ * canvas does, so a portrait or landscape upload fills the square instead of
+ * being letterboxed onto the disc. It is then clipped to the disc, so the disc
+ * edge is the hard boundary no matter how far a cover-crop overflows.
+ *
+ * The `<image href="data:...">` shape is the one `downscaleRaster()` in
+ * `assistant/src/platform/sync-avatar.ts` already feeds resvg, so the daemon's
+ * rasterizer is known to render it.
+ */
+export function notificationAvatarSvg({
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const href = `data:${innerMediaType};base64,${innerPngBase64}`;
+  const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${px(size)}" height="${px(size)}" viewBox="0 0 ${px(size)} ${px(size)}">` +
+    `<circle ${disc} fill="${notificationAvatarDiscHex(accentHex)}"/>` +
+    `<defs><clipPath id="${CLIP_ID}"><circle ${disc}/></clipPath></defs>` +
+    `<image x="${px(offset)}" y="${px(offset)}" width="${px(inner)}" height="${px(inner)}" ` +
+    `preserveAspectRatio="xMidYMid slice" clip-path="url(#${CLIP_ID})" ` +
+    `href="${href}" xlink:href="${href}"/></svg>`
+  );
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./accent": "./src/accent.ts"
+    "./accent": "./src/accent.ts",
+    "./notification-avatar": "./src/notification-avatar.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+  NOTIFICATION_AVATAR_INSET,
+  NOTIFICATION_AVATAR_MAX_BYTES,
+  NOTIFICATION_AVATAR_MAX_LOCAL_BYTES,
+  NOTIFICATION_AVATAR_SIZE,
+  NOTIFICATION_AVATAR_SPEC_VERSION,
+  notificationAvatarDiscHex,
+  notificationAvatarGeometry,
+  notificationAvatarSvg,
+} from "../notification-avatar.js";
+
+function allAttributes(tag: string, svg: string): Record<string, string>[] {
+  return [...svg.matchAll(new RegExp(`<${tag}\\s([^>]*)/>`, "g"))].map(
+    (match) => {
+      const out: Record<string, string> = {};
+      for (const [, name, value] of match[1]!.matchAll(
+        /([\w:-]+)="([^"]*)"/g,
+      )) {
+        out[name!] = value!;
+      }
+      return out;
+    },
+  );
+}
+
+function attributes(tag: string, svg: string): Record<string, string> {
+  const all = allAttributes(tag, svg);
+  expect(all.length).toBeGreaterThan(0);
+  return all[0]!;
+}
+
+function countOf(tag: string, svg: string): number {
+  return svg.split(`<${tag}`).length - 1;
+}
+
+const PNG_BASE64 = "iVBORw0KGgo=";
+
+describe("notificationAvatarDiscHex", () => {
+  test("mixes the accent into white", () => {
+    expect(notificationAvatarDiscHex("#E9642F")).toBe("#FCE9E2");
+    expect(notificationAvatarDiscHex("#4C9B50")).toBe("#E6F1E7");
+  });
+
+  test("is case insensitive and always returns uppercase #RRGGBB", () => {
+    expect(notificationAvatarDiscHex("#e9642f")).toBe("#FCE9E2");
+  });
+
+  test("keeps white white and lifts black to near white", () => {
+    expect(notificationAvatarDiscHex("#FFFFFF")).toBe("#FFFFFF");
+    expect(notificationAvatarDiscHex("#000000")).toBe("#DBDBDB");
+  });
+
+  test.each([
+    ["null", null],
+    ["short form", "#abc"],
+    ["no hash", "e9642f"],
+    ["garbage", "not a colour"],
+    ["empty", ""],
+  ])("falls back to the neutral disc for %s", (_label, value) => {
+    expect(notificationAvatarDiscHex(value as string | null)).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarSvg", () => {
+  test("draws one disc and one inset avatar at the default size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(countOf("svg", svg)).toBe(1);
+    expect(countOf("image", svg)).toBe(1);
+
+    expect(svg.startsWith("<svg ")).toBe(true);
+    expect(svg).toContain(`width="256" height="256"`);
+    expect(svg).toContain(`viewBox="0 0 256 256"`);
+
+    const circle = attributes("circle", svg);
+    expect(circle).toMatchObject({ cx: "128", cy: "128", r: "128" });
+    expect(circle.fill).toBe("#FCE9E2");
+
+    const inset = NOTIFICATION_AVATAR_SIZE * NOTIFICATION_AVATAR_INSET;
+    const inner = NOTIFICATION_AVATAR_SIZE - 2 * inset;
+    const image = attributes("image", svg);
+    expect(Number(image.x)).toBeCloseTo(inset, 3);
+    expect(Number(image.y)).toBeCloseTo(inset, 3);
+    expect(Number(image.width)).toBeCloseTo(inner, 3);
+    expect(Number(image.height)).toBeCloseTo(inner, 3);
+    expect(image.href).toBe(`data:image/png;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("cover-crops a non-square raster and clips it to the disc", () => {
+    // The builder never sees the source dimensions, so what makes a 1024x512
+    // upload fill the square instead of letterboxing is the pair of attributes
+    // asserted here.
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.preserveAspectRatio).toBe("xMidYMid slice");
+
+    const clipRef = image["clip-path"]!;
+    const clipId = clipRef.match(/^url\(#([\w-]+)\)$/)?.[1];
+    expect(clipId).toBeTruthy();
+    expect(svg).toContain(`<clipPath id="${clipId}">`);
+
+    // The clip circle carries the disc geometry and nothing else, so the
+    // painted disc and the boundary can never drift apart.
+    const [disc, clip] = allAttributes("circle", svg);
+    expect(clip).toEqual({ cx: "128", cy: "128", r: "128" });
+    expect(disc).toMatchObject({ cx: "128", cy: "128", r: "128" });
+  });
+
+  test("scales the geometry to a custom size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+      size: 100,
+    });
+
+    expect(svg).toContain(`width="100" height="100"`);
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: "50",
+      cy: "50",
+      r: "50",
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: "11",
+      y: "11",
+      width: "78",
+      height: "78",
+    });
+  });
+
+  test("carries a non-PNG inner raster with its own media type", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      innerMediaType: "image/jpeg",
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.href).toBe(`data:image/jpeg;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("paints the fallback disc when there is no accent", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+    });
+    expect(attributes("circle", svg).fill).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarGeometry", () => {
+  test("derives the disc, the border and the avatar edge from the size", () => {
+    expect(notificationAvatarGeometry(100)).toEqual({
+      radius: 50,
+      offset: 11,
+      inner: 78,
+    });
+  });
+
+  test("measures the default size when given none", () => {
+    expect(notificationAvatarGeometry()).toEqual(
+      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    );
+  });
+
+  test("is the geometry the SVG is drawn with", () => {
+    const size = 100;
+    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+      size,
+    });
+
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: String(radius),
+      cy: String(radius),
+      r: String(radius),
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: String(offset),
+      y: String(offset),
+      width: String(inner),
+      height: String(inner),
+    });
+  });
+});
+
+describe("the transport contract", () => {
+  test("caps a notification PNG at 128 KB for the platform sync", () => {
+    expect(NOTIFICATION_AVATAR_MAX_BYTES).toBe(128 * 1024);
+  });
+
+  test("gives the local desktop path a looser cap of its own", () => {
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBe(512 * 1024);
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBeGreaterThan(
+      NOTIFICATION_AVATAR_MAX_BYTES,
+    );
+  });
+
+  test("stamps the drawing with a spec version", () => {
+    expect(Number.isInteger(NOTIFICATION_AVATAR_SPEC_VERSION)).toBe(true);
+    expect(NOTIFICATION_AVATAR_SPEC_VERSION).toBeGreaterThan(0);
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -0,0 +1,139 @@
+/**
+ * The notification avatar: the assistant's avatar centered on an accent-tinted
+ * disc, the icon a native notification shows as the sender.
+ *
+ * The disc is inscribed in the square, so the four corners stay transparent.
+ * That is deliberate: iOS, Android, and the Windows toast logo slot all
+ * circle-crop what they are handed, and a square of colour behind the disc
+ * would only show through as a ring on any surface that does not crop. The
+ * disc itself is fully opaque, and so is everything inside it.
+ *
+ * Every platform draws the same picture with a different rasterizer (resvg in
+ * the daemon, a canvas in the desktop renderer), so the geometry and the disc
+ * colour live here once. Pure arithmetic and string building, no decoder and
+ * no node builtins, so a browser can call it too.
+ */
+
+import { isAvatarAccentHex } from "./accent.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+export const NOTIFICATION_AVATAR_INSET = 0.11;
+
+/** The disc when the assistant has no accent. */
+export const NOTIFICATION_AVATAR_FALLBACK_DISC_HEX = "#ECEFEA";
+
+/** How much of the accent survives the mix into white. */
+const ACCENT_MIX = 0.14;
+
+/**
+ * Largest notification PNG the platform sync ships, in bytes. It bounds the
+ * `notification_avatar_base64` field of the PATCH that uploads the disc, which
+ * is what APNs and FCM later hand their clients a URL and a hash for. A
+ * photographic avatar is quantised (or dropped) to fit.
+ */
+export const NOTIFICATION_AVATAR_MAX_BYTES = 128 * 1024;
+
+/**
+ * Largest notification PNG the local desktop path carries, in bytes. The
+ * renderer composites the disc, hands it to the Electron host over IPC and the
+ * host caches it on disk, so nothing crosses a push transport and a
+ * photographic avatar that renders past the sync cap still shows.
+ */
+export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
+
+/**
+ * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
+ * a disc rendered by an older spec even when the avatar itself is unchanged.
+ */
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+
+/** The id the inner raster's clip path is referenced by inside the document. */
+const CLIP_ID = "notification-avatar-disc";
+
+/**
+ * The disc fill for an accent: the accent mixed into white, so the avatar reads
+ * against it at notification size. Uppercase `#RRGGBB`; the neutral fallback
+ * when there is no accent or the value is not a hex.
+ */
+export function notificationAvatarDiscHex(accentHex: string | null): string {
+  if (!isAvatarAccentHex(accentHex)) {
+    return NOTIFICATION_AVATAR_FALLBACK_DISC_HEX;
+  }
+  const rgb = parseInt(accentHex.slice(1), 16);
+  const mixed = (shift: number) => {
+    const channel = (rgb >> shift) & 0xff;
+    return Math.round(255 + (channel - 255) * ACCENT_MIX)
+      .toString(16)
+      .padStart(2, "0");
+  };
+  return `#${mixed(16)}${mixed(8)}${mixed(0)}`.toUpperCase();
+}
+
+/** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
+export type NotificationAvatarMediaType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif";
+
+/**
+ * The three measurements the drawing derives from the edge: the disc's radius,
+ * which is also its centre; the free border around the avatar; and the
+ * avatar's own edge. Every rasterizer reads them from here, so the daemon's
+ * SVG and the desktop canvas cannot drift.
+ */
+export function notificationAvatarGeometry(
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = size * NOTIFICATION_AVATAR_INSET;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  /** The avatar raster to draw inside the disc, base64 with no data prefix. */
+  innerPngBase64: string;
+  /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
+  innerMediaType?: NotificationAvatarMediaType;
+  accentHex: string | null;
+  size?: number;
+}
+
+/** Trims the float noise a fractional inset leaves in the coordinates. */
+function px(value: number): string {
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * The notification avatar as an SVG document: a filled disc with the avatar
+ * drawn inset into it.
+ *
+ * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
+ * canvas does, so a portrait or landscape upload fills the square instead of
+ * being letterboxed onto the disc. It is then clipped to the disc, so the disc
+ * edge is the hard boundary no matter how far a cover-crop overflows.
+ *
+ * The `<image href="data:...">` shape is the one `downscaleRaster()` in
+ * `assistant/src/platform/sync-avatar.ts` already feeds resvg, so the daemon's
+ * rasterizer is known to render it.
+ */
+export function notificationAvatarSvg({
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const href = `data:${innerMediaType};base64,${innerPngBase64}`;
+  const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${px(size)}" height="${px(size)}" viewBox="0 0 ${px(size)} ${px(size)}">` +
+    `<circle ${disc} fill="${notificationAvatarDiscHex(accentHex)}"/>` +
+    `<defs><clipPath id="${CLIP_ID}"><circle ${disc}/></clipPath></defs>` +
+    `<image x="${px(offset)}" y="${px(offset)}" width="${px(inner)}" height="${px(inner)}" ` +
+    `preserveAspectRatio="xMidYMid slice" clip-path="url(#${CLIP_ID})" ` +
+    `href="${href}" xlink:href="${href}"/></svg>`
+  );
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/package.json

@@ -26,7 +26,8 @@
     "./error": "./src/error.ts",
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
-    "./platform-credential": "./src/platform-credential.ts"
+    "./platform-credential": "./src/platform-credential.ts",
+    "./plan-credit": "./src/plan-credit.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/__tests__/plan-credit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  extraCreditUsd,
+  planCreditUsedFraction,
+  usageGrantRatio,
+} from "../plan-credit.js";
+
+describe("usageGrantRatio", () => {
+  test("reads the used share and clamps to 0..1", () => {
+    expect(usageGrantRatio(20, 9.1)).toBeCloseTo(0.545);
+    expect(usageGrantRatio(20, 0)).toBe(1);
+    expect(usageGrantRatio(20, 25)).toBe(0);
+  });
+
+  test("has no reading without both figures or with nothing granted", () => {
+    expect(usageGrantRatio(null, 5)).toBeNull();
+    expect(usageGrantRatio(20, null)).toBeNull();
+    expect(usageGrantRatio(0, 0)).toBeNull();
+  });
+});
+
+describe("planCreditUsedFraction", () => {
+  test("prefers the ratio whatever the plan", () => {
+    expect(planCreditUsedFraction(20, 9.1, "base")).toBeCloseTo(0.545);
+    expect(planCreditUsedFraction(20, 9.1, null)).toBeCloseTo(0.545);
+  });
+
+  test("treats a Pro plan with nothing granted as fully spent", () => {
+    expect(planCreditUsedFraction(0, 0, "pro")).toBe(1);
+    expect(planCreditUsedFraction(0, null, "pro")).toBe(1);
+  });
+
+  test("gives a base or unknown plan with nothing granted no reading", () => {
+    expect(planCreditUsedFraction(0, 0, "base")).toBeNull();
+    expect(planCreditUsedFraction(0, 0, null)).toBeNull();
+    expect(planCreditUsedFraction(null, null, "pro")).toBeNull();
+  });
+});
+
+describe("extraCreditUsd", () => {
+  test("nets unused grant credit out of the balance to the cent", () => {
+    expect(extraCreditUsd(42.17, 9.1)).toBe(33.07);
+    expect(extraCreditUsd(34.65, 9.1)).toBe(25.55);
+  });
+
+  test("never goes below zero", () => {
+    expect(extraCreditUsd(5, 9.1)).toBe(0);
+    expect(extraCreditUsd(-2.5, 0)).toBe(0);
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/index.ts

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./plan-credit.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/plan-credit.ts

@@ -0,0 +1,66 @@
+/**
+ * Plan-credit derivations shared by the assistant runtime's `platform credits`
+ * route and the web client's usage meter, so both read the billing summary's
+ * grant figures the same way and can never quote different readings.
+ */
+
+export type BillingPlanId = "base" | "pro";
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value > 1 ? 1 : value;
+}
+
+/**
+ * How much of the usage credit an account was granted it has already used:
+ * the granted total less what is still unused, over that total. The initial
+ * $5 grant burns 0 to 100% as it is spent, and a further grant grows the total
+ * so the bar drops back. Null when nothing was ever granted, or when the
+ * platform reports neither figure, which has no honest reading rather than a
+ * full or empty bar.
+ */
+export function usageGrantRatio(
+  totalUsd: number | null,
+  availableUsd: number | null,
+): number | null {
+  if (totalUsd == null || availableUsd == null || totalUsd <= 0) {
+    return null;
+  }
+  return clamp01((totalUsd - availableUsd) / totalUsd);
+}
+
+/**
+ * The plan-credit reading with the plan's fallback applied. The grant figures
+ * count only unexpired grants, so a Pro subscription whose grants total
+ * nothing has used or expired everything it was granted (a full bar, with
+ * nothing scheduled to refill it), while a base plan in that position was
+ * never granted anything (no reading). An unknown plan gets the ratio when
+ * the figures allow one and no fallback otherwise.
+ */
+export function planCreditUsedFraction(
+  totalUsd: number | null,
+  availableUsd: number | null,
+  planId: BillingPlanId | null,
+): number | null {
+  const ratio = usageGrantRatio(totalUsd, availableUsd);
+  if (ratio != null) {
+    return ratio;
+  }
+  if (planId === "pro" && totalUsd != null && totalUsd <= 0) {
+    return 1;
+  }
+  return null;
+}
+
+/**
+ * Credit bought or earned on top of the plan-included grants: the balance less
+ * whatever is still unused on those grants, never below zero, to the cent.
+ */
+export function extraCreditUsd(
+  balanceUsd: number,
+  availableUsd: number,
+): number {
+  return Math.round(Math.max(0, balanceUsd - availableUsd) * 100) / 100;
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/reactions.ts

@@ -7,11 +7,13 @@
  * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
  * that separates the namespace from the name.
  *
- * `shortcode` is a name in a channel's own namespace whose kind the channel
- * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
- * for a workspace upload with nothing to tell them apart, and only the
- * workspace token can resolve the second. It is a distinct kind from
- * `unicode`, not a stand-in for an unknown one.
+ * `shortcode` is a name in a channel's own namespace that the channel's
+ * adapter could not place among the standard emoji. Slack sends `+1` and
+ * `blob_wave` alike, as names; its normalizer resolves the standard ones to
+ * `unicode` from Slack's own list, and what remains is a workspace upload
+ * only the workspace can render. It is a distinct kind from `unicode`, not
+ * a stand-in for an unknown one, and nothing past an adapter needs a
+ * channel's naming to read it.
  */
 import { z } from "zod";
 
@@ -39,6 +41,12 @@ export const ReactionEmojiFieldsSchema = z.object({
 });
 export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
 
+/** The typed fields with the kind and name known. */
+export type ReactionEmojiIdentity = ReactionEmojiFields & {
+  emojiKind: ReactionEmojiKind;
+  emojiName: string;
+};
+
 /**
  * The typed emoji fields a source actually carries, with undefined ones
  * omitted: an absent key and a present-but-undefined one serialize alike, but the
@@ -58,3 +66,75 @@ export function pickReactionEmojiFields(
       : {}),
   };
 }
+
+/**
+ * Parse Discord's custom-emoji mention form. The form travels the wire as a
+ * reaction's spelling, so more than one package reads it: the daemon rebuilds
+ * a REST path from it when the assistant reacts, and a row carrying only the
+ * spelling recovers its kind from it. One parser, so the two cannot disagree
+ * about what counts as one.
+ *
+ * `animated` reports whether the spelling carries the `a` marker. Discord's
+ * normalizer never writes that marker, so it is read only from spellings that
+ * arrive from elsewhere: a row written by another producer, or a value the
+ * model hands back as it received it.
+ */
+export function parseDiscordEmojiMention(
+  emoji: string,
+): { name: string; id: string; animated: boolean } | null {
+  const match = /^<(a?):([^:>]+):(\d+)>$/.exec(emoji);
+  return match
+    ? { name: match[2]!, id: match[3]!, animated: match[1] === "a" }
+    : null;
+}
+
+/**
+ * Recover an emoji's kind from its spelling alone. This is the one inference
+ * the design permits, reserved for a value that carries the string and no
+ * typed fields: a persisted row or a replayed retry payload. A value that
+ * declares its kind never reaches this; `reactionEmojiIdentity` makes that
+ * choice for every reader.
+ *
+ * A mention form is unambiguous. Past that the two remaining kinds are told
+ * apart by whether the string is a name at all: a channel's shortcode is
+ * ASCII word characters, optionally carrying Slack's `::skin-tone-N`
+ * suffix, and anything else is the character itself.
+ */
+export function classifyReactionEmojiSpelling(
+  emoji: string,
+): ReactionEmojiIdentity {
+  const custom = parseDiscordEmojiMention(emoji);
+  if (custom) {
+    // The plain `<:name:id>` form says nothing about animation: the
+    // normalizer spells every custom emoji that way and reports animation
+    // in the typed field instead, so a spelling without the `a` marker is
+    // "unrecorded", not "not animated". Only the `<a:` form asserts it.
+    return {
+      emojiKind: "custom",
+      emojiName: custom.name,
+      emojiId: custom.id,
+      ...(custom.animated ? { emojiAnimated: true } : {}),
+    };
+  }
+  return /^[\w+-]+(::skin-tone-[2-6])?$/.test(emoji)
+    ? { emojiKind: "shortcode", emojiName: emoji }
+    : { emojiKind: "unicode", emojiName: emoji };
+}
+
+/**
+ * The typed identity of a reaction's emoji: the fields it declares when it
+ * declares a kind, otherwise the kind recovered from its spelling. Every
+ * reader that must know what an emoji is goes through this, so the wire
+ * contract and the web agree on when the spelling is consulted.
+ */
+export function reactionEmojiIdentity(
+  reaction: { emoji: string } & ReactionEmojiFields,
+): ReactionEmojiIdentity {
+  return reaction.emojiKind !== undefined && reaction.emojiName !== undefined
+    ? {
+        ...pickReactionEmojiFields(reaction),
+        emojiKind: reaction.emojiKind,
+        emojiName: reaction.emojiName,
+      }
+    : classifyReactionEmojiSpelling(reaction.emoji);
+}

package/node_modules/@vellumai/service-contracts/package.json

@@ -26,7 +26,8 @@
     "./error": "./src/error.ts",
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
-    "./platform-credential": "./src/platform-credential.ts"
+    "./platform-credential": "./src/platform-credential.ts",
+    "./plan-credit": "./src/plan-credit.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/__tests__/plan-credit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  extraCreditUsd,
+  planCreditUsedFraction,
+  usageGrantRatio,
+} from "../plan-credit.js";
+
+describe("usageGrantRatio", () => {
+  test("reads the used share and clamps to 0..1", () => {
+    expect(usageGrantRatio(20, 9.1)).toBeCloseTo(0.545);
+    expect(usageGrantRatio(20, 0)).toBe(1);
+    expect(usageGrantRatio(20, 25)).toBe(0);
+  });
+
+  test("has no reading without both figures or with nothing granted", () => {
+    expect(usageGrantRatio(null, 5)).toBeNull();
+    expect(usageGrantRatio(20, null)).toBeNull();
+    expect(usageGrantRatio(0, 0)).toBeNull();
+  });
+});
+
+describe("planCreditUsedFraction", () => {
+  test("prefers the ratio whatever the plan", () => {
+    expect(planCreditUsedFraction(20, 9.1, "base")).toBeCloseTo(0.545);
+    expect(planCreditUsedFraction(20, 9.1, null)).toBeCloseTo(0.545);
+  });
+
+  test("treats a Pro plan with nothing granted as fully spent", () => {
+    expect(planCreditUsedFraction(0, 0, "pro")).toBe(1);
+    expect(planCreditUsedFraction(0, null, "pro")).toBe(1);
+  });
+
+  test("gives a base or unknown plan with nothing granted no reading", () => {
+    expect(planCreditUsedFraction(0, 0, "base")).toBeNull();
+    expect(planCreditUsedFraction(0, 0, null)).toBeNull();
+    expect(planCreditUsedFraction(null, null, "pro")).toBeNull();
+  });
+});
+
+describe("extraCreditUsd", () => {
+  test("nets unused grant credit out of the balance to the cent", () => {
+    expect(extraCreditUsd(42.17, 9.1)).toBe(33.07);
+    expect(extraCreditUsd(34.65, 9.1)).toBe(25.55);
+  });
+
+  test("never goes below zero", () => {
+    expect(extraCreditUsd(5, 9.1)).toBe(0);
+    expect(extraCreditUsd(-2.5, 0)).toBe(0);
+  });
+});

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

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./plan-credit.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/plan-credit.ts

@@ -0,0 +1,66 @@
+/**
+ * Plan-credit derivations shared by the assistant runtime's `platform credits`
+ * route and the web client's usage meter, so both read the billing summary's
+ * grant figures the same way and can never quote different readings.
+ */
+
+export type BillingPlanId = "base" | "pro";
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value > 1 ? 1 : value;
+}
+
+/**
+ * How much of the usage credit an account was granted it has already used:
+ * the granted total less what is still unused, over that total. The initial
+ * $5 grant burns 0 to 100% as it is spent, and a further grant grows the total
+ * so the bar drops back. Null when nothing was ever granted, or when the
+ * platform reports neither figure, which has no honest reading rather than a
+ * full or empty bar.
+ */
+export function usageGrantRatio(
+  totalUsd: number | null,
+  availableUsd: number | null,
+): number | null {
+  if (totalUsd == null || availableUsd == null || totalUsd <= 0) {
+    return null;
+  }
+  return clamp01((totalUsd - availableUsd) / totalUsd);
+}
+
+/**
+ * The plan-credit reading with the plan's fallback applied. The grant figures
+ * count only unexpired grants, so a Pro subscription whose grants total
+ * nothing has used or expired everything it was granted (a full bar, with
+ * nothing scheduled to refill it), while a base plan in that position was
+ * never granted anything (no reading). An unknown plan gets the ratio when
+ * the figures allow one and no fallback otherwise.
+ */
+export function planCreditUsedFraction(
+  totalUsd: number | null,
+  availableUsd: number | null,
+  planId: BillingPlanId | null,
+): number | null {
+  const ratio = usageGrantRatio(totalUsd, availableUsd);
+  if (ratio != null) {
+    return ratio;
+  }
+  if (planId === "pro" && totalUsd != null && totalUsd <= 0) {
+    return 1;
+  }
+  return null;
+}
+
+/**
+ * Credit bought or earned on top of the plan-included grants: the balance less
+ * whatever is still unused on those grants, never below zero, to the cent.
+ */
+export function extraCreditUsd(
+  balanceUsd: number,
+  availableUsd: number,
+): number {
+  return Math.round(Math.max(0, balanceUsd - availableUsd) * 100) / 100;
+}

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

@@ -7,11 +7,13 @@
  * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
  * that separates the namespace from the name.
  *
- * `shortcode` is a name in a channel's own namespace whose kind the channel
- * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
- * for a workspace upload with nothing to tell them apart, and only the
- * workspace token can resolve the second. It is a distinct kind from
- * `unicode`, not a stand-in for an unknown one.
+ * `shortcode` is a name in a channel's own namespace that the channel's
+ * adapter could not place among the standard emoji. Slack sends `+1` and
+ * `blob_wave` alike, as names; its normalizer resolves the standard ones to
+ * `unicode` from Slack's own list, and what remains is a workspace upload
+ * only the workspace can render. It is a distinct kind from `unicode`, not
+ * a stand-in for an unknown one, and nothing past an adapter needs a
+ * channel's naming to read it.
  */
 import { z } from "zod";
 
@@ -39,6 +41,12 @@ export const ReactionEmojiFieldsSchema = z.object({
 });
 export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
 
+/** The typed fields with the kind and name known. */
+export type ReactionEmojiIdentity = ReactionEmojiFields & {
+  emojiKind: ReactionEmojiKind;
+  emojiName: string;
+};
+
 /**
  * The typed emoji fields a source actually carries, with undefined ones
  * omitted: an absent key and a present-but-undefined one serialize alike, but the
@@ -58,3 +66,75 @@ export function pickReactionEmojiFields(
       : {}),
   };
 }
+
+/**
+ * Parse Discord's custom-emoji mention form. The form travels the wire as a
+ * reaction's spelling, so more than one package reads it: the daemon rebuilds
+ * a REST path from it when the assistant reacts, and a row carrying only the
+ * spelling recovers its kind from it. One parser, so the two cannot disagree
+ * about what counts as one.
+ *
+ * `animated` reports whether the spelling carries the `a` marker. Discord's
+ * normalizer never writes that marker, so it is read only from spellings that
+ * arrive from elsewhere: a row written by another producer, or a value the
+ * model hands back as it received it.
+ */
+export function parseDiscordEmojiMention(
+  emoji: string,
+): { name: string; id: string; animated: boolean } | null {
+  const match = /^<(a?):([^:>]+):(\d+)>$/.exec(emoji);
+  return match
+    ? { name: match[2]!, id: match[3]!, animated: match[1] === "a" }
+    : null;
+}
+
+/**
+ * Recover an emoji's kind from its spelling alone. This is the one inference
+ * the design permits, reserved for a value that carries the string and no
+ * typed fields: a persisted row or a replayed retry payload. A value that
+ * declares its kind never reaches this; `reactionEmojiIdentity` makes that
+ * choice for every reader.
+ *
+ * A mention form is unambiguous. Past that the two remaining kinds are told
+ * apart by whether the string is a name at all: a channel's shortcode is
+ * ASCII word characters, optionally carrying Slack's `::skin-tone-N`
+ * suffix, and anything else is the character itself.
+ */
+export function classifyReactionEmojiSpelling(
+  emoji: string,
+): ReactionEmojiIdentity {
+  const custom = parseDiscordEmojiMention(emoji);
+  if (custom) {
+    // The plain `<:name:id>` form says nothing about animation: the
+    // normalizer spells every custom emoji that way and reports animation
+    // in the typed field instead, so a spelling without the `a` marker is
+    // "unrecorded", not "not animated". Only the `<a:` form asserts it.
+    return {
+      emojiKind: "custom",
+      emojiName: custom.name,
+      emojiId: custom.id,
+      ...(custom.animated ? { emojiAnimated: true } : {}),
+    };
+  }
+  return /^[\w+-]+(::skin-tone-[2-6])?$/.test(emoji)
+    ? { emojiKind: "shortcode", emojiName: emoji }
+    : { emojiKind: "unicode", emojiName: emoji };
+}
+
+/**
+ * The typed identity of a reaction's emoji: the fields it declares when it
+ * declares a kind, otherwise the kind recovered from its spelling. Every
+ * reader that must know what an emoji is goes through this, so the wire
+ * contract and the web agree on when the spelling is consulted.
+ */
+export function reactionEmojiIdentity(
+  reaction: { emoji: string } & ReactionEmojiFields,
+): ReactionEmojiIdentity {
+  return reaction.emojiKind !== undefined && reaction.emojiName !== undefined
+    ? {
+        ...pickReactionEmojiFields(reaction),
+        emojiKind: reaction.emojiKind,
+        emojiName: reaction.emojiName,
+      }
+    : classifyReactionEmojiSpelling(reaction.emoji);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.10",
+  "version": "0.11.11-staging.2",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {