@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/config/loader.ts

@@ -5,14 +5,14 @@ import {
   renameSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 
 import { safeStatSync } from "../util/fs.js";
 import { getLogger } from "../util/logger.js";
 import {
   ensureDataDir,
+  getConfigQuarantineNoticePath,
   getWorkspaceConfigPath,
-  getWorkspaceDir,
 } from "../util/platform.js";
 import { AssistantConfigSchema } from "./schema.js";
 import type { AssistantConfig } from "./types.js";
@@ -201,10 +201,9 @@ function filesystemSafeTimestamp(date: Date = new Date()): string {
  * in `.json` so editors syntax-highlight the preserved content:
  *   `<path>.corrupt-<ISO-timestamp>.json`
  *
- * On a successful rename, also appends a bulletin to `<workspace>/UPDATES.md`
- * so the background update-bulletin job surfaces the event to the user
- * proactively on their next interaction (log-level errors alone are invisible
- * to users).
+ * On a successful rename, also writes a small JSON sentinel recording the
+ * event so the per-turn `config-quarantine-notice` injector can surface it to
+ * the agent (log-level errors alone are invisible to users).
  */
 function quarantineCorruptConfig(configPath: string, err: unknown): string {
   const quarantinePath = `${configPath}.corrupt-${filesystemSafeTimestamp()}.json`;
@@ -215,7 +214,7 @@ function quarantineCorruptConfig(configPath: string, err: unknown): string {
         `quarantined to ${quarantinePath} and loaded defaults. ` +
         `Inspect the quarantined file to recover any hand-edited settings.`,
     );
-    appendQuarantineBulletin(configPath, quarantinePath);
+    writeQuarantineNotice(configPath, quarantinePath);
   } catch (renameErr) {
     log.error(
       { renameErr },
@@ -227,66 +226,55 @@ function quarantineCorruptConfig(configPath: string, err: unknown): string {
 }
 
 /**
- * Append a config-quarantine bulletin to `<workspace>/UPDATES.md`. On the
- * next daemon boot the background update-bulletin job picks up UPDATES.md
- * and processes it inside a background-only conversation (not the user's
- * chat). The agent decides whether and when to surface the event — typical
- * cases are the user asking why their settings changed or noticing missing
- * API keys. The bulletin is agent-visible context, not a push notification.
+ * Write a small JSON sentinel recording that the config file was quarantined.
+ * The per-turn `config-quarantine-notice` injector reads this sentinel and, if
+ * it is recent, injects a system block so the agent can explain the reset when
+ * the user asks why their settings changed or notices missing API keys.
  *
- * Idempotency: the appended block embeds a marker keyed on the quarantine
- * filename's basename. If that marker is already present in UPDATES.md (a
- * prior append succeeded but the process crashed before control returned, or
- * the file was hand-edited), the function is a no-op. This mirrors the
- * pattern release-notes workspace migrations use — see the "Release Update
- * Hygiene" section in the root `AGENTS.md`.
+ * Writes with pure `node:fs` and a workspace-derived path
+ * ({@link getConfigQuarantineNoticePath}) deliberately: config load happens
+ * extremely early at daemon startup — before the SQLite DB is initialized and
+ * before `getConfig().dataDir` is available — so neither a DB checkpoint nor a
+ * config-dependent path can be used here without risking import-time DB init.
+ *
+ * Idempotent per quarantine event: each call overwrites the sentinel with the
+ * latest event, so a crash-then-retry re-records the same (or newer) event
+ * rather than accumulating duplicates.
  *
  * Best-effort: any write failure is logged at `warn` and swallowed. The
  * quarantine path must never block startup, and the error log from
  * `quarantineCorruptConfig` remains the authoritative record.
  *
- * Exported with an underscore-prefixed alias (`_appendQuarantineBulletin`) so
- * tests can exercise the idempotent-skip branch directly with a deterministic
- * quarantine basename. Non-test callers should never import the underscore
- * alias — the wiring into `quarantineCorruptConfig` is the production entry
- * point.
+ * Exported with an underscore-prefixed alias (`_writeQuarantineNotice`) so
+ * tests can exercise the write directly. Non-test callers should never import
+ * the underscore alias — the wiring into `quarantineCorruptConfig` is the
+ * production entry point.
  */
-function appendQuarantineBulletin(
+function writeQuarantineNotice(
   originalPath: string,
   quarantinePath: string,
 ): void {
   try {
-    const updatesPath = join(getWorkspaceDir(), "UPDATES.md");
-    const quarantineBasename = basename(quarantinePath);
-    const marker = `<!-- config-quarantine:${quarantineBasename} -->`;
-
-    const existing = existsSync(updatesPath)
-      ? readFileSync(updatesPath, "utf-8")
-      : "";
-    if (existing.includes(marker)) return;
-
-    const timestamp = new Date().toISOString();
-    const block =
-      `## Config was reset to defaults\n\n` +
-      `Your \`config.json\` was unreadable at ${timestamp} and couldn't be parsed ` +
-      `as JSON. The assistant preserved the original file at \`${quarantinePath}\` ` +
-      `and loaded defaults so the app stays working.\n\n` +
-      `If you had custom settings (API keys, model choices, voice preferences), ` +
-      `they are still in the quarantined file — \`cat ${quarantinePath}\` to ` +
-      `recover them, then re-enter through Settings or the CLI.\n\n` +
-      `${marker}\n`;
-
-    const toWrite = existing.length === 0 ? block : `${existing}\n${block}`;
-    writeFileSync(updatesPath, toWrite, "utf-8");
+    const noticePath = getConfigQuarantineNoticePath();
+    const dir = dirname(noticePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const notice = {
+      quarantinedAt: new Date().toISOString(),
+      quarantinePath,
+      originalPath,
+    };
+    writeFileSync(noticePath, JSON.stringify(notice, null, 2) + "\n", "utf-8");
     log.info(
-      `Appended config-quarantine bulletin to ${updatesPath} for ${originalPath} ` +
-        `(quarantined as ${quarantineBasename}).`,
+      `Wrote config-quarantine notice to ${noticePath} for ${originalPath} ` +
+        `(quarantined as ${quarantinePath}).`,
     );
-  } catch (bulletinErr) {
+  } catch (noticeErr) {
     log.warn(
-      { bulletinErr },
-      `Failed to append config-quarantine bulletin to UPDATES.md; ` +
-        `the quarantine event is still recorded in the assistant logs.`,
+      { noticeErr },
+      `Failed to write config-quarantine notice; the quarantine event is ` +
+        `still recorded in the assistant logs.`,
     );
   }
 }
@@ -660,7 +648,9 @@ export function loadConfig(): AssistantConfig {
           quarantineCorruptConfig(
             configPath,
             new Error(
-              `config.json must contain a JSON object at the top level; got ${describeJsonShape(parsed)}`,
+              `config.json must contain a JSON object at the top level; got ${describeJsonShape(
+                parsed,
+              )}`,
             ),
           );
           fileConfig = {};
@@ -889,7 +879,9 @@ export function loadRawConfig(): Record<string, unknown> {
     quarantineCorruptConfig(
       configPath,
       new Error(
-        `config.json must contain a JSON object at the top level; got ${describeJsonShape(parsed)}`,
+        `config.json must contain a JSON object at the top level; got ${describeJsonShape(
+          parsed,
+        )}`,
       ),
     );
     return {};
@@ -963,8 +955,9 @@ export function setNestedValue(
 }
 
 /**
- * Test-only alias for `appendQuarantineBulletin`. Exists so the crash-mid-
- * append idempotency branch can be exercised with a deterministic quarantine
- * basename without widening the runtime surface. Not for production use.
+ * Test-only alias for `writeQuarantineNotice`. Exists so the sentinel write
+ * (and its overwrite/idempotency semantics) can be exercised directly with a
+ * deterministic quarantine path without widening the runtime surface. Not for
+ * production use.
  */
-export const _appendQuarantineBulletin = appendQuarantineBulletin;
+export const _writeQuarantineNotice = writeQuarantineNotice;

package/src/config/schema.ts

@@ -56,7 +56,6 @@ import {
   TimeoutConfigSchema,
 } from "./schemas/timeouts.js";
 import { ToolsConfigSchema } from "./schemas/tools.js";
-import { UpdatesConfigSchema } from "./schemas/updates.js";
 import { WorkspaceGitConfigSchema } from "./schemas/workspace-git.js";
 
 export const AssistantConfigSchema = z
@@ -89,7 +88,6 @@ export const AssistantConfigSchema = z
     llmRequestLogs: LlmRequestLogsConfigSchema,
     filing: FilingConfigSchema.default(FilingConfigSchema.parse({})),
     heartbeat: HeartbeatConfigSchema.default(HeartbeatConfigSchema.parse({})),
-    updates: UpdatesConfigSchema.default(UpdatesConfigSchema.parse({})),
     hostBrowser: HostBrowserConfigSchema.default(
       HostBrowserConfigSchema.parse({}),
     ),

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

@@ -24,6 +24,7 @@ describe("MemoryV2ConfigSchema", () => {
       bm25_b: 0.4,
       consolidation_interval_hours: 4,
       consolidation_max_buffer_lines: 100,
+      consolidation_max_entries_per_run: 150,
       max_page_chars: 5000,
       consolidation_prompt_path: null,
       rerank: {

package/src/config/schemas/__tests__/memory-v3.test.ts

@@ -8,9 +8,19 @@ describe("MemoryV3ConfigSchema", () => {
     expect(parsed).toEqual({
       prune: { maxResidentBytes: 393216, targetResidentBytes: 262144 },
       hotSet: { k: 40, halfLifeDays: 14 },
+      freshSet: { k: 100 },
+      learnedEdges: {
+        halfLifeDays: 30,
+        minCount: 3,
+        npmiFloor: 0.2,
+        maxPerPage: 6,
+        perSeed: 3,
+        cap: 20,
+      },
       spotlight: { n: 6, windowTurns: 2 },
       needleK: 100,
       denseK: 100,
+      replyQueryK: 12,
       edge: { hubDegree: 30, seedCount: 18, perSeed: 6, cap: 45 },
     });
   });

package/src/config/schemas/llm.ts

@@ -331,6 +331,15 @@ export const LLMConfigBase = z.object({
   // `profileConfigFragment`, which strips it from the merge), so a preset
   // can't bleed from a lower-precedence profile into one that didn't opt in.
   logitBias: LogitBiasPresetSchema.optional(),
+  /**
+   * Opt this config out of prompt caching. Providers send no cache
+   * breakpoints and strip caller-stamped `cache_control` markers. Intended
+   * for one-shot call sites whose prompts never repeat (or repeat slower
+   * than the cache TTL), where every breakpoint is a paid cache write with
+   * no future read. Optional (no schema default) so it only appears in
+   * resolved configs when a layer sets it.
+   */
+  disableCache: z.boolean().optional(),
 });
 export type LLMConfigBase = z.infer<typeof LLMConfigBase>;
 
@@ -352,6 +361,7 @@ const LLMConfigFragment = z.object({
   contextWindow: ContextWindowDeepPartialSchema.optional(),
   openrouter: OpenRouterDeepPartialSchema.optional(),
   logitBias: LogitBiasPresetSchema.optional(),
+  disableCache: z.boolean().optional(),
 });
 type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
 

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

@@ -207,6 +207,19 @@ export const MemoryV2ConfigSchema = z
       .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`.",
       ),
+    consolidation_max_entries_per_run: z
+      .number({
+        error: "memory.v2.consolidation_max_entries_per_run must be a number",
+      })
+      .int("memory.v2.consolidation_max_entries_per_run must be an integer")
+      .positive(
+        "memory.v2.consolidation_max_entries_per_run must be a positive integer",
+      )
+      .nullable()
+      .default(150)
+      .describe(
+        "Upper bound on buffer entries one consolidation run may process. When the buffer holds more, the run's cutoff is moved back to the first over-cap entry's timestamp so the overflow is deferred to a follow-up pass (the `consolidation_max_buffer_lines` size trigger re-fires while the remainder stays over threshold). Bounds the context a single agentic run must read after a backlog. Set to `null` to always process the full buffer.",
+      ),
     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")

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

@@ -63,6 +63,86 @@ export const MemoryV3HotSetSchema = z
   })
   .describe("Memory v3 hot-set lane (decayed selection frequency) tuning.");
 
+/**
+ * Fresh-set lane tuning: the top-K pages by most-recent on-disk modification
+ * folded into the candidate pool as a stable-prefix lane. Recency covers the
+ * window before the other lanes can reach a just-written page (no selection
+ * history for the hot set; nothing lexical for the finders on summary-shaped
+ * messages).
+ */
+export const MemoryV3FreshSetSchema = z
+  .object({
+    k: z
+      .number({ error: "memory.v3.freshSet.k must be a number" })
+      .int("memory.v3.freshSet.k must be an integer")
+      .nonnegative("memory.v3.freshSet.k must be a non-negative integer")
+      .default(100)
+      .describe(
+        "Number of most-recently-modified pages included in the fresh-set lane (0 disables the lane). Sized to cover roughly the last day or two of page writes — the recency window conversations reference most.",
+      ),
+  })
+  .describe("Memory v3 fresh-set lane (page-modification recency) tuning.");
+
+/**
+ * Learned-edge lane tuning: a co-selection NPMI association graph over the
+ * selection log, expanded alongside the static link graph. Behavioral edges
+ * reach association-relevant pages no lexical, semantic, or authored-link
+ * lane can surface.
+ */
+export const MemoryV3LearnedEdgesSchema = z
+  .object({
+    halfLifeDays: z
+      .number({ error: "memory.v3.learnedEdges.halfLifeDays must be a number" })
+      .positive("memory.v3.learnedEdges.halfLifeDays must be a positive number")
+      .default(30)
+      .describe(
+        "Co-selection decay half-life in days: a selector call this old contributes half the weight of one made now.",
+      ),
+    minCount: z
+      .number({ error: "memory.v3.learnedEdges.minCount must be a number" })
+      .positive("memory.v3.learnedEdges.minCount must be a positive number")
+      .default(3)
+      .describe(
+        "Minimum decayed co-occurrence mass for a pair to form an edge (the rare-pair noise floor).",
+      ),
+    npmiFloor: z
+      .number({ error: "memory.v3.learnedEdges.npmiFloor must be a number" })
+      .nonnegative(
+        "memory.v3.learnedEdges.npmiFloor must be a non-negative number",
+      )
+      .default(0.2)
+      .describe("Minimum NPMI for a pair to form an edge."),
+    maxPerPage: z
+      .number({ error: "memory.v3.learnedEdges.maxPerPage must be a number" })
+      .int("memory.v3.learnedEdges.maxPerPage must be an integer")
+      .nonnegative(
+        "memory.v3.learnedEdges.maxPerPage must be a non-negative integer",
+      )
+      .default(6)
+      .describe(
+        "Maximum learned out-edges kept per page, strongest NPMI first (0 disables the lane).",
+      ),
+    perSeed: z
+      .number({ error: "memory.v3.learnedEdges.perSeed must be a number" })
+      .int("memory.v3.learnedEdges.perSeed must be an integer")
+      .positive("memory.v3.learnedEdges.perSeed must be a positive integer")
+      .default(3)
+      .describe(
+        "Maximum learned neighbours surfaced per expanded seed each turn.",
+      ),
+    cap: z
+      .number({ error: "memory.v3.learnedEdges.cap must be a number" })
+      .int("memory.v3.learnedEdges.cap must be an integer")
+      .nonnegative("memory.v3.learnedEdges.cap must be a non-negative integer")
+      .default(20)
+      .describe(
+        "Hard cap on total learned-lane surfaced articles per turn (0 disables the pass).",
+      ),
+  })
+  .describe(
+    "Memory v3 learned-edge lane (co-selection NPMI association graph) tuning.",
+  );
+
 /**
  * Ephemeral section-spotlight tuning: how many of the current turn's selected
  * finder hits render their matched section into the `<memory_spotlight>`
@@ -142,6 +222,10 @@ export const MemoryV3ConfigSchema = z
   .object({
     prune: MemoryV3PruneSchema.default(MemoryV3PruneSchema.parse({})),
     hotSet: MemoryV3HotSetSchema.default(MemoryV3HotSetSchema.parse({})),
+    freshSet: MemoryV3FreshSetSchema.default(MemoryV3FreshSetSchema.parse({})),
+    learnedEdges: MemoryV3LearnedEdgesSchema.default(
+      MemoryV3LearnedEdgesSchema.parse({}),
+    ),
     spotlight: MemoryV3SpotlightSchema.default(
       MemoryV3SpotlightSchema.parse({}),
     ),
@@ -161,6 +245,14 @@ export const MemoryV3ConfigSchema = z
       .describe(
         "Number of dense-lane articles folded into the candidate pool each turn.",
       ),
+    replyQueryK: z
+      .number({ error: "memory.v3.replyQueryK must be a number" })
+      .int("memory.v3.replyQueryK must be an integer")
+      .nonnegative("memory.v3.replyQueryK must be a non-negative integer")
+      .default(12)
+      .describe(
+        "Per-lane article budget for the reply-query finder pass: needle and dense each re-run over the assistant's previous message as separate queries (never concatenated with the user's message). 0 disables the pass. Deliberately small next to needleK/denseK — the pass adds the assistant-side retrieval signal, not a second full sweep.",
+      ),
     edge: MemoryV3EdgeSchema.default(MemoryV3EdgeSchema.parse({})),
   })
   .describe("Memory v3 — section-grain lane retrieval");

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

@@ -74,23 +74,19 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
     thinking: { enabled: false, streamThinking: false },
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
   },
-  // Open-weight economy option: Kimi K2.6 served by Fireworks via managed
-  // platform inference. Carries the `suppress-cjk` logit-bias preset to
-  // discourage the model from spontaneously emitting Chinese in English
-  // output; the preset is profile-scoped and only forwarded on the Fireworks
-  // path (see `providers/inference/logit-bias.ts`).
+  // Open-weight economy option: MiniMax M3 served by Fireworks via managed
+  // platform inference.
   "balanced-economy": {
     intent: "balanced",
     provider: "fireworks",
     connectionName: "fireworks-managed",
     source: "managed",
     label: "Balanced Economy",
-    description: "Strong open model (Kimi K2.6) at a lower price point",
-    maxTokens: 16000,
+    description: "Strong open model (MiniMax M3) at a lower price point",
+    maxTokens: 32000,
     effort: "high",
     thinking: { enabled: true, streamThinking: true },
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
-    logitBias: "suppress-cjk",
   },
 };
 

package/src/context/post-turn-tool-result-truncation.ts

@@ -50,6 +50,27 @@ function buildToolNameById(messages: Message[]): Map<string, string> {
   return byId;
 }
 
+/**
+ * Shared eligibility rules for replacing an oversized tool result with the
+ * on-disk stub: string content over the size threshold, not an error result,
+ * not from an exempt tool (durable instructions like skill bodies), and not
+ * already truncated (idempotency marker). Used by both the post-turn pass and
+ * the result-time spool pass so the two converge on the same results.
+ */
+export function isTruncationEligible(
+  tr: ToolResultContent,
+  toolName: string | undefined,
+): boolean {
+  if (typeof tr.content !== "string") return false;
+  if (tr.content.length <= THRESHOLD_CHARS) return false;
+  if (tr.is_error) return false;
+  if (toolName !== undefined && TRUNCATION_EXEMPT_TOOLS.has(toolName)) {
+    return false;
+  }
+  if (tr.content.includes(TRUNCATION_MARKER)) return false;
+  return true;
+}
+
 /**
  * Deterministic file path for a tool result's full content on disk.
  * Uses the first 12 hex chars of the SHA-256 of the tool_use_id.
@@ -58,7 +79,10 @@ export function getToolResultFilePath(
   conversationDir: string,
   toolUseId: string,
 ): string {
-  const hash = createHash("sha256").update(toolUseId).digest("hex").slice(0, 12);
+  const hash = createHash("sha256")
+    .update(toolUseId)
+    .digest("hex")
+    .slice(0, 12);
   return join(conversationDir, TOOL_RESULT_DIR, `${hash}.txt`);
 }
 
@@ -73,7 +97,11 @@ export function buildTruncatedContent(
 ): string {
   const half = Math.floor(TARGET_CHARS / 2);
   const prefix = safeStringSlice(original, 0, half);
-  const suffix = safeStringSlice(original, original.length - half, original.length);
+  const suffix = safeStringSlice(
+    original,
+    original.length - half,
+    original.length,
+  );
   const omittedChars = original.length - TARGET_CHARS;
   const estimatedTokens = Math.round(omittedChars / 4);
   return `${prefix}\n\n...(${estimatedTokens} tokens omitted ${TRUNCATION_MARKER} ${filePath})\n\n${suffix}`;
@@ -86,9 +114,7 @@ export function buildTruncatedContent(
  * - The full content is persisted to a deterministic file path on disk.
  * - The in-context content is replaced with a prefix/suffix stub.
  *
- * Results are skipped if they are below threshold, are error results,
- * have already been truncated (contain `TRUNCATION_MARKER`), or were produced
- * by a tool in `TRUNCATION_EXEMPT_TOOLS` (durable instructions like skill bodies).
+ * Results are skipped unless {@link isTruncationEligible} allows them.
  *
  * Returns a shallow-copied messages array (only modified messages are cloned)
  * and the count of results that were truncated.
@@ -107,22 +133,10 @@ export function postTurnTruncateToolResults(
       if (block.type !== "tool_result") return block;
       const tr = block as ToolResultContent;
 
-      // Skip short results.
-      if (tr.content.length <= THRESHOLD_CHARS) return block;
-
-      // Skip error results.
-      if (tr.is_error) return block;
-
-      // Skip results from tools whose output is durable operating instructions
-      // (e.g. skill_load); middle-truncating them strips the workflow.
-      const toolName = toolNameById.get(tr.tool_use_id);
-      if (toolName !== undefined && TRUNCATION_EXEMPT_TOOLS.has(toolName)) {
+      if (!isTruncationEligible(tr, toolNameById.get(tr.tool_use_id))) {
         return block;
       }
 
-      // Skip already-truncated results (idempotency).
-      if (tr.content.includes(TRUNCATION_MARKER)) return block;
-
       const filePath = getToolResultFilePath(
         options.conversationDir,
         tr.tool_use_id,

package/src/context/tool-result-spool.ts

@@ -0,0 +1,104 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ContentBlock, ToolResultContent } from "../providers/types.js";
+import {
+  buildTruncatedContent,
+  getToolResultFilePath,
+  isTruncationEligible,
+  TOOL_RESULT_DIR,
+} from "./post-turn-tool-result-truncation.js";
+
+/**
+ * AX-tree snapshots have their own dedicated history compactor
+ * (`compactAxTreeHistory`) with placeholder semantics tuned for computer-use
+ * sessions, and the model needs the freshest tree inline to act on it, so the
+ * result-time pass leaves them alone.
+ */
+const AX_TREE_TAG = "<ax-tree>";
+
+/**
+ * Tools whose results keep their full content at result time even when
+ * oversized. `file_read` is the model's only way to page spooled content back
+ * into context: stubbing a read of a `.tool-results/` file would spool a
+ * fresh copy and hand back another stub, so oversized content could never be
+ * read at all. Explicit reads are therefore honored in full; the post-turn
+ * pass still truncates them at turn end, after the model has consumed the
+ * content.
+ */
+const RESULT_TIME_STUB_EXEMPT_TOOLS = new Set<string>(["file_read"]);
+
+/**
+ * Whether a tool result is eligible for the result-time spool/stub pass:
+ * the post-turn pass's shared rules plus the AX-tree and `file_read`
+ * exemptions above.
+ */
+function isSpoolEligible(
+  tr: ToolResultContent,
+  toolName: string | undefined,
+): boolean {
+  if (!isTruncationEligible(tr, toolName)) return false;
+  if (toolName !== undefined && RESULT_TIME_STUB_EXEMPT_TOOLS.has(toolName)) {
+    return false;
+  }
+  if (tr.content.includes(AX_TREE_TAG)) return false;
+  return true;
+}
+
+/**
+ * Spool every oversized tool result in `blocks` to its deterministic
+ * `.tool-results/` file and replace the inline content with the post-turn
+ * pass's prefix/suffix stub — at result time, before the blocks join history.
+ *
+ * Because the swap happens before the content is ever sent, the
+ * provider-bound history stays strictly append-only across the turn's model
+ * calls, which is what keeps the provider's prompt-cache prefix valid:
+ * rewriting an earlier message between calls would invalidate the cache from
+ * that point on every iteration. The model still gets the head/tail preview
+ * plus the on-disk path, so it can page the full content back in with
+ * `file_read` (whose results are exempt from this pass) when it actually
+ * needs it.
+ *
+ * Uses the same file paths, stub bytes, and eligibility rules as
+ * `postTurnTruncateToolResults`, whose `TRUNCATION_MARKER` guard then skips
+ * these results at turn end. Eligible elements of `blocks` are replaced in
+ * place (the block objects themselves are not mutated). A result is only
+ * stubbed after its file is written, so a stub never points at a missing
+ * file; on filesystem errors the remaining blocks keep their full content and
+ * the post-turn pass covers them.
+ *
+ * Returns the number of results spooled and stubbed.
+ */
+export function spoolAndStubOversizedToolResults(
+  blocks: ContentBlock[],
+  options: {
+    conversationDir: string;
+    toolNameById: (toolUseId: string) => string | undefined;
+  },
+): number {
+  let stubbedCount = 0;
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (block.type !== "tool_result") continue;
+    if (!isSpoolEligible(block, options.toolNameById(block.tool_use_id))) {
+      continue;
+    }
+
+    if (stubbedCount === 0) {
+      mkdirSync(join(options.conversationDir, TOOL_RESULT_DIR), {
+        recursive: true,
+      });
+    }
+    const filePath = getToolResultFilePath(
+      options.conversationDir,
+      block.tool_use_id,
+    );
+    writeFileSync(filePath, block.content, "utf-8");
+    blocks[i] = {
+      ...block,
+      content: buildTruncatedContent(block.content, filePath),
+    };
+    stubbedCount++;
+  }
+  return stubbedCount;
+}

package/src/credential-execution/feature-gates.ts

@@ -59,4 +59,3 @@ export function isCesSecureInstallEnabled(config: AssistantConfig): boolean {
 export function isCesGrantAuditEnabled(config: AssistantConfig): boolean {
   return isAssistantFeatureFlagEnabled(CES_GRANT_AUDIT_FLAG_KEY, config);
 }
-