@vellumai/assistant 0.4.54 → 0.4.56

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

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+import { renderCharacterAscii } from "./ascii-renderer.js";
+import { renderCharacterPng } from "./png-renderer.js";
+
+const log = getLogger("traits-png-sync");
+
+export interface CharacterTraits {
+  bodyShape: string;
+  eyeStyle: string;
+  color: string;
+}
+
+export type TraitsSyncResult =
+  | { ok: true; asciiWritten: boolean }
+  | {
+      ok: false;
+      reason: "invalid_traits" | "render_error";
+      message: string;
+    };
+
+/**
+ * Renders avatar-image.png and character-ascii.txt from the given traits,
+ * writing each file atomically.  Does NOT touch character-traits.json.
+ *
+ * Returns `true` if the ASCII sidecar was also written successfully.
+ */
+function renderAndWriteAvatarFiles(
+  traits: CharacterTraits,
+  avatarDir: string,
+): boolean {
+  const pngPath = join(avatarDir, "avatar-image.png");
+
+  // Render PNG first — this validates trait IDs (composeSvg throws on
+  // unknown components), so we fail before writing anything to disk.
+  const pngBuffer = renderCharacterPng(
+    traits.bodyShape,
+    traits.eyeStyle,
+    traits.color,
+  );
+  const pngTmp = `${pngPath}.${randomUUID()}.tmp`;
+  writeFileSync(pngTmp, pngBuffer);
+  renameSync(pngTmp, pngPath);
+
+  // Render and write ASCII art — isolated so a failure here doesn't cause
+  // the primary operation to report failure.
+  try {
+    const asciiPath = join(avatarDir, "character-ascii.txt");
+    const asciiArt = renderCharacterAscii(
+      traits.bodyShape,
+      traits.eyeStyle,
+      traits.color,
+    );
+    const asciiTmp = `${asciiPath}.${randomUUID()}.tmp`;
+    writeFileSync(asciiTmp, asciiArt);
+    renameSync(asciiTmp, asciiPath);
+    return true;
+  } catch (asciiErr) {
+    log.warn(
+      { err: asciiErr },
+      "Failed to write ASCII sidecar — primary files still written",
+    );
+    return false;
+  }
+}
+
+/**
+ * Writes character-traits.json, regenerates avatar-image.png, and updates
+ * character-ascii.txt in one atomic operation.  Accepts the trait values
+ * directly so callers don't need to touch the filesystem first.
+ *
+ * Renders the PNG before writing the traits file so that if rendering fails
+ * (e.g. unknown component IDs), neither file is modified.
+ */
+export function writeTraitsAndRenderAvatar(
+  traits: CharacterTraits,
+): TraitsSyncResult {
+  if (
+    !traits ||
+    typeof traits !== "object" ||
+    !traits.bodyShape ||
+    !traits.eyeStyle ||
+    !traits.color
+  ) {
+    log.warn({ traits }, "Invalid character traits — missing required fields");
+    return {
+      ok: false,
+      reason: "invalid_traits",
+      message: "Missing required fields: bodyShape, eyeStyle, color",
+    };
+  }
+
+  const avatarDir = join(getWorkspaceDir(), "data", "avatar");
+  const traitsPath = join(avatarDir, "character-traits.json");
+
+  try {
+    mkdirSync(avatarDir, { recursive: true });
+
+    // Render avatar files first — validates trait IDs before committing
+    // the traits file, so we never leave traits and PNG out of sync.
+    const asciiWritten = renderAndWriteAvatarFiles(traits, avatarDir);
+
+    // Write traits file atomically (after successful render)
+    const traitsJson = JSON.stringify(traits, null, 2);
+    const traitsTmp = `${traitsPath}.${randomUUID()}.tmp`;
+    writeFileSync(traitsTmp, traitsJson);
+    renameSync(traitsTmp, traitsPath);
+
+    log.info(
+      {
+        bodyShape: traits.bodyShape,
+        eyeStyle: traits.eyeStyle,
+        color: traits.color,
+      },
+      asciiWritten
+        ? "Wrote character traits, regenerated avatar PNG, and updated ASCII art"
+        : "Wrote character traits and regenerated avatar PNG",
+    );
+    return { ok: true, asciiWritten };
+  } catch (err) {
+    log.error({ err }, "Failed to write traits / render avatar");
+    return {
+      ok: false,
+      reason: "render_error",
+      message:
+        err instanceof Error ? err.message : "Failed to render avatar PNG",
+    };
+  }
+}

package/src/calls/call-controller.ts

@@ -1,7 +1,7 @@
 /**
- * Session-backed voice call controller.
+ * Conversation-backed voice call controller.
  *
- * Routes voice turns through the daemon session pipeline via
+ * Routes voice turns through the daemon conversation pipeline via
  * voice-session-bridge instead of calling provider.sendMessage() directly.
  * This gives voice calls access to tools, memory, skills, and runtime
  * injections while preserving all existing call UX behavior (control markers,
@@ -9,8 +9,8 @@
  */
 
 import { getGatewayInternalBaseUrl } from "../config/env.js";
+import type { TrustContext } from "../daemon/conversation-runtime-assembly.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
-import type { TrustContext } from "../daemon/session-runtime-assembly.js";
 import {
   expireCanonicalGuardianRequest,
   getCanonicalRequestByPendingQuestionId,
@@ -118,10 +118,10 @@ export class CallController {
   /** Conversation ID for the voice session. */
   private conversationId: string;
   /**
-   * Track whether the last message sent to the session was a user message
+   * Track whether the last message sent to the conversation was a user message
    * whose assistant response has not yet been received. This is used to
    * prevent sending consecutive user messages that would violate role
-   * alternation in the underlying session pipeline.
+   * alternation in the underlying conversation pipeline.
    */
   private lastSentWasOpener = false;
   /**
@@ -434,7 +434,7 @@ export class CallController {
   }
 
   /**
-   * Execute a single voice turn through the session pipeline and stream
+   * Execute a single voice turn through the conversation pipeline and stream
    * the response back through the relay.
    */
   private runTurn(content: string): Promise<void> {
@@ -507,7 +507,7 @@ export class CallController {
   }
 
   /**
-   * Stream TTS tokens from the session pipeline, buffering to strip
+   * Stream TTS tokens from the conversation pipeline, buffering to strip
    * control markers before they reach the relay. Returns the full
    * accumulated response text for post-turn marker detection.
    */
@@ -843,7 +843,7 @@ export class CallController {
       // Clear any pending consultation before completing the call.
       // Without this, the consultation timeout can fire on an already-ended
       // call, overwriting 'completed' status back to 'in_progress' and
-      // starting a new LLM turn on a dead session. Similarly, a late
+      // starting a new LLM turn on a dead conversation. Similarly, a late
       // handleUserAnswer could be accepted since pendingGuardianInput is
       // still non-null.
       if (this.pendingGuardianInput) {

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

@@ -1,6 +1,6 @@
 /**
  * Persistence + formatting helpers for messages that belong in the
- * dedicated voice conversation thread.
+ * dedicated voice conversation.
  */
 
 import { addMessage } from "../memory/conversation-crud.js";

package/src/calls/call-domain.ts

@@ -286,7 +286,7 @@ export function createInboundVoiceSession(
   }
 
   // Create a dedicated voice conversation keyed by CallSid so inbound calls
-  // get their own conversation thread.
+  // get their own conversation.
   const voiceConvKey =
     assistantId && assistantId !== DAEMON_INTERNAL_ASSISTANT_ID
       ? `asst:${assistantId}:voice:inbound:${callSid}`
@@ -445,7 +445,7 @@ export async function startCall(
     sessionId = session.id;
 
     // Create a dedicated voice conversation for this call so that voice
-    // transcripts live in their own thread, separate from the chat that
+    // transcripts live in their own conversation, separate from the chat that
     // triggered the call.
     const voiceConvKey = assistantId
       ? `asst:${assistantId}:voice:call:${session.id}`
@@ -937,7 +937,7 @@ export async function startVerificationCall(
 
     // Create a minimal conversation so the call session has a valid FK,
     // and bind it to the voice channel so it never appears as an unbound
-    // desktop thread.
+    // desktop conversation.
     const convKey = `guardian-verify:${verificationSessionId}`;
     const { conversationId } = getOrCreateConversation(convKey);
 
@@ -1069,7 +1069,7 @@ export async function startInviteCall(
 
     // Create a minimal conversation so the call session has a valid FK,
     // and bind it to the voice channel so it never appears as an unbound
-    // desktop thread.
+    // desktop conversation.
     const timestamp = Date.now();
     const convKey = `invite-call:${phoneNumber}:${timestamp}`;
     const { conversationId } = getOrCreateConversation(convKey);

package/src/calls/call-pointer-message-composer.ts

@@ -2,7 +2,7 @@
  * Deterministic call pointer message templates and instruction builder.
  *
  * Provides fallback templates for untrusted audiences and builds
- * structured instructions for the daemon session to generate pointer
+ * structured instructions for the daemon conversation to generate pointer
  * copy as a natural conversation turn for trusted audiences.
  */
 
@@ -31,7 +31,7 @@ export interface CallPointerMessageContext {
 // ---------------------------------------------------------------------------
 
 /**
- * Build an instruction message to send to the daemon session so the
+ * Build an instruction message to send to the daemon conversation so the
  * assistant generates a natural pointer status update as a conversation turn.
  */
 export function buildPointerInstruction(

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

@@ -4,7 +4,7 @@
  * (which lives in the dedicated voice conversation).
  *
  * Trust-aware: trusted audiences get pointer messages routed through the
- * daemon session as a conversation turn (the assistant generates the text).
+ * daemon conversation as a conversation turn (the assistant generates the text).
  * Untrusted/unknown audiences always receive deterministic fallback text
  * written directly to the conversation store.
  */
@@ -13,7 +13,7 @@ import {
   addMessage,
   getConversationOriginChannel,
   getConversationRecentProvenanceTrustClass,
-  getConversationThreadType,
+  getConversationType,
 } from "../memory/conversation-crud.js";
 import { getLogger } from "../util/logger.js";
 import {
@@ -34,7 +34,7 @@ export type PointerEvent =
 export type PointerAudienceMode = "auto" | "trusted" | "untrusted";
 
 /**
- * Daemon-injected function that sends a message through the daemon session
+ * Daemon-injected function that sends a message through the daemon conversation
  * pipeline (persistAndProcessMessage), letting the assistant generate the
  * pointer text as a natural conversation turn.
  *
@@ -80,7 +80,7 @@ export function resetPointerMessageProcessor(): void {
  *
  * Trusted when:
  * - recent message provenance trust class is 'guardian' or 'trusted_contact'
- * - conversation threadType is 'private' (local desktop-origin context)
+ * - conversation conversationType is 'private' (local desktop-origin context)
  * - conversation origin channel is 'vellum' (desktop app)
  *
  * Untrusted by default when insufficient evidence.
@@ -89,14 +89,14 @@ function resolvePointerAudienceTrust(conversationId: string): boolean {
   try {
     // Check provenance trust class on recent messages first — this catches
     // trusted contacts who initiate calls from gateway channels (e.g. WhatsApp)
-    // where the conversation itself isn't a desktop-origin private thread.
+    // where the conversation itself isn't a desktop-origin private conversation.
     const provenance =
       getConversationRecentProvenanceTrustClass(conversationId);
     if (provenance === "guardian" || provenance === "trusted_contact")
       return true;
 
-    const threadType = getConversationThreadType(conversationId);
-    if (threadType === "private") return true;
+    const conversationType = getConversationType(conversationId);
+    if (conversationType === "private") return true;
 
     const originChannel = getConversationOriginChannel(conversationId);
     if (originChannel === "vellum") return true;
@@ -157,7 +157,7 @@ export async function addPointerMessage(
     (audienceMode === "auto" && resolvePointerAudienceTrust(conversationId));
 
   if (trustedAudience && pointerMessageProcessor) {
-    // Route through the daemon session — the assistant generates the
+    // Route through the daemon conversation — the assistant generates the
     // pointer text as a natural conversation turn, shaped by context,
     // identity, and preferences.
     const instruction = buildPointerInstruction(context);
@@ -183,9 +183,9 @@ export async function addPointerMessage(
   const text = getPointerFallbackMessage(context);
 
   // Pointer messages are assistant-generated status updates in the initiating
-  // desktop thread. Do not set userMessageChannel — doing so would mark the
+  // desktop conversation. Do not set userMessageChannel — doing so would mark the
   // conversation's origin channel as voice, causing it to leak into the
-  // desktop thread list as a channel-bound session.
+  // desktop conversation list as a channel-bound conversation.
   await addMessage(
     conversationId,
     "assistant",

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

@@ -6,7 +6,7 @@
  * 1. Expires the request and all its deliveries in the store
  * 2. Expires the associated pending question so the call-side timeout fires
  * 3. Sends expiry notices to external delivery destinations (telegram)
- * 4. Adds an expiry message to mac guardian thread conversations
+ * 4. Adds an expiry message to mac guardian conversations
  */
 
 import { addMessage } from "../memory/conversation-crud.js";
@@ -31,7 +31,7 @@ let sweepInProgress = false;
 
 /**
  * Send expiry notices to all delivery destinations for a guardian action
- * request. Handles both vellum/mac thread messages and external channel
+ * request. Handles both vellum/mac conversation messages and external channel
  * replies (telegram, slack).
  *
  * Deliveries must be captured *before* their status is changed to 'expired'
@@ -70,7 +70,7 @@ export async function sendGuardianExpiryNotices(
         delivery.destinationChannel === "vellum" &&
         delivery.destinationConversationId
       ) {
-        // Add expiry message to vellum guardian thread.
+        // Add expiry message to vellum guardian conversation.
         await addMessage(
           delivery.destinationConversationId,
           "assistant",

package/src/calls/guardian-dispatch.ts

@@ -97,7 +97,7 @@ async function dispatchGuardianQuestionInner(
   try {
     const expiresAt = Date.now() + getUserConsultationTimeoutMs();
 
-    // Voice decisions are handled in guardian threads tied to the assistant-
+    // Voice decisions are handled in guardian conversations tied to the assistant-
     // level guardian identity. Resolve the principal from the contacts table.
     let guardianPrincipalId: string | undefined;
 
@@ -144,7 +144,7 @@ async function dispatchGuardianQuestionInner(
       guardianPrincipalId,
       toolName,
       inputDigest,
-      expiresAt: new Date(expiresAt).toISOString(),
+      expiresAt,
     });
 
     log.info(
@@ -158,7 +158,7 @@ async function dispatchGuardianQuestionInner(
 
     // Count how many canonical guardian requests are already pending for
     // this call session. Used as a candidate-affinity hint so the decision
-    // engine prefers reusing an existing thread.
+    // engine prefers reusing an existing conversation.
     const activeGuardianRequestCount = listCanonicalGuardianRequests({
       status: "pending",
       sourceType: "voice",
@@ -167,7 +167,7 @@ async function dispatchGuardianQuestionInner(
     // Look up the vellum conversation used for the first guardian question
     // delivery in this call session. When found, pass it as an affinity hint
     // so the notification pipeline deterministically routes to the same
-    // conversation instead of letting the LLM choose a different thread.
+    // conversation instead of letting the LLM choose a different conversation.
     // Find earlier canonical requests for this call session and check their
     // deliveries for a vellum destination conversation ID.
     let existingGuardianConversationId: string | null = null;
@@ -192,12 +192,12 @@ async function dispatchGuardianQuestionInner(
     if (existingGuardianConversationId) {
       log.info(
         { callSessionId, existingGuardianConversationId },
-        "Found existing guardian conversation for call session — enforcing thread affinity",
+        "Found existing guardian conversation for call session — enforcing conversation affinity",
       );
     }
 
     // Route through the canonical notification pipeline. The paired vellum
-    // conversation from this pipeline is the canonical guardian thread.
+    // conversation from this pipeline is the canonical guardian conversation.
     let vellumDeliveryId: string | null = null;
     const requestCode =
       request.requestCode ?? request.id.slice(0, 6).toUpperCase();
@@ -223,7 +223,7 @@ async function dispatchGuardianQuestionInner(
       },
       conversationAffinityHint,
       dedupeKey: `guardian:${request.id}`,
-      onThreadCreated: (info) => {
+      onConversationCreated: (info) => {
         if (info.sourceEventName !== "guardian.question" || vellumDeliveryId)
           return;
         const delivery = createCanonicalGuardianDelivery({

package/src/calls/guardian-question-copy.ts

@@ -1,8 +1,8 @@
 /**
- * Generative copy for guardian question threads.
+ * Generative copy for guardian question conversations.
  *
  * Uses the configured provider to generate an attention-oriented emoji-prefixed
- * thread title and a richer initial message. Falls back to deterministic copy
+ * conversation title and a richer initial message. Falls back to deterministic copy
  * when the provider is unavailable or generation fails/times out.
  */
 
@@ -20,7 +20,7 @@ const log = getLogger("guardian-question-copy");
 const GENERATION_TIMEOUT_MS = 5_000;
 
 export interface GuardianCopy {
-  threadTitle: string;
+  conversationTitle: string;
   initialMessage: string;
 }
 
@@ -29,7 +29,7 @@ export interface GuardianCopy {
  */
 export function buildFallbackCopy(questionText: string): GuardianCopy {
   return {
-    threadTitle: `\u26A0\uFE0F ${questionText.slice(0, 70)}`,
+    conversationTitle: `\u26A0\uFE0F ${questionText.slice(0, 70)}`,
     initialMessage: [
       "Your assistant needs your input during a phone call.",
       "",
@@ -41,7 +41,7 @@ export function buildFallbackCopy(questionText: string): GuardianCopy {
 }
 
 /**
- * Generate guardian thread copy (title + initial message) via the configured
+ * Generate guardian conversation copy (title + initial message) via the configured
  * LLM provider. Returns deterministic fallback when the provider is unavailable,
  * generation times out, or any error occurs.
  */
@@ -64,7 +64,7 @@ export async function generateGuardianCopy(
 
   try {
     const prompt = [
-      "Generate a thread title and initial message for a guardian question during a live phone call.",
+      "Generate a conversation title and initial message for a guardian question during a live phone call.",
       "",
       `Question: ${questionText}`,
       ...(requestCode ? [`Reference code: ${requestCode}`] : []),
@@ -134,5 +134,5 @@ function parseGeneratedCopy(text: string): GuardianCopy | null {
     return null;
   }
 
-  return { threadTitle: title, initialMessage: message };
+  return { conversationTitle: title, initialMessage: message };
 }

package/src/calls/relay-server.ts

@@ -1946,8 +1946,8 @@ export class RelayConnection {
 
     const session = getCallSession(this.callSessionId);
     if (session) {
-      // User message persistence is handled by the session pipeline
-      // (voice-session-bridge -> session.persistUserMessage) so we only
+      // User message persistence is handled by the conversation pipeline
+      // (voice-session-bridge -> conversation.persistUserMessage) so we only
       // need to fire the transcript notifier for UI subscribers here.
       fireCallTranscriptNotifier(
         session.conversationId,
@@ -1957,13 +1957,13 @@ export class RelayConnection {
       );
     }
 
-    // Route to controller for session-backed response
+    // Route to controller for conversation-backed response
     if (this.controller) {
       await this.controller.handleCallerUtterance(msg.voicePrompt, speaker);
     } else {
       // Fallback if controller not yet initialized — persist the caller's
       // transcript so it is available in conversation history once setup
-      // completes. The session pipeline normally handles persistence, but
+      // completes. The conversation pipeline normally handles persistence, but
       // this early-utterance path bypasses it entirely.
       if (session) {
         try {

package/src/calls/twilio-routes.ts

@@ -108,7 +108,7 @@ export function buildWelcomeGreeting(
   const override = configuredGreeting?.trim();
   if (override) return override;
   // The contextual first opener now comes from the call controller's
-  // initial LLM turn via the session pipeline. Keep Twilio's relay-level
+  // initial LLM turn via the conversation pipeline. Keep Twilio's relay-level
   // greeting empty by default so we don't speak a deterministic static line first.
   return "";
 }