@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/config/sanitize-for-transfer.ts

@@ -6,6 +6,7 @@
  * - `ingress.publicBaseUrl` → set to `""`
  * - `ingress.enabled` → deleted
  * - `ingress.publicBaseUrlManagedBy` → deleted
+ * - `telegram.registeredWebhookUrl` → deleted
  * - `daemon` → deleted entirely
  * - `skills.load.extraDirs` → set to `[]`
  * - `hostBrowser.cdpInspect.desktopAuto` → deleted **only when the source
@@ -45,6 +46,16 @@ export function sanitizeConfigForTransfer(configJson: string): string {
     delete ingress.publicBaseUrlManagedBy;
   }
 
+  // Strip the recorded Telegram webhook URL. It records where *this*
+  // deployment pointed Telegram, so carrying it across a teleport would have
+  // the destination compare its own registration against the source's address
+  // and report a mismatch on a channel that is fine. Absent, the health sweep
+  // reports unverified until the destination reconciles and records its own.
+  if (config.telegram && typeof config.telegram === "object") {
+    const telegram = config.telegram as Record<string, unknown>;
+    delete telegram.registeredWebhookUrl;
+  }
+
   // Strip daemon entirely
   delete config.daemon;
 

package/src/config/schema.ts

@@ -50,6 +50,7 @@ import {
   PlatformConfigSchema,
   UiConfigSchema,
 } from "./schemas/platform.js";
+import { PluginUpdatesConfigSchema } from "./schemas/plugin-updates.js";
 import { SecretDetectionConfigSchema } from "./schemas/security.js";
 import { ServicesSchema } from "./schemas/services.js";
 import { SkillsConfigSchema } from "./schemas/skills.js";
@@ -142,6 +143,9 @@ export const AssistantConfigSchema = z.object({
     .describe(
       "Per-plugin configuration keyed by plugin name. Validated downstream by each plugin's manifest.config validator at bootstrap.",
     ),
+  pluginUpdates: PluginUpdatesConfigSchema.default(
+    PluginUpdatesConfigSchema.parse({}),
+  ),
   legacyTelemetryOptOut: z
     .boolean()
     .optional()

package/src/config/schemas/__tests__/stt.test.ts

@@ -66,11 +66,22 @@ describe("SttServiceSchema", () => {
     );
   });
 
-  test("language is optional and stays absent when unset", () => {
-    // Absent (not defaulted to "en") so the resolver can tell "user chose
-    // nothing" from "user chose English" and omit the param entirely.
+  test("language defaults to multilingual rather than staying absent", () => {
+    // Every config carries a real language, so nothing downstream has to
+    // infer one from an absent key. Omitting the param entirely is not a
+    // neutral state on Deepgram and the managed relay: it decodes as
+    // English, which is what this default exists to stop.
     const parsed = SttServiceSchema.parse({ provider: "vellum" });
-    expect(parsed.language).toBeUndefined();
+    expect(parsed.language).toBe("multi");
+  });
+
+  test("a chosen language is never replaced by the default", () => {
+    expect(
+      SttServiceSchema.parse({ provider: "deepgram", language: "ta" }).language,
+    ).toBe("ta");
+    expect(
+      SttServiceSchema.parse({ provider: "deepgram", language: "en" }).language,
+    ).toBe("en");
   });
 
   test("language round-trips a code and the multi code-switching mode", () => {
@@ -107,6 +118,10 @@ describe("managed provider", () => {
       mode: "managed",
       provider: "vellum",
     });
-    expect(parsed).toEqual({ provider: "vellum", providers: {} });
+    expect(parsed).toEqual({
+      provider: "vellum",
+      language: "multi",
+      providers: {},
+    });
   });
 });

package/src/config/schemas/channels.ts

@@ -68,6 +68,19 @@ export const TelegramConfigSchema = z
       .string({ error: "telegram.apiBaseUrl must be a string" })
       .default("https://api.telegram.org")
       .describe("Base URL for the Telegram Bot API"),
+    // Written by the gateway reconciler, read by the health sweep. Deployment
+    // state rather than user configuration: it records where this deployment
+    // last pointed Telegram, so the sweep can tell our own registration from a
+    // stale tunnel address or another deployment's callback. Unset until a
+    // reconciliation succeeds, which the sweep reports as unverified rather
+    // than healthy. Stripped by sanitize-for-transfer, like
+    // ingress.publicBaseUrlManagedBy, because it does not travel between hosts.
+    registeredWebhookUrl: z
+      .string({ error: "telegram.registeredWebhookUrl must be a string" })
+      .optional()
+      .describe(
+        "Webhook URL this deployment last registered with Telegram (managed by the gateway)",
+      ),
     deliverAuthBypass: z
       .boolean({ error: "telegram.deliverAuthBypass must be a boolean" })
       .default(false)

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

@@ -2,6 +2,28 @@ import { z } from "zod";
 
 export const MemoryRetrospectiveConfigSchema = z
   .object({
+    // This kill switch exists only because conversation forking is expensive:
+    // a fork full-copies the source conversation (messages + attachments), so
+    // on a large conversation the retrospective's write burst can lock the
+    // SQLite table against other writers. Until forking is referential, an
+    // operator needs a way to stop retrospectives without turning off memory.
+    enabled: z
+      .boolean({ error: "memory.retrospective.enabled must be a boolean" })
+      .default(true)
+      .describe(
+        "Whether the memory-retrospective background pass runs. When false, no retrospective is enqueued by any trigger (interval, message count, pre-compaction, scheduled sweep), the scheduled sweep job stops being queued, and any row already queued completes as a no-op. The rest of the memory system (extraction, retrieval, embeddings, `<memory>` injection) is unaffected. Use `memory.enabled` to disable memory as a whole.",
+      ),
+
+    forkStrategy: z
+      .enum(["cloning", "reference"], {
+        error:
+          "memory.retrospective.forkStrategy must be 'cloning' or 'reference'",
+      })
+      .default("cloning")
+      .describe(
+        "How a retrospective's fork of the source conversation is materialized. `cloning` (default) full-copies the source conversation's messages and attachments into the fork. `reference` makes the fork referential: it holds only its own messages and reads the source's through `fork_parent_message_id`, so a fork costs a single row instead of a full copy of the conversation.",
+      ),
+
     timeThresholdMs: z
       .number({
         error: "memory.retrospective.timeThresholdMs must be a number",
@@ -108,3 +130,6 @@ export const MemoryRetrospectiveConfigSchema = z
 export type MemoryRetrospectiveConfig = z.infer<
   typeof MemoryRetrospectiveConfigSchema
 >;
+
+/** How a retrospective materializes its fork of the source conversation. */
+export type MemoryForkStrategy = MemoryRetrospectiveConfig["forkStrategy"];

package/src/config/schemas/plugin-updates.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+/**
+ * Unattended plugin upgrade configuration.
+ *
+ * The resource monitor process runs a periodic sweep (see
+ * `monitoring/plugin-auto-update.ts`) that moves every installed, enabled
+ * plugin to its source's current revision. The sweep is off by default:
+ * `mode: "manual"` means nothing upgrades unless a human runs
+ * `assistant plugins upgrade <name>` (or the equivalent route), which is the
+ * behavior every workspace had before this block existed. Setting
+ * `mode: "auto"` opts the workspace into the hourly sweep.
+ */
+export const PluginUpdatesConfigSchema = z
+  .object({
+    mode: z
+      .enum(["manual", "auto"], {
+        error: 'pluginUpdates.mode must be "manual" or "auto"',
+      })
+      .default("manual")
+      .describe(
+        'How installed plugins move to newer revisions. "manual" (default) never upgrades on its own — upgrades happen only when a human asks for one. "auto" lets the resource monitor upgrade every installed, enabled plugin on the `checkIntervalMs` cadence.',
+      ),
+    strategy: z
+      // Deliberately narrower than the full `PluginUpgradeStrategy` union: the
+      // `assistant` strategy resolves conflicts by writing git conflict
+      // markers into the plugin's files and expecting someone to resolve
+      // them. Unattended, that would leave a syntactically broken plugin on
+      // disk with nobody in the loop, so it is not selectable here. It stays
+      // available for interactive `assistant plugins upgrade --strategy
+      // assistant`.
+      .enum(["theirs", "ours", "overwrite"], {
+        error:
+          'pluginUpdates.strategy must be "theirs", "ours", or "overwrite"',
+      })
+      .default("theirs")
+      .describe(
+        'How an automatic upgrade reconciles local edits to a plugin with the incoming revision. "theirs" (default) three-way merges and resolves conflicting hunks toward the incoming revision, keeping non-conflicting local edits; "ours" merges the same way but resolves conflicts toward the local edit; "overwrite" discards local edits and re-installs the revision wholesale. Only consulted when `mode` is "auto".',
+      ),
+    checkIntervalMs: z
+      .number({ error: "pluginUpdates.checkIntervalMs must be a number" })
+      .int("pluginUpdates.checkIntervalMs must be an integer")
+      .min(300_000, "pluginUpdates.checkIntervalMs must be at least 300000ms")
+      .max(
+        604_800_000,
+        "pluginUpdates.checkIntervalMs must be <= 604800000ms (7 days)",
+      )
+      .default(3_600_000)
+      .describe(
+        'Minimum interval between automatic upgrade sweeps, in milliseconds (default 1 hour). The last sweep is stamped on disk, so restarting the daemon does not re-run a sweep that already ran within the interval. Only consulted when `mode` is "auto".',
+      ),
+  })
+  .describe("Unattended plugin upgrade configuration");
+
+export type PluginUpdatesConfig = z.infer<typeof PluginUpdatesConfigSchema>;

package/src/config/schemas/services.ts

@@ -139,10 +139,14 @@ export const ServicesSchema = z.object({
     WebSearchServiceSchema.parse({}),
   ),
   "web-fetch": WebFetchServiceSchema.default(WebFetchServiceSchema.parse({})),
-  stt: SttServiceSchema.default({
-    provider: "deepgram" as const,
-    providers: {},
-  }),
+  // Parsed rather than handed a literal, like every sibling here: a literal
+  // default short-circuits the inner parse, so field-level defaults inside
+  // the block (the multilingual `language`) would never materialize for a
+  // config that omits `services.stt` entirely, which is every fresh
+  // workspace.
+  stt: SttServiceSchema.default(
+    SttServiceSchema.parse({ provider: "deepgram", providers: {} }),
+  ),
   tts: TtsServiceSchema.default(TtsServiceSchema.parse({})),
   "google-oauth": GoogleOAuthServiceSchema.default(
     GoogleOAuthServiceSchema.parse({}),

package/src/config/schemas/stt.ts

@@ -67,22 +67,34 @@ export const SttServiceSchema = z
       .describe("Active STT provider used for speech-to-text transcription"),
     /**
      * Spoken-language selection, forwarded to providers whose adapters accept
-     * a language (Deepgram, xAI, and the managed relay). Left unset the
-     * provider applies its own default, which for Deepgram (and therefore
-     * for the managed relay) is English, NOT auto-detection.
+     * a language (Deepgram, xAI, and the managed relay).
      *
      * `"multi"` selects Deepgram's nova-3 code-switching mode, which follows
      * a speaker moving between languages inside a single utterance (e.g.
      * Hinglish). Providers that auto-detect natively and take no language
      * option (Gemini, Whisper) ignore this field.
+     *
+     * Defaults to `"multi"` rather than staying unset, so there is no state
+     * where the answer to "what language is this assistant listening for"
+     * has to be inferred. Every config carries the answer, and the settings
+     * surfaces render a real selection rather than a sentinel standing in
+     * for one.
+     *
+     * The default applies on load, not just at creation, so an existing
+     * config that never set a language materializes `"multi"` on its next
+     * start. That changes no behavior: `effectiveSttLanguage` already
+     * resolved unset to `"multi"` on Deepgram and the managed relay, and the
+     * providers that detect natively ignore the field either way. It only
+     * makes the value explicit. An assistant that has chosen a language
+     * keeps it, since a default fills nothing that is already set.
      */
     language: z
       .string({ error: "services.stt.language must be a string" })
       .trim()
       .min(1, { error: "services.stt.language must not be empty" })
-      .optional()
+      .default("multi")
       .describe(
-        "BCP-47 language code (e.g. 'en-US', 'hi') or 'multi' for code-switching across languages. Unset uses the provider default (English on Deepgram/managed, not auto-detect)",
+        "BCP-47 language code (e.g. 'en-US', 'hi') or 'multi' for code-switching across languages. Defaults to 'multi'; providers that detect natively ignore it",
       ),
     providers: SttProvidersSchema.default({}),
   })

package/src/config/schemas/timeouts.ts

@@ -26,7 +26,7 @@ export const TimeoutConfigSchema = z
       .positive("timeouts.permissionTimeoutSec must be a positive number")
       .default(300)
       .describe(
-        "How long to wait for user permission approval before timing out (seconds)",
+        "How long to wait for a human to approve a tool call before timing out (seconds). Spent by both approval paths: the interactive permission prompt, and the inline wait when a contact's sensitive tool call is escalated to the guardian.",
       ),
     questionResponseTimeoutSec: z
       .number({ error: "timeouts.questionResponseTimeoutSec must be a number" })

package/src/contacts/__tests__/guardian-delivery-reader.test.ts

@@ -44,6 +44,7 @@ import {
   getGuardianDeliveryFresh,
   guardianForChannel,
   invalidateGuardianDeliveryCache,
+  warmGuardianBindings,
 } from "../guardian-delivery-reader.js";
 
 const METHOD = "resolve_guardian_delivery";
@@ -299,3 +300,18 @@ describe("selectors", () => {
     expect(anyGuardian([])).toBeUndefined();
   });
 });
+
+describe("warmGuardianBindings", () => {
+  test("warms both the vellum-channel key and the unfiltered fallback key", async () => {
+    const keys: string[] = [];
+    await warmGuardianBindings(async (input) => {
+      keys.push(input?.channelTypes?.join(",") ?? "ALL");
+      return null;
+    });
+    // Both keys the sync persona resolvers read — peekGuardianForChannel
+    // ("vellum") and the peekAnyGuardian() fallback — must be warmed;
+    // warming only the channel key leaves the any-channel fallback cold for
+    // guardians bound on non-vellum channels.
+    expect(keys.sort()).toEqual(["ALL", "vellum"]);
+  });
+});

package/src/contacts/guardian-delivery-reader.ts

@@ -151,8 +151,8 @@ export async function getGuardianDelivery(input?: {
  * Returns the fresh cached list for the given channel filter, or `undefined`
  * when the cache is cold or expired. Used by sync hot paths (SSE subscribe)
  * that cannot await {@link getGuardianDelivery} but must resolve the SAME
- * gateway-owned principal the async paths land on. A cold/expired return lets
- * the caller fall back to the local store as before.
+ * gateway-owned principal the async paths land on. There is no fallback
+ * fetch: on a cold/expired cache the caller proceeds without a principal.
  */
 export function peekCachedGuardianDelivery(input?: {
   channelTypes?: string[];
@@ -181,6 +181,33 @@ export async function getGuardianDeliveryFresh(input?: {
   });
 }
 
+type GuardianDeliveryFetch = (input?: {
+  channelTypes?: string[];
+}) => Promise<unknown>;
+
+/**
+ * Warm both guardian-binding cache keys the sync persona resolvers read: the
+ * `"vellum"`-channel key for `peekGuardianForChannel("vellum")` and the
+ * unfiltered key for the `peekAnyGuardian()` fallback. Warming only one key
+ * still resolves `users/default.md` when the guardian lives on a non-vellum
+ * channel (phone / Telegram).
+ *
+ * Uses the FRESH reader so warmup bypasses a stale/empty cached entry: a
+ * gateway-side binding write (onboarding, rebind) does not invalidate the
+ * daemon cache, so a non-fresh read could return an empty binding cached
+ * before the guardian existed and freeze `users/default.md` until the TTL
+ * expires. The fresh reads repopulate the cache the sync `peek*` resolvers
+ * then read. Best-effort: the reader swallows failures.
+ */
+export async function warmGuardianBindings(
+  fetchDelivery: GuardianDeliveryFetch = getGuardianDeliveryFresh,
+): Promise<void> {
+  await Promise.all([
+    fetchDelivery({ channelTypes: ["vellum"] }),
+    fetchDelivery(),
+  ]);
+}
+
 /**
  * Clear ALL cached guardian deliveries so contact mutations refetch on the next
  * read. Called by {@link notifyContactsChanged} after a contact write, and

package/src/context/compactor.ts

@@ -865,10 +865,10 @@ function resolveTailFloorIndex(messages: Message[], tailIndex: number): number {
 // Retained-image hydration
 // ---------------------------------------------------------------------------
 
-function buildRetainedImageBlocks(
+async function buildRetainedImageBlocks(
   filenames: string[],
   manifest: ManifestEntry[],
-): { blocks: ImageContent[]; resolved: string[]; missing: string[] } {
+): Promise<{ blocks: ImageContent[]; resolved: string[]; missing: string[] }> {
   const blocks: ImageContent[] = [];
   const resolved: string[] = [];
   const missing: string[] = [];
@@ -887,7 +887,7 @@ function buildRetainedImageBlocks(
     // 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.
-    const optimized = optimizeImageForTransport(
+    const optimized = await optimizeImageForTransport(
       content.toString("base64"),
       sourceMime,
     );
@@ -1393,7 +1393,7 @@ export async function runAssistantDrivenCompaction(
     blocks: retainedImageBlocks,
     resolved,
     missing,
-  } = buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
+  } = await buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
   if (missing.length > 0) {
     log.warn(
       { missing },

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

@@ -37,20 +37,43 @@ export const TRUNCATION_MARKER = "\u2014 full result:";
 export const TRUNCATION_EXEMPT_TOOLS = new Set<string>(["skill_load"]);
 
 /**
- * File-read tools that page spooled `.tool-results/` content back into context.
- * `file_read` reads inside the workspace; `host_file_read` reads anywhere on the
- * host. Both are (a) exempt from the result-time spool pass — re-stubbing a read
- * of a spooled file would hand back another stub, so the content could never be
- * paged back at all — and (b) recognized by {@link derefToolResultReReads}, so a
- * re-read of a spooled file collapses to a stub instead of duplicating content
- * already in context. Sharing one set keeps the two passes from drifting if a
- * new file-read tool is added.
+ * File-read tools that can page spooled `.tool-results/` content back into
+ * context. `file_read` reads inside the workspace; `host_file_read` reads
+ * anywhere on the host. A new file-read tool belongs here so
+ * {@link isSpooledToolResultRead} recognizes it.
  */
 export const FILE_READ_TOOL_NAMES = new Set<string>([
   "file_read",
   "host_file_read",
 ]);
 
+/**
+ * Whether a tool call is a file read aimed at a spooled `.tool-results/` file.
+ *
+ * Such a read is the model paging content back in, so both passes treat it
+ * specially: the result-time spool pass leaves it alone (re-stubbing it would
+ * write a fresh copy and hand back another stub, putting the content out of
+ * reach for good), and {@link derefToolResultReReads} collapses it at turn end
+ * (its prefix and suffix are already in context above). A file read aimed
+ * anywhere else is ordinary tool output and gets no such treatment.
+ */
+export function isSpooledToolResultRead(
+  toolName: string | undefined,
+  input: Record<string, unknown> | undefined,
+): boolean {
+  if (toolName === undefined || !FILE_READ_TOOL_NAMES.has(toolName)) {
+    return false;
+  }
+  const filePath = input?.path ?? input?.file_path;
+  if (typeof filePath !== "string") {
+    return false;
+  }
+  // The path in the stub comes from `join`, so it is backslash-separated on
+  // Windows. Compare on a normalized form: a missed match would let the spool
+  // pass stub this read and put the saved content permanently out of reach.
+  return filePath.replace(/\\/g, "/").includes(`/${TOOL_RESULT_DIR}/`);
+}
+
 /**
  * Build a map of tool_use_id -> originating tool name by walking the tool_use
  * blocks in assistant messages. A tool_result only carries `tool_use_id`, so
@@ -329,14 +352,7 @@ export function derefToolResultReReads(messages: Message[]): {
         continue;
       }
       const tu = block as ToolUseContent;
-      if (!FILE_READ_TOOL_NAMES.has(tu.name)) {
-        continue;
-      }
-      const filePath = tu.input.path ?? tu.input.file_path;
-      if (typeof filePath !== "string") {
-        continue;
-      }
-      if (filePath.includes(`/${TOOL_RESULT_DIR}/`)) {
+      if (isSpooledToolResultRead(tu.name, tu.input)) {
         reReadToolUseIds.add(tu.id);
       }
     }

package/src/context/strip-injections.ts

@@ -136,6 +136,48 @@ export function stripSpotlightInjections(messages: Message[]): Message[] {
   return stripUserTextBlocksByPrefix(messages, [MEMORY_SPOTLIGHT_MATCHER]);
 }
 
+/**
+ * Whether the TURN-STARTING user message carries a memory-v3
+ * `<memory_spotlight>` block.
+ *
+ * The spotlight is the only injected block that is strip-and-replaced from
+ * every user message each turn, so its presence is exactly what makes that
+ * message volatile across turns. Every other injected block (turn context,
+ * workspace, `<info>`, `<memory>` cards, NOW.md) is frozen into history and
+ * re-renders byte-identically, so a message without a spotlight is a stable
+ * cache anchor. Providers consume this through the `mutableLatestUserMessage`
+ * config field when placing cache breakpoints.
+ *
+ * The turn start is the most recent user message carrying TEXT content, which
+ * is the same message the Anthropic client anchors on. Tool-result messages
+ * are skipped: they are user-role but carry no injected blocks, and letting
+ * them answer this question would flip the signal to `false` partway through a
+ * tool loop. The provider would then mark the very same turn-start block at a
+ * different TTL than it did on the turn's first request, billing a second
+ * write for one reusable prefix. Anchoring on the turn start keeps the signal
+ * constant for every request in the turn.
+ *
+ * Detection uses {@link MEMORY_SPOTLIGHT_MATCHER}, the same full-wrapper
+ * matcher {@link stripSpotlightInjections} strips with, so the two can never
+ * disagree about which blocks are ephemeral.
+ */
+export function turnStartUserMessageHasSpotlight(messages: Message[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "user") {
+      continue;
+    }
+    const textBlocks = message.content.filter((block) => block.type === "text");
+    if (textBlocks.length === 0) {
+      continue;
+    }
+    return textBlocks.some((block) =>
+      textBlockMatchesInjection(block.text, [MEMORY_SPOTLIGHT_MATCHER]),
+    );
+  }
+  return false;
+}
+
 /** `<NOW.md>` scratchpad prefixes (current tag, pre-line-limit variant, legacy `<now_scratchpad>`) — shared with `stripNowScratchpad` so the two strip paths can't drift. */
 export const NOW_SCRATCHPAD_STRIP_PREFIXES: InjectionMatcher[] = [
   "<NOW.md Always keep this up to date",

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

@@ -4,8 +4,8 @@ import { join } from "node:path";
 import type { ContentBlock, ToolResultContent } from "../providers/types.js";
 import {
   buildTruncatedContent,
-  FILE_READ_TOOL_NAMES,
   getToolResultFilePath,
+  isSpooledToolResultRead,
   isTruncationEligible,
   TOOL_RESULT_DIR,
 } from "./post-turn-tool-result-truncation.js";
@@ -32,27 +32,32 @@ export const RESULT_TIME_SPOOL_EXEMPT_TOOLS = new Set<string>(["web_fetch"]);
 
 /**
  * Whether a tool result is eligible for the result-time spool/stub pass: the
- * post-turn pass's shared rules plus the AX-tree exemption, minus the file-read
- * tools ({@link FILE_READ_TOOL_NAMES}) and the explicit self-sized reads
- * ({@link RESULT_TIME_SPOOL_EXEMPT_TOOLS}). The file-read tools are 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.
+ * post-turn pass's shared rules plus the AX-tree exemption, minus reads of
+ * already-spooled `.tool-results/` files ({@link isSpooledToolResultRead}) and
+ * the explicit self-sized reads ({@link RESULT_TIME_SPOOL_EXEMPT_TOOLS}).
+ *
+ * The spooled-read exemption is what keeps paging possible: a file read is the
+ * model's only way to pull spooled content back into context, so stubbing a
+ * read of a `.tool-results/` file would write a fresh copy and hand back
+ * another stub, putting that content out of reach for good. It is scoped by
+ * target path rather than by tool name, because a file read aimed anywhere
+ * else is ordinary oversized output with no such circularity, and exempting it
+ * keeps a whole file inline on every LLM call for the rest of the turn.
+ * Explicit self-sized reads are honored in full; the post-turn pass still
+ * truncates them at turn end, after the model has consumed the content.
  */
 function isSpoolEligible(
   tr: ToolResultContent,
   toolName: string | undefined,
+  toolInput: Record<string, unknown> | undefined,
 ): boolean {
   if (!isTruncationEligible(tr, toolName)) {
     return false;
   }
-  if (
-    toolName !== undefined &&
-    (FILE_READ_TOOL_NAMES.has(toolName) ||
-      RESULT_TIME_SPOOL_EXEMPT_TOOLS.has(toolName))
-  ) {
+  if (isSpooledToolResultRead(toolName, toolInput)) {
+    return false;
+  }
+  if (toolName !== undefined && RESULT_TIME_SPOOL_EXEMPT_TOOLS.has(toolName)) {
     return false;
   }
   if (tr.content.includes(AX_TREE_TAG)) {
@@ -72,8 +77,8 @@ function isSpoolEligible(
  * 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` or `host_file_read` (whose results are exempt from this pass)
- * when it actually needs it.
+ * `file_read` or `host_file_read` (a read of a `.tool-results/` path is 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
@@ -89,7 +94,15 @@ export function spoolAndStubOversizedToolResults(
   blocks: ContentBlock[],
   options: {
     conversationDir: string;
-    toolNameById: (toolUseId: string) => string | undefined;
+    /**
+     * The originating call for a `tool_use_id`. A `tool_result` carries only
+     * the id, and eligibility turns on both the tool's name and the path it
+     * was pointed at, so the two travel together rather than as separate
+     * lookups that could disagree.
+     */
+    toolCallById: (
+      toolUseId: string,
+    ) => { name: string; input: Record<string, unknown> } | undefined;
   },
 ): number {
   let stubbedCount = 0;
@@ -98,7 +111,8 @@ export function spoolAndStubOversizedToolResults(
     if (block.type !== "tool_result") {
       continue;
     }
-    if (!isSpoolEligible(block, options.toolNameById(block.tool_use_id))) {
+    const toolCall = options.toolCallById(block.tool_use_id);
+    if (!isSpoolEligible(block, toolCall?.name, toolCall?.input)) {
       continue;
     }
 

package/src/credential-execution/ces-runtime.ts

@@ -176,6 +176,9 @@ export async function startCes(config: AssistantConfig): Promise<void> {
       },
     });
     if (client) {
+      log.info(
+        "CES client injected into credential resolver at startup; credential reads route through CES RPC",
+      );
       setCesClient(client);
     } else {
       // The handshake lost the startup race, so provider init proceeds on the

package/src/credential-execution/client.ts

@@ -9,6 +9,15 @@
  * delegated to the shared package.
  */
 
+import {
+  type CesRpcClient,
+  type CesRpcClientConfig,
+  type CesTransport,
+  createCesRpcClient,
+} from "@vellumai/ces-client/rpc-client";
+
+import { getLogger } from "../util/logger.js";
+
 export {
   type CesRpcClient as CesClient,
   type CesRpcClientConfig as CesClientConfig,
@@ -17,5 +26,17 @@ export {
   CesHandshakeError,
   type CesTransport,
   CesTransportError,
-  createCesRpcClient as createCesClient,
 } from "@vellumai/ces-client/rpc-client";
+
+const log = getLogger("ces-rpc-client");
+
+/**
+ * Construct a CES RPC client wired to the assistant logger so handshake-ready
+ * and close transitions are visible in the daemon logs.
+ */
+export function createCesClient(
+  transport: CesTransport,
+  config?: CesRpcClientConfig,
+): CesRpcClient {
+  return createCesRpcClient(transport, { logger: log, ...config });
+}