@vellumai/assistant 0.8.2 → 0.8.4

package/src/config/schemas/memory-v2.ts

@@ -194,6 +194,19 @@ export const MemoryV2ConfigSchema = z
       .describe(
         "Hours between scheduled consolidation runs that synthesize buffered memories into concept pages",
       ),
+    consolidation_max_buffer_lines: z
+      .number({
+        error: "memory.v2.consolidation_max_buffer_lines must be a number",
+      })
+      .int("memory.v2.consolidation_max_buffer_lines must be an integer")
+      .positive(
+        "memory.v2.consolidation_max_buffer_lines must be a positive integer",
+      )
+      .nullable()
+      .default(100)
+      .describe(
+        "Size-based trigger for consolidation. When `memory/buffer.md` reaches this many non-empty lines, consolidation runs even if the time-based interval hasn't elapsed. Defaults to 100. Set to `null` to disable the size trigger and rely solely on `consolidation_interval_hours`.",
+      ),
     max_page_chars: z
       .number({ error: "memory.v2.max_page_chars must be a number" })
       .int("memory.v2.max_page_chars must be an integer")
@@ -260,9 +273,9 @@ export const MemoryV2ConfigSchema = z
       .object({
         enabled: z
           .boolean()
-          .default(false)
+          .default(true)
           .describe(
-            "Whether to use the LLM router as the per-turn page-selection mechanism in place of spreading activation. Disabled by default — opt in once the router orchestration and dispatcher land.",
+            "Whether to use the LLM router as the per-turn page-selection mechanism in place of spreading activation. Enabled by default.",
           ),
         max_page_ids: z
           .number()
@@ -282,10 +295,44 @@ export const MemoryV2ConfigSchema = z
           .describe(
             "Optional path to a file whose contents replace the bundled router prompt. Absolute paths are used as-is, a leading `~/` is expanded to the home directory, otherwise the path is resolved under the workspace root. The loaded contents may include `{{ASSISTANT_NAME}}`, `{{USER_NAME}}`, and `{{PAGE_INDEX}}`, which are substituted at runtime. If the file is missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
           ),
+        batch_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Target batch size for parallel page-index routing. `null` (default) sends the entire page index in one call — identical to v3 behavior. When set, pages are split into `ceil(N / batch_size)` batches by stable FNV-1a hash on slug (so adding/removing a single page only invalidates one batch's KV cache), routed in parallel, and the selected slugs are unioned. A failure in one batch does not abort the turn as long as at least one batch succeeds.",
+          ),
+        tier1_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Pool size for the tier-1 'recently modified' batch. `null` (default) disables tier 1 entirely — all pages flow through tier 3 batching. When set, the top-N concept pages by file mtime become their own dedicated parallel batch with mtime-desc ordering; everything else is partitioned into tier 3 batches by `batch_size`. Synthetic entries (skills, CLI commands) have mtime=0 and naturally rank below real concept pages so they don't crowd tier 1.",
+          ),
+        tier2_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Pool size for the tier-2 'useful' batch. `null` (default) disables tier 2 — pages skip straight from tier 1 to tier 3. When set, the top-M pages by injection-frequency EMA (excluding tier 1) become their own parallel batch ordered by score desc. Pages with score 0 (never selected since EMA tracking began) are ineligible for tier 2 and stay in tier 3 regardless of `tier2_size`. Score is the time-decayed sum `Σ exp(-λ(now - tᵢ))` with 3-day half-life, computed on read from `memory_v2_injection_events`.",
+          ),
+      })
+      .default({
+        enabled: true,
+        max_page_ids: 25,
+        router_prompt_path: null,
+        batch_size: null,
+        tier1_size: null,
+        tier2_size: null,
       })
-      .default({ enabled: false, max_page_ids: 25, router_prompt_path: null })
       .describe(
-        "LLM router configuration. When enabled, a single Sonnet router call replaces spreading activation for per-turn page selection.",
+        "LLM router configuration. When enabled, a single router LLM call replaces spreading activation for per-turn page selection.",
       ),
   })
   .describe(

package/src/config/schemas/memory.ts

@@ -23,7 +23,9 @@ export const MemoryConfigSchema = z
     enabled: z
       .boolean({ error: "memory.enabled must be a boolean" })
       .default(true)
-      .describe("Whether the long-term memory system is enabled"),
+      .describe(
+        "Whether the long-term memory system is enabled — gates background memory jobs, embedding generation, and `<memory>` block injection into user messages",
+      ),
     embeddings: MemoryEmbeddingsConfigSchema.default(
       MemoryEmbeddingsConfigSchema.parse({}),
     ),

package/src/config/seed-inference-profiles.ts

@@ -3,6 +3,8 @@ import {
   createConnection,
   disableManagedConnectionsForByokHatch,
   getConnection,
+  MANAGED_CONNECTION_NAMES,
+  PROVIDERS_REQUIRING_BASE_URL_AND_MODELS,
 } from "../providers/inference/connections.js";
 import { PROVIDER_CATALOG } from "../providers/model-catalog.js";
 import { resolveModelIntent } from "../providers/model-intents.js";
@@ -17,10 +19,6 @@ import {
 
 const log = getLogger("seed-inference-profiles");
 
-const MANAGED_CONNECTION_NAME = "anthropic-managed";
-const MANAGED_PROFILE_PROVIDER: NonNullable<ProfileEntry["provider"]> =
-  "anthropic";
-
 /**
  * Template for a daemon-managed inference profile. The profile's model is
  * resolved at seed time from `PROVIDER_MODEL_INTENTS` so the catalog stays the
@@ -31,16 +29,20 @@ type ManagedProfileTemplate = Omit<
   "provider" | "model" | "provider_connection"
 > & {
   intent: ModelIntent;
+  provider: NonNullable<ProfileEntry["provider"]>;
+  connectionName: string;
 };
 
 /**
- * Managed Anthropic profiles. Overwritten on every daemon boot so Vellum can
- * push model/config updates to customers in new releases. Platform overlays
+ * Managed profiles. Overwritten on every daemon boot so Vellum can push
+ * model/config updates to customers in new releases. Platform overlays
  * (`preserveProfileNames`) take precedence when present.
  */
 const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   balanced: {
     intent: "balanced",
+    provider: "anthropic",
+    connectionName: "anthropic-managed",
     source: "managed",
     label: "Balanced",
     description: "Good balance of quality, cost, and speed",
@@ -51,6 +53,8 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   },
   "quality-optimized": {
     intent: "quality-optimized",
+    provider: "anthropic",
+    connectionName: "anthropic-managed",
     source: "managed",
     label: "Quality",
     description: "Best results with the most capable model",
@@ -61,6 +65,8 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   },
   "cost-optimized": {
     intent: "latency-optimized",
+    provider: "anthropic",
+    connectionName: "anthropic-managed",
     source: "managed",
     label: "Speed",
     description: "Fastest responses at lower cost",
@@ -74,11 +80,15 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
 /**
  * User profile templates. Materialized at hatch time for off-platform
  * installations. Each points at the user's personal provider connection
- * (backed by their API key in CES).
+ * (backed by their API key in CES). The `provider` and `connectionName`
+ * fields are placeholders — they are overridden at hatch time with the
+ * user's chosen provider and personal connection name.
  */
 const USER_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   "custom-balanced": {
     intent: "balanced",
+    provider: "anthropic",
+    connectionName: "",
     source: "user",
     label: "Balanced",
     description: "Good balance of quality, cost, and speed",
@@ -89,6 +99,8 @@ const USER_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   },
   "custom-quality-optimized": {
     intent: "quality-optimized",
+    provider: "anthropic",
+    connectionName: "",
     source: "user",
     label: "Quality",
     description: "Best results with the most capable model",
@@ -99,6 +111,8 @@ const USER_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   },
   "custom-cost-optimized": {
     intent: "latency-optimized",
+    provider: "anthropic",
+    connectionName: "",
     source: "user",
     label: "Speed",
     description: "Fastest responses at lower cost",
@@ -164,11 +178,12 @@ export function seedInferenceProfiles(
   // BYOK mode = off-platform installs. The user is bringing their own provider
   // API key; managed profile labels get a " (Managed)" suffix to disambiguate
   // from the personal "custom-*" profiles that share base labels. Managed
-  // profile + connection status is initially "disabled" so the picker doesn't
-  // offer an unusable platform-auth option on day one — but ONLY at hatch
-  // time, and ONLY when the entry isn't already in the user's config (i.e.
-  // first materialization). Post-hatch user toggles survive every subsequent
-  // boot.
+  // profile + connection status is initially "disabled" for true BYOK hatches
+  // so the picker doesn't offer an unusable platform-auth option on day one.
+  // When the hatch overlay explicitly selects a managed profile, the matching
+  // managed connection stays active so the first post-onboarding message can
+  // use the user's chosen managed route. Post-hatch user toggles survive every
+  // subsequent boot.
   const isByokMode = !isPlatform;
 
   // 1. Managed profiles. Off-platform: overwrite on every boot so Vellum can
@@ -198,10 +213,18 @@ export function seedInferenceProfiles(
   //        rewritten to the suffixed form. Any other previous label value
   //        (user-set custom string, explicit null, already-suffixed) is
   //        preserved as-is.
-  //      • status: "disabled" on fresh materialization at hatch only —
-  //        gated on (isHatch && !previous) so post-hatch boots and existing
-  //        installs are never auto-disabled. A user re-enable persists
-  //        across boots via the key-presence preservation below.
+  //      • status: "disabled" on fresh materialization at BYOK hatch only —
+  //        gated on (isHatch && !previous) and skipped for any managed
+  //        connection explicitly selected by the hatch overlay. Post-hatch
+  //        boots and existing installs are never auto-disabled. A user
+  //        re-enable persists across boots via the key-presence preservation
+  //        below.
+  const hatchSelectedManagedConnection = getHatchSelectedManagedConnection(
+    llm,
+    profiles,
+    options,
+  );
+
   for (const [name, template] of Object.entries(MANAGED_PROFILE_TEMPLATES)) {
     if (preservedProfileNames.has(name)) continue;
     if (isPlatform && readObject(profiles[name]) !== null) continue;
@@ -212,10 +235,15 @@ export function seedInferenceProfiles(
       : template;
     const next = materializeProfile(
       effectiveTemplate,
-      MANAGED_PROFILE_PROVIDER,
-      MANAGED_CONNECTION_NAME,
+      template.provider,
+      template.connectionName,
     ) as Record<string, unknown>;
-    if (isByokMode && options.isHatch && !previous) {
+    if (
+      isByokMode &&
+      options.isHatch &&
+      !previous &&
+      template.connectionName !== hatchSelectedManagedConnection
+    ) {
       next.status = "disabled";
     }
     if (previous) {
@@ -238,17 +266,24 @@ export function seedInferenceProfiles(
   // 2. User profiles — only at hatch time for off-platform installations.
   let userConnectionName: string | undefined;
   if (options.isHatch && !isPlatform) {
-    // BYOK hatch: disable the three canonical managed connections so the
-    // picker doesn't surface unusable platform-auth options on day one.
-    // Runs only here, only at hatch — `seedCanonicalConnections` leaves
-    // `status` alone on subsequent boots so a post-hatch user re-enable
-    // persists.
+    // BYOK hatch: disable canonical managed connections so the picker doesn't
+    // surface unusable platform-auth options on day one. If the hatch overlay
+    // selected a managed profile, leave that connection active; the user has
+    // already chosen managed inference. Runs only here, only at hatch —
+    // `seedCanonicalConnections` leaves `status` alone on subsequent boots so
+    // a post-hatch user re-enable persists.
     if (options.db) {
-      disableManagedConnectionsForByokHatch(options.db);
+      disableManagedConnectionsForByokHatch(options.db, {
+        excludeConnection: hatchSelectedManagedConnection,
+      });
     }
 
     const hatchProvider = readString(readObject(llm.default)?.provider);
-    if (hatchProvider && hatchProvider !== "ollama") {
+    if (
+      hatchProvider &&
+      hatchProvider !== "ollama" &&
+      !PROVIDERS_REQUIRING_BASE_URL_AND_MODELS.has(hatchProvider)
+    ) {
       userConnectionName = `${hatchProvider}-personal`;
 
       if (options.db) {
@@ -269,8 +304,7 @@ export function seedInferenceProfiles(
         }
       }
 
-      const provider =
-        hatchProvider as NonNullable<ProfileEntry["provider"]>;
+      const provider = hatchProvider as NonNullable<ProfileEntry["provider"]>;
       for (const [name, template] of Object.entries(USER_PROFILE_TEMPLATES)) {
         if (preservedProfileNames.has(name)) continue;
         profiles[name] = materializeProfile(
@@ -342,7 +376,7 @@ function materializeProfile(
   provider: NonNullable<ProfileEntry["provider"]>,
   connectionName: string,
 ): ProfileEntry {
-  const { intent, ...rest } = template;
+  const { intent, provider: _p, connectionName: _c, ...rest } = template;
   return {
     ...rest,
     provider,
@@ -361,6 +395,42 @@ function readString(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function getHatchSelectedManagedConnection(
+  llm: Record<string, unknown>,
+  profiles: Record<string, Record<string, unknown>>,
+  options: SeedInferenceProfilesOptions,
+): string | undefined {
+  if (!options.isHatch || options.preserveActiveProfile !== true) {
+    return undefined;
+  }
+
+  const activeProfile = readString(llm.activeProfile);
+  if (!activeProfile) return undefined;
+
+  const activeProfileEntry = readObject(profiles[activeProfile]);
+  if (
+    activeProfileEntry &&
+    Object.prototype.hasOwnProperty.call(
+      activeProfileEntry,
+      "provider_connection",
+    )
+  ) {
+    const explicitConnection = readString(
+      activeProfileEntry.provider_connection,
+    );
+    return explicitConnection &&
+      MANAGED_CONNECTION_NAMES.has(explicitConnection)
+      ? explicitConnection
+      : undefined;
+  }
+
+  const templateConnection =
+    MANAGED_PROFILE_TEMPLATES[activeProfile]?.connectionName;
+  return templateConnection && MANAGED_CONNECTION_NAMES.has(templateConnection)
+    ? templateConnection
+    : undefined;
+}
+
 /**
  * Format the human-readable label seeded onto a personal provider connection
  * at hatch time, e.g. `"Anthropic (Personal)"`. The display name is sourced

package/src/context/compactor.ts

@@ -155,6 +155,11 @@ export interface CompactionRunResult {
   thresholdTokens: number;
   compactedMessages: number;
   compactedPersistedMessages: number;
+  /**
+   * Number of recent ("tail") messages preserved verbatim alongside the
+   * summary. Omitted on no-op / skipped results — defaults to 0 at render.
+   */
+  preservedTailMessages?: number;
   summaryCalls: number;
   summaryInputTokens: number;
   summaryOutputTokens: number;
@@ -327,7 +332,7 @@ export function renderImageManifest(entries: ManifestEntry[]): string {
  * runtime emitted — typically
  * `2026-04-02 (Thursday) 01:52:33 -05:00 (America/Chicago)`).
  */
-function extractTurnContextTimestamp(message: Message): string | null {
+export function extractTurnContextTimestamp(message: Message): string | null {
   if (message.role !== "user") return null;
   for (const block of message.content) {
     if (block.type !== "text") continue;
@@ -439,6 +444,44 @@ function resolveTailStartIndex(
   return null;
 }
 
+/**
+ * Walk a model-chosen tail index backward until it lands on a user message
+ * that does not contain client-side `tool_result` blocks. Prevents the
+ * orphan-`tool_result` failure where the matching assistant `tool_use` sits
+ * in the discarded prefix and Anthropic rejects the next call with
+ * `unexpected tool_use_id found in tool_result blocks`.
+ *
+ * Walking back (rather than forward) preserves the recent context the model
+ * deliberately chose to keep; the tail just expands by the few messages
+ * needed to re-anchor the orphaned `tool_result` against its `tool_use`.
+ *
+ * Returns 0 when the walk falls off the front — the caller treats this as
+ * "nothing to compact" via the existing `tailIndex === 0` branch.
+ *
+ * Only `type === "tool_result"` blocks count. Server-side tools
+ * (`server_tool_use` / `web_search_tool_result`) are self-paired inside an
+ * assistant message and never trigger an adjustment.
+ */
+export function adjustTailIndexForToolPairing(
+  messages: Message[],
+  tailIndex: number,
+): number {
+  let k = tailIndex;
+  while (k > 0) {
+    const m = messages[k];
+    if (
+      m.role === "user" &&
+      // guard:allow-tool-result-only — server-side web_search_tool_result is
+      // self-paired inside its assistant message and never spans user turns.
+      !m.content.some((block) => block.type === "tool_result")
+    ) {
+      return k;
+    }
+    k--;
+  }
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // Retained-image hydration
 // ---------------------------------------------------------------------------
@@ -655,8 +698,12 @@ export async function runAssistantDrivenCompaction(
   }
 
   const timestamps = buildTimestampIndex(args.messages);
-  const tailIndex = resolveTailStartIndex(args.messages, timestamps, parsed);
-  if (tailIndex == null) {
+  const resolvedTailIndex = resolveTailStartIndex(
+    args.messages,
+    timestamps,
+    parsed,
+  );
+  if (resolvedTailIndex == null) {
     log.warn(
       {
         timestamp: parsed.tailStartTimestamp,
@@ -680,6 +727,22 @@ export async function runAssistantDrivenCompaction(
     };
   }
 
+  const tailIndex = adjustTailIndexForToolPairing(
+    args.messages,
+    resolvedTailIndex,
+  );
+  if (tailIndex !== resolvedTailIndex) {
+    log.info(
+      {
+        conversationId: args.conversationId,
+        originalTailIndex: resolvedTailIndex,
+        tailIndex,
+        walkedBy: resolvedTailIndex - tailIndex,
+      },
+      "Adjusted compaction tail backward to preserve tool_use/tool_result pairing",
+    );
+  }
+
   if (tailIndex === 0) {
     return {
       ...emptyResult(
@@ -762,6 +825,9 @@ export async function runAssistantDrivenCompaction(
       compactedMessages: compactableMessages.length,
       compactedPersistedMessages,
       tailIndex,
+      ...(tailIndex !== resolvedTailIndex
+        ? { originalTailIndex: resolvedTailIndex }
+        : {}),
       retainedImages: resolved.length,
       summaryChars: summaryText.length,
     },
@@ -780,6 +846,7 @@ export async function runAssistantDrivenCompaction(
     thresholdTokens,
     compactedMessages: compactableMessages.length,
     compactedPersistedMessages,
+    preservedTailMessages: args.messages.length - tailIndex,
     summaryCalls: 1,
     summaryInputTokens: response.usage.inputTokens,
     summaryOutputTokens: response.usage.outputTokens,
@@ -885,10 +952,12 @@ export async function runEmergencyCompaction(
 
   const splitIndex = findLastToolPairStart(args.messages);
   if (splitIndex == null || splitIndex === 0) {
-    log.info(
-      "Emergency compaction: no tool pair found — falling through",
+    log.info("Emergency compaction: no tool pair found — falling through");
+    return emptyResult(
+      args,
+      thresholdTokens,
+      "no tool pair for emergency split",
     );
-    return emptyResult(args, thresholdTokens, "no tool pair for emergency split");
   }
 
   const keptTail = stripInjectionsForCompaction(
@@ -904,8 +973,7 @@ export async function runEmergencyCompaction(
   const prefixBudget = args.maxInputTokens - instructionBudget - outputBudget;
 
   let prefixEstimate = estimatePromptTokens(prefix, args.systemPrompt, {
-    providerName:
-      args.provider.tokenEstimationProvider ?? args.provider.name,
+    providerName: args.provider.tokenEstimationProvider ?? args.provider.name,
   });
 
   if (prefixEstimate > prefixBudget && prefix.length > 1) {
@@ -920,10 +988,7 @@ export async function runEmergencyCompaction(
     // Drop messages from the front until we fit. Keep at least the first
     // message (may be an existing summary) and try to preserve recent context.
     let dropCount = 0;
-    while (
-      prefixEstimate > prefixBudget &&
-      dropCount < prefix.length - 1
-    ) {
+    while (prefixEstimate > prefixBudget && dropCount < prefix.length - 1) {
       dropCount++;
       const truncated = prefix.slice(dropCount);
       prefixEstimate = estimatePromptTokens(truncated, args.systemPrompt, {
@@ -1015,7 +1080,8 @@ export async function runEmergencyCompaction(
       compactedMessages: compactedCount,
       keptTailMessages: keptTail.length,
       summaryChars: summaryText.length,
-      prefixTruncated: prefix[0]?.content?.[0]?.type === "text" &&
+      prefixTruncated:
+        prefix[0]?.content?.[0]?.type === "text" &&
         (prefix[0].content[0] as { text: string }).text.includes("truncated"),
     },
     "Applied emergency mid-turn compaction",
@@ -1030,6 +1096,7 @@ export async function runEmergencyCompaction(
     thresholdTokens,
     compactedMessages: compactedCount,
     compactedPersistedMessages: Math.max(0, compactedCount - nonPersistedAway),
+    preservedTailMessages: keptTail.length,
     summaryCalls: 1,
     summaryInputTokens: response.usage.inputTokens,
     summaryOutputTokens: response.usage.outputTokens,

package/src/context/token-estimator.ts

@@ -33,18 +33,42 @@ const OTHER_BLOCK_TOKENS = 16;
 const SYSTEM_PROMPT_OVERHEAD_TOKENS = 8;
 const GEMINI_INLINE_FILE_MIME_TYPES = new Set(["application/pdf"]);
 
-// Anthropic scales images to fit within 1568x1568 maintaining aspect ratio,
-// then charges ~(width * height) / 750 tokens.
-const ANTHROPIC_IMAGE_MAX_DIMENSION = 1568;
-// Anthropic caps images at ~1.2 megapixels in addition to the 1568px dimension limit.
-// Images exceeding this are further scaled down. The docs state images above ~1,600 tokens
-// are resized. 1,200,000 / 750 = 1,600 tokens, matching the documented threshold.
-// Reference table (max sizes that won't be resized):
+// Dimension-based image token estimate, used as a universal default for every
+// provider. The formula and constants below come from Anthropic's published
+// vision spec — scale to a 1568x1568 bounding box, then charge
+// ~(width * height) / 750 tokens, with a ~1.2-megapixel cap that lands at
+// ~1,600 tokens per image. Reference table (max sizes that won't be resized):
 //   1:1 → 1092x1092 (~1,590 tokens)   1:2 → 784x1568 (~1,639 tokens)
 // See: https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size
-const ANTHROPIC_IMAGE_MAX_PIXELS = 1_200_000;
-const ANTHROPIC_IMAGE_TOKENS_PER_PIXEL = 1 / 750;
-const ANTHROPIC_IMAGE_MAX_TOKENS = 1_600;
+//
+// Other multimodal providers (OpenAI/GPT-4V tile pricing, Moonshot/Kimi,
+// Gemini fixed-cost, OpenRouter pass-through) price differently in detail,
+// but every published rate lands in the same hundreds-to-low-thousands range
+// per image. Using this formula as the default gets compaction within ~2-3x
+// of reality instead of the ~30-100x over-counting produced by treating the
+// raw base64 payload as if it were text.
+const IMAGE_MAX_DIMENSION = 1568;
+const IMAGE_MAX_PIXELS = 1_200_000;
+const IMAGE_TOKENS_PER_PIXEL = 1 / 750;
+const IMAGE_MAX_TOKENS = 1_600;
+
+// Gemini prices images differently: any side ≤384px counts as a single 258-token
+// tile; anything larger is resized so the longest side is ≤3072px and then
+// split into 768x768 tiles at 258 tokens each. A 4000x4000 image clamps to
+// 3072x3072 → ceil(3072/768)^2 = 16 tiles = 4,128 tokens. Without the clamp
+// we'd over-count it as 36 tiles (~9,288 tokens) and trigger spurious
+// compaction. The clamped 16-tile, 4,128-token figure is also the per-image
+// ceiling we fall back to when dimensions are unparseable (e.g. HEIC/HEIF
+// from iOS attachments) — the generic 1,600 cap can under-count Gemini
+// images by ~2.5x.
+// See: https://ai.google.dev/gemini-api/docs/tokens#multimodal-tokens
+const GEMINI_IMAGE_SMALL_THRESHOLD = 384;
+const GEMINI_IMAGE_TILE_SIZE = 768;
+const GEMINI_IMAGE_TOKENS_PER_TILE = 258;
+const GEMINI_IMAGE_MAX_DIMENSION = 3072;
+const GEMINI_IMAGE_MAX_TOKENS =
+  Math.ceil(GEMINI_IMAGE_MAX_DIMENSION / GEMINI_IMAGE_TILE_SIZE) ** 2 *
+  GEMINI_IMAGE_TOKENS_PER_TILE;
 
 // Anthropic renders each PDF page as an image (~1,568 tokens at standard
 // resolution) plus any extracted text. Typical PDF pages are 50-150 KB.
@@ -103,45 +127,62 @@ function estimateFileDataTokens(
   return 0;
 }
 
-function estimateAnthropicImageTokens(width: number, height: number): number {
+function estimateImageTokensByDimensions(
+  width: number,
+  height: number,
+): number {
   // Step 1: Scale to fit within 1568px bounding box
-  const dimScale = Math.min(
-    1,
-    ANTHROPIC_IMAGE_MAX_DIMENSION / Math.max(width, height),
-  );
+  const dimScale = Math.min(1, IMAGE_MAX_DIMENSION / Math.max(width, height));
   let scaledWidth = Math.round(width * dimScale);
   let scaledHeight = Math.round(height * dimScale);
 
   // Step 2: Scale further if exceeds megapixel budget
   const pixels = scaledWidth * scaledHeight;
-  if (pixels > ANTHROPIC_IMAGE_MAX_PIXELS) {
-    const mpScale = Math.sqrt(ANTHROPIC_IMAGE_MAX_PIXELS / pixels);
+  if (pixels > IMAGE_MAX_PIXELS) {
+    const mpScale = Math.sqrt(IMAGE_MAX_PIXELS / pixels);
     scaledWidth = Math.round(scaledWidth * mpScale);
     scaledHeight = Math.round(scaledHeight * mpScale);
   }
 
-  return Math.ceil(
-    scaledWidth * scaledHeight * ANTHROPIC_IMAGE_TOKENS_PER_PIXEL,
-  );
+  return Math.ceil(scaledWidth * scaledHeight * IMAGE_TOKENS_PER_PIXEL);
+}
+
+function estimateGeminiImageTokens(width: number, height: number): number {
+  if (
+    width <= GEMINI_IMAGE_SMALL_THRESHOLD &&
+    height <= GEMINI_IMAGE_SMALL_THRESHOLD
+  ) {
+    return GEMINI_IMAGE_TOKENS_PER_TILE;
+  }
+  // Gemini resizes images so the longest side is ≤3072px before tiling.
+  const clampedWidth = Math.min(width, GEMINI_IMAGE_MAX_DIMENSION);
+  const clampedHeight = Math.min(height, GEMINI_IMAGE_MAX_DIMENSION);
+  const tilesWide = Math.ceil(clampedWidth / GEMINI_IMAGE_TILE_SIZE);
+  const tilesHigh = Math.ceil(clampedHeight / GEMINI_IMAGE_TILE_SIZE);
+  return tilesWide * tilesHigh * GEMINI_IMAGE_TOKENS_PER_TILE;
 }
 
 function estimateImageTokens(
   block: Extract<ContentBlock, { type: "image" }>,
   options?: TokenEstimatorOptions,
 ): number {
-  if (options?.providerName === "anthropic") {
-    const dims = parseImageDimensions(
-      block.source.data,
-      block.source.media_type,
-    );
-    if (dims) {
-      return estimateAnthropicImageTokens(dims.width, dims.height);
+  const dims = parseImageDimensions(block.source.data, block.source.media_type);
+  if (dims) {
+    if (options?.providerName === "gemini") {
+      return estimateGeminiImageTokens(dims.width, dims.height);
     }
-    // Fallback: if dimensions can't be parsed, use Anthropic's max
-    return ANTHROPIC_IMAGE_MAX_TOKENS;
+    return estimateImageTokensByDimensions(dims.width, dims.height);
+  }
+  // Dimensions unparseable (corrupt header, or formats parseImageDimensions
+  // doesn't recognize like HEIC/HEIF coming from iOS attachments). Fall back
+  // to the per-provider per-image ceiling rather than the raw base64 length,
+  // which over-counts by 30-100x. Gemini's tile pricing tops out well above
+  // the universal 1,600-token cap, so use its max-tile budget instead to
+  // avoid under-counting large iPhone screenshots.
+  if (options?.providerName === "gemini") {
+    return GEMINI_IMAGE_MAX_TOKENS;
   }
-  // Non-Anthropic: keep existing base64-size heuristic
-  return estimateTextTokens(block.source.data);
+  return IMAGE_MAX_TOKENS;
 }
 
 export function estimateContentBlockTokens(