@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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,11 @@ 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;
+  if (service?.isDailyCapReached) 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) {

package/src/calls/voice-session-bridge.ts

@@ -516,13 +516,9 @@ export async function startVoiceTurn(
               },
               "Consumed scoped grant — allowing non-guardian voice confirmation",
             );
-            conversation.handleConfirmationResponse(
-              msg.requestId,
-              "allow",
-              undefined,
-              undefined,
-              `Permission approved for "${msg.toolName}": guardian pre-approved via scoped grant.`,
-            );
+            conversation.handleConfirmationResponse(msg.requestId, "allow", {
+              decisionContext: `Permission approved for "${msg.toolName}": guardian pre-approved via scoped grant.`,
+            });
             broadcastMessage(msg);
             return;
           }
@@ -537,13 +533,9 @@ export async function startVoiceTurn(
           { turnId, toolName: msg.toolName },
           "Auto-denying confirmation request for non-guardian voice turn (no matching scoped grant)",
         );
-        conversation.handleConfirmationResponse(
-          msg.requestId,
-          "deny",
-          undefined,
-          undefined,
-          `Permission denied for "${msg.toolName}": this voice call does not have interactive approval capabilities. Side-effect tools are not available for non-guardian voice callers. In your next assistant reply, explain briefly that this action requires guardian-level access and cannot be performed during this call.`,
-        );
+        conversation.handleConfirmationResponse(msg.requestId, "deny", {
+          decisionContext: `Permission denied for "${msg.toolName}": this voice call does not have interactive approval capabilities. Side-effect tools are not available for non-guardian voice callers. In your next assistant reply, explain briefly that this action requires guardian-level access and cannot be performed during this call.`,
+        });
         broadcastMessage(msg);
         return;
       }
@@ -552,13 +544,9 @@ export async function startVoiceTurn(
           { turnId, toolName: msg.toolName },
           "Auto-approving confirmation request for guardian voice turn",
         );
-        conversation.handleConfirmationResponse(
-          msg.requestId,
-          "allow",
-          undefined,
-          undefined,
-          `Permission approved for "${msg.toolName}": this is a verified guardian voice call.`,
-        );
+        conversation.handleConfirmationResponse(msg.requestId, "allow", {
+          decisionContext: `Permission approved for "${msg.toolName}": this is a verified guardian voice call.`,
+        });
         broadcastMessage(msg);
         return;
       }
@@ -594,10 +582,8 @@ export async function startVoiceTurn(
       // flag into subsequent non-voice turns on the same conversation.
       conversation.forcePromptSideEffects =
         !isGuardian && !usesLocalInteractiveApprovals;
-      await conversation.runAgentLoop(
-        persistedContent,
-        messageId,
-        (msg: ServerMessage) => {
+      await conversation.runAgentLoop(persistedContent, messageId, {
+        onEvent: (msg: ServerMessage) => {
           if (msg.type === "error") {
             lastError = msg.message;
           } else if (msg.type === "conversation_error") {
@@ -624,8 +610,8 @@ export async function startVoiceTurn(
           // Note: tool_use_preview_start is intentionally not handled here.
           // Voice only reacts to the definitive tool_use_start event.
         },
-        { callSite: "callAgent" },
-      );
+        callSite: "callAgent",
+      });
       if (lastError) {
         log.error(
           { turnId, error: lastError },