@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/plugins/defaults/memory/v3/span-query.ts

@@ -0,0 +1,71 @@
+/**
+ * Memory v3 — deterministic clause chunking for the span-query dense pass.
+ *
+ * A single embedding of a long, multi-topic message averages its distinct
+ * retrieval intents into one vector that matches none of them — the
+ * within-message form of the cross-speaker averaging the reply-query pass
+ * exists to avoid. The span pass re-runs the dense lane over the message's
+ * clause spans as separate queries so a motif buried in one clause retrieves
+ * at full strength.
+ *
+ * Chunking is pure text processing: split at newlines and sentence
+ * punctuation, drop fragments below {@link MIN_SPAN_WEIGHT}. A message yielding
+ * more than {@link MAX_SPAN_CHUNKS} spans is NOT truncated to its head — all
+ * spans are partitioned into {@link MAX_SPAN_CHUNKS} contiguous near-equal
+ * groups, so the whole message stays covered and long messages are simply
+ * queried at paragraph grain instead of clause grain.
+ */
+
+/** Hard cap on span chunks per message — bounds the pass at
+ *  `MAX_SPAN_CHUNKS × spanQueryK` extra candidates and as many embed calls. */
+export const MAX_SPAN_CHUNKS = 8;
+
+/** Spans weighing less than this carry no retrieval signal ("ok.", bare emoji
+ *  lines) and are dropped before chunking. Weight, not raw length — see
+ *  {@link spanWeight}. */
+const MIN_SPAN_WEIGHT = 15;
+
+/** Dense CJK scripts pack roughly a clause into the character budget English
+ *  needs for a few words, so a raw char floor tuned for spaced scripts would
+ *  drop nearly every realistic Chinese/Japanese/Korean sentence. Weigh those
+ *  chars at 3× so the floor measures comparable information content. */
+const DENSE_SCRIPT = /[\p{sc=Han}\p{sc=Hiragana}\p{sc=Katakana}\p{sc=Hangul}]/u;
+
+function spanWeight(span: string): number {
+  let weight = 0;
+  for (const ch of span) {
+    weight += DENSE_SCRIPT.test(ch) ? 3 : 1;
+  }
+  return weight;
+}
+
+/**
+ * Split `message` into at most {@link MAX_SPAN_CHUNKS} contiguous clause
+ * chunks. Messages with that many spans or fewer return them unchanged;
+ * longer messages merge adjacent spans into near-equal groups covering the
+ * whole message. Deterministic; returns `[]` for empty/whitespace input.
+ */
+export function spanChunksOf(message: string): string[] {
+  // Boundaries: newlines; any Unicode sentence terminator (`\p{STerm}` covers
+  // ASCII `.!?` plus CJK `。！？`, Arabic `؟`, Devanagari `।`, …) or ellipsis
+  // followed by whitespace; and a zero-width split after fullwidth CJK
+  // terminators, which conventionally have NO trailing space. The whitespace
+  // requirement on the general arm keeps ASCII `.` from splitting decimals
+  // and dotted abbreviations; fullwidth terminators never appear there.
+  const spans = message
+    .split(/\n+|(?<=[\p{STerm}…])\s+|(?<=[。！？｡])/u)
+    .map((s) => s.trim())
+    .filter((s) => spanWeight(s) >= MIN_SPAN_WEIGHT);
+  if (spans.length <= MAX_SPAN_CHUNKS) {
+    return spans;
+  }
+  const chunks: string[] = [];
+  for (let i = 0; i < MAX_SPAN_CHUNKS; i++) {
+    const lo = Math.floor((i * spans.length) / MAX_SPAN_CHUNKS);
+    const hi = Math.floor(((i + 1) * spans.length) / MAX_SPAN_CHUNKS);
+    if (hi > lo) {
+      chunks.push(spans.slice(lo, hi).join(" "));
+    }
+  }
+  return chunks;
+}

package/src/plugins/defaults/memory/v3/tuning-profile.ts

@@ -28,6 +28,7 @@ export interface ResolvedV3Tuning {
   needleK: number;
   denseK: number;
   replyQueryK: number;
+  spanQueryK: number;
   selectorEnabled: boolean;
   learnedEdgesCap: number;
   edgeSeedCount: number;
@@ -55,6 +56,7 @@ export const MEMORY_V3_NEW_USER_TUNING: ResolvedV3Tuning = {
   needleK: 12,
   denseK: 0,
   replyQueryK: 0,
+  spanQueryK: 0,
   selectorEnabled: false,
   learnedEdgesCap: 0,
   edgeSeedCount: 6,
@@ -82,6 +84,7 @@ export function resolveV3Tuning(
     needleK: v3.needleK,
     denseK: v3.denseK,
     replyQueryK: v3.replyQueryK,
+    spanQueryK: v3.spanQueryK,
     selectorEnabled: v3.selectorEnabled,
     learnedEdgesCap: v3.learnedEdges.cap,
     edgeSeedCount: v3.edge.seedCount,

package/src/plugins/defaults/memory/v3/types.ts

@@ -96,7 +96,9 @@ export interface MemoryRoutingTurn {
  * frecency hot set, modification-recency fresh set); `needle` / `dense` /
  * `edge` are the per-turn finder lanes over the user's message; `reply` marks
  * finder candidates first surfaced by the reply-query pass (needle + dense
- * re-run over the assistant's previous message); `learned` marks candidates
+ * re-run over the assistant's previous message); `span` marks candidates first
+ * surfaced by the span-query pass (dense re-run over the current message's
+ * clause chunks as separate queries); `learned` marks candidates
  * surfaced by the co-selection NPMI association graph; `entity` marks
  * candidates surfaced because the message named an entity that titles a section
  * heading (the heading-anchored entity lane).
@@ -114,6 +116,7 @@ export const SELECTION_SOURCES = [
   "dense",
   "edge",
   "reply",
+  "span",
   "learned",
   "entity",
 ] as const;

package/src/plugins/defaults/memory/v3-eval/eval-packets.ts

@@ -36,11 +36,11 @@ import {
   messages,
 } from "../../../../persistence/schema/index.js";
 import { FRONTMATTER_REGEX, parseFrontmatterFields } from "../frontmatter.js";
+import { injectedConceptHeader } from "../substrate/injected-block-slugs.js";
+import { slugFromConceptPath } from "../substrate/page-store.js";
 import { renderCard } from "../v3/card.js";
 import { buildSectionNeedle } from "../v3/section-needle.js";
 import { buildSectionIndex } from "../v3/sections.js";
-import { injectedConceptHeader } from "../v3/substrate/injected-block-slugs.js";
-import { slugFromConceptPath } from "../v3/substrate/page-store.js";
 import type { SectionIndex, Slug } from "../v3/types.js";
 
 type DrizzleDb = ReturnType<typeof getDb>;

package/src/plugins/defaults/memory/validation.ts

@@ -14,7 +14,7 @@ export function clampUnitInterval(value: number): number {
  * `(x + 1) / 2`, then clamp. Single-channel display normalization for the
  * legacy v1 semantic-search path; do **not** use before hybrid fusion —
  * the affine rescale halves pairwise dense differences and shifts ranking
- * toward sparse. Hybrid fusion (`v2/sim.ts`) instead clamps negative
+ * toward sparse. Hybrid fusion (`substrate/sim.ts`) instead clamps negative
  * cosines to 0 with `Math.max(0, x)` and lets positive cosines pass
  * through unchanged.
  */

package/src/plugins/defaults/memory/worker.ts

@@ -13,6 +13,7 @@
 import { writeFileSync } from "node:fs";
 
 import { getConfig } from "../../../config/loader.js";
+import { isMemoryEnabled } from "../../../config/memory-v3-gate.js";
 import { rehydratePlatformCredentials } from "../../../config/platform-rehydration.js";
 import { resetDb } from "../../../persistence/db-connection.js";
 import { disableStreamSeqStamping } from "../../../runtime/assistant-stream-state.js";
@@ -34,7 +35,7 @@ async function main(): Promise<void> {
   const config = getConfig();
   const pidPath = getMemoryWorkerPidPath();
 
-  if (config.memory.enabled === false) {
+  if (!isMemoryEnabled(config)) {
     log.info("Memory is disabled in config; worker process exiting");
     process.exit(0);
   }

package/src/plugins/defaults/platform-hosted/__tests__/reengage.test.ts

@@ -12,6 +12,8 @@
  * Covers:
  * - Happy path: model writes valid JSON → structured subject/body, file cleaned up
  * - Runs in a fresh background conversation
+ * - Offers standard conversations as candidates; returns the assistant's chosen
+ *   id, drops hallucinated ids, excludes surfaced background rows
  * - Fenced JSON in the file → still parsed
  * - Model writes nothing → 502
  * - Model writes JSON missing a field → 502
@@ -32,12 +34,30 @@ import type { RunConversationTurnOptions } from "@vellumai/plugin-api";
 // prompt).
 // ---------------------------------------------------------------------------
 
+interface ConversationRowStub {
+  id: string;
+  title: string | null;
+  conversationType: string;
+}
+
+/** JSON the assistant "writes", including its chosen conversation id. */
+function draftJson(conversation: string | null): string {
+  return JSON.stringify({
+    subject: "Ready when you are",
+    body: "Just picking up where we left off.",
+    conversation,
+  });
+}
+
 let workspaceDir = mkdtempSync(join(tmpdir(), "reengage-test-"));
-let fileContents: string | null = JSON.stringify({
-  subject: "Ready when you are",
-  body: "Just picking up where we left off.",
-});
+let fileContents: string | null = draftJson("conv-42");
 let lastOptions: RunConversationTurnOptions | undefined;
+// Rows the mocked `listConversations` returns, newest-first — the route filters
+// these to genuine `standard` rows and offers them as link candidates.
+let conversationRows: ConversationRowStub[] = [
+  { id: "conv-42", title: "Roadmap planning", conversationType: "standard" },
+];
+let lastListArgs: unknown[] | undefined;
 
 function extractInjectedPath(prompt: string): string {
   const match = prompt.match(/`([^`]+)`/);
@@ -57,6 +77,10 @@ mock.module("@vellumai/plugin-api", () => ({
     }
     return { content: [], userMessageId: "msg-1", conversationId: "conv-1" };
   },
+  listConversations: async (...args: unknown[]) => {
+    lastListArgs = args;
+    return conversationRows;
+  },
 }));
 
 const { POST } = await import("../routes/reengage.js");
@@ -72,23 +96,34 @@ describe("platform-hosted /reengage POST", () => {
   beforeEach(() => {
     workspaceDir = mkdtempSync(join(tmpdir(), "reengage-test-"));
     lastOptions = undefined;
-    fileContents = JSON.stringify({
-      subject: "Ready when you are",
-      body: "Just picking up where we left off.",
-    });
+    lastListArgs = undefined;
+    conversationRows = [
+      {
+        id: "conv-42",
+        title: "Roadmap planning",
+        conversationType: "standard",
+      },
+    ];
+    fileContents = draftJson("conv-42");
   });
 
+  function promptText(): string {
+    return (lastOptions?.content[0] as { text: string }).text;
+  }
+
   test("returns the structured subject/body the model wrote, and cleans up", async () => {
     const response = await POST(postRequest());
     expect(response.status).toBe(200);
-    const json = (await response.json()) as { subject: string; body: string };
+    const json = (await response.json()) as {
+      subject: string;
+      body: string;
+      conversation: string | null;
+    };
     expect(json.subject).toBe("Ready when you are");
     expect(json.body).toBe("Just picking up where we left off.");
 
     // The injected file is removed after the handler returns.
-    const injectedPath = extractInjectedPath(
-      (lastOptions?.content[0] as { text: string }).text,
-    );
+    const injectedPath = extractInjectedPath(promptText());
     expect(existsSync(injectedPath)).toBe(false);
   });
 
@@ -103,6 +138,63 @@ describe("platform-hosted /reengage POST", () => {
     expect(lastOptions?.callSite).toBe("inference");
   });
 
+  test("offers the standard conversations as candidates and returns the chosen id", async () => {
+    conversationRows = [
+      {
+        id: "conv-42",
+        title: "Roadmap planning",
+        conversationType: "standard",
+      },
+      { id: "older", title: "Trip notes", conversationType: "standard" },
+    ];
+    fileContents = draftJson("conv-42");
+    const response = await POST(postRequest());
+    const json = (await response.json()) as { conversation: string | null };
+
+    expect(json.conversation).toBe("conv-42");
+    // The candidates are offered to the model in the prompt (id + title).
+    expect(promptText()).toContain("conv-42: Roadmap planning");
+    expect(promptText()).toContain("older: Trip notes");
+    // The standard bucket is queried (subagent/background excluded there).
+    expect(lastListArgs).toEqual([20, "standard"]);
+  });
+
+  test("drops a chosen id that isn't among the offered candidates", async () => {
+    // A hallucinated / stale id the assistant made up is never trusted.
+    fileContents = draftJson("made-up-id");
+    const response = await POST(postRequest());
+    const json = (await response.json()) as { conversation: string | null };
+    expect(json.conversation).toBeNull();
+  });
+
+  test("null conversation is returned when the assistant declines to pick", async () => {
+    fileContents = draftJson(null);
+    const response = await POST(postRequest());
+    const json = (await response.json()) as { conversation: string | null };
+    expect(json.conversation).toBeNull();
+  });
+
+  test("excludes surfaced background/scheduled rows from the candidates", async () => {
+    // `listConversations(…, "standard")` can surface promoted background rows;
+    // they are not real chats to re-open, so they are filtered out — never
+    // offered, and rejected even if the model somehow names one.
+    conversationRows = [
+      { id: "surfaced-bg", title: "Heartbeat", conversationType: "background" },
+      {
+        id: "conv-42",
+        title: "Roadmap planning",
+        conversationType: "standard",
+      },
+    ];
+    fileContents = draftJson("surfaced-bg");
+    const response = await POST(postRequest());
+    const json = (await response.json()) as { conversation: string | null };
+
+    expect(json.conversation).toBeNull();
+    expect(promptText()).not.toContain("surfaced-bg");
+    expect(promptText()).toContain("conv-42: Roadmap planning");
+  });
+
   test("tolerates JSON wrapped in a code fence", async () => {
     fileContents =
       '```json\n{"subject": "A quick nudge", "body": "Let me know."}\n```';

package/src/plugins/defaults/platform-hosted/routes/reengage.ts

@@ -14,12 +14,22 @@
  * from structured JSON rather than parsed out of the chat reply. The turn runs
  * in a fresh `background` conversation, so it stays out of the user's visible
  * chats.
+ *
+ * The response also carries `conversation` — the id of the conversation the
+ * email's "jump back in" link should re-open, or `null`. The assistant chooses
+ * it: the prompt offers a list of the owner's recent conversations and asks it
+ * to name the one its email is about, and the route returns that id only after
+ * validating it against the offered set. See {@link conversationCandidates}.
  */
 
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 
-import { getWorkspaceDir, runConversationTurn } from "@vellumai/plugin-api";
+import {
+  getWorkspaceDir,
+  listConversations,
+  runConversationTurn,
+} from "@vellumai/plugin-api";
 
 // ---------------------------------------------------------------------------
 // Output location — the plugin's own data directory
@@ -34,7 +44,15 @@ function pluginDataDir(): string {
 // Prompt
 // ---------------------------------------------------------------------------
 
-function buildPrompt(outputPath: string): string {
+function buildPrompt(
+  outputPath: string,
+  candidates: ConversationCandidate[],
+): string {
+  const conversationList =
+    candidates.length > 0
+      ? candidates.map((c) => `- ${c.id}: ${c.title}`).join("\n")
+      : "(you have no recent conversations)";
+
   return `Compose a short re-engagement email to me, in your own voice as my assistant, to gently draw me back into our work together.
 
 Draw on what you know about me and our recent conversations to make it personal and specific — reference something concrete we have been working on, or a next step that is waiting on me, rather than a generic "just checking in." Keep it warm, brief, and low-pressure: a few sentences at most, with no pushy or salesy language.
@@ -43,22 +61,38 @@ When the email is ready, use your file-writing tool to write it to exactly this
 
 \`${outputPath}\`
 
-Write ONLY a raw JSON object to that file — no markdown, no code fence, no surrounding prose — with exactly these two string fields:
-{"subject": "<the subject line>", "body": "<the plain-text email body>"}
+Write ONLY a raw JSON object to that file — no markdown, no code fence, no surrounding prose — with exactly these fields:
+{"subject": "<the subject line>", "body": "<the plain-text email body>", "conversation": "<id or null>"}
+
+The subject should be short and specific. The body is the email itself, written as if you are speaking directly to me.
 
-The subject should be short and specific. The body is the email itself, written as if you are speaking directly to me. The file is the deliverable; do not include the email in your chat reply.`;
+For "conversation", choose the one conversation below that your email is about — the thread I should re-open to pick up where we left off — and use its id exactly as written. If none of them fit what your email references, use null. Never invent an id; only use one from this list:
+${conversationList}
+
+The file is the deliverable; do not include the email in your chat reply.`;
 }
 
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
 
+interface ParsedEmail {
+  subject: string;
+  body: string;
+  /** The conversation id the assistant chose, or `null` for none. */
+  conversation: string | null;
+}
+
 /**
- * Read `{ subject, body }` out of the JSON the assistant wrote. The instruction
- * asks for a bare object, but tolerate a stray code fence or surrounding prose
- * by falling back to the first brace-delimited span.
+ * Read `{ subject, body, conversation }` out of the JSON the assistant wrote.
+ * The instruction asks for a bare object, but tolerate a stray code fence or
+ * surrounding prose by falling back to the first brace-delimited span.
+ *
+ * `conversation` is optional and the id it names is not trusted here — the
+ * handler validates it against the offered candidates. A missing value, JSON
+ * `null`, or the literal string `"null"` all normalize to `null`.
  */
-function parseEmail(raw: string): { subject: string; body: string } | null {
+function parseEmail(raw: string): ParsedEmail | null {
   const candidates = [raw.trim()];
   const brace = raw.match(/\{[\s\S]*\}/);
   if (brace?.[0]) {
@@ -73,7 +107,12 @@ function parseEmail(raw: string): { subject: string; body: string } | null {
           typeof record.subject === "string" ? record.subject.trim() : "";
         const body = typeof record.body === "string" ? record.body.trim() : "";
         if (subject && body) {
-          return { subject, body };
+          const raw =
+            typeof record.conversation === "string"
+              ? record.conversation.trim()
+              : "";
+          const conversation = raw && raw !== "null" ? raw : null;
+          return { subject, body, conversation };
         }
       }
     } catch {
@@ -87,6 +126,42 @@ function jsonError(message: string, status: number): Response {
   return Response.json({ error: { message } }, { status });
 }
 
+// ---------------------------------------------------------------------------
+// Conversation candidates for the "jump back in" link
+// ---------------------------------------------------------------------------
+
+/** A conversation the assistant may choose to link the email back to. */
+interface ConversationCandidate {
+  id: string;
+  title: string;
+}
+
+/** How many recent conversations to offer the assistant to choose from. */
+const CANDIDATE_LIMIT = 10;
+
+/**
+ * Recent, genuinely-standard conversations the assistant can pick from for the
+ * email's "jump back in" link.
+ *
+ * The assistant chooses which conversation the email is about (see
+ * {@link buildPrompt}), but it has no reliable handle on raw conversation ids —
+ * there is no list/search-conversations tool and ids are not in its context —
+ * so we hand it real candidates to choose among and validate its pick against
+ * this set, rather than trusting a free-formed (hallucinatable) id.
+ *
+ * `listConversations(…, "standard")` also surfaces background/scheduled rows
+ * that were promoted via `surfaced_at`, which are not real chats to re-open, so
+ * the result is filtered to rows whose type is actually `"standard"`. That also
+ * excludes the drafting turn's own background conversation.
+ */
+async function conversationCandidates(): Promise<ConversationCandidate[]> {
+  const rows = await listConversations(CANDIDATE_LIMIT * 2, "standard");
+  return rows
+    .filter((row) => row.conversationType === "standard")
+    .slice(0, CANDIDATE_LIMIT)
+    .map((row) => ({ id: row.id, title: row.title?.trim() || "Untitled" }));
+}
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -96,9 +171,13 @@ export const POST = async (request: Request): Promise<Response> => {
   await mkdir(dir, { recursive: true });
   const outputPath = join(dir, `reengage-${crypto.randomUUID()}.json`);
 
+  // Offer the assistant real conversations to choose the "jump back in" link
+  // from, so the id it writes can be validated against actual chats.
+  const candidates = await conversationCandidates();
+
   try {
     await runConversationTurn({
-      content: [{ type: "text", text: buildPrompt(outputPath) }],
+      content: [{ type: "text", text: buildPrompt(outputPath, candidates) }],
       conversationType: "background",
       // Drafting a short email is latency-bound, not depth-bound, so run it on
       // the fast model rather than the balanced main-agent default. `inference`
@@ -127,7 +206,20 @@ export const POST = async (request: Request): Promise<Response> => {
       );
     }
 
-    return Response.json(email);
+    // Trust the assistant's choice only if it names one of the conversations we
+    // offered — never a free-formed id. The platform wraps `body` in a template
+    // whose CTA deep-links to this conversation when present, else the
+    // assistant root.
+    const candidateIds = new Set(candidates.map((c) => c.id));
+    const conversation =
+      email.conversation && candidateIds.has(email.conversation)
+        ? email.conversation
+        : null;
+    return Response.json({
+      subject: email.subject,
+      body: email.body,
+      conversation,
+    });
   } finally {
     await rm(outputPath, { force: true });
   }

package/src/plugins/types.ts

@@ -91,8 +91,8 @@ export type {
 /**
  * The complete set of compaction circuit-breaker transition events:
  * `compaction_circuit_open` when the breaker trips and `compaction_circuit_closed`
- * on the open→closed transition. Both are a subset of `ServerMessage`, so any
- * existing `ServerMessage` sink remains assignable to a
+ * on the open→closed transition. Both are a subset of `AssistantEvent`, so any
+ * existing `AssistantEvent` sink remains assignable to a
  * `(msg: CompactionCircuitEvent) => void` parameter.
  */
 export type CompactionCircuitEvent =

package/src/prompts/sections.ts

@@ -3,7 +3,10 @@ import { join } from "node:path";
 
 import { parseFrontmatterFields } from "../skills/frontmatter.js";
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
+import {
+  getWorkspacePromptPath,
+  getWorkspaceSystemPromptDir,
+} from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import {
   BUNDLED_SYSTEM_SECTIONS,
@@ -25,21 +28,6 @@ const log = getLogger("system-prompt-sections");
  */
 export type SectionRenderContext = Record<string, unknown>;
 
-/**
- * Workspace override location for user-authored system prompt sections.
- * Layout: `<workspace>/prompts/system/<NN-name>.md`.
- *
- * The bundled section registry (`templates/system-sections.ts`) is the
- * source of default truth; this directory is an optional override layer.
- * Drop a file with the same id as a bundled section to replace its body,
- * or drop a file with a brand-new `<NN-name>` to add a workspace-only
- * section.  Either path is opt-in — the directory may not exist on a
- * fresh install, and the renderer will simply use bundled defaults.
- */
-export function getWorkspaceSystemPromptDir(): string {
-  return join(getWorkspaceDir(), "prompts", "system");
-}
-
 /**
  * Render static sections in id-sort order, then dynamic sections in id-sort
  * order, returning the trimmed bodies of enabled sections grouped into

package/src/providers/__tests__/registry-native-web-search.test.ts

@@ -1,4 +1,12 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  setSystemTime,
+  test,
+} from "bun:test";
 
 import { LLMSchema } from "../../config/schemas/llm.js";
 import type { ProviderConnection } from "../inference/auth.js";
@@ -52,7 +60,6 @@ function makeConfig(): ProvidersConfig {
     services: {
       inference: {},
       "image-generation": {
-        mode: "your-own",
         provider: "gemini",
         model: "gemini-3.1-flash-image-preview",
       },
@@ -115,6 +122,44 @@ describe("resolveProviderFromConnection native web search selection", () => {
   });
 });
 
+describe("resolveProviderFromConnection connection cache TTL", () => {
+  beforeEach(() => {
+    adapterCalls.length = 0;
+    clearConnectionProviderCache();
+    setSystemTime(new Date("2026-01-01T00:00:00Z"));
+  });
+
+  afterEach(() => {
+    // Restore the real clock so later suites are not frozen.
+    setSystemTime();
+  });
+
+  test("serves a cached provider within the TTL, re-resolves after it expires", async () => {
+    // First resolution: a cache miss builds an adapter.
+    await resolveProviderFromConnection(openRouterConnection, makeConfig(), {
+      model: "anthropic/claude-opus-4-7",
+    });
+    expect(adapterCalls).toHaveLength(1);
+
+    // A second resolution 59s later is a cache hit — no new adapter, so the
+    // baked-in credential is reused.
+    setSystemTime(new Date("2026-01-01T00:00:59Z"));
+    await resolveProviderFromConnection(openRouterConnection, makeConfig(), {
+      model: "anthropic/claude-opus-4-7",
+    });
+    expect(adapterCalls).toHaveLength(1);
+
+    // Past the 60s TTL the entry is stale: the next resolution re-reads the
+    // credential and rebuilds the adapter, so a key rotated out-of-band is
+    // picked up without any explicit cache invalidation.
+    setSystemTime(new Date("2026-01-01T00:01:01Z"));
+    await resolveProviderFromConnection(openRouterConnection, makeConfig(), {
+      model: "anthropic/claude-opus-4-7",
+    });
+    expect(adapterCalls).toHaveLength(2);
+  });
+});
+
 describe("isNativeWebSearchCapableProvider gateway anthropic routing", () => {
   test("vercel-ai-gateway anthropic/* models are capable", () => {
     expect(

package/src/providers/anthropic/client.ts

@@ -1790,8 +1790,8 @@ export class AnthropicProvider implements Provider {
               ),
           );
 
-        // Preserve assistant turns that would otherwise become empty after filtering
-        // unknown block types (e.g. ui_surface). Dropping these messages can violate
+        // Preserve assistant turns that would otherwise become empty after
+        // filtering unknown block types. Dropping these messages can violate
         // Anthropic's role alternation requirement.
         if (
           content.length === 0 &&
@@ -1940,10 +1940,13 @@ export class AnthropicProvider implements Provider {
   }
 
   /**
-   * Convert a content block to Anthropic format, returning null for unknown
-   * block types instead of throwing.  Unknown types (e.g. ui_surface stored
-   * in DB) are silently dropped so they don't prevent the request from being
-   * sent or break tool_use/tool_result pairing.
+   * Convert a content block to Anthropic format, returning null for blocks the
+   * Messages API cannot carry instead of throwing, so they don't prevent the
+   * request from being sent or break tool_use/tool_result pairing.
+   *
+   * Two distinct null cases: `ui_surface` is a known client-rendering block
+   * dropped by design, while a block reaching `default` is genuinely
+   * unrecognised and warns so the gap is visible.
    */
   private toAnthropicBlockSafe(
     block: ContentBlock,
@@ -2086,6 +2089,12 @@ export class AnthropicProvider implements Provider {
           tool_use_id: block.tool_use_id,
           content: block.content,
         } as unknown as Anthropic.ContentBlockParam;
+      case "ui_surface":
+        // A client rendering instruction, not model context. Dropped by
+        // design: the producer's sibling `_surfaceFallback` text block is what
+        // the model reads. `buildSentMessages` projects the surface to text
+        // for legacy rows that have no fallback sibling.
+        return null;
       default: {
         log.warn(
           { blockType: (block as { type: string }).type },