@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -190,7 +190,7 @@ mock.module("../runtime/sync/resource-sync-events.js", () => ({
 
 // findConversation mock
 type MockConversation = {
-  processing: boolean;
+  isProcessing(): boolean;
   messages: unknown[];
   getMessages: () => unknown[];
 };
@@ -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,39 @@ 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");
+  });
+});

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

@@ -0,0 +1,62 @@
+_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 should 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;

package/src/providers/openai/__tests__/chat-completions-provider-reasoning.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 
+import { isPlaceholderSentinelText } from "../../placeholder-sentinels.js";
 import {
+  EMPTY_ASSISTANT_TURN_PLACEHOLDER,
   OpenAIChatCompletionsProvider,
   type OpenAIChatCompletionsProviderOptions,
 } from "../chat-completions-provider.js";
@@ -348,6 +350,116 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
     expect(assistantMsg.reasoning_content).toBeUndefined();
   });
 
+  test("backfills placeholder content for a reasoning-only assistant turn when enabled", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      {
+        assistantReasoningField: "reasoning",
+        backfillEmptyAssistantContent: true,
+      },
+    );
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "question" }] },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "truncated chain of thought",
+            signature: "",
+          },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        content: string | null;
+        reasoning?: string;
+        tool_calls?: unknown;
+      }>;
+    };
+    const assistantMsg = params.messages.find((m) => m.role === "assistant")!;
+    // content or tool_calls must be set; reasoning alone does not satisfy it.
+    expect(assistantMsg.content).toBe(EMPTY_ASSISTANT_TURN_PLACEHOLDER);
+    expect(assistantMsg.tool_calls).toBeUndefined();
+    expect(assistantMsg.reasoning).toBe("truncated chain of thought");
+    // The placeholder is a recognized sentinel, so it is stripped from
+    // persisted/rendered history if a model echoes it back, and it carries no
+    // control characters that a strict OpenAI-compatible backend might reject.
+    expect(isPlaceholderSentinelText(EMPTY_ASSISTANT_TURN_PLACEHOLDER)).toBe(
+      true,
+    );
+    expect(EMPTY_ASSISTANT_TURN_PLACEHOLDER).not.toContain("\x00");
+  });
+
+  test("leaves reasoning-only assistant content null when backfill is disabled", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      { assistantReasoningField: "reasoning_content" },
+    );
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "question" }] },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "truncated chain of thought",
+            signature: "",
+          },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{ role: string; content: string | null }>;
+    };
+    const assistantMsg = params.messages.find((m) => m.role === "assistant")!;
+    // Backfill defaults off, so providers that tolerate null assistant content
+    // (e.g. OpenAI proper) are unaffected by the OpenRouter-specific guard.
+    expect(assistantMsg.content).toBeNull();
+  });
+
+  test("does not backfill content when tool calls are present", async () => {
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
+
+    await provider.sendMessage([
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "call_1", name: "search", input: { q: "x" } },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{ role: string; content: string | null }>;
+    };
+    // Tool-call-only assistant messages keep null content (preferred by
+    // Anthropic-proxy/Bedrock backends); the placeholder is only for the
+    // neither-content-nor-tool_calls case.
+    expect(params.messages[0].content).toBeNull();
+  });
+
   test("skips Anthropic-originated thinking blocks (with signatures)", async () => {
     const { provider, requests } = stubProvider(
       [

package/src/providers/openai/chat-completions-provider.ts

@@ -4,6 +4,7 @@ import { isAbortReason } from "../../util/abort-reasons.js";
 import { ProviderError } from "../../util/errors.js";
 import { extractRetryAfterMs } from "../../util/retry.js";
 import { escapeXmlAttr } from "../../util/xml.js";
+import { PLACEHOLDER_EMPTY_TURN } from "../placeholder-sentinels.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import type {
   ContentBlock,
@@ -100,6 +101,26 @@ export function extractApiErrorDetail(
  *  OpenRouter's `error.metadata.raw` strings, which are typically <1KB. */
 const MAX_API_ERROR_DETAIL_CHARS = 2000;
 
+/**
+ * Fallback `content` for an assistant turn that has neither visible text nor
+ * tool calls (e.g. a reasoning-only turn truncated at the output-token limit).
+ *
+ * The OpenAI chat-completions schema requires an assistant message to carry
+ * `content` or `tool_calls`. OpenAI itself tolerates `content: null`/`""` here,
+ * but strict OpenAI-compatible backends do not: DeepSeek via OpenRouter rejects
+ * the request with `Invalid assistant message: content or tool_calls must be
+ * set`, and vLLM-style validators coerce empty-string content back to null and
+ * reject it the same way. The placeholder must therefore be a non-empty string.
+ *
+ * We reuse the shared empty-turn sentinel so that
+ * `isPlaceholderSentinelText`/`cleanAssistantContent` strip it from persisted
+ * and rendered history if a model ever echoes it back. The null-byte prefix is
+ * dropped because some OpenAI-compatible backends reject control characters in
+ * message content; the bare form is still recognized by
+ * `isPlaceholderSentinelText`.
+ */
+export const EMPTY_ASSISTANT_TURN_PLACEHOLDER = PLACEHOLDER_EMPTY_TURN.slice(1);
+
 /**
  * Read the first matching header from an SDK error's headers object,
  * tolerating both Map-like (`Headers.get()`) and plain-object shapes.
@@ -153,6 +174,13 @@ export interface OpenAIChatCompletionsProviderOptions {
    *  DeepSeek/Fireworks use `"reasoning_content"`; OpenRouter uses `"reasoning"`.
    *  When unset, thinking blocks are dropped from outbound assistant messages. */
   assistantReasoningField?: "reasoning" | "reasoning_content";
+  /** Backfill a non-empty placeholder for assistant turns that would otherwise
+   *  serialize with neither `content` nor `tool_calls` (e.g. reasoning-only
+   *  turns). Off by default; enabled for OpenRouter, whose downstream providers
+   *  (e.g. DeepSeek) reject such messages with `Invalid assistant message:
+   *  content or tool_calls must be set`. See {@link
+   *  EMPTY_ASSISTANT_TURN_PLACEHOLDER}. */
+  backfillEmptyAssistantContent?: boolean;
 }
 
 /** Wire-level reasoning_effort values. The OpenAI SDK type doesn't include
@@ -228,6 +256,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
     | "reasoning"
     | "reasoning_content"
     | undefined;
+  private backfillEmptyAssistantContent: boolean;
 
   constructor(
     apiKey: string,
@@ -251,6 +280,8 @@ export class OpenAIChatCompletionsProvider implements Provider {
     this.requestHeaders = options.requestHeaders ?? {};
     this.parseThinkTags = options.parseThinkTags ?? false;
     this.assistantReasoningField = options.assistantReasoningField;
+    this.backfillEmptyAssistantContent =
+      options.backfillEmptyAssistantContent ?? false;
   }
 
   async sendMessage(
@@ -794,6 +825,19 @@ export class OpenAIChatCompletionsProvider implements Provider {
       result.tool_calls = toolCalls;
     }
 
+    // An assistant message must carry `content` or `tool_calls`. A turn with
+    // neither (e.g. reasoning-only) would serialize to null/empty content with
+    // no tool calls, which strict OpenAI-compatible backends reject. Reasoning
+    // lives in a separate field and does not satisfy this constraint. Scoped to
+    // providers that need it (OpenRouter) via `backfillEmptyAssistantContent`.
+    if (
+      this.backfillEmptyAssistantContent &&
+      !result.tool_calls &&
+      (result.content === null || result.content === "")
+    ) {
+      result.content = EMPTY_ASSISTANT_TURN_PLACEHOLDER;
+    }
+
     return result;
   }
 

package/src/providers/openrouter/client.ts

@@ -122,6 +122,7 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
       streamTimeoutMs: options.streamTimeoutMs,
       requestHeaders: OPENROUTER_APP_ATTRIBUTION_HEADERS,
       assistantReasoningField: "reasoning",
+      backfillEmptyAssistantContent: true,
     });
     this.openRouterApiKey = apiKey;
     this.defaultModel = model;

package/src/providers/placeholder-sentinels.ts

@@ -0,0 +1,35 @@
+// Internal placeholder sentinels injected as assistant-message content when a
+// turn would otherwise serialize with neither text nor tool calls. Provider
+// request bodies must keep a non-empty content slot (Anthropic to preserve
+// role alternation; strict OpenAI-compatible backends to satisfy the
+// "content or tool_calls must be set" constraint), but these markers must
+// never be persisted or rendered to users.
+//
+// The null-byte prefix makes the prefixed form impossible to produce via
+// normal model output or user input, preventing false positives. Some
+// OpenAI-compatible backends reject control characters in message content, so
+// the OpenAI path emits the bare (prefix-stripped) form, which
+// `isPlaceholderSentinelText` still recognizes.
+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 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 provider request bodies.
+ */
+export function isPlaceholderSentinelText(text: string): boolean {
+  const normalized = text.startsWith("\x00") ? text.slice(1) : text;
+  return PLACEHOLDER_SENTINEL_BARE.has(normalized);
+}

package/src/runtime/__tests__/agent-wake.test.ts

@@ -136,6 +136,10 @@ import {
 const runResult = (history: Message[]): AgentLoopRunResult => ({
   history,
   exitReason: null,
+  appendedNewMessages: true,
+  // The wake path slices its own new-message boundary off the returned
+  // history (it never destructures `newMessages`), so this is type-only.
+  newMessages: [],
 });
 
 interface MockTarget extends WakeTarget {
@@ -1077,7 +1081,7 @@ describe("wakeAgentForOpportunity", () => {
     expect(target.drainQueueCalls).toBe(1);
     // Critical ordering invariant: drain runs after processing=false.
     // If drain ran while processing was still true,
-    // `enqueueMessage`'s `if (!ctx.processing) return ...` gate would
+    // `enqueueMessage`'s `if (!ctx.isProcessing()) return ...` gate would
     // see processing=true and the drained item would itself just
     // re-enqueue — no progress. Snapshot the live flag *inside* drain
     // (rather than inferring from toggle order) so a future regression

package/src/runtime/agent-wake.ts

@@ -140,7 +140,7 @@ export interface WakeTarget {
    * The wake invokes this in its `finally` block AFTER
    * `markProcessing(false)`. Order matters: if drain ran while
    * processing was still true, `enqueueMessage`'s gate
-   * (`if (!ctx.processing) return ...`) would still see processing=true
+   * (`if (!ctx.isProcessing()) return ...`) would still see processing=true
    * and the drain itself would be a no-op against any racy late sends.
    * Running drain after processing is released matches the canonical
    * user-turn finally path in `conversation-agent-loop.ts`.
@@ -963,7 +963,7 @@ export async function wakeAgentForOpportunity(
 
       // Run completed cleanly. The canonical user-turn pattern
       // (conversation-agent-loop.ts:1860, 2106-2126) updates
-      // `ctx.messages` first, then resets `ctx.processing = false`, then
+      // `ctx.messages` first, then clears the flag via `ctx.setProcessing(false)`, then
       // calls `ctx.drainQueue(...)`. We mirror that order so a message
       // queued during the wake dequeues against an already-updated
       // history — otherwise `drainSingleMessage` reads `ctx.messages`