@vellumai/assistant 0.5.0 → 0.5.2

package/src/__tests__/workspace-migration-backfill-installation-id.test.ts

@@ -0,0 +1,328 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+const existsSyncFn = mock((_path: string): boolean => false);
+const readFileSyncFn = mock((_path: string, _enc: string): string => "");
+const writeFileSyncFn = mock((_path: string, _data: string): void => undefined);
+const randomUUIDFn = mock((): string => "generated-uuid-1234");
+const getMemoryCheckpointFn = mock((_key: string): string | null => null);
+const deleteMemoryCheckpointFn = mock((_key: string): void => undefined);
+const getExternalAssistantIdFn = mock((): string | undefined => "my-assistant");
+const homedirFn = mock((): string => "/mock-home");
+
+// ---------------------------------------------------------------------------
+// Mock modules — before importing module under test
+// ---------------------------------------------------------------------------
+
+mock.module("node:fs", () => ({
+  existsSync: existsSyncFn,
+  readFileSync: readFileSyncFn,
+  writeFileSync: writeFileSyncFn,
+}));
+
+mock.module("node:crypto", () => ({
+  randomUUID: randomUUIDFn,
+}));
+
+mock.module("node:os", () => ({
+  homedir: homedirFn,
+}));
+
+mock.module("../memory/checkpoints.js", () => ({
+  getMemoryCheckpoint: getMemoryCheckpointFn,
+  deleteMemoryCheckpoint: deleteMemoryCheckpointFn,
+}));
+
+mock.module("../runtime/auth/external-assistant-id.js", () => ({
+  getExternalAssistantId: getExternalAssistantIdFn,
+}));
+
+// Import after mocking
+import { backfillInstallationIdMigration } from "../workspace/migrations/002-backfill-installation-id.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const BASE = "/mock-home";
+const LOCK_PATH = `${BASE}/.vellum.lock.json`;
+const LEGACY_LOCK_PATH = `${BASE}/.vellum.lockfile.json`;
+const WORKSPACE_DIR = `${BASE}/.vellum/workspace`;
+
+function makeLockfile(assistants: Array<Record<string, unknown>>): string {
+  return JSON.stringify({ assistants });
+}
+
+function setupFs(fileContents: Record<string, string>): void {
+  existsSyncFn.mockImplementation((path: string) => path in fileContents);
+  readFileSyncFn.mockImplementation((path: string, _enc: string) => {
+    if (path in fileContents) return fileContents[path];
+    throw new Error(`ENOENT: ${path}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("002-backfill-installation-id migration", () => {
+  beforeEach(() => {
+    existsSyncFn.mockClear();
+    readFileSyncFn.mockClear();
+    writeFileSyncFn.mockClear();
+    randomUUIDFn.mockClear();
+    getMemoryCheckpointFn.mockClear();
+    deleteMemoryCheckpointFn.mockClear();
+    getExternalAssistantIdFn.mockClear();
+    homedirFn.mockClear();
+
+    // Defaults
+    homedirFn.mockReturnValue("/mock-home");
+    getExternalAssistantIdFn.mockReturnValue("my-assistant");
+    getMemoryCheckpointFn.mockReturnValue(null);
+    randomUUIDFn.mockReturnValue("generated-uuid-1234");
+    delete process.env.BASE_DATA_DIR;
+  });
+
+  test("no-op when no lockfile exists", () => {
+    setupFs({});
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when lockfile has no assistants array", () => {
+    setupFs({
+      [LOCK_PATH]: JSON.stringify({ version: 1 }),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when lockfile is malformed JSON", () => {
+    setupFs({
+      [LOCK_PATH]: "{{not json",
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when lockfile is an array", () => {
+    setupFs({
+      [LOCK_PATH]: JSON.stringify([1, 2, 3]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("no-op when no matching assistant entry found", () => {
+    getExternalAssistantIdFn.mockReturnValue("my-assistant");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([
+        { assistantId: "other-assistant", installationId: undefined },
+      ]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("backfills installationId from SQLite checkpoint", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-install-id");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [path, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    expect(path).toBe(LOCK_PATH);
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("sqlite-install-id");
+  });
+
+  test("generates new UUID when no SQLite checkpoint exists", () => {
+    getMemoryCheckpointFn.mockReturnValue(null);
+    randomUUIDFn.mockReturnValue("new-uuid-5678");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("new-uuid-5678");
+  });
+
+  test("generates new UUID when SQLite table does not exist", () => {
+    getMemoryCheckpointFn.mockImplementation(() => {
+      throw new Error("no such table: memory_checkpoints");
+    });
+    randomUUIDFn.mockReturnValue("fallback-uuid");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("fallback-uuid");
+  });
+
+  test("skips lockfile write when entry already has installationId", () => {
+    setupFs({
+      [LOCK_PATH]: makeLockfile([
+        { assistantId: "my-assistant", installationId: "existing-id" },
+      ]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).not.toHaveBeenCalled();
+  });
+
+  test("cleans up SQLite checkpoint when entry already has installationId", () => {
+    setupFs({
+      [LOCK_PATH]: makeLockfile([
+        { assistantId: "my-assistant", installationId: "existing-id" },
+      ]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(deleteMemoryCheckpointFn).toHaveBeenCalledWith(
+      "telemetry:installation_id",
+    );
+  });
+
+  test("cleans up SQLite checkpoint after writing lockfile", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    expect(deleteMemoryCheckpointFn).toHaveBeenCalledWith(
+      "telemetry:installation_id",
+    );
+  });
+
+  test("handles deleteMemoryCheckpoint throwing gracefully", () => {
+    deleteMemoryCheckpointFn.mockImplementation(() => {
+      throw new Error("no such table");
+    });
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    // Should not throw
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+  });
+
+  test("reads from legacy .vellum.lockfile.json when primary is absent", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+    setupFs({
+      [LEGACY_LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [path, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    expect(path).toBe(LEGACY_LOCK_PATH);
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("sqlite-id");
+  });
+
+  test("prefers primary lockfile over legacy when both exist", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+    setupFs({
+      [LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+      [LEGACY_LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [path] = writeFileSyncFn.mock.calls[0] as [string, string];
+    expect(path).toBe(LOCK_PATH);
+  });
+
+  test("falls through to legacy lockfile when primary is malformed", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+    setupFs({
+      [LOCK_PATH]: "{{not json",
+      [LEGACY_LOCK_PATH]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [path, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    expect(path).toBe(LEGACY_LOCK_PATH);
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("sqlite-id");
+  });
+
+  test("respects BASE_DATA_DIR environment variable", () => {
+    process.env.BASE_DATA_DIR = "/custom-base";
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+
+    const customLockPath = "/custom-base/.vellum.lock.json";
+    setupFs({
+      [customLockPath]: makeLockfile([{ assistantId: "my-assistant" }]),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [path] = writeFileSyncFn.mock.calls[0] as [string, string];
+    expect(path).toBe(customLockPath);
+  });
+
+  test("preserves other assistants in lockfile when writing", () => {
+    getMemoryCheckpointFn.mockReturnValue("sqlite-id");
+    setupFs({
+      [LOCK_PATH]: JSON.stringify({
+        assistants: [
+          { assistantId: "other-assistant", installationId: "other-id" },
+          { assistantId: "my-assistant" },
+        ],
+      }),
+    });
+
+    backfillInstallationIdMigration.run(WORKSPACE_DIR);
+
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(1);
+    const [, data] = writeFileSyncFn.mock.calls[0] as [string, string];
+    const parsed = JSON.parse(data);
+    expect(parsed.assistants[0].installationId).toBe("other-id");
+    expect(parsed.assistants[1].installationId).toBe("sqlite-id");
+  });
+
+  test("has migration id 002-backfill-installation-id", () => {
+    expect(backfillInstallationIdMigration.id).toBe(
+      "002-backfill-installation-id",
+    );
+  });
+});

package/src/__tests__/workspace-migration-seed-device-id.test.ts

@@ -10,7 +10,7 @@ const writeFileSyncFn = mock(
   (_path: string, _data: string, _opts?: object) => {},
 );
 const mkdirSyncFn = mock((_path: string, _opts?: object) => {});
-const getBaseDataDirFn = mock((): string | undefined => undefined);
+const getDeviceIdBaseDirFn = mock((): string => "/mock-home");
 
 // ---------------------------------------------------------------------------
 // Mock modules — before importing module under test
@@ -23,12 +23,8 @@ mock.module("node:fs", () => ({
   mkdirSync: mkdirSyncFn,
 }));
 
-mock.module("node:os", () => ({
-  homedir: () => "/mock-home",
-}));
-
-mock.module("../config/env-registry.js", () => ({
-  getBaseDataDir: getBaseDataDirFn,
+mock.module("../util/device-id.js", () => ({
+  getDeviceIdBaseDir: getDeviceIdBaseDirFn,
 }));
 
 // Import after mocking
@@ -67,7 +63,7 @@ describe("003-seed-device-id migration", () => {
     readFileSyncFn.mockClear();
     writeFileSyncFn.mockClear();
     mkdirSyncFn.mockClear();
-    getBaseDataDirFn.mockReturnValue(undefined);
+    getDeviceIdBaseDirFn.mockReturnValue("/mock-home");
   });
 
   test("no-op when device.json already has a deviceId", () => {
@@ -269,9 +265,9 @@ describe("003-seed-device-id migration", () => {
     expect(parsed.deviceId).toBe("install-legacy");
   });
 
-  test("respects BASE_DATA_DIR override", () => {
+  test("respects BASE_DATA_DIR override via getDeviceIdBaseDir", () => {
     const customBase = "/custom-base";
-    getBaseDataDirFn.mockReturnValue(customBase);
+    getDeviceIdBaseDirFn.mockReturnValue(customBase);
 
     const customLockPath = `${customBase}/.vellum.lock.json`;
     const customDevicePath = `${customBase}/.vellum/device.json`;

package/src/agent/attachments.ts

@@ -1,4 +1,4 @@
-import type { ContentBlock } from "../providers/types.js";
+import type { ContentBlock, Message } from "../providers/types.js";
 
 export interface MessageAttachmentInput {
   id?: string;
@@ -6,6 +6,7 @@ export interface MessageAttachmentInput {
   mimeType: string;
   data: string;
   extractedText?: string;
+  filePath?: string;
 }
 
 export function attachmentsToContentBlocks(
@@ -35,3 +36,28 @@ export function attachmentsToContentBlocks(
     } as ContentBlock;
   });
 }
+
+/**
+ * Return a copy of the message with text annotations for image source paths.
+ * The annotations are appended as a text content block so the LLM knows where
+ * the images came from on disk. The caller should persist the ORIGINAL message
+ * (without annotations) so the UI stays clean.
+ */
+export function enrichMessageWithSourcePaths(
+  message: Message,
+  attachments: MessageAttachmentInput[],
+): Message {
+  const imageAttachments = attachments.filter(
+    (a) => a.mimeType.toLowerCase().startsWith("image/") && a.filePath,
+  );
+  if (imageAttachments.length === 0) return message;
+
+  const annotation = imageAttachments
+    .map((a) => `[Attached image source: ${a.filePath}]`)
+    .join("\n");
+
+  return {
+    ...message,
+    content: [...message.content, { type: "text" as const, text: annotation }],
+  };
+}

package/src/agent/loop.ts

@@ -88,6 +88,7 @@ export type AgentEvent =
       cacheCreationInputTokens?: number;
       cacheReadInputTokens?: number;
       model: string;
+      actualProvider?: string;
       providerDurationMs: number;
       rawRequest?: unknown;
       rawResponse?: unknown;
@@ -100,6 +101,7 @@ const DEFAULT_CONFIG: AgentLoopConfig = {
 };
 
 const PROGRESS_CHECK_INTERVAL = 5;
+const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
 const PROGRESS_CHECK_REMINDER =
   "You have been using tools for several turns. Check whether you are making meaningful progress toward the user's goal. If you are stuck in a loop or not making progress, summarize what you have tried and ask the user for guidance instead of continuing.";
 
@@ -200,6 +202,7 @@ export class AgentLoop {
     const history = [...messages];
     let toolUseTurns = 0;
     let nudgedForEmptyResponse = false;
+    let consecutiveErrorTurns = 0;
     let lastLlmCallTime = 0;
     const rlog = requestId ? log.child({ requestId }) : log;
 
@@ -350,6 +353,7 @@ export class AgentLoop {
           cacheCreationInputTokens: response.usage.cacheCreationInputTokens,
           cacheReadInputTokens: response.usage.cacheReadInputTokens,
           model: response.model,
+          actualProvider: response.actualProvider ?? this.provider.name,
           providerDurationMs,
           rawRequest: response.rawRequest,
           rawResponse: response.rawResponse,
@@ -566,13 +570,37 @@ export class AgentLoop {
 
         // Track tool-use turns and inject progress reminder every N turns
         toolUseTurns++;
-        if (toolUseTurns % PROGRESS_CHECK_INTERVAL === 0) {
+        const isProgressCheckTurn =
+          toolUseTurns % PROGRESS_CHECK_INTERVAL === 0;
+        if (isProgressCheckTurn) {
           resultBlocks.push({
             type: "text",
             text: `<system_notice>${PROGRESS_CHECK_REMINDER}</system_notice>`,
           });
         }
 
+        // When any tool returned an error, nudge the LLM to retry with
+        // corrected parameters instead of ending its turn. Skip the nudge
+        // when the progress check fires (to avoid contradictory instructions)
+        // and after MAX_CONSECUTIVE_ERROR_NUDGES consecutive error turns
+        // (the error is likely unrecoverable at that point).
+        const hasToolError = toolResults.some(({ result }) => result.isError);
+        if (hasToolError) {
+          consecutiveErrorTurns++;
+        } else {
+          consecutiveErrorTurns = 0;
+        }
+        if (
+          hasToolError &&
+          !isProgressCheckTurn &&
+          consecutiveErrorTurns <= MAX_CONSECUTIVE_ERROR_NUDGES
+        ) {
+          resultBlocks.push({
+            type: "text",
+            text: "<system_notice>One or more tool calls returned an error. If the error looks recoverable (e.g. missing or invalid parameters), fix the parameters and retry. If the error is clearly unrecoverable (e.g. a service is down, a resource does not exist, or a permission is permanently denied), report it to the user.</system_notice>",
+          });
+        }
+
         // Remind the LLM not to repeat text it already streamed
         if (hasTextBlock) {
           resultBlocks.push({

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

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { renderCharacterAscii } from "./ascii-renderer.js";
+import { getCharacterComponents } from "./character-components.js";
 import { renderCharacterPng } from "./png-renderer.js";
 
 const log = getLogger("traits-png-sync");
@@ -24,37 +25,56 @@ export type TraitsSyncResult =
     };
 
 /**
- * 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.
+ * Renders avatar PNG and ASCII art into memory without touching the filesystem.
+ * Call this before any disk writes so a render failure leaves all files untouched.
  */
-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.
+function renderAvatarBuffers(traits: CharacterTraits): {
+  pngBuffer: Buffer;
+  asciiArt: string | null;
+} {
   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.
+  let asciiArt: string | null = null;
   try {
-    const asciiPath = join(avatarDir, "character-ascii.txt");
-    const asciiArt = renderCharacterAscii(
+    asciiArt = renderCharacterAscii(
       traits.bodyShape,
       traits.eyeStyle,
       traits.color,
     );
+  } catch (asciiErr) {
+    log.warn(
+      { err: asciiErr },
+      "Failed to render ASCII art — will still write PNG and traits",
+    );
+  }
+
+  return { pngBuffer, asciiArt };
+}
+
+/**
+ * Writes pre-rendered avatar files (PNG + optional ASCII) to disk atomically.
+ * Returns `true` if the ASCII sidecar was also written successfully.
+ */
+function writeAvatarFiles(
+  avatarDir: string,
+  pngBuffer: Buffer,
+  asciiArt: string | null,
+): boolean {
+  const pngPath = join(avatarDir, "avatar-image.png");
+  const pngTmp = `${pngPath}.${randomUUID()}.tmp`;
+  writeFileSync(pngTmp, pngBuffer);
+  renameSync(pngTmp, pngPath);
+
+  if (asciiArt == null) {
+    return false;
+  }
+
+  try {
+    const asciiPath = join(avatarDir, "character-ascii.txt");
     const asciiTmp = `${asciiPath}.${randomUUID()}.tmp`;
     writeFileSync(asciiTmp, asciiArt);
     renameSync(asciiTmp, asciiPath);
@@ -73,8 +93,10 @@ function renderAndWriteAvatarFiles(
  * 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.
+ * Validates trait IDs against the component set, then renders into memory
+ * before any disk writes.  Writes the traits file first, then the rendered
+ * avatar files, so a render failure leaves all files untouched and a disk
+ * failure after traits are written never leaves the PNG ahead of the traits.
  */
 export function writeTraitsAndRenderAvatar(
   traits: CharacterTraits,
@@ -94,22 +116,55 @@ export function writeTraitsAndRenderAvatar(
     };
   }
 
+  // Validate trait IDs against the known component set so that unknown values
+  // are surfaced as input-validation errors (400) rather than server errors (500).
+  const components = getCharacterComponents();
+  const validBodyShapes = components.bodyShapes.map((b) => b.id);
+  if (!validBodyShapes.includes(traits.bodyShape)) {
+    return {
+      ok: false,
+      reason: "invalid_traits",
+      message: `Unknown body shape: "${traits.bodyShape}". Valid IDs: ${validBodyShapes.join(", ")}`,
+    };
+  }
+  const validEyeStyles = components.eyeStyles.map((e) => e.id);
+  if (!validEyeStyles.includes(traits.eyeStyle)) {
+    return {
+      ok: false,
+      reason: "invalid_traits",
+      message: `Unknown eye style: "${traits.eyeStyle}". Valid IDs: ${validEyeStyles.join(", ")}`,
+    };
+  }
+  const validColors = components.colors.map((c) => c.id);
+  if (!validColors.includes(traits.color)) {
+    return {
+      ok: false,
+      reason: "invalid_traits",
+      message: `Unknown color: "${traits.color}". Valid IDs: ${validColors.join(", ")}`,
+    };
+  }
+
   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);
+    // Phase 1: Render everything into memory — no disk writes yet.
+    // If rendering fails, all files remain untouched.
+    const { pngBuffer, asciiArt } = renderAvatarBuffers(traits);
 
-    // Write traits file atomically (after successful render)
+    // Phase 2: Write traits file atomically first.
     const traitsJson = JSON.stringify(traits, null, 2);
     const traitsTmp = `${traitsPath}.${randomUUID()}.tmp`;
     writeFileSync(traitsTmp, traitsJson);
     renameSync(traitsTmp, traitsPath);
 
+    // Phase 3: Write rendered avatar files to disk.
+    // Traits are already committed, so a failure here leaves traits ahead of
+    // the PNG — acceptable because the next render call will reconcile them.
+    const asciiWritten = writeAvatarFiles(avatarDir, pngBuffer, asciiArt);
+
     log.info(
       {
         bodyShape: traits.bodyShape,

package/src/bundler/app-bundler.ts

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import archiver from "archiver";
 import JSZip from "jszip";
 
-import { getApp, getAppsDir, isMultifileApp } from "../memory/app-store.js";
+import { getApp, getAppDirPath, isMultifileApp } from "../memory/app-store.js";
 import { computeContentId } from "../util/content-id.js";
 import { getLogger } from "../util/logger.js";
 import { compileApp } from "./app-compiler.js";
@@ -79,7 +79,7 @@ export async function packageApp(
   // Compile the app and bundle the output.
   const compiledFiles: { name: string; data: Buffer }[] = [];
 
-  const appDir = join(getAppsDir(), appId);
+  const appDir = getAppDirPath(appId);
 
   if (multifile) {
     // Multi-file TSX app: compile src/ -> dist/
@@ -154,7 +154,7 @@ export async function packageApp(
     }
 
     // Include app icon if one was generated
-    const iconPath = join(getAppsDir(), appId, "icon.png");
+    const iconPath = join(getAppDirPath(appId), "icon.png");
     if (existsSync(iconPath)) {
       archive.append(readFileSync(iconPath), { name: "icon.png" });
     }
@@ -202,7 +202,7 @@ export async function packageApp(
 
   // Read icon for inclusion in the response
   let iconImageBase64: string | undefined;
-  const iconFilePath = join(getAppsDir(), appId, "icon.png");
+  const iconFilePath = join(getAppDirPath(appId), "icon.png");
   if (existsSync(iconFilePath)) {
     iconImageBase64 = readFileSync(iconFilePath).toString("base64");
   }

package/src/calls/call-domain.ts

@@ -1088,6 +1088,7 @@ export async function startInviteCall(
       callMode: "invite",
       inviteFriendName: friendName,
       inviteGuardianName: guardianName,
+      initiatedFromConversationId: conversationId,
     });
     sessionId = session.id;