@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/plugins/user-loader.ts

@@ -1,39 +1,23 @@
 /**
- * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` via
- * one of two paths, gated by the contents of each candidate directory.
+ * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
+ * registers each one.
  *
- * **External plugin framework path** (`package.json` present **and** no
- * `register.{ts,js}`): the harness delegates to {@link loadExternalPlugin},
- * which builds a `Plugin` from the directory's interface dirs (`hooks/`,
- * `tools/`) and registers it directly. This path is opt-in by the plugin
- * author and currently experimental — see
- * `assistant/src/plugins/external-plugin-loader.ts` for the full
- * convention.
- *
- * **Legacy path** (`register.{ts,js}` present): the file is dynamic-imported
- * and expected to call {@link registerPlugin} at import time as a side
- * effect, populating the registry before {@link bootstrapPlugins} runs.
- *
- * The legacy path takes precedence when a directory contains both
- * `package.json` and `register.{ts,js}` — a migration-friendly default
- * that keeps existing plugins (including the in-repo `examples/plugins/echo`
- * reference) working unchanged while we iterate the external-plugin
- * convention. A directory matching neither path is skipped silently.
+ * A plugin directory is recognized by a `package.json` manifest. The harness
+ * delegates to {@link loadExternalPlugin}, which builds a `Plugin` from the
+ * directory's interface dirs (`hooks/`, `tools/`) and registers it directly.
+ * The full convention lives in
+ * `assistant/src/plugins/external-plugin-loader.ts`. A directory with no
+ * `package.json` is skipped silently.
  *
  * The loader deliberately:
  *
  * - Uses `getWorkspaceDir()` so each instance loads its own plugin set
  *   when `VELLUM_WORKSPACE_DIR` is set.
- * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics).
- *   The external loader applies the same rule per surface file; the
- *   legacy path picks between `register.js` and `register.ts`.
+ * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics);
+ *   the rule is applied by {@link loadExternalPlugin}.
  * - Treats any error from a plugin load as a per-plugin isolation
- *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout;
- *   the legacy path is wrapped here. One bad user plugin must not crash
- *   the daemon.
- * - Bounds each plugin load with {@link USER_PLUGIN_IMPORT_TIMEOUT_MS}
- *   so a plugin whose top-level `await` hangs or whose module evaluation
- *   never resolves cannot stall daemon startup.
+ *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout, so
+ *   one bad user plugin must not crash the daemon.
  *
  * Call order relative to the rest of the plugin system:
  *
@@ -46,7 +30,6 @@
 
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspacePluginsDir } from "../util/platform.js";
@@ -57,27 +40,24 @@ import { closeRegistration } from "./registry.js";
 const log = getLogger("user-plugin-loader");
 
 /**
- * Upper bound on how long a single user plugin's dynamic `import()` may take.
- * A plugin with a hanging top-level `await` (or a never-resolving module
- * evaluation) would otherwise block daemon startup indefinitely, since a raw
- * `try/catch` only isolates thrown errors — not hung promises. Ten seconds is
- * generous relative to a typical side-effect registration (milliseconds) and
- * matches the per-plugin isolation contract: slow plugins get skipped the
- * same way thrown-error plugins do.
+ * Upper bound on how long a single user plugin's load may take. A plugin with
+ * a hanging top-level `await` (or a never-resolving module evaluation) would
+ * otherwise block daemon startup indefinitely. Ten seconds is generous
+ * relative to a typical plugin load (milliseconds) and matches the per-plugin
+ * isolation contract: slow plugins get skipped the same way thrown-error
+ * plugins do. Enforced by {@link loadExternalPlugin}.
  */
 const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 
 /**
- * Scan `getWorkspaceDir()/plugins/` for subdirectories, then dispatch each
- * one to the external loader (if `package.json` is present and there is no
- * `register.{ts,js}`) or the legacy side-effect importer (if
- * `register.{ts,js}` is present).
+ * Scan `getWorkspaceDir()/plugins/` for subdirectories and dispatch each one
+ * that carries a `package.json` to {@link loadExternalPlugin}.
  *
  * Invariants:
  *
  * - No-ops when `getWorkspaceDir()/plugins/` does not exist — a clean install with
  *   zero user plugins must not generate errors.
- * - Per-plugin isolation: a failing import is logged and skipped. The
+ * - Per-plugin isolation: a failing load is logged and skipped. The
  *   function resolves normally even when every plugin fails to load.
  * - Does not return plugin instances. The registry is the single source of
  *   truth for who got registered, and the caller inspects it directly.
@@ -86,7 +66,7 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
  *
  * - Must be invoked exactly once during daemon startup, before
  *   `bootstrapPlugins()` walks the registry.
- * - Holds no locks during the import — bun's dynamic `import()` resolution
+ * - Holds no locks during the load — bun's dynamic `import()` resolution
  *   is concurrency-safe.
  */
 export async function loadUserPlugins(
@@ -151,96 +131,19 @@ export async function loadUserPlugins(
     }
     if (!stats.isDirectory()) continue;
 
-    // Path selection: the legacy side-effect path takes precedence when
-    // both a `register.{ts,js}` and a `package.json` are present.
-    // Migration-friendly: any plugin in the wild today that happens to
-    // ship a `package.json` keeps loading via its existing register entry.
-    // The external-plugin path only fires when the directory is
-    // unambiguously the new convention.
-    const jsPath = join(pluginDir, "register.js");
-    const tsPath = join(pluginDir, "register.ts");
-    let registerPath: string | undefined;
-    if (existsSync(jsPath)) {
-      registerPath = jsPath;
-    } else if (existsSync(tsPath)) {
-      registerPath = tsPath;
-    }
-
-    if (registerPath === undefined) {
-      // External plugin framework path. `loadExternalPlugin` owns its own
-      // try/catch + timeout, so a `continue` is the entire branch here.
-      if (existsSync(join(pluginDir, "package.json"))) {
-        await loadExternalPlugin(pluginDir, { importTimeoutMs });
-        continue;
-      }
-      log.debug(
-        { pluginDir },
-        "loadUserPlugins: no register.{ts,js} or package.json — skipping",
-      );
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      log.debug({ pluginDir }, "loadUserPlugins: no package.json — skipping");
       continue;
     }
 
-    // Legacy side-effect import path. `import()` with a `file://` URL
-    // works identically under Node and bun and sidesteps platform-specific
-    // absolute-path quirks on Windows.
-    const moduleUrl = pathToFileURL(registerPath).href;
-    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-    try {
-      // Race the import against a timeout so a plugin with a hanging top-level
-      // await or never-resolving module evaluation cannot stall daemon startup.
-      // The per-plugin try/catch already handles thrown errors; this extends
-      // the isolation boundary to cover hung promises as well.
-      const timeoutSentinel = Symbol("user-plugin-import-timeout");
-      const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
-        timeoutHandle = setTimeout(
-          () => resolve(timeoutSentinel),
-          importTimeoutMs,
-        );
-      });
-      // Retain the import promise so we can attach a terminal `.catch` on the
-      // timeout branch. `Promise.race` does not cancel the losing promise —
-      // the module evaluation keeps running in the background even after we
-      // stop awaiting it, and if it eventually throws (either from the
-      // module body or from the late `registerPlugin()` hitting a closed
-      // registry) an unhandled rejection would crash the daemon.
-      const importPromise = import(moduleUrl);
-      const result = await Promise.race([importPromise, timeoutPromise]);
-      if (result === timeoutSentinel) {
-        importPromise.catch(() => {
-          // Abandoned import completed (or threw) after the timeout. The
-          // closed-registration latch in registry.ts guarantees any late
-          // `registerPlugin()` call is rejected, so swallowing the outcome
-          // here is the safe default.
-        });
-        log.warn(
-          { pluginDir, registerPath, timeoutMs: importTimeoutMs },
-          `Timed out loading user plugin ${pluginDir} after ${importTimeoutMs}ms — skipping`,
-        );
-      } else {
-        log.info(
-          { pluginDir, registerPath },
-          "loaded user plugin (side-effect import completed)",
-        );
-      }
-    } catch (err) {
-      // One plugin's failure must never prevent other plugins from loading
-      // or crash the daemon. Log with the directory name so operators can
-      // find the broken plugin quickly.
-      const message = err instanceof Error ? err.message : String(err);
-      log.error(
-        { err, pluginDir },
-        `Failed to load user plugin ${pluginDir}: ${message}`,
-      );
-    } finally {
-      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
-    }
+    // `loadExternalPlugin` owns its own try/catch + timeout, so a bare
+    // `await` is the entire branch here.
+    await loadExternalPlugin(pluginDir, { importTimeoutMs });
   }
 
   // Close the registration window once every candidate plugin has been
-  // awaited (or timed out). The per-plugin try/catch guarantees no throw
-  // escapes the loop, so this line always runs. Any abandoned import that
-  // later resolves and reaches `registerPlugin()` is rejected by the latch,
-  // preserving the `bootstrapPlugins()` invariant that the registry is
-  // fully populated before it is walked.
+  // awaited (or timed out). The per-plugin try/catch inside
+  // `loadExternalPlugin` guarantees no throw escapes the loop, so this line
+  // always runs and `bootstrapPlugins()` sees a fully populated registry.
   closeRegistration();
 }

package/src/proactive-artifact/aux-message-injector.ts

@@ -7,7 +7,7 @@
  */
 
 import { createAssistantMessage } from "../agent/message-types.js";
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import {
   conversationMessagesSyncTag,
   SYNC_TAGS,
@@ -24,7 +24,7 @@ async function waitForIdle(conversationId: string): Promise<boolean> {
   const start = Date.now();
   while (Date.now() - start < IDLE_TIMEOUT_MS) {
     const conv = findConversation(conversationId);
-    if (!conv || !conv.processing) return true;
+    if (!conv || !conv.isProcessing()) return true;
     await new Promise((resolve) => setTimeout(resolve, IDLE_POLL_MS));
   }
   return false;
@@ -36,7 +36,7 @@ export async function injectAuxAssistantMessage(params: {
   broadcastMessage: BroadcastFn;
 }): Promise<void> {
   const conv = findConversation(params.conversationId);
-  if (conv?.processing) {
+  if (conv?.isProcessing()) {
     const reachedIdle = await waitForIdle(params.conversationId);
     if (!reachedIdle) {
       log.warn(
@@ -54,7 +54,7 @@ export async function injectAuxAssistantMessage(params: {
   );
 
   const current = findConversation(params.conversationId);
-  if (current && !current.processing) {
+  if (current && !current.isProcessing()) {
     current.getMessages().push(createAssistantMessage(params.text));
 
     params.broadcastMessage({

package/src/proactive-artifact/job.test.ts

@@ -190,13 +190,13 @@ mock.module("../runtime/sync/resource-sync-events.js", () => ({
 
 // findConversation mock
 type MockConversation = {
-  processing: boolean;
+  isProcessing(): boolean;
   messages: unknown[];
   getMessages: () => unknown[];
 };
 let mockConversations: Map<string, MockConversation> = new Map();
 
-mock.module("../daemon/conversation-store.js", () => ({
+mock.module("../daemon/conversation-registry.js", () => ({
   findConversation: (id: string) => mockConversations.get(id),
 }));
 
@@ -426,7 +426,7 @@ describe("runProactiveArtifactJob", () => {
       // Set up an idle conversation so injection works fully
       const convMessages: unknown[] = [];
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: convMessages,
         getMessages: () => convMessages,
       });
@@ -510,7 +510,7 @@ describe("runProactiveArtifactJob", () => {
         "MESSAGE: I created a monthly budget guide tailored to your needs.";
 
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: [],
         getMessages: () => [],
       });
@@ -646,7 +646,7 @@ describe("runProactiveArtifactJob", () => {
       ];
 
       mockConversations.set("conv-1", {
-        processing: false,
+        isProcessing: () => false,
         messages: [],
         getMessages: () => [],
       });
@@ -710,7 +710,7 @@ describe("injectAuxAssistantMessage", () => {
   test("idle conversation: persists with skipIndexing, pushes to getMessages(), broadcasts delta + complete(aux) + list sync", async () => {
     const messages: unknown[] = [];
     mockConversations.set("conv-inject-1", {
-      processing: false,
+      isProcessing: () => false,
       messages,
       getMessages: () => messages,
     });
@@ -767,12 +767,7 @@ describe("injectAuxAssistantMessage", () => {
     const messages: unknown[] = [];
     let processingFlag = true;
     const conv: MockConversation = {
-      get processing() {
-        return processingFlag;
-      },
-      set processing(v: boolean) {
-        processingFlag = v;
-      },
+      isProcessing: () => processingFlag,
       messages,
       getMessages: () => messages,
     };
@@ -801,7 +796,7 @@ describe("injectAuxAssistantMessage", () => {
     const messages: unknown[] = [];
     // Conversation stays processing permanently — never becomes idle
     const conv: MockConversation = {
-      processing: true,
+      isProcessing: () => true,
       messages,
       getMessages: () => messages,
     };

package/src/prompts/__tests__/system-prompt.test.ts

@@ -114,3 +114,45 @@ describe("maybeReseedBootstrap — content-automation template", () => {
     expect(content).toContain("VOICE.md");
   });
 });
+
+describe("maybeReseedBootstrap — activation rail template", () => {
+  const templatesDir = join(import.meta.dirname!, "..", "templates");
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    copyFileSync(
+      join(templatesDir, "BOOTSTRAP.md"),
+      join(TEST_DIR, "BOOTSTRAP.md"),
+    );
+  });
+
+  test("replaces generic bootstrap with the activation rail template", () => {
+    maybeReseedBootstrap("BOOTSTRAP-ACTIVATION-RAIL.md");
+    const content = readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
+
+    expect(content).toContain("BOOTSTRAP — Activation Rail");
+    expect(content).toContain("People don't read");
+    expect(content).toContain("Speed wins");
+
+    // Propose: anti-speculation boundary on what "unstated" means.
+    expect(content).toContain("status word");
+    expect(content).toContain("don't say it");
+
+    // Propose: infer-first framing — recommendation bound to the click.
+    expect(content).toContain("You didn't say this");
+    expect(content).toContain("the recommendation IS the click");
+
+    // Propose: a surviving extract-and-offer mechanic.
+    expect(content).toContain("clickable component, strongest first");
+
+    // Propose: the extract-shape vs infer-shape example block.
+    expect(content).toContain("extract-shape");
+    expect(content).toContain("infer-shape");
+
+    // Port: prompt-writing guidance (JARVIS-1124).
+    expect(content).toContain("portable context brief, not a self-summary");
+    expect(content).toContain("load-bearing work in the next month");
+    expect(content).toContain("what to help with first");
+    expect(content).toContain("another tool or collaborator");
+  });
+});

package/src/prompts/templates/BOOTSTRAP-ACTIVATION-RAIL.md

@@ -0,0 +1,64 @@
+_Replaces BOOTSTRAP.md for users in cohort experiment-activation-flow-2026-06-03._ _Same delete-on-wrap lifecycle as BOOTSTRAP.md._
+
+# BOOTSTRAP — Activation Rail
+
+The user just finished pre-chat. You know their name and vibe; maybe their Google. Your job in this conversation is to get them to a real first-run. Something they actually use, not a demo.
+
+## The shape
+
+Four moves. Goals, not steps.
+
+**Port.** Pull their existing assistant context with two pastes. About a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
+
+The prompt asks for a portable context brief, not a self-summary. Anchor it to load-bearing work in the next month or so, ask for specifics over generalities, and request a prioritized "what to help with first" so Propose has something to point at. Frame the destination as another tool or collaborator. Do not frame it as "I'm switching," which triggers ceremonial farewell-shaped responses from the source assistant. Tell them to use names, dates, real examples, and to say "not much here" rather than fill space.
+
+The prompt itself must be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
+
+**Propose.** Don't organize what they already told you — infer what they didn't. Name the unstated thing sitting in their context and say *why* you think it: point at the specific surface that made you say it. "You didn't say this, but —". Then recommend, and lean one way; the recommendation IS the click, not a neutral menu of equally-weighted options.
+
+"Unstated" is inference, not invention. Read only three surfaces, each a positive signal you can point at in the paste: dates / recency / time gaps; entities that recur (people, projects, accounts named more than once); and status words ("stuck", "behind", "waiting on", "still"). If you can't point to the surface that made you say it, don't say it — no free-speculating about goals, feelings, or facts that aren't traceable to the paste, and no "you didn't mention X" absence-inference.
+
+Surface the outcome as a clickable component, strongest first. The component is the question — don't follow it with a prose "or something else?" Pick from skills you already have loaded first; fall back to `vellum-skills-catalog` `skill_search` for what's missing. Compose the offer in their language, not in skill names.
+
+- ✗ extract-shape: "I see three meetings in your paste — want help with one?"
+- ✓ infer-shape (dates/recency): "Two of these are with the same client and the last was 3 weeks ago — looks stalled; I'd send a re-engage note." (The recommendation lands as the clickable surface — no trailing "want me to?")
+- ✗ extract-shape: "You mentioned a launch and a hiring plan — which one?"
+- ✓ infer-shape (repeated entity + status word): "Acme comes up four times and you said you're 'waiting on' them — that's the thing actually blocking the launch; I'd chase it first."
+
+**Run.** Do it. Real tools, real data. The user watches something happen.
+
+**Follow-through.** Offer the next concrete thing. One primary recommendation.
+
+If the user opens with a task instead of a conversation, do the task. You're already at Follow-through. Backfill the Port move at the first natural lull, or skip it.
+
+Pick. Be wrong recoverably. Move. The user can tell when you're hedging.
+
+## People don't read
+
+Brevity is the product. Lead with the move, not the rationale for the move. If the rationale takes more than one short sentence, cut it. Meta-narration about what you're trying to do ("I want to make this useful...") is rationale. Cut it harder.
+
+One CTA per turn. If your CTA is a clickable surface, don't follow it with a prose "or..." / "unless..." / "is there something else?" — the surface IS the menu. Open-ended questions after a structured offer are the most common version of a stacked CTA.
+
+No hedging the offer. Not "worth doing if you have history to bring." Make the move and let them say no.
+
+If an action requires the user to type a path or remember a string, the affordance is wrong. Move it inside a surface they can click.
+
+Every CTA surface must commit on the surface. If the user can select but can't confirm, the surface is broken. "They can just type a reply" doesn't count. Either selecting must commit the choice on click, or there must be a visible submit button below the options. The most common version of this bug: a radio or checkbox list with nothing clickable underneath.
+
+## Feeling seen
+
+The summary after the Port move is the first place the user can feel like you actually heard them. The follow-through in the final move is the second. In both, the bar is the same surface-grounded inference Propose already runs: notice what they hedged, point at the mechanism behind what they described, reframe what they're really asking for. Specific observations earn the rest of the conversation. Generic recap loses it.
+
+## What to defer
+
+Identity writes (IDENTITY.md, SOUL.md), user-profile writes, journal entries: all wait until the rail produces real signal, which is Moment 1 output at the earliest. None of them delay a user-visible response. None of them happen alongside the opening turn.
+
+The base BOOTSTRAP task_preferences fallback is not on this rail. Your opener is the Port pitch.
+
+## Wrap
+
+When the user is clearly done with this conversation, write one journal entry: what they needed, which outcome they accepted, what follow-through they took. Update NOW.md. Delete this file.
+
+The rail-completion shape in your journal is the dataset for v2 tuning. Which outcome they took at Propose, whether they bounced to "what else?", which follow-through they picked. Write it so the next iteration has signal to learn from.
+
+Speed wins until the rail produces real signal. Trust yourself.

package/src/prompts/templates/BOOTSTRAP.md

@@ -26,9 +26,9 @@ Private setup waits until there is enough signal to justify it. Low-signal bante
 
 ## Opening move
 
-The first message in your conversation context is a system trigger used to generate the canned greeting. Don't reference it, quote it, or respond to it as if the user said it.
+Some first conversations include an internal opener such as "Wake up, my friend!" only to generate the canned greeting. If you see that system trigger, don't reference it, quote it, or respond to it as if the user said it. If the first visible user turn is an onboarding self-introduction like "Hi <assistant>, I'm <user>. Nice to meet you.", treat it as the real first user turn: answer it briefly without re-introducing yourself, and if there is no task yet include the migration offer from `## Assistant migration`.
 
-If an `onboarding` JSON context is present, treat it as known — not as a briefing. Don't surface the selections as a list. Don't say "you mentioned" or "I see you use." Just apply the knowledge. Tools and tasks selected are context for how you respond, not content to recap. The canned first greeting already introduced you by name, so don't repeat introductions.
+If an `onboarding` JSON context is present, treat it as known — not as a briefing. Don't surface the selections as a list. Don't say "you mentioned" or "I see you use." Just apply the knowledge. Tools and tasks selected are context for how you respond, not content to recap. If the opener already introduced names, don't repeat introductions.
 
 If there's no onboarding context, pick a working name for yourself ("I'll go by Pax") and get to work. Their name can come up later, or never.
 

package/src/prompts/templates/system-sections.ts

@@ -230,6 +230,21 @@ export const BUNDLED_SYSTEM_SECTIONS: readonly BundledSection[] = [
     body: "",
     enabled: "!excludeCustomPrefix",
   },
+  {
+    id: "01-communication",
+    body: `## Communication
+
+Keep your reasoning, planning, and deliberation in your private thinking — never in user-facing text. A user-facing message is only ever: an optional one-line acknowledgement when starting longer work, the actual answer or question the user needs, and a single concise summary when you're done. 
+
+Keep reasoning and tool calls adjacent (think, call a tool, think, call a tool) with no user-facing prose between them, so one stream of work renders as one block. 
+
+Meet your user where they are. If they are nontechnical, prefer "Gmail needs reconnecting," not "the OAuth token expired". You can use more acronyms and industry-specific jargon if your user is a subject matter expert in the domain you are working together on. This applies for marketers, engineers, consultants, entrepreneurs, etc. 
+
+Err toward brevity; expand only when the user follows up or their style calls for more.
+
+These are default guidelines. Always prioritize communication preferences that you've established through your relationship with your human.
+`,
+  },
   {
     id: "01-parallel-tool-calls",
     body: `<use_parallel_tool_calls>

package/src/providers/anthropic/client.ts

@@ -5,6 +5,11 @@ import { ProviderError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
 import { extractRetryAfterMs } from "../../util/retry.js";
 import { stripOrphanedSurrogatesDeep } from "../../util/unicode.js";
+import {
+  isPlaceholderSentinelText,
+  PLACEHOLDER_BLOCKS_OMITTED,
+  PLACEHOLDER_EMPTY_TURN,
+} from "../placeholder-sentinels.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import type {
   ContentBlock,
@@ -161,33 +166,6 @@ function sanitizeToolId(id: string): string {
 const SYNTHETIC_RESULT =
   "<synthesized_result>tool result missing from history</synthesized_result>";
 
-// Null-byte prefix makes these placeholders impossible to produce via normal
-// model output or user input, preventing false positives in isPlaceholder().
-export const PLACEHOLDER_EMPTY_TURN =
-  "\x00__PLACEHOLDER__[empty assistant turn]";
-export const PLACEHOLDER_BLOCKS_OMITTED =
-  "\x00__PLACEHOLDER__[internal blocks omitted]";
-
-// Compared against the payload with any leading `\x00` stripped, so the check
-// matches both the prefixed sentinel we emit and any bare variant that lost
-// the null byte in transit (e.g. the model echoing the text back without
-// reproducing the control character).
-const PLACEHOLDER_SENTINEL_BARE: ReadonlySet<string> = new Set([
-  PLACEHOLDER_EMPTY_TURN.slice(1),
-  PLACEHOLDER_BLOCKS_OMITTED.slice(1),
-]);
-
-/**
- * True when the text is one of the provider's internal alternation-preserving
- * sentinels, with or without the null-byte prefix. These must never be
- * persisted or rendered to users — they exist only in outbound Anthropic API
- * request bodies.
- */
-export function isPlaceholderSentinelText(text: string): boolean {
-  const normalized = text.startsWith("\x00") ? text.slice(1) : text;
-  return PLACEHOLDER_SENTINEL_BARE.has(normalized);
-}
-
 /**
  * Synthetic placeholder injected as user-message content when Anthropic API
  * alternation requires a user turn but no real user content exists. Uses the
@@ -1230,6 +1208,23 @@ export class AnthropicProvider implements Provider {
         sentMessages = params.messages;
       }
 
+      // Haiku does not support the extended-cache-ttl beta, so it must never
+      // receive a `ttl` on any cache_control. The client's own breakpoints
+      // already omit it for Haiku, but callers (e.g. v3's `cachedTextBlock`)
+      // can stamp a `ttl` on message blocks before the provider sees them —
+      // strip it here so the request stays valid on Haiku models.
+      if (isHaiku) {
+        for (const msg of sentMessages) {
+          if (!Array.isArray(msg.content)) continue;
+          for (const block of msg.content) {
+            if (typeof block === "string") continue;
+            const cc = (block as { cache_control?: { ttl?: unknown } })
+              .cache_control;
+            if (cc && "ttl" in cc) delete cc.ttl;
+          }
+        }
+      }
+
       const { signal: timeoutSignal, cleanup: cleanupTimeout } =
         createStreamTimeout(this.streamTimeoutMs, signal);
       innerTimeoutSignal = timeoutSignal;
@@ -1650,8 +1645,21 @@ export class AnthropicProvider implements Provider {
     block: ContentBlock,
   ): Anthropic.ContentBlockParam | null {
     switch (block.type) {
-      case "text":
-        return { type: "text", text: block.text };
+      case "text": {
+        // Preserve a caller-stamped cache_control breakpoint (e.g. v3's
+        // `cachedTextBlock`, which marks a stable per-leaf / leaf-tree prefix
+        // that should be cached on its own rather than only as part of the
+        // per-turn anchor prefix). The internal ContentBlock type omits the
+        // field, so reach for it via cast. The Haiku ttl-strip downstream still
+        // applies. Only v3 stamps this today, so the per-request breakpoint
+        // budget (≤4) is unaffected for other callers.
+        const cacheControl = (
+          block as { cache_control?: Anthropic.CacheControlEphemeral }
+        ).cache_control;
+        return cacheControl
+          ? { type: "text", text: block.text, cache_control: cacheControl }
+          : { type: "text", text: block.text };
+      }
       case "thinking":
         if (!block.signature) {
           return null;