@vellumai/assistant 0.8.6 → 0.8.7

package/src/avatar/__tests__/avatar-store.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for the avatar store — atomic artifact + manifest mutations.
+ *
+ * Each operation must leave `avatar.json` consistent with the on-disk
+ * artifacts:
+ *   - setCharacter  → traits.json + PNG (+ ASCII) on disk, `character` manifest
+ *   - setImage      → PNG on disk, character sidecars removed, `image` manifest
+ *   - clearAvatar   → everything removed, `none` manifest
+ *
+ * The avatar directory is controlled per-test via VELLUM_WORKSPACE_DIR, which
+ * `getAvatarDir()` resolves live. Per the test-isolation rule in
+ * assistant/AGENTS.md, this file imports ONLY the module under test
+ * (`avatar-store`); state is asserted by reading `avatar.json` and the artifact
+ * files directly off the per-test workspace dir via `node:fs`.
+ *
+ * `setCharacter` routes through the native @resvg/resvg-js renderer. Rather than
+ * stub that native path (which would require importing production machinery), we
+ * branch on the store's documented return value: when the binding is available
+ * the success path is asserted, and when it is not the `native_unavailable`
+ * failure contract is asserted instead — so the suite passes deterministically
+ * whether or not the native binding is installed in the test environment.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { clearAvatar, setCharacter, setImage } from "../avatar-store.js";
+
+// A valid trait triple drawn from the real component set.
+const VALID_TRAITS = { bodyShape: "blob", eyeStyle: "curious", color: "green" };
+
+const IMAGE_FILENAME = "avatar-image.png";
+const TRAITS_FILENAME = "character-traits.json";
+const ASCII_FILENAME = "character-ascii.txt";
+const MANIFEST_FILENAME = "avatar.json";
+
+interface ManifestShape {
+  kind: string;
+  traits: Record<string, unknown> | null;
+  source: string | null;
+  image: { updatedAt: string; etag: string } | null;
+}
+
+describe("avatar-store", () => {
+  let workspaceDir: string;
+  let avatarDir: string;
+  let prevWorkspaceDir: string | undefined;
+
+  beforeEach(() => {
+    workspaceDir = mkdtempSync(join(tmpdir(), "avatar-store-test-"));
+    // getAvatarDir() === <workspace>/data/avatar
+    avatarDir = join(workspaceDir, "data", "avatar");
+    prevWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+    // Pre-create the avatar dir so tests that seed legacy artifacts can write
+    // into it before the store's own mkdir runs.
+    mkdirSync(avatarDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (prevWorkspaceDir === undefined) {
+      delete process.env.VELLUM_WORKSPACE_DIR;
+    } else {
+      process.env.VELLUM_WORKSPACE_DIR = prevWorkspaceDir;
+    }
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  const path = (name: string) => join(avatarDir, name);
+
+  /** Reads and parses the on-disk manifest, or returns null when absent. */
+  const readManifestFile = (): ManifestShape | null => {
+    const manifestPath = path(MANIFEST_FILENAME);
+    if (!existsSync(manifestPath)) return null;
+    return JSON.parse(readFileSync(manifestPath, "utf-8")) as ManifestShape;
+  };
+
+  describe("setCharacter", () => {
+    test("writes traits + PNG and a character manifest when render succeeds", () => {
+      const result = setCharacter(VALID_TRAITS);
+
+      // The native @resvg/resvg-js binding may be absent in this environment.
+      // When it is, the store returns `native_unavailable` and writes nothing —
+      // we assert that contract instead of the success path so the suite is
+      // deterministic either way.
+      if (!result.ok) {
+        expect(result.reason).toBe("native_unavailable");
+        expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+        expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+        expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
+        return;
+      }
+
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(true);
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+      expect(JSON.parse(readFileSync(path(TRAITS_FILENAME), "utf-8"))).toEqual(
+        VALID_TRAITS,
+      );
+
+      const manifest = readManifestFile();
+      expect(manifest).not.toBeNull();
+      expect(manifest!.kind).toBe("character");
+      expect(manifest!.traits).toEqual(VALID_TRAITS);
+      expect(manifest!.source).toBe("builder");
+      expect(manifest!.image).not.toBeNull();
+      expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+    });
+
+    test("propagates invalid_traits without writing a manifest", () => {
+      const result = setCharacter({ bodyShape: "", eyeStyle: "", color: "" });
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toBe("invalid_traits");
+      expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+    });
+  });
+
+  describe("setImage", () => {
+    test("writes the PNG and an image manifest", () => {
+      setImage(Buffer.from("fake png bytes"), "upload");
+
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+      expect(readFileSync(path(IMAGE_FILENAME)).toString()).toBe(
+        "fake png bytes",
+      );
+
+      const manifest = readManifestFile();
+      expect(manifest).not.toBeNull();
+      expect(manifest!.kind).toBe("image");
+      expect(manifest!.traits).toBeNull();
+      expect(manifest!.source).toBe("upload");
+      expect(manifest!.image).not.toBeNull();
+      expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+      expect(manifest!.image!.updatedAt).toMatch(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+      );
+    });
+
+    test("removes stale character sidecars on transition", () => {
+      // Seed legacy character artifacts.
+      writeFileSync(path(TRAITS_FILENAME), JSON.stringify(VALID_TRAITS));
+      writeFileSync(path(ASCII_FILENAME), "ascii art");
+
+      setImage(Buffer.from("png"), "ai");
+
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(ASCII_FILENAME))).toBe(false);
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+      expect(readManifestFile()!.kind).toBe("image");
+    });
+
+    test("is idempotent across repeated calls", () => {
+      setImage(Buffer.from("v1"), "upload");
+      setImage(Buffer.from("v2"), "upload");
+
+      expect(readFileSync(path(IMAGE_FILENAME)).toString()).toBe("v2");
+      expect(readManifestFile()!.kind).toBe("image");
+    });
+  });
+
+  describe("clearAvatar", () => {
+    test("removes all artifacts AND the manifest (none == absence)", () => {
+      writeFileSync(path(IMAGE_FILENAME), Buffer.from("png"));
+      writeFileSync(path(TRAITS_FILENAME), JSON.stringify(VALID_TRAITS));
+      writeFileSync(path(ASCII_FILENAME), "ascii art");
+
+      clearAvatar();
+
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(ASCII_FILENAME))).toBe(false);
+      // "No avatar" is represented by the absence of avatar.json, so a later
+      // legacy sidecar write isn't shadowed by a stale `none` manifest.
+      expect(readManifestFile()).toBeNull();
+    });
+
+    test("is idempotent when nothing exists", () => {
+      clearAvatar();
+      clearAvatar();
+      expect(readManifestFile()).toBeNull();
+    });
+  });
+});

package/src/avatar/avatar-manifest.ts

@@ -0,0 +1,195 @@
+/**
+ * Avatar state manifest — schema + pure filesystem helpers.
+ *
+ * The manifest (`avatar.json`) is the canonical record of the user's avatar
+ * configuration. This module is intentionally pure: it only reads/writes the
+ * filesystem and derives state from legacy sidecar files. It must not import
+ * route or handler code.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../util/logger.js";
+import {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  getAvatarDir,
+} from "../util/platform.js";
+import { type CharacterTraits, TRAITS_FILENAME } from "./traits-png-sync.js";
+
+const log = getLogger("avatar-manifest");
+
+export type AvatarKind = "character" | "image" | "none";
+export type AvatarSource = "builder" | "upload" | "ai";
+
+export interface AvatarImageMeta {
+  updatedAt: string;
+  etag: string;
+}
+
+export interface AvatarState {
+  kind: AvatarKind;
+  traits: CharacterTraits | null;
+  source: AvatarSource | null;
+  image: AvatarImageMeta | null;
+}
+
+const AVATAR_KINDS: ReadonlySet<string> = new Set<AvatarKind>([
+  "character",
+  "image",
+  "none",
+]);
+
+/** Narrows an unknown value to valid CharacterTraits (presence check only). */
+function isValidTraits(value: unknown): value is CharacterTraits {
+  if (!value || typeof value !== "object") return false;
+  const t = value as Record<string, unknown>;
+  return (
+    typeof t.bodyShape === "string" &&
+    !!t.bodyShape &&
+    typeof t.eyeStyle === "string" &&
+    !!t.eyeStyle &&
+    typeof t.color === "string" &&
+    !!t.color
+  );
+}
+
+/** Narrows an unknown value to valid AvatarImageMeta (presence check only). */
+function isValidImageMeta(value: unknown): value is AvatarImageMeta {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return (
+    typeof m.updatedAt === "string" &&
+    !!m.updatedAt &&
+    typeof m.etag === "string" &&
+    !!m.etag
+  );
+}
+
+/**
+ * Reads and validates the avatar manifest. Returns `null` when the manifest is
+ * missing, unreadable, unparseable, has an invalid `kind`, or carries a
+ * partial/malformed per-kind payload so callers can fall back to legacy
+ * derivation rather than surfacing an avatar with null traits/image.
+ */
+export function readManifest(
+  avatarDir: string = getAvatarDir(),
+): AvatarState | null {
+  const manifestPath = join(avatarDir, AVATAR_MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf-8")) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const obj = parsed as Record<string, unknown>;
+    if (typeof obj.kind !== "string" || !AVATAR_KINDS.has(obj.kind)) {
+      return null;
+    }
+    const kind = obj.kind as AvatarKind;
+
+    // Reject partial manifests: a valid `kind` with a missing/malformed payload
+    // would otherwise short-circuit the legacy fallback and surface an avatar
+    // with null traits/image.
+    if (kind === "character" && !isValidTraits(obj.traits)) return null;
+    if (kind === "image" && !isValidImageMeta(obj.image)) return null;
+
+    return {
+      kind,
+      traits: (obj.traits as CharacterTraits | null) ?? null,
+      source: (obj.source as AvatarSource | null) ?? null,
+      image: (obj.image as AvatarImageMeta | null) ?? null,
+    };
+  } catch (err) {
+    log.warn({ err }, "Failed to read avatar manifest — treating as absent");
+    return null;
+  }
+}
+
+/**
+ * Writes the avatar manifest atomically (tmp-write + rename), mirroring the
+ * write pattern in traits-png-sync.ts.
+ */
+export function writeManifest(
+  state: AvatarState,
+  avatarDir: string = getAvatarDir(),
+): void {
+  mkdirSync(avatarDir, { recursive: true });
+  const manifestPath = join(avatarDir, AVATAR_MANIFEST_FILENAME);
+  const tmp = `${manifestPath}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, manifestPath);
+}
+
+/** Computes a stable etag for the avatar image from its size and mtime. */
+function computeImageEtag(sizeBytes: number, mtimeMs: number): string {
+  return createHash("sha256")
+    .update(`${sizeBytes}:${mtimeMs}`)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * Computes {@link AvatarImageMeta} for an avatar PNG already on disk. The etag
+ * is derived from the file's size and mtime and `updatedAt` is the mtime in ISO
+ * form, so both the legacy-derivation path and the store's write path agree on
+ * the same meta shape for the same file. Caller must ensure the file exists.
+ */
+export function computeImageMeta(imagePath: string): AvatarImageMeta {
+  const stats = statSync(imagePath);
+  return {
+    updatedAt: new Date(stats.mtimeMs).toISOString(),
+    etag: computeImageEtag(stats.size, stats.mtimeMs),
+  };
+}
+
+/**
+ * Derives avatar state from the legacy sidecar files (traits JSON + PNG).
+ * Used by the read handlers to self-heal once on a manifest-miss: the derived
+ * state is persisted via `writeManifest` so subsequent reads are manifest-only.
+ *
+ * Inference is **traits-first**: whenever a valid `character-traits.json`
+ * exists, the result is `character` regardless of whether a PNG is also
+ * present. We deliberately do NOT compare mtimes to break the both-present
+ * tie, because the builder writes the rendered PNG *after* the traits file
+ * (see traits-png-sync.ts), so the PNG is always newer even when the
+ * character is the source of truth. Comparing mtimes would misclassify a
+ * builder-generated character as an uploaded image.
+ */
+export function deriveStateFromLegacyFiles(
+  avatarDir: string = getAvatarDir(),
+): AvatarState {
+  const traitsPath = join(avatarDir, TRAITS_FILENAME);
+  if (existsSync(traitsPath)) {
+    try {
+      const traits = JSON.parse(readFileSync(traitsPath, "utf-8")) as unknown;
+      if (isValidTraits(traits)) {
+        return { kind: "character", traits, source: null, image: null };
+      }
+    } catch (err) {
+      log.warn(
+        { err },
+        "Corrupt character-traits.json — falling back to image/none",
+      );
+    }
+  }
+
+  const imagePath = join(avatarDir, AVATAR_IMAGE_FILENAME);
+  if (existsSync(imagePath)) {
+    return {
+      kind: "image",
+      traits: null,
+      source: null,
+      image: computeImageMeta(imagePath),
+    };
+  }
+
+  return { kind: "none", traits: null, source: null, image: null };
+}

package/src/avatar/avatar-store.ts

@@ -0,0 +1,113 @@
+/**
+ * Avatar store — atomic, transition-aware avatar mutations.
+ *
+ * Each operation updates the on-disk artifacts (PNG / traits / ASCII) AND the
+ * canonical manifest (`avatar.json`) together, removing artifacts that no
+ * longer belong to the new state. Artifacts are written FIRST and the manifest
+ * LAST, so an interrupted call never leaves the manifest pointing at a state
+ * the artifacts don't back. This mirrors the "traits before PNG" ordering in
+ * traits-png-sync.ts.
+ *
+ * This module is the single writer of avatar state. Callers (HTTP/IPC routes)
+ * should go through it rather than touching artifacts or the manifest directly.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../util/logger.js";
+import {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  getAvatarDir,
+  getAvatarImagePath,
+} from "../util/platform.js";
+import {
+  type AvatarSource,
+  computeImageMeta,
+  writeManifest,
+} from "./avatar-manifest.js";
+import {
+  ASCII_FILENAME,
+  type CharacterTraits,
+  TRAITS_FILENAME,
+  type TraitsSyncResult,
+  writeTraitsAndRenderAvatar,
+} from "./traits-png-sync.js";
+
+const log = getLogger("avatar-store");
+
+/**
+ * Sets the avatar to a builder-rendered character: writes traits.json, renders
+ * the PNG + ASCII (via {@link writeTraitsAndRenderAvatar}), then records a
+ * `character` manifest derived from the freshly-rendered PNG.
+ *
+ * Returns the underlying {@link TraitsSyncResult} unchanged so the route layer
+ * keeps its existing error semantics (`invalid_traits` / `native_unavailable` /
+ * `render_error`). The manifest is written ONLY when the render succeeded — a
+ * failed render leaves both artifacts and manifest untouched.
+ */
+export function setCharacter(traits: CharacterTraits): TraitsSyncResult {
+  const result = writeTraitsAndRenderAvatar(traits);
+  if (!result.ok) {
+    return result;
+  }
+
+  writeManifest({
+    kind: "character",
+    traits,
+    source: "builder",
+    image: computeImageMeta(getAvatarImagePath()),
+  });
+  return result;
+}
+
+/**
+ * Sets the avatar to an uploaded/AI image: atomically writes the PNG, removes
+ * the now-stale character sidecars (traits + ASCII), then records an `image`
+ * manifest. The PNG is written before the manifest so an interrupted call never
+ * leaves the manifest ahead of the artifact.
+ */
+export function setImage(pngBuffer: Buffer, source: AvatarSource): void {
+  const avatarDir = getAvatarDir();
+  mkdirSync(avatarDir, { recursive: true });
+
+  const pngPath = join(avatarDir, AVATAR_IMAGE_FILENAME);
+  const pngTmp = `${pngPath}.${randomUUID()}.tmp`;
+  writeFileSync(pngTmp, pngBuffer);
+  renameSync(pngTmp, pngPath);
+
+  rmSync(join(avatarDir, TRAITS_FILENAME), { force: true });
+  rmSync(join(avatarDir, ASCII_FILENAME), { force: true });
+
+  writeManifest({
+    kind: "image",
+    traits: null,
+    source,
+    image: computeImageMeta(pngPath),
+  });
+
+  log.info({ source }, "Set avatar from image and removed character sidecars");
+}
+
+/**
+ * Clears the avatar entirely: removes the PNG, character sidecars, and the
+ * manifest itself. Idempotent — safe to call when nothing exists.
+ *
+ * "No avatar" is represented by the ABSENCE of a manifest, not a persisted
+ * `kind:"none"`. Deleting avatar.json (rather than writing `none`) keeps an
+ * emptied workspace manifest-less, so a later legacy sidecar write is still
+ * picked up by the read-time self-heal instead of being shadowed by a stale
+ * `none` manifest.
+ */
+export function clearAvatar(): void {
+  const avatarDir = getAvatarDir();
+  mkdirSync(avatarDir, { recursive: true });
+
+  rmSync(join(avatarDir, AVATAR_IMAGE_FILENAME), { force: true });
+  rmSync(join(avatarDir, TRAITS_FILENAME), { force: true });
+  rmSync(join(avatarDir, ASCII_FILENAME), { force: true });
+  rmSync(join(avatarDir, AVATAR_MANIFEST_FILENAME), { force: true });
+
+  log.info("Cleared avatar — removed all artifacts");
+}

package/src/avatar/traits-png-sync.ts

@@ -11,6 +11,12 @@ import { isResvgAvailable } from "./resvg-lazy.js";
 
 const log = getLogger("traits-png-sync");
 
+/** Sidecar filename for the persisted character traits JSON. */
+export const TRAITS_FILENAME = "character-traits.json";
+
+/** Sidecar filename for the rendered ASCII art. */
+export const ASCII_FILENAME = "character-ascii.txt";
+
 export interface CharacterTraits {
   bodyShape: string;
   eyeStyle: string;
@@ -75,7 +81,7 @@ function writeAvatarFiles(
   }
 
   try {
-    const asciiPath = join(avatarDir, "character-ascii.txt");
+    const asciiPath = join(avatarDir, ASCII_FILENAME);
     const asciiTmp = `${asciiPath}.${randomUUID()}.tmp`;
     writeFileSync(asciiTmp, asciiArt);
     renameSync(asciiTmp, asciiPath);
@@ -165,7 +171,7 @@ export function writeTraitsAndRenderAvatar(
   }
 
   const avatarDir = getAvatarDir();
-  const traitsPath = join(avatarDir, "character-traits.json");
+  const traitsPath = join(avatarDir, TRAITS_FILENAME);
 
   try {
     mkdirSync(avatarDir, { recursive: true });

package/src/background-wake/next-wake.test.ts

@@ -25,6 +25,7 @@ type MockSchedule = {
 
 let heartbeatConfig: MockHeartbeatConfig;
 let heartbeatNextRunAt: number | null;
+let heartbeatConsecutiveRunCapReached: boolean;
 let schedules: MockSchedule[];
 let computedCronNextRunAt: number;
 
@@ -39,7 +40,10 @@ mock.module("../heartbeat/heartbeat-service.js", () => ({
     getInstance: () =>
       heartbeatNextRunAt == null
         ? undefined
-        : { nextRunAt: heartbeatNextRunAt },
+        : {
+            nextRunAt: heartbeatNextRunAt,
+            isConsecutiveRunCapReached: heartbeatConsecutiveRunCapReached,
+          },
   },
 }));
 
@@ -70,6 +74,7 @@ describe("computeNextBackgroundWakeIntent", () => {
       maxConsecutiveRuns: 3,
     };
     heartbeatNextRunAt = null;
+    heartbeatConsecutiveRunCapReached = false;
     schedules = [];
     computedCronNextRunAt = NOW + 3_600_000;
   });
@@ -270,6 +275,31 @@ describe("computeNextBackgroundWakeIntent", () => {
     expect(first!.computedAt).not.toBe(second!.computedAt);
     expect(first!.sourceGeneration).toBe(second!.sourceGeneration);
   });
+
+  test("returns null when heartbeat consecutive run cap is reached and no schedules", () => {
+    heartbeatNextRunAt = NOW + 30_000;
+    heartbeatConsecutiveRunCapReached = true;
+
+    expect(computeNextBackgroundWakeIntent(NOW)).toBeNull();
+  });
+
+  test("returns schedule-only intent when heartbeat consecutive run cap is reached", () => {
+    heartbeatNextRunAt = NOW + 30_000;
+    heartbeatConsecutiveRunCapReached = true;
+    schedules = [
+      scheduleFixture({
+        id: "still-active",
+        nextRunAt: NOW + 60_000,
+      }),
+    ];
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.reason).toBe("schedule");
+    expect(intent!.sourcePayload.heartbeat).toBeNull();
+    expect(intent!.sourcePayload.schedules).toHaveLength(1);
+  });
 });
 
 function scheduleFixture(overrides: Partial<MockSchedule>): MockSchedule {

package/src/background-wake/next-wake.ts

@@ -95,7 +95,10 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
   const config = getConfig().heartbeat;
   if (!config.enabled) return null;
 
-  const serviceNextRunAt = HeartbeatService.getInstance()?.nextRunAt ?? null;
+  const service = HeartbeatService.getInstance();
+  if (service?.isConsecutiveRunCapReached) return null;
+
+  const serviceNextRunAt = service?.nextRunAt ?? null;
   let nextRunAt = serviceNextRunAt;
   const mode = config.cronExpression != null ? "cron" : "interval";
 

package/src/calls/call-conversation-messages.ts

@@ -69,10 +69,12 @@ export async function persistCallCompletionMessage(
       },
     ]),
     {
-      userMessageChannel: "phone",
-      assistantMessageChannel: "phone",
-      userMessageInterface: "phone",
-      assistantMessageInterface: "phone",
+      metadata: {
+        userMessageChannel: "phone",
+        assistantMessageChannel: "phone",
+        userMessageInterface: "phone",
+        assistantMessageInterface: "phone",
+      },
     },
   );
   return summaryText;

package/src/calls/guardian-action-sweep.ts

@@ -74,10 +74,12 @@ export async function sendGuardianExpiryNotices(
           "assistant",
           JSON.stringify([{ type: "text", text: expiryText }]),
           {
-            userMessageChannel: "phone",
-            assistantMessageChannel: "vellum",
-            userMessageInterface: "phone",
-            assistantMessageInterface: "web",
+            metadata: {
+              userMessageChannel: "phone",
+              assistantMessageChannel: "vellum",
+              userMessageInterface: "phone",
+              assistantMessageInterface: "web",
+            },
           },
         );
       } else if (delivery.destinationChatId) {

package/src/calls/relay-server.ts

@@ -769,10 +769,12 @@ export class RelayConnection {
         "assistant",
         JSON.stringify([{ type: "text", text: codeMsg }]),
         {
-          userMessageChannel: "phone",
-          assistantMessageChannel: "phone",
-          userMessageInterface: "phone",
-          assistantMessageInterface: "phone",
+          metadata: {
+            userMessageChannel: "phone",
+            assistantMessageChannel: "phone",
+            userMessageInterface: "phone",
+            assistantMessageInterface: "phone",
+          },
         },
       );
     }
@@ -1977,10 +1979,12 @@ export class RelayConnection {
             "user",
             JSON.stringify([{ type: "text", text: msg.voicePrompt }]),
             {
-              userMessageChannel: "phone",
-              assistantMessageChannel: "phone",
-              userMessageInterface: "phone",
-              assistantMessageInterface: "phone",
+              metadata: {
+                userMessageChannel: "phone",
+                assistantMessageChannel: "phone",
+                userMessageInterface: "phone",
+                assistantMessageInterface: "phone",
+              },
             },
           );
         } catch (err) {