@vellumai/assistant 0.4.57 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.57",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -1055,39 +1055,46 @@ describe("applyRuntimeInjections with inboundActorContext", () => {
 
 describe("buildTurnContextBlock (channel-only)", () => {
   test("collapses to single field when all channels match", () => {
-    const block = buildTurnContextBlock({
-      turnContext: {
-        userMessageChannel: "telegram",
-        assistantMessageChannel: "telegram",
+    const block = buildTurnContextBlock(
+      {
+        turnContext: {
+          userMessageChannel: "telegram",
+          assistantMessageChannel: "telegram",
+        },
+        conversationOriginChannel: "telegram",
       },
-      conversationOriginChannel: "telegram",
-    }, undefined);
+      undefined,
+    );
     expect(block).toBe(
-      "<turn_context>\n" +
-        "channel: telegram\n" +
-        "</turn_context>",
+      "<turn_context>\n" + "channel: telegram\n" + "</turn_context>",
     );
   });
 
   test('uses "unknown" when conversationOriginChannel is null', () => {
-    const block = buildTurnContextBlock({
-      turnContext: {
-        userMessageChannel: "vellum",
-        assistantMessageChannel: "vellum",
+    const block = buildTurnContextBlock(
+      {
+        turnContext: {
+          userMessageChannel: "vellum",
+          assistantMessageChannel: "vellum",
+        },
+        conversationOriginChannel: null,
       },
-      conversationOriginChannel: null,
-    }, undefined);
+      undefined,
+    );
     expect(block).toContain("conversation_origin_channel: unknown");
   });
 
   test("handles mixed channels", () => {
-    const block = buildTurnContextBlock({
-      turnContext: {
-        userMessageChannel: "telegram",
-        assistantMessageChannel: "vellum",
+    const block = buildTurnContextBlock(
+      {
+        turnContext: {
+          userMessageChannel: "telegram",
+          assistantMessageChannel: "vellum",
+        },
+        conversationOriginChannel: "vellum",
       },
-      conversationOriginChannel: "vellum",
-    }, undefined);
+      undefined,
+    );
     expect(block).toContain("user_message_channel: telegram");
     expect(block).toContain("assistant_message_channel: vellum");
     expect(block).toContain("conversation_origin_channel: vellum");

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

@@ -1,8 +1,4 @@
-import {
-  createCipheriv,
-  pbkdf2Sync,
-  randomBytes,
-} from "node:crypto";
+import { createCipheriv, pbkdf2Sync, randomBytes } from "node:crypto";
 import {
   chmodSync,
   existsSync,
@@ -72,11 +68,23 @@ const SALT_LENGTH = 32;
 /** Local copy of the legacy machine entropy derivation (the export was removed). */
 function legacyMachineEntropy(): string {
   const parts: string[] = [];
-  try { parts.push(hostname()); } catch { parts.push("unknown-host"); }
-  try { parts.push(userInfo().username); } catch { parts.push("unknown-user"); }
+  try {
+    parts.push(hostname());
+  } catch {
+    parts.push("unknown-host");
+  }
+  try {
+    parts.push(userInfo().username);
+  } catch {
+    parts.push("unknown-user");
+  }
   parts.push(process.platform);
   parts.push(process.arch);
-  try { parts.push(userInfo().homedir); } catch { parts.push("/tmp"); }
+  try {
+    parts.push(userInfo().homedir);
+  } catch {
+    parts.push("/tmp");
+  }
   return parts.join(":");
 }
 
@@ -346,7 +354,8 @@ describe("encrypted-store", () => {
       // Create a v1 store using legacy encryption
       const salt = randomBytes(SALT_LENGTH);
       const legacyKey = legacyDeriveKey(salt);
-      const entries: Record<string, { iv: string; tag: string; data: string }> = {};
+      const entries: Record<string, { iv: string; tag: string; data: string }> =
+        {};
       entries["api-key"] = legacyEncrypt("secret-123", legacyKey);
       entries["other-key"] = legacyEncrypt("secret-456", legacyKey);
       writeV1Store(STORE_PATH, salt, entries);
@@ -372,7 +381,8 @@ describe("encrypted-store", () => {
       // Create a v1 store
       const salt = randomBytes(SALT_LENGTH);
       const legacyKey = legacyDeriveKey(salt);
-      const entries: Record<string, { iv: string; tag: string; data: string }> = {};
+      const entries: Record<string, { iv: string; tag: string; data: string }> =
+        {};
       entries["my-key"] = legacyEncrypt("my-value", legacyKey);
       writeV1Store(STORE_PATH, salt, entries);
 
@@ -393,7 +403,8 @@ describe("encrypted-store", () => {
       // Create a v1 store with one good entry and one tampered entry
       const salt = randomBytes(SALT_LENGTH);
       const legacyKey = legacyDeriveKey(salt);
-      const entries: Record<string, { iv: string; tag: string; data: string }> = {};
+      const entries: Record<string, { iv: string; tag: string; data: string }> =
+        {};
       entries["good"] = legacyEncrypt("good-value", legacyKey);
       entries["bad"] = legacyEncrypt("bad-value", legacyKey);
       // Tamper with the bad entry
@@ -423,7 +434,8 @@ describe("encrypted-store", () => {
       // write v1 store + store.key but leave store as v1
       const salt = randomBytes(SALT_LENGTH);
       const legacyKey = legacyDeriveKey(salt);
-      const entries: Record<string, { iv: string; tag: string; data: string }> = {};
+      const entries: Record<string, { iv: string; tag: string; data: string }> =
+        {};
       entries["test-key"] = legacyEncrypt("test-value", legacyKey);
       writeV1Store(STORE_PATH, salt, entries);
 

package/src/__tests__/file-read-tool.test.ts

@@ -177,3 +177,43 @@ describe("file_read image support", () => {
     expect(result.content).toContain("outside the working directory");
   });
 });
+
+// ── Out-of-bounds hint for host_file_read ─────────────────────────────
+
+describe("file_read out-of-bounds hint", () => {
+  test("suggests host_file_read for out-of-bounds text file path", async () => {
+    const dir = makeTempDir();
+
+    const result = await fileReadTool.execute(
+      { path: "/etc/passwd" },
+      makeContext(dir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("host_file_read");
+  });
+
+  test("suggests host_file_read for out-of-bounds image file path", async () => {
+    const dir = makeTempDir();
+
+    const result = await fileReadTool.execute(
+      { path: "/Users/someone/Desktop/screenshot.png" },
+      makeContext(dir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("host_file_read");
+  });
+
+  test("does not suggest host_file_read for missing file within sandbox", async () => {
+    const dir = makeTempDir();
+
+    const result = await fileReadTool.execute(
+      { path: "nonexistent.txt" },
+      makeContext(dir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).not.toContain("host_file_read");
+  });
+});

package/src/__tests__/host-file-read-tool.test.ts

@@ -8,6 +8,12 @@ import type { ToolContext } from "../tools/types.js";
 
 const testDirs: string[] = [];
 
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "host-file-read-test-"));
+  testDirs.push(dir);
+  return dir;
+}
+
 function makeContext(): ToolContext {
   return {
     workingDir: "/tmp",
@@ -22,6 +28,18 @@ afterEach(() => {
   }
 });
 
+// Minimal valid JPEG: FF D8 FF E0 header
+const JPEG_HEADER = Buffer.from([
+  0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01,
+  0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00,
+]);
+
+// Minimal PNG header
+const PNG_HEADER = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49,
+  0x48, 0x44, 0x52,
+]);
+
 describe("host_file_read tool", () => {
   test("rejects relative paths", async () => {
     const result = await hostFileReadTool.execute(
@@ -145,3 +163,72 @@ describe("host_file_read tool", () => {
     expect(result.content).toContain("symlink-content");
   });
 });
+
+describe("host_file_read image support", () => {
+  test("returns image content block for .png file", async () => {
+    const dir = makeTempDir();
+    const filePath = join(dir, "screenshot.png");
+    writeFileSync(filePath, PNG_HEADER);
+
+    const result = await hostFileReadTool.execute(
+      { path: filePath },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Image loaded");
+    expect(result.content).toContain("image/png");
+    expect((result as any).contentBlocks).toBeDefined();
+    expect((result as any).contentBlocks[0].type).toBe("image");
+    expect((result as any).contentBlocks[0].source.media_type).toBe(
+      "image/png",
+    );
+  });
+
+  test("returns correct media type for .jpg file", async () => {
+    const dir = makeTempDir();
+    const filePath = join(dir, "photo.jpg");
+    writeFileSync(filePath, JPEG_HEADER);
+
+    const result = await hostFileReadTool.execute(
+      { path: filePath },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Image loaded");
+    expect(result.content).toContain("image/jpeg");
+    expect((result as any).contentBlocks).toBeDefined();
+    expect((result as any).contentBlocks[0].type).toBe("image");
+    expect((result as any).contentBlocks[0].source.media_type).toBe(
+      "image/jpeg",
+    );
+  });
+
+  test("returns error for non-existent image path", async () => {
+    const filePath = join(tmpdir(), `host-file-read-missing-${Date.now()}.png`);
+    const result = await hostFileReadTool.execute(
+      { path: filePath },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("file not found");
+  });
+
+  test("text file still works as before (regression)", async () => {
+    const dir = makeTempDir();
+    const filePath = join(dir, "notes.txt");
+    writeFileSync(filePath, "hello world\nsecond line\n");
+
+    const result = await hostFileReadTool.execute(
+      { path: filePath },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("1  hello world");
+    expect(result.content).toContain("2  second line");
+    expect((result as any).contentBlocks).toBeUndefined();
+  });
+});

package/src/__tests__/identity-intro-cache.test.ts

@@ -0,0 +1,209 @@
+/**
+ * Unit tests for the identity intro cache (identity-intro-cache.ts).
+ *
+ * Validates TTL-based expiration, content-hash-based invalidation when
+ * workspace identity files change, and round-trip get/set behavior.
+ */
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be defined before importing the module under test
+// ---------------------------------------------------------------------------
+
+// Suppress logger output
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// In-memory checkpoint store
+const checkpointStore = new Map<string, string>();
+
+mock.module("../memory/checkpoints.js", () => ({
+  getMemoryCheckpoint: (key: string) => checkpointStore.get(key) ?? null,
+  setMemoryCheckpoint: (key: string, value: string) => {
+    checkpointStore.set(key, value);
+  },
+}));
+
+// Simulated workspace file contents
+const workspaceFiles: Record<string, string> = {};
+
+mock.module("../util/platform.js", () => ({
+  getWorkspacePromptPath: (name: string) => `/mock/workspace/${name}`,
+}));
+
+mock.module("node:fs", () => ({
+  existsSync: (path: string) => {
+    const name = path.split("/").pop() ?? "";
+    return name in workspaceFiles;
+  },
+  readFileSync: (path: string, _encoding: string) => {
+    const name = path.split("/").pop() ?? "";
+    if (name in workspaceFiles) return workspaceFiles[name];
+    throw new Error(`ENOENT: ${path}`);
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Imports (after mocks)
+// ---------------------------------------------------------------------------
+
+import {
+  computeIdentityContentHash,
+  getCachedIntro,
+  setCachedIntro,
+} from "../runtime/routes/identity-intro-cache.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+afterEach(() => {
+  checkpointStore.clear();
+  for (const key of Object.keys(workspaceFiles)) {
+    delete workspaceFiles[key];
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("identity intro cache", () => {
+  test("returns null when cache is empty", () => {
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("round-trip: set then get returns cached text", () => {
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Atlas";
+    workspaceFiles["SOUL.md"] = "Be playful.";
+    workspaceFiles["USER.md"] = "The user likes coffee.";
+
+    setCachedIntro("Hey, I'm Atlas.");
+    const cached = getCachedIntro();
+    expect(cached).not.toBeNull();
+    expect(cached!.text).toBe("Hey, I'm Atlas.");
+  });
+
+  test("returns null when cache is expired (TTL exceeded)", () => {
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Atlas";
+
+    setCachedIntro("Hello!");
+
+    // Manually set the timestamp to 5 hours ago
+    const fiveHoursAgo = String(Date.now() - 5 * 60 * 60 * 1000);
+    checkpointStore.set("identity:intro:cached_at", fiveHoursAgo);
+
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("returns cached text when within TTL (3 hours ago)", () => {
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Atlas";
+
+    setCachedIntro("Hello!");
+
+    // Set timestamp to 3 hours ago (within 4-hour TTL)
+    const threeHoursAgo = String(Date.now() - 3 * 60 * 60 * 1000);
+    checkpointStore.set("identity:intro:cached_at", threeHoursAgo);
+
+    const cached = getCachedIntro();
+    expect(cached).not.toBeNull();
+    expect(cached!.text).toBe("Hello!");
+  });
+
+  test("busts cache when IDENTITY.md changes", () => {
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Atlas";
+    setCachedIntro("I'm Atlas!");
+
+    // Change IDENTITY.md
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Nova";
+
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("busts cache when SOUL.md changes", () => {
+    workspaceFiles["SOUL.md"] = "Be playful.";
+    setCachedIntro("Hey there!");
+
+    // Change SOUL.md
+    workspaceFiles["SOUL.md"] = "Be serious and formal.";
+
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("busts cache when USER.md changes", () => {
+    workspaceFiles["USER.md"] = "Likes coffee.";
+    setCachedIntro("Good morning!");
+
+    // Change USER.md
+    workspaceFiles["USER.md"] = "Likes tea.";
+
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("cache survives when files are unchanged", () => {
+    workspaceFiles["IDENTITY.md"] = "- **Name:** Atlas";
+    workspaceFiles["SOUL.md"] = "Be chill.";
+    workspaceFiles["USER.md"] = "Likes sunsets.";
+
+    setCachedIntro("Atlas here.");
+
+    // Read twice — both should return the cached value
+    expect(getCachedIntro()?.text).toBe("Atlas here.");
+    expect(getCachedIntro()?.text).toBe("Atlas here.");
+  });
+
+  test("computeIdentityContentHash is deterministic", () => {
+    workspaceFiles["IDENTITY.md"] = "test";
+    workspaceFiles["SOUL.md"] = "test2";
+    workspaceFiles["USER.md"] = "test3";
+
+    const hash1 = computeIdentityContentHash();
+    const hash2 = computeIdentityContentHash();
+    expect(hash1).toBe(hash2);
+    expect(hash1).toMatch(/^[a-f0-9]{64}$/); // SHA-256 hex
+  });
+
+  test("computeIdentityContentHash changes when file content changes", () => {
+    workspaceFiles["IDENTITY.md"] = "v1";
+    const hash1 = computeIdentityContentHash();
+
+    workspaceFiles["IDENTITY.md"] = "v2";
+    const hash2 = computeIdentityContentHash();
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  test("handles missing workspace files gracefully", () => {
+    // No files exist — should still work (empty content hashed)
+    setCachedIntro("Hello!");
+    const cached = getCachedIntro();
+    expect(cached).not.toBeNull();
+    expect(cached!.text).toBe("Hello!");
+  });
+
+  test("returns null when text checkpoint is missing", () => {
+    checkpointStore.set("identity:intro:content_hash", "abc");
+    checkpointStore.set("identity:intro:cached_at", String(Date.now()));
+    // Missing text — should return null
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("returns null when hash checkpoint is missing", () => {
+    checkpointStore.set("identity:intro:text", "Hello");
+    checkpointStore.set("identity:intro:cached_at", String(Date.now()));
+    // Missing hash — should return null
+    expect(getCachedIntro()).toBeNull();
+  });
+
+  test("returns null when timestamp checkpoint is missing", () => {
+    checkpointStore.set("identity:intro:text", "Hello");
+    checkpointStore.set("identity:intro:content_hash", "abc");
+    // Missing timestamp — should return null
+    expect(getCachedIntro()).toBeNull();
+  });
+});

package/src/__tests__/model-intents.test.ts

@@ -65,7 +65,7 @@ describe("model intents", () => {
       "claude-opus-4-6",
     );
     expect(resolveModelIntent("openai", "latency-optimized")).toBe(
-      "gpt-4o-mini",
+      "gpt-5.4-nano",
     );
   });
 

package/src/__tests__/non-member-access-request.test.ts

@@ -623,7 +623,7 @@ describe("access-request-helper unit tests", () => {
     expect(telegram!.status).toBe("sent");
   });
 
-  test("notifyGuardianOfAccessRequest records failed vellum fallback when pipeline has no vellum delivery", async () => {
+  test("notifyGuardianOfAccessRequest skips vellum fallback for same-channel-only routing (telegram)", async () => {
     mockEmitResult = {
       signalId: "sig-no-vellum",
       deduplicated: false,
@@ -657,8 +657,8 @@ describe("access-request-helper unit tests", () => {
       (d) => d.destinationChannel === "telegram",
     );
 
-    expect(vellum).toBeDefined();
-    expect(vellum!.status).toBe("failed");
+    // Same-channel routing skips vellum delivery entirely — no fallback record
+    expect(vellum).toBeUndefined();
     expect(telegram).toBeDefined();
     expect(telegram!.destinationChatId).toBe("guardian-chat-456");
     expect(telegram!.status).toBe("sent");

package/src/__tests__/skill-memory.test.ts

@@ -1,14 +1,7 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import {
-  afterAll,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from "bun:test";
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { eq } from "drizzle-orm";
 
@@ -46,8 +39,9 @@ mock.module("../memory/qdrant-client.js", () => ({
 }));
 
 // Controllable mock for resolveCatalog used by seedCatalogSkillMemories
-let mockResolveCatalog: () => Promise<import("../skills/catalog-install.js").CatalogSkill[]> =
-  async () => [];
+let mockResolveCatalog: () => Promise<
+  import("../skills/catalog-install.js").CatalogSkill[]
+> = async () => [];
 
 mock.module("../skills/catalog-install.js", () => ({
   resolveCatalog: (..._args: unknown[]) => mockResolveCatalog(),
@@ -453,7 +447,11 @@ describe("seedCatalogSkillMemories", () => {
 
   test("skips skills whose feature flag is disabled", async () => {
     const skills: CatalogSkill[] = [
-      makeSkill({ id: "unflagged-skill", name: "Unflagged", description: "No flag" }),
+      makeSkill({
+        id: "unflagged-skill",
+        name: "Unflagged",
+        description: "No flag",
+      }),
       makeSkill({
         id: "flagged-skill",
         name: "Flagged",
@@ -485,7 +483,11 @@ describe("seedCatalogSkillMemories", () => {
   test("prunes pre-existing capability for a skill whose flag becomes disabled", async () => {
     // First seed with both skills, all flags enabled
     const skills: CatalogSkill[] = [
-      makeSkill({ id: "unflagged-skill", name: "Unflagged", description: "No flag" }),
+      makeSkill({
+        id: "unflagged-skill",
+        name: "Unflagged",
+        description: "No flag",
+      }),
       makeSkill({
         id: "flagged-skill",
         name: "Flagged",

package/src/daemon/conversation-runtime-assembly.ts

@@ -655,7 +655,6 @@ export function injectTurnContext(
   };
 }
 
-
 /**
  * Build the `<inbound_actor_context>` text block used for model grounding.
  *
@@ -737,7 +736,10 @@ export function buildInboundActorContextBlock(
   }
   // Contact metadata - only included when the sender has a contact record
   // with non-default values.
-  if (ctx.contactNotes && sanitizeInlineContextValue(ctx.contactNotes) !== ctx.trustClass) {
+  if (
+    ctx.contactNotes &&
+    sanitizeInlineContextValue(ctx.contactNotes) !== ctx.trustClass
+  ) {
     lines.push(
       `contact_notes: ${sanitizeInlineContextValue(ctx.contactNotes)}`,
     );
@@ -932,7 +934,6 @@ export interface InterfaceTurnContextParams {
   conversationOriginInterface: InterfaceId | null;
 }
 
-
 /** Strip interface turn context blocks (both legacy separate and unified). */
 export function stripInterfaceTurnContext(messages: Message[]): Message[] {
   return stripUserTextBlocksByPrefix(messages, [

package/src/daemon/trace-emitter.ts

@@ -67,13 +67,14 @@ export class TraceEmitter {
       attributes,
     };
 
+    // Send to client first so synchronous DB writes don't block SSE delivery.
+    this.sendToClient(event);
+
     try {
       persistTraceEvent(event as TraceEvent);
     } catch (err) {
       log.warn({ err, eventId }, "Failed to persist trace event");
     }
-
-    this.sendToClient(event);
   }
 }
 

package/src/memory/search/staleness.ts

@@ -22,7 +22,10 @@ export function computeStaleness(
   now: number,
 ): { level: StalenessLevel; ratio: number } {
   const baseLifetime = BASE_LIFETIME_MS[item.kind] ?? DEFAULT_LIFETIME_MS;
-  const reinforcement = Math.max(1, 1 + 0.3 * (item.sourceConversationCount - 1));
+  const reinforcement = Math.max(
+    1,
+    1 + 0.3 * (item.sourceConversationCount - 1),
+  );
   const effectiveLifetime = baseLifetime * reinforcement;
   const age = now - item.firstSeenAt;
   const ratio = age / effectiveLifetime;