@vellumai/assistant 0.8.0 → 0.8.1

package/src/memory/v2/qdrant.ts

@@ -18,11 +18,16 @@
 // fusion using `dense_weight` / `sparse_weight` from `config.memory.v2`,
 // which RRF fusion would discard.
 
+import { existsSync } from "node:fs";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
 import { QdrantClient as QdrantRestClient } from "@qdrant/js-client-rest";
 import { v5 as uuidv5 } from "uuid";
 
 import { getConfig } from "../../config/loader.js";
 import { getLogger } from "../../util/logger.js";
+import { getDataDir } from "../../util/platform.js";
 import type { SparseEmbedding } from "../embedding-types.js";
 import { resolveQdrantUrl } from "../qdrant-client.js";
 
@@ -86,6 +91,49 @@ let _collectionReadyPromise: Promise<{ migrated: boolean }> | null = null;
 const REQUIRED_DENSE_VECTORS = ["dense", "summary_dense"] as const;
 const REQUIRED_SPARSE_VECTORS = ["sparse", "summary_sparse"] as const;
 
+/**
+ * Marker file written before the destructive collection-recreate path runs,
+ * cleared by the lifecycle hook once the reembed job has been enqueued.
+ *
+ * The sentinel exists to close a narrow data-loss window in
+ * `ensureConceptPageCollectionOnce`: a transient Qdrant failure between
+ * `deleteCollection` and `createCollection` would otherwise lose the
+ * "needs reembed" signal — `migrated` is reinitialized on the next call,
+ * any subsequent caller (e.g. an upsert) recreates the collection empty,
+ * and the lifecycle hook never enqueues the backfill. By persisting the
+ * intent on disk *before* delete, the signal survives crashes and
+ * intra-process retries: every later `ensureConceptPageCollection` call
+ * returns `migrated: true` until the lifecycle hook enqueues the reembed
+ * and clears the sentinel.
+ */
+const REEMBED_SENTINEL_FILENAME = ".memory-v2-reembed-required";
+
+function reembedSentinelPath(): string {
+  return join(getDataDir(), REEMBED_SENTINEL_FILENAME);
+}
+
+function reembedSentinelExists(): boolean {
+  return existsSync(reembedSentinelPath());
+}
+
+async function writeReembedSentinel(): Promise<void> {
+  const path = reembedSentinelPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, "");
+}
+
+/**
+ * Remove the reembed sentinel after the lifecycle hook has enqueued the
+ * `memory_v2_reembed` job. Idempotent — missing-file is not an error.
+ */
+export async function clearReembedSentinel(): Promise<void> {
+  try {
+    await unlink(reembedSentinelPath());
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+}
+
 /** Lazily create a Qdrant REST client bound to the resolved URL. */
 function getClient(): QdrantRestClient {
   if (_client) return _client;
@@ -127,7 +175,11 @@ async function ensureConceptPageCollectionOnce(): Promise<{
   const vectorSize = config.memory.qdrant.vectorSize;
   const onDisk = config.memory.qdrant.onDisk;
 
-  let migrated = false;
+  // A leftover sentinel means a prior call deleted the collection but never
+  // got to enqueue the reembed (e.g. createCollection threw, or the process
+  // died mid-rebuild). Carry that signal forward until the lifecycle hook
+  // clears it.
+  let migrated = reembedSentinelExists();
 
   try {
     const exists = await client.collectionExists(MEMORY_V2_COLLECTION);
@@ -156,6 +208,10 @@ async function ensureConceptPageCollectionOnce(): Promise<{
         { collection: MEMORY_V2_COLLECTION, missingNamedVectors: missing },
         "Memory v2 concept-page collection schema drift detected — deleting and recreating; embeddings will be regenerated by background reembed",
       );
+      // Persist the reembed intent BEFORE the destructive delete so a crash
+      // (or transient createCollection failure) between delete and recreate
+      // still triggers reembed on the next ensure call.
+      await writeReembedSentinel();
       await client.deleteCollection(MEMORY_V2_COLLECTION);
       migrated = true;
       // Fall through to creation below.
@@ -279,10 +335,17 @@ export async function upsertConceptPageEmbedding(params: {
   sparse: SparseEmbedding;
   summary?: { dense: number[]; sparse: SparseEmbedding };
   updatedAt: number;
+  /**
+   * Optional payload discriminator. Used to distinguish skill-seeded points
+   * (`kind: "skill"`) from user-authored concept pages so namespace pruning
+   * via {@link pruneSlugsWithPrefixExcept} can scope deletes to a single kind.
+   * Omitted for plain concept pages.
+   */
+  kind?: string;
 }): Promise<void> {
   await ensureConceptPageCollection();
 
-  const { slug, dense, sparse, summary, updatedAt } = params;
+  const { slug, dense, sparse, summary, updatedAt, kind } = params;
   const client = getClient();
   const pointId = pointIdForSlug(slug);
 
@@ -296,6 +359,9 @@ export async function upsertConceptPageEmbedding(params: {
     vector.summary_sparse = summary.sparse;
   }
 
+  const payload: Record<string, unknown> = { slug, updated_at: updatedAt };
+  if (kind !== undefined) payload.kind = kind;
+
   const upsertOnce = () =>
     client.upsert(MEMORY_V2_COLLECTION, {
       wait: true,
@@ -303,7 +369,7 @@ export async function upsertConceptPageEmbedding(params: {
         {
           id: pointId,
           vector,
-          payload: { slug, updated_at: updatedAt },
+          payload,
         },
       ],
     });
@@ -352,17 +418,25 @@ export async function deleteConceptPageEmbedding(slug: string): Promise<void> {
  * since skills now share the concept-page collection rather than living in a
  * dedicated one.
  *
+ * `kind` scopes pruning to a payload discriminator: only points whose
+ * `payload.kind` matches are eligible for deletion. This is critical because
+ * `validateSlug` permits user-authored concept pages slugged like
+ * `skills/foo`; without a kind filter they would collide with the skill
+ * namespace and be repeatedly pruned every seed run.
+ *
  * Idempotent: when the live `<prefix>*` slugs already match `activeSuffixes`,
  * the function performs a single scroll and no deletes.
  */
 export async function pruneSlugsWithPrefixExcept(
   prefix: string,
   activeSuffixes: readonly string[],
+  options: { kind?: string } = {},
 ): Promise<void> {
   await ensureConceptPageCollection();
 
   const client = getClient();
   const activeSet = new Set(activeSuffixes);
+  const requiredKind = options.kind;
 
   const doPrune = async (): Promise<void> => {
     const stalePointIds: Array<string | number> = [];
@@ -377,9 +451,15 @@ export async function pruneSlugsWithPrefixExcept(
         ...(offset !== undefined ? { offset } : {}),
       });
       for (const point of result.points) {
-        const slug = (point.payload as { slug?: unknown } | null)?.slug;
+        const payload = point.payload as {
+          slug?: unknown;
+          kind?: unknown;
+        } | null;
+        const slug = payload?.slug;
         if (typeof slug !== "string") continue;
         if (!slug.startsWith(prefix)) continue;
+        if (requiredKind !== undefined && payload?.kind !== requiredKind)
+          continue;
         const suffix = slug.slice(prefix.length);
         if (!activeSet.has(suffix)) {
           stalePointIds.push(point.id);
@@ -435,6 +515,22 @@ export async function countConceptPagePoints(): Promise<number> {
   }
 }
 
+/**
+ * Probe whether the v2 concept-page collection currently exists in Qdrant
+ * **without** triggering creation. Read-only diagnostics use this to avoid
+ * the side effect of bootstrapping storage just by inspecting it.
+ */
+export async function conceptPageCollectionExists(): Promise<boolean> {
+  const client = getClient();
+  try {
+    const result = await client.collectionExists(MEMORY_V2_COLLECTION);
+    return result.exists;
+  } catch (err) {
+    if (isCollectionMissing(err)) return false;
+    throw err;
+  }
+}
+
 /**
  * Best-effort delete of the legacy `memory_v2_skills` Qdrant collection. Skill
  * embeddings now live alongside concept pages in `memory_v2_concept_pages`
@@ -579,89 +675,6 @@ export async function hybridQueryConceptPages(
   return Array.from(merged.values());
 }
 
-/**
- * Page through the v2 concept-page collection and return up to `maxSamples`
- * stored dense vectors. Used by the anisotropy-fit pipeline to compute a
- * corpus mean + top-k principal components without re-embedding every page.
- *
- * Sparse vectors are skipped — anisotropy is a dense-embedding phenomenon, and
- * pulling the sparse side would just inflate the response. Payload is also
- * skipped because the fit doesn't need slug identity.
- *
- * Returns an empty array when the collection is empty or missing. Caller
- * decides what to do (typically: surface a "no vectors to fit" error).
- */
-export async function sampleConceptPageDenseVectors(
-  maxSamples: number,
-): Promise<number[][]> {
-  if (maxSamples <= 0) return [];
-  await ensureConceptPageCollection();
-
-  const client = getClient();
-  const out: number[][] = [];
-  let offset: string | number | undefined = undefined;
-  // Same pagination guard pattern as the rest of the file — bounds the loop
-  // even if Qdrant somehow keeps handing back a non-null offset.
-  const maxIterations = 10_000;
-  const batchSize = Math.min(256, maxSamples);
-
-  for (let i = 0; i < maxIterations; i++) {
-    if (out.length >= maxSamples) break;
-    const remaining = maxSamples - out.length;
-    let result;
-    try {
-      result = await client.scroll(MEMORY_V2_COLLECTION, {
-        limit: Math.min(batchSize, remaining),
-        with_payload: false,
-        // Fetch only the dense named vector — sparse is irrelevant for
-        // anisotropy correction.
-        with_vector: ["dense"],
-        ...(offset !== undefined ? { offset } : {}),
-      });
-    } catch (err) {
-      if (isCollectionMissing(err)) {
-        _collectionReady = false;
-        return out;
-      }
-      throw err;
-    }
-
-    for (const point of result.points) {
-      const v = extractDenseVector(point.vector);
-      if (v) out.push(v);
-      if (out.length >= maxSamples) break;
-    }
-
-    const next = result.next_page_offset;
-    if (next == null) break;
-    offset = typeof next === "string" ? next : (next as number);
-  }
-
-  return out;
-}
-
-/**
- * Pull the `dense` named-vector payload out of a Qdrant point. Defensively
- * handles both the named-vector shape (`{ dense: [...] }`) and the legacy
- * unnamed-vector shape (`number[]`) so older collection layouts don't trip
- * the sampler. Returns `null` for shapes we don't recognise.
- */
-function extractDenseVector(vector: unknown): number[] | null {
-  if (Array.isArray(vector)) {
-    if (vector.every((n) => typeof n === "number")) {
-      return vector as number[];
-    }
-    return null;
-  }
-  if (vector && typeof vector === "object") {
-    const dense = (vector as { dense?: unknown }).dense;
-    if (Array.isArray(dense) && dense.every((n) => typeof n === "number")) {
-      return dense as number[];
-    }
-  }
-  return null;
-}
-
 /**
  * Detect "collection not found" errors so callers can reset readiness and
  * retry after an external deletion (e.g. workspace reset).

package/src/memory/v2/reranker.ts

@@ -10,8 +10,8 @@ import { readPage } from "./page-store.js";
 
 const log = getLogger("memory-v2-reranker");
 
-// ~512-token model context for bge-reranker-base; cap input to bound payload.
-const PASSAGE_CHAR_CAP = 240;
+// Cap passage input to bound batched payload size and tokenization cost.
+const PASSAGE_CHAR_CAP = 1500;
 
 interface CacheEntry {
   scores: Map<string, number>;
@@ -22,9 +22,16 @@ const CACHE_TTL_MS = 2 * 60 * 1000;
 const CACHE_MAX_ENTRIES = 64;
 const cache = new Map<string, CacheEntry>();
 
-function cacheKey(query: string, slugs: readonly string[]): string {
+function cacheKey(
+  query: string,
+  slugs: readonly string[],
+  model: string,
+  dtype: string,
+): string {
   const sorted = [...slugs].sort().join("\0");
-  return createHash("sha256").update(`${query}\0${sorted}`).digest("hex");
+  return createHash("sha256")
+    .update(`${model}\0${dtype}\0${query}\0${sorted}`)
+    .digest("hex");
 }
 
 function evictExpired(now: number): void {
@@ -73,6 +80,7 @@ export async function rerankCandidates(
   if (queries.length === 0) return [];
   if (candidates.length === 0) return queries.map(() => new Map());
 
+  const { model, dtype } = config.memory.v2.rerank;
   const now = Date.now();
   evictExpired(now);
 
@@ -84,7 +92,7 @@ export async function rerankCandidates(
       results[i] = new Map();
       continue;
     }
-    const key = cacheKey(q, candidates);
+    const key = cacheKey(q, candidates, model, dtype);
     const cached = cache.get(key);
     if (cached) {
       // Refresh insertion order so frequently-hit entries survive eviction.
@@ -137,7 +145,6 @@ export async function rerankCandidates(
     }
   }
 
-  const { model, dtype } = config.memory.v2.rerank;
   let scores: number[];
   try {
     const backend = getOrCreateRerankBackend(model, dtype);
@@ -162,7 +169,7 @@ export async function rerankCandidates(
       result.set(slugsForPassages[i], Math.max(0, Math.min(1, s)));
     }
     results[qi] = result;
-    cache.set(cacheKey(queries[qi], candidates), {
+    cache.set(cacheKey(queries[qi], candidates, model, dtype), {
       scores: new Map(result),
       ts: now,
     });

package/src/memory/v2/router.ts

@@ -0,0 +1,322 @@
+/**
+ * Memory v2 — Sonnet router orchestration.
+ *
+ * Replaces the per-turn spreading-activation page selector with a single LLM
+ * call. Given the rendered page index, the most recent user/assistant turn,
+ * and the list of pages already injected on prior turns, the router returns a
+ * small set of concept-page IDs to inject for the next reply.
+ *
+ * The design mirrors `sweep-job.ts`:
+ *   - resolve the configured provider via `getConfiguredProvider`,
+ *   - call `provider.sendMessage` with a forced `tool_choice`,
+ *   - validate the tool input via Zod,
+ *   - map back to slugs and let the caller drive injection.
+ *
+ * Cache strategy. Two 1h ephemeral breakpoints carry the bulk of the
+ * routing cost across turns:
+ *   1. The last text block of the system prompt — the page index is the
+ *      single largest input and changes only when concept pages are edited.
+ *      Auto-applied by the Anthropic provider at the configured 1h TTL.
+ *   2. The first user-message block (`<now>`) — stable across most turns
+ *      since NOW.md only changes when the model rewrites it. We set the 1h
+ *      TTL explicitly here to match the provider-side breakpoints; the
+ *      default 5m would force unnecessary cache re-creation.
+ * The Anthropic provider also auto-applies a 1h breakpoint on the last text
+ * block of a turn-starting user message, so the trailing uncached block does
+ * not need an explicit `cache_control`.
+ *
+ * This module is pure orchestration — it does not mutate activation state,
+ * write any files, or update the conversation. PR 10 wires it into
+ * `injectMemoryV2Block`; until then nothing in the daemon calls it.
+ */
+
+import { z } from "zod";
+
+import type { AssistantConfig } from "../../config/types.js";
+import {
+  getAssistantName,
+  resolveUserName,
+} from "../../daemon/identity-helpers.js";
+import {
+  extractToolUse,
+  getConfiguredProvider,
+} from "../../providers/provider-send-message.js";
+import type {
+  ContentBlock,
+  Message,
+  ToolDefinition,
+} from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getPageIndex } from "./page-index.js";
+import { resolveRouterPrompt } from "./prompts/router.js";
+import type { EverInjectedEntry } from "./types.js";
+
+const log = getLogger("memory-v2-router");
+
+/**
+ * Reasons the router may fall short of returning a usable selection. The
+ * caller (PR 10) maps each reason to a fallback path; the closed string-
+ * literal union lets that dispatch stay exhaustive without a brittle
+ * free-form string match.
+ */
+export type RouterFailureReason =
+  | "no_provider"
+  | "tool_use_missing"
+  | "schema_mismatch"
+  | "api_error"
+  | "empty_index";
+
+/**
+ * Result of a single router call. `selectedSlugs` preserves the order the
+ * model returned and is already capped at `config.memory.v2.router.max_page_ids`
+ * with out-of-range IDs dropped.
+ */
+export interface RouterResult {
+  /** Selected page slugs in the order the model returned them. */
+  selectedSlugs: string[];
+  /** `null` on success; one of the failure reasons above otherwise. */
+  failureReason: RouterFailureReason | null;
+}
+
+/** Tool name forced via `tool_choice`. Single shared constant so tests can match it. */
+const ROUTER_TOOL_NAME = "select_pages_to_inject";
+
+/**
+ * Build the tool definition handed to the provider. The JSON schema is what
+ * the model sees; the Zod schema below validates the response at runtime.
+ *
+ * `maxItems` mirrors the runtime `config.memory.v2.router.max_page_ids` cap
+ * so the model is told the same upper bound the post-call truncation
+ * enforces. Built per-call rather than module-scoped because the cap is
+ * configurable per workspace.
+ */
+function buildRouterTool(maxPageIds: number): ToolDefinition {
+  return {
+    name: ROUTER_TOOL_NAME,
+    description: `Choose up to ${maxPageIds} concept page IDs to inject for the next reply. Lean toward inclusion when in doubt — missing a relevant page is a worse error than surfacing unused ones. Return [] only when nothing in the index plausibly bears on the turn.`,
+    input_schema: {
+      type: "object",
+      properties: {
+        page_ids: {
+          type: "array",
+          items: { type: "integer" },
+          maxItems: maxPageIds,
+        },
+      },
+      required: ["page_ids"],
+    },
+  };
+}
+
+const RouterResultSchema = z.object({
+  page_ids: z.array(z.number().int()),
+});
+
+/** Empty-result helper so call sites don't reconstruct the shape inline. */
+function emptyResult(reason: RouterFailureReason | null): RouterResult {
+  return { selectedSlugs: [], failureReason: reason };
+}
+
+interface RunRouterParams {
+  workspaceDir: string;
+  userMessage: string;
+  assistantMessage: string;
+  /** Verbatim contents to inject into `<now>...</now>` on this turn. */
+  nowText: string;
+  /** Slugs already injected on prior turns (used to seed `<already_injected_ids>`). */
+  priorEverInjected: readonly EverInjectedEntry[];
+  config: AssistantConfig;
+  signal?: AbortSignal;
+}
+
+/**
+ * Run the router for one turn. The implementation steps (mirroring
+ * `sweep-job.ts` end-to-end):
+ *
+ *   1. Build the page index. If the workspace has no concept pages and no
+ *      seeded skill entries, abstain immediately with `empty_index`.
+ *   2. Resolve the configured provider for the `memoryRouter` call site.
+ *      Missing → `no_provider` so the caller can fall back to spreading
+ *      activation or an empty injection.
+ *   3. Build system + user prompts. The system prompt is the rendered
+ *      router template with the page index inlined and gets one ephemeral
+ *      breakpoint at the end (the page-index block). The user message is
+ *      *two* text blocks: the cached `<now>` block and the uncached
+ *      already-injected/last-turn block.
+ *   4. Force `tool_choice` so the model can only emit `select_pages_to_inject`.
+ *   5. Parse the tool input via Zod. Anything off-shape collapses to
+ *      `schema_mismatch`.
+ *   6. Map IDs to slugs through the page index, dropping IDs outside
+ *      `[1, N]` and truncating at `max_page_ids`.
+ *
+ * Any uncaught throw inside the call (network, provider SDK error, abort)
+ * collapses to `api_error` and is logged at warn so callers can keep going
+ * without crashing the daemon. `AbortSignal.aborted` errors are *not*
+ * special-cased; they propagate as `api_error` because the caller treats
+ * "router didn't finish" the same regardless of cause.
+ */
+export async function runRouter(
+  params: RunRouterParams,
+): Promise<RouterResult> {
+  const {
+    workspaceDir,
+    userMessage,
+    assistantMessage,
+    nowText,
+    priorEverInjected,
+    config,
+    signal,
+  } = params;
+
+  const pageIndex = await getPageIndex(workspaceDir);
+  if (pageIndex.entries.length === 0) {
+    return emptyResult("empty_index");
+  }
+
+  const provider = await getConfiguredProvider("memoryRouter");
+  if (!provider) {
+    log.warn("memoryRouter provider unavailable; router skipped");
+    return emptyResult("no_provider");
+  }
+
+  const systemPrompt = resolveRouterPrompt(
+    config.memory?.v2?.router?.router_prompt_path ?? null,
+    {
+      assistantName: getAssistantName(),
+      userName: resolveUserName(workspaceDir),
+      pageIndexBlock: pageIndex.rendered,
+    },
+  );
+
+  // Already-injected slugs that map back to a current index ID. Slugs whose
+  // page has been deleted since the prior turn drop out silently — the model
+  // only sees IDs that still resolve.
+  const priorIds: number[] = [];
+  for (const entry of priorEverInjected) {
+    const idx = pageIndex.bySlug.get(entry.slug);
+    if (idx) priorIds.push(idx.id);
+  }
+
+  // Cache breakpoint 2 — `<now>` is stable across most turns (NOW.md only
+  // changes when the model rewrites it), so the bulk of the user message
+  // rides the cache. We use a 1h TTL to match the system-prompt breakpoint
+  // and the provider's auto-applied breakpoints. The trailing block has no
+  // `cache_control`; the Anthropic provider auto-applies a 1h breakpoint on
+  // the last text block of a turn-starting user message, which covers it.
+  const userMsg: Message = {
+    role: "user",
+    content: [
+      cachedTextBlock(`<now>\n${nowText}\n</now>`),
+      {
+        type: "text",
+        text:
+          `<already_injected_ids>\n${priorIds.join(", ")}\n</already_injected_ids>\n\n` +
+          `<last_turn>\n[user]: ${userMessage}\n[assistant]: ${assistantMessage}\n</last_turn>`,
+      },
+    ],
+  };
+
+  const maxPageIds = config.memory?.v2?.router?.max_page_ids ?? 25;
+  const routerTool = buildRouterTool(maxPageIds);
+
+  let response;
+  try {
+    response = await provider.sendMessage(
+      [userMsg],
+      [routerTool],
+      systemPrompt,
+      {
+        config: {
+          callSite: "memoryRouter" as const,
+          tool_choice: { type: "tool" as const, name: ROUTER_TOOL_NAME },
+        },
+        ...(signal ? { signal } : {}),
+      },
+    );
+  } catch (err) {
+    log.warn({ err }, "Router provider call threw; treating as api_error");
+    return emptyResult("api_error");
+  }
+
+  const toolBlock = extractToolUse(response);
+  if (!toolBlock || toolBlock.name !== ROUTER_TOOL_NAME) {
+    log.warn(
+      { stopReason: response.stopReason },
+      "Router model returned no select_pages_to_inject tool_use block",
+    );
+    return emptyResult("tool_use_missing");
+  }
+
+  const parsed = RouterResultSchema.safeParse(toolBlock.input);
+  if (!parsed.success) {
+    log.warn(
+      { error: parsed.error.message },
+      "Router tool input did not match schema",
+    );
+    return emptyResult("schema_mismatch");
+  }
+
+  const N = pageIndex.entries.length;
+
+  const inRangeIds: number[] = [];
+  const droppedIds: number[] = [];
+  for (const id of parsed.data.page_ids) {
+    if (id >= 1 && id <= N) {
+      inRangeIds.push(id);
+    } else {
+      droppedIds.push(id);
+    }
+  }
+  if (droppedIds.length > 0) {
+    log.warn(
+      { droppedIds, indexSize: N },
+      "Router returned page IDs outside the valid range; dropping",
+    );
+  }
+
+  const truncated = inRangeIds.length > maxPageIds;
+  const finalIds = truncated ? inRangeIds.slice(0, maxPageIds) : inRangeIds;
+  if (truncated) {
+    log.warn(
+      { returned: inRangeIds.length, max: maxPageIds },
+      "Router returned more page IDs than max_page_ids; truncating",
+    );
+  }
+
+  // De-duplicate while preserving order — the index lookup alone wouldn't
+  // catch repeats from the model.
+  const seen = new Set<number>();
+  const selectedSlugs: string[] = [];
+  for (const id of finalIds) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const entry = pageIndex.byId.get(id);
+    if (!entry) continue;
+    selectedSlugs.push(entry.slug);
+  }
+
+  return { selectedSlugs, failureReason: null };
+}
+
+/**
+ * Build a text content block carrying an ephemeral `cache_control`
+ * breakpoint with a 1h TTL. The Anthropic SDK accepts the field as an extra
+ * property on text blocks, but our internal `TextContent` type intentionally
+ * omits it (only the Anthropic provider transforms it onto the wire), so we
+ * reach through a `Record` cast here for the same reason `client.ts` does —
+ * it keeps the core types provider-agnostic. The 1h TTL matches the
+ * provider's auto-applied breakpoints (see `cacheTtl` in
+ * `providers/anthropic/client.ts`); the `<now>` block is stable across most
+ * turns, so default 5m would force unnecessary re-creation. The
+ * `extended-cache-ttl-2025-04-11` beta header is added unconditionally for
+ * non-Haiku models in `client.ts`, so this works without any call-site
+ * config.
+ */
+function cachedTextBlock(text: string): ContentBlock {
+  const block: ContentBlock = { type: "text", text };
+  (block as unknown as Record<string, unknown>).cache_control = {
+    type: "ephemeral",
+    ttl: "1h",
+  };
+  return block;
+}