@vellumai/assistant 0.11.4-dev.202608200019.f77fe6a → 0.11.4-dev.202608201011.f81ab8d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-dev.202608200019.f77fe6a",
+  "version": "0.11.4-dev.202608201011.f81ab8d",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/compactor-retained-image-validation.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Compaction must never bake invalid image bytes into the rebuilt history.
+ *
+ * Retained images are re-hydrated from the attachment store and re-optimized
+ * at compaction time. If that pipeline yields bytes that no longer parse as an
+ * image (e.g. a corrupt conversion-cache entry), embedding them would make the
+ * provider reject EVERY subsequent turn with a 400: the conversation wedges
+ * until the block is manually removed. `buildRetainedImageBlocks` drops such
+ * payloads instead.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  buildRetainedImageBlocks,
+  collectImageManifest,
+} from "../context/compactor.js";
+import { attachInlineAttachmentToMessage } from "../persistence/attachments-store.js";
+import {
+  addMessage,
+  createConversation,
+} from "../persistence/conversation-crud.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+
+await initializeDb();
+
+// 1x1 transparent PNG.
+const PNG_1X1_BASE64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+
+// Declared image/png, but the bytes are not any known image format:
+// the stand-in for a corrupted payload surviving in the pipeline.
+const GARBAGE_BASE64 = Buffer.from("definitely not an image").toString(
+  "base64",
+);
+
+function resetTables(): void {
+  const db = getDb();
+  db.run("DELETE FROM message_attachments");
+  db.run("DELETE FROM attachments");
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+async function addImageMessage(
+  conversationId: string,
+  filename: string,
+  dataBase64: string,
+): Promise<void> {
+  const inserted = await addMessage(
+    conversationId,
+    "user",
+    JSON.stringify([{ type: "text", text: filename }]),
+    {
+      metadata: { provenanceTrustClass: "guardian" },
+      skipIndexing: true,
+    },
+  );
+  await attachInlineAttachmentToMessage(
+    inserted.id,
+    0,
+    filename,
+    "image/png",
+    dataBase64,
+  );
+}
+
+describe("buildRetainedImageBlocks corrupt-bytes gate", () => {
+  beforeEach(resetTables);
+
+  test("valid image bytes are retained", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["good.png"],
+      manifest,
+    );
+
+    expect(resolved).toEqual(["good.png"]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].source.type).toBe("base64");
+  });
+
+  test("bytes that do not parse as an image are dropped, not embedded", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "corrupt.png", GARBAGE_BASE64);
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["corrupt.png", "good.png"],
+      manifest,
+    );
+
+    // The corrupt payload is dropped (not listed as manifest-missing, since
+    // it resolved fine; its bytes were the problem) and the valid one
+    // survives.
+    expect(resolved).toEqual(["good.png"]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(1);
+  });
+
+  test("a truncated JPEG (valid SOI header, no EOI) is dropped", async () => {
+    // A JPEG torn mid-write keeps its SOI header, so a format sniff alone
+    // accepts it; the gate must also require an EOI marker.
+    const tornJpeg = Buffer.concat([
+      Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10]),
+      Buffer.from("JFIF\0"),
+      Buffer.alloc(64),
+    ]).toString("base64");
+    const conv = createConversation();
+    await addImageMessage(conv.id, "torn.jpg", tornJpeg);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["torn.jpg"],
+      manifest,
+    );
+
+    expect(resolved).toEqual([]);
+    expect(missing).toEqual([]);
+    expect(blocks).toHaveLength(0);
+  });
+
+  test("unresolvable filenames still land in missing", async () => {
+    const conv = createConversation();
+    await addImageMessage(conv.id, "good.png", PNG_1X1_BASE64);
+    const manifest = collectImageManifest(conv.id, "guardian");
+
+    const { blocks, resolved, missing } = await buildRetainedImageBlocks(
+      ["never-uploaded.png", "good.png"],
+      manifest,
+    );
+
+    expect(missing).toEqual(["never-uploaded.png"]);
+    expect(resolved).toEqual(["good.png"]);
+    expect(blocks).toHaveLength(1);
+  });
+});

package/src/__tests__/image-conversion.test.ts

@@ -6,13 +6,16 @@
  * gated on darwin.
  */
 
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
 import {
   convertImageToJpeg,
+  hasValidJpegStructure,
+  isCompleteJpeg,
   isHeifImage,
   jpegFilenameFor,
   normalizeImageBase64,
@@ -131,6 +134,119 @@ describe("sniffImageMimeType", () => {
   });
 });
 
+describe("isCompleteJpeg", () => {
+  test("accepts SOI...EOI framed payloads", () => {
+    expect(
+      isCompleteJpeg(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0xff, 0xd9])),
+    ).toBe(true);
+  });
+
+  test("rejects empty, truncated, and non-JPEG payloads", () => {
+    expect(isCompleteJpeg(Buffer.alloc(0))).toBe(false);
+    // Valid head, torn tail: the poisoned-cache signature.
+    expect(isCompleteJpeg(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]))).toBe(
+      false,
+    );
+    expect(isCompleteJpeg(PNG_1PX_BYTES)).toBe(false);
+  });
+});
+
+// Mirrors the converter's cache-key derivation so the test can plant a
+// poisoned entry at the exact path a conversion will consult.
+function cacheKeyFor(bytes: Uint8Array, quality: number): string {
+  const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+  return `${hash}-full-q${quality}`;
+}
+
+// Minimal structurally valid JPEG: SOI, APP0 (len 4, 2 payload bytes),
+// SOF0 (len 5, 3 payload bytes), SOS (len 3, 1 payload byte), entropy data
+// with a stuffed FF, then EOI.
+function minimalJpeg(extra: {
+  trailing?: Uint8Array;
+  dropEoi?: boolean;
+}): Buffer {
+  const parts: Uint8Array[] = [
+    Buffer.from([0xff, 0xd8]), // SOI
+    Buffer.from([0xff, 0xe0, 0x00, 0x04, 0x4a, 0x46]), // APP0
+    Buffer.from([0xff, 0xc0, 0x00, 0x05, 0x08, 0x00, 0x01]), // SOF0
+    Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01]), // SOS header
+    Buffer.from([0x12, 0xff, 0x00, 0x34]), // entropy data with stuffed FF
+  ];
+  if (!extra.dropEoi) {
+    parts.push(Buffer.from([0xff, 0xd9])); // EOI
+  }
+  if (extra.trailing) {
+    parts.push(extra.trailing);
+  }
+  return Buffer.concat(parts);
+}
+
+describe("hasValidJpegStructure", () => {
+  test("accepts a JPEG with trailing bytes after the EOI marker", () => {
+    // Some encoders append padding or metadata past the EOI; the structural
+    // walk tolerates it where isCompleteJpeg's exact tail framing does not.
+    const padded = minimalJpeg({ trailing: Buffer.from([0x00, 0x00]) });
+    expect(hasValidJpegStructure(padded)).toBe(true);
+    expect(isCompleteJpeg(padded)).toBe(false);
+  });
+
+  test("accepts restart markers inside entropy-coded data", () => {
+    const withRst = Buffer.concat([
+      Buffer.from([0xff, 0xd8]),
+      Buffer.from([0xff, 0xc0, 0x00, 0x05, 0x08, 0x00, 0x01]), // SOF0
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01]),
+      Buffer.from([0x12, 0xff, 0xd0, 0x34]), // RST0 continues the scan
+      Buffer.from([0xff, 0xd9]),
+    ]);
+    expect(hasValidJpegStructure(withRst)).toBe(true);
+  });
+
+  test("rejects a truncated JPEG whose metadata segment contains FF D9", () => {
+    // An EXIF-style APP1 payload can embed a complete thumbnail JPEG, so an
+    // FF D9 pair appears inside the segment while the main image is torn. A
+    // raw byte search would accept this; the marker walk skips the segment
+    // payload and reports the truncation.
+    const tornWithThumbnail = Buffer.concat([
+      Buffer.from([0xff, 0xd8]), // SOI
+      Buffer.from([0xff, 0xe1, 0x00, 0x08]), // APP1, length 8
+      Buffer.from([0x45, 0x78, 0xff, 0xd9, 0x00, 0x00]), // payload with FF D9
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01, 0x12, 0x34]), // torn scan
+    ]);
+    expect(hasValidJpegStructure(tornWithThumbnail)).toBe(false);
+  });
+
+  test("rejects truncated JPEGs and non-JPEG payloads", () => {
+    expect(hasValidJpegStructure(minimalJpeg({ dropEoi: true }))).toBe(false);
+    expect(
+      hasValidJpegStructure(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00])),
+    ).toBe(false);
+    expect(hasValidJpegStructure(Buffer.alloc(0))).toBe(false);
+    expect(hasValidJpegStructure(PNG_1PX_BYTES)).toBe(false);
+  });
+
+  test("rejects a top-level EOI with no frame or scan", () => {
+    // Bare SOI+EOI is structurally walkable but carries no image data;
+    // providers reject it, so the gate must too.
+    expect(hasValidJpegStructure(Buffer.from([0xff, 0xd8, 0xff, 0xd9]))).toBe(
+      false,
+    );
+    // A scan without a frame header is equally undecodable.
+    const scanNoFrame = Buffer.concat([
+      Buffer.from([0xff, 0xd8]),
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01, 0x12]),
+      Buffer.from([0xff, 0xd9]),
+    ]);
+    expect(hasValidJpegStructure(scanNoFrame)).toBe(false);
+  });
+
+  test("rejects a segment length that runs past the buffer", () => {
+    // A declared length larger than the remaining bytes is truncation, not a
+    // reason to scan beyond the buffer.
+    const overrun = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0xff, 0xff, 0x00]);
+    expect(hasValidJpegStructure(overrun)).toBe(false);
+  });
+});
+
 describe("normalizeImageBytes passthrough", () => {
   test("non-HEIF bytes pass through untouched", async () => {
     const result = await normalizeImageBytes("image/png", PNG_1PX_BYTES);
@@ -205,6 +321,9 @@ describe.skipIf(process.platform !== "darwin")(
       const converted = await convertImageToJpeg(heicBytes);
       expect(converted).not.toBeNull();
       expect(startsWithJpegMagic(converted!)).toBe(true);
+      // A real encoder's output must pass the structural walk, or the
+      // compactor gate would drop every legitimately converted image.
+      expect(hasValidJpegStructure(converted!)).toBe(true);
     });
 
     test("conversion options produce distinct outputs (cache key isolation)", async () => {
@@ -228,6 +347,29 @@ describe.skipIf(process.platform !== "darwin")(
       expect(first!.equals(second!)).toBe(true);
     });
 
+    test("a poisoned (truncated) cache entry is discarded, not returned", async () => {
+      // Distinct quality so this test owns its cache key.
+      const quality = 77;
+      const cacheDir = join(tmpdir(), "vellum-optimized-images");
+      mkdirSync(cacheDir, { recursive: true });
+      const poisonedPath = join(
+        cacheDir,
+        `${cacheKeyFor(heicBytes, quality)}.jpg`,
+      );
+      // A torn write: valid JPEG head, no EOI tail. readFromCache must
+      // discard it rather than return it as the converted image.
+      writeFileSync(poisonedPath, Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]));
+
+      const converted = await convertImageToJpeg(heicBytes, { quality });
+      expect(converted).not.toBeNull();
+      expect(isCompleteJpeg(converted!)).toBe(true);
+
+      // The poisoned entry was replaced by the re-converted result.
+      expect(existsSync(poisonedPath)).toBe(true);
+      const { readFileSync } = await import("node:fs");
+      expect(isCompleteJpeg(readFileSync(poisonedPath))).toBe(true);
+    });
+
     test("normalizeImageBytes converts to a JPEG master", async () => {
       const result = await normalizeImageBytes("image/heic", heicBytes);
       expect(result.converted).toBe(true);

package/src/context/compactor.ts

@@ -39,6 +39,10 @@ import type {
 } from "../providers/types.js";
 import { type TrustClass } from "../runtime/actor-trust-resolver.js";
 import { resolveCapabilities } from "../runtime/capabilities.js";
+import {
+  hasValidJpegStructure,
+  sniffImageMimeType,
+} from "../util/image-conversion.js";
 import { getLogger } from "../util/logger.js";
 import { preModelCallSanitize } from "./outbound-sanitize.js";
 import { stripInjectionsForCompaction } from "./strip-injections.js";
@@ -865,7 +869,8 @@ function resolveTailFloorIndex(messages: Message[], tailIndex: number): number {
 // Retained-image hydration
 // ---------------------------------------------------------------------------
 
-async function buildRetainedImageBlocks(
+/** Exported for unit testing (the corrupt-bytes drop gate). */
+export async function buildRetainedImageBlocks(
   filenames: string[],
   manifest: ManifestEntry[],
 ): Promise<{ blocks: ImageContent[]; resolved: string[]; missing: string[] }> {
@@ -883,7 +888,11 @@ async function buildRetainedImageBlocks(
       missing.push(name);
       continue;
     }
-    const sourceMime = guessMimeFromFilename(name);
+    // Sniff the declared MIME from the stored bytes rather than the filename:
+    // clients derive extensions from user input, and providers reject an image
+    // whose bytes disagree with the declared media type.
+    const sourceMime =
+      sniffImageMimeType(content) ?? guessMimeFromFilename(name);
     // Run the same downscale pass the agent uses when first sending an
     // image. Without this, attachments that exceed the provider's per-image
     // byte limit (Anthropic: 5 MB) crash the next turn after compaction.
@@ -891,6 +900,26 @@ async function buildRetainedImageBlocks(
       content.toString("base64"),
       sourceMime,
     );
+    // Last-line gate before the bytes are baked into the rebuilt history: a
+    // corrupt payload would be rejected by the provider with a 400 on EVERY
+    // subsequent turn, wedging the conversation. Dropping the image loses a
+    // retained picture; shipping it loses the conversation. Format sniffing
+    // alone is not enough for JPEG: a truncated JPEG (e.g. persisted from a
+    // torn conversion-cache read) keeps its SOI header, so JPEG payloads must
+    // also walk to a terminal EOI marker.
+    const optimizedBytes = Buffer.from(optimized.data, "base64");
+    const optimizedFormat = sniffImageMimeType(optimizedBytes);
+    const bytesAreValidImage =
+      optimizedFormat != null &&
+      (optimizedFormat !== "image/jpeg" ||
+        hasValidJpegStructure(optimizedBytes));
+    if (!bytesAreValidImage) {
+      log.warn(
+        { filename: name, attachmentId: entry.attachmentId },
+        "Retained image bytes are not a valid image after transport optimization; dropping",
+      );
+      continue;
+    }
     blocks.push({
       type: "image",
       source: {

package/src/util/image-conversion.ts

@@ -22,6 +22,7 @@ import {
   readdirSync,
   readFileSync,
   readSync,
+  renameSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -42,26 +43,151 @@ function getCacheDir(): string {
   return join(tmpdir(), "vellum-optimized-images");
 }
 
+/**
+ * Structural completeness check for a JPEG payload: SOI marker (FF D8) at the
+ * head and EOI marker (FF D9) at the tail. Every cache entry and every sips
+ * output is a JPEG, so a payload failing this is truncated or empty (the
+ * signature of a torn cache write) and must never reach a provider, which
+ * rejects it with a 400 that wedges the conversation (the corrupt block is
+ * resent on every subsequent turn).
+ */
+export function isCompleteJpeg(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === 0xff &&
+    bytes[1] === 0xd8 &&
+    bytes[bytes.length - 2] === 0xff &&
+    bytes[bytes.length - 1] === 0xd9
+  );
+}
+
+/**
+ * Structural JPEG truncation check for payloads of arbitrary origin: walk the
+ * marker segments from SOI and report whether a terminal EOI is reached.
+ * Unlike {@link isCompleteJpeg} (exact tail framing, for sips output and
+ * cache entries, which always end on EOI), this tolerates encoders that
+ * append padding or metadata after the EOI.
+ *
+ * A raw byte search for FF D9 is not enough: length-delimited APP/COM
+ * segments (an EXIF thumbnail is itself a complete embedded JPEG) may contain
+ * FF D9, so a truncated file with an intact metadata prefix would pass.
+ * Walking segment boundaries skips those payloads entirely; only an EOI at
+ * the top level of the marker stream counts. Entropy-coded scan data is
+ * traversed byte-wise, where FF is stuffed as FF 00 and restart markers
+ * (D0-D7) continue the scan, so a marker byte there is unambiguous.
+ *
+ * The EOI only counts after at least one frame header (SOF) and one scan
+ * (SOS) have been seen: a degenerate payload such as bare SOI+EOI carries no
+ * image data and providers reject it.
+ */
+export function hasValidJpegStructure(bytes: Uint8Array): boolean {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) {
+    return false;
+  }
+  let sawFrame = false;
+  let sawScan = false;
+  let i = 2;
+  while (i + 1 < bytes.length) {
+    if (bytes[i] !== 0xff) {
+      return false;
+    }
+    // FF fill bytes before a marker are legal padding.
+    let j = i + 1;
+    while (j < bytes.length && bytes[j] === 0xff) {
+      j++;
+    }
+    if (j >= bytes.length) {
+      return false;
+    }
+    const marker = bytes[j];
+    i = j + 1;
+    if (marker === 0xd9) {
+      return sawFrame && sawScan;
+    }
+    // SOF0-SOF15 occupy C0-CF, excluding DHT (C4), JPG (C8), and DAC (CC).
+    if (
+      marker >= 0xc0 &&
+      marker <= 0xcf &&
+      marker !== 0xc4 &&
+      marker !== 0xc8 &&
+      marker !== 0xcc
+    ) {
+      sawFrame = true;
+    }
+    // Standalone markers carry no length field: repeated SOI, TEM, RST0-7.
+    if (
+      marker === 0xd8 ||
+      marker === 0x01 ||
+      (marker >= 0xd0 && marker <= 0xd7)
+    ) {
+      continue;
+    }
+    if (i + 1 >= bytes.length) {
+      return false;
+    }
+    const segmentLength = (bytes[i] << 8) | bytes[i + 1];
+    if (segmentLength < 2) {
+      return false;
+    }
+    i += segmentLength;
+    if (marker === 0xda) {
+      sawScan = true;
+      // SOS: entropy-coded data follows the header. Scan to the next real
+      // marker; FF 00 (stuffed data byte) and FF D0-D7 (restart) stay inside
+      // the scan.
+      while (i + 1 < bytes.length) {
+        if (
+          bytes[i] === 0xff &&
+          bytes[i + 1] !== 0x00 &&
+          !(bytes[i + 1] >= 0xd0 && bytes[i + 1] <= 0xd7)
+        ) {
+          break;
+        }
+        i++;
+      }
+    }
+  }
+  return false;
+}
+
 function readFromCache(key: string): Buffer | null {
+  const cachePath = join(getCacheDir(), `${key}.jpg`);
   try {
-    const cachePath = join(getCacheDir(), `${key}.jpg`);
     if (!existsSync(cachePath)) {
       return null;
     }
-    return readFileSync(cachePath) as Buffer;
+    const bytes = readFileSync(cachePath) as Buffer;
+    if (!isCompleteJpeg(bytes)) {
+      // Poisoned entry (torn write, disk full, etc.): drop it so the caller
+      // re-converts and re-caches.
+      unlinkSync(cachePath);
+      return null;
+    }
+    return bytes;
   } catch {
     return null;
   }
 }
 
 function writeToCache(key: string, convertedBytes: Buffer): void {
+  const dir = getCacheDir();
+  // Write-then-rename so concurrent readers (the cache dir is shared across
+  // daemon processes) never observe a partially written entry; rename within
+  // the same directory is atomic. The pid+uuid suffix keeps concurrent
+  // writers of the same key off each other's temp file.
+  const tmpPath = join(dir, `${key}.${process.pid}-${uuid().slice(0, 8)}.tmp`);
   try {
-    const dir = getCacheDir();
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, `${key}.jpg`), convertedBytes);
+    writeFileSync(tmpPath, convertedBytes);
+    renameSync(tmpPath, join(dir, `${key}.jpg`));
     evictIfNeeded(dir);
   } catch {
     // Cache write failure is non-fatal.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
   }
 }
 
@@ -141,7 +267,14 @@ async function runSips(
     if (proc.exitCode !== 0) {
       return null;
     }
-    return readFileSync(outPath) as Buffer;
+    const out = readFileSync(outPath) as Buffer;
+    // A zero-exit sips can still leave a truncated file (disk full, timeout
+    // kill racing the write). Returning it would poison the cache and every
+    // downstream provider call. Treat it as a failed conversion instead.
+    if (!isCompleteJpeg(out)) {
+      return null;
+    }
+    return out;
   } catch {
     return null;
   } finally {