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

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 {
@@ -428,7 +432,7 @@ describe("wakeAgentForOpportunity", () => {
     expect(target.runCalls).toHaveLength(0);
   });
 
-  test("threads cleanup-mode injection context for explicit local-owner wakes", async () => {
+  test("builds a guardian turn context for explicit local-owner cleanup-mode wakes", async () => {
     mockDiskPressureStatus = {
       enabled: true,
       state: "critical",
@@ -459,11 +463,11 @@ describe("wakeAgentForOpportunity", () => {
 
     expect(result).toEqual({ invoked: true, producedToolCalls: false });
     expect(target.runCalls).toHaveLength(1);
-    expect(target.runCalls[0]!.turnContext).toMatchObject({
+    expect(target.runCalls[0]!.turnContext).toEqual({
+      requestId: "wake:local-cleanup",
       conversationId: target.conversationId,
-      injectionInputs: {
-        diskPressureContext: { cleanupModeActive: true },
-      },
+      turnIndex: 0,
+      trust: { sourceChannel: "vellum", trustClass: "guardian" },
     });
   });
 
@@ -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/__tests__/interactive-ui.test.ts

@@ -50,7 +50,7 @@ let surfaceCalls: Array<{
   surfaceId: string;
 }> = [];
 
-mock.module("../../daemon/conversation-store.js", () => ({
+mock.module("../../daemon/conversation-registry.js", () => ({
   findConversation: (_conversationId: string) => {
     return mockConversation ?? undefined;
   },

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`.
@@ -432,9 +432,6 @@ function buildWakeTurnContext(
         sourceChannel: opts.sourceChannel ?? "vellum",
         trustClass: "guardian",
       } satisfies TrustContext),
-    injectionInputs: {
-      diskPressureContext: { cleanupModeActive: true },
-    },
   };
 }
 
@@ -963,7 +960,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`

package/src/runtime/assistant-event-hub.ts

@@ -43,7 +43,7 @@ import { appendEventToStream } from "../signals/event-stream.js";
 import { getLogger } from "../util/logger.js";
 import type { AssistantEvent } from "./assistant-event.js";
 import { buildAssistantEvent } from "./assistant-event.js";
-import { stampAndBuffer } from "./conversation-stream-state.js";
+import { stampAndBuffer } from "./assistant-stream-state.js";
 
 const log = getLogger("assistant-event-hub");
 
@@ -64,6 +64,13 @@ export interface AssistantEventSubscription {
   dispose(): void;
   /** True until `dispose()` has been called. */
   readonly active: boolean;
+  /**
+   * Per-connection identifier, unique within the hub instance. Distinguishes
+   * connections that share a `clientId` (e.g. an old connection and the new
+   * one that replaced it on reconnect) so subscribe / dispose / shed log
+   * lines can be attributed to a specific connection.
+   */
+  readonly connectionId: string;
 }
 
 // ── Subscriber entries (discriminated union) ─────────────────────────────────
@@ -75,6 +82,13 @@ interface BaseSubscriberEntry {
   onEvict: () => void;
   connectedAt: Date;
   lastActiveAt: Date;
+  /**
+   * Per-connection identifier, unique within the hub instance. Two entries
+   * with the same `clientId` (old vs reconnected connection) get distinct
+   * connection ids, making them traceable across subscribe / dispose / shed
+   * logs.
+   */
+  connectionId: string;
 }
 
 interface ClientEntry extends BaseSubscriberEntry {
@@ -106,10 +120,15 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
   ? Omit<T, K>
   : never;
 
-/** Input shape for `subscribe()` — hub fills `active`, `connectedAt`, `lastActiveAt` and defaults `filter`/`onEvict`. */
+/** Input shape for `subscribe()` — hub fills `active`, `connectedAt`, `lastActiveAt`, `connectionId` and defaults `filter`/`onEvict`. */
 type SubscriberInput = DistributiveOmit<
   SubscriberEntry,
-  "active" | "connectedAt" | "lastActiveAt" | "filter" | "onEvict"
+  | "active"
+  | "connectedAt"
+  | "lastActiveAt"
+  | "filter"
+  | "onEvict"
+  | "connectionId"
 > & {
   filter?: AssistantEventFilter;
   onEvict?: () => void;
@@ -132,6 +151,8 @@ type SubscriberInput = DistributiveOmit<
 export class AssistantEventHub {
   private readonly subscribers = new Set<SubscriberEntry>();
   private readonly maxSubscribers: number;
+  /** Monotonic source for per-connection ids, scoped to this hub. */
+  private connectionCounter = 0;
 
   constructor(options?: { maxSubscribers?: number }) {
     this.maxSubscribers = options?.maxSubscribers ?? Infinity;
@@ -173,7 +194,11 @@ export class AssistantEventHub {
       }
       if (stale.length > 0) {
         log.info(
-          { clientId: subscriber.clientId, count: stale.length },
+          {
+            clientId: subscriber.clientId,
+            count: stale.length,
+            disposedConnectionIds: stale.map((entry) => entry.connectionId),
+          },
           "disposed stale subscribers for reconnecting client",
         );
       }
@@ -196,6 +221,7 @@ export class AssistantEventHub {
     }
 
     const now = new Date();
+    const connectionId = `conn-${++this.connectionCounter}`;
     const entry: SubscriberEntry = {
       ...subscriber,
       filter: subscriber.filter ?? {},
@@ -203,6 +229,7 @@ export class AssistantEventHub {
       active: true,
       connectedAt: now,
       lastActiveAt: now,
+      connectionId,
     } as SubscriberEntry;
 
     if (entry.type === "client") {
@@ -211,11 +238,12 @@ export class AssistantEventHub {
           clientId: entry.clientId,
           interfaceId: entry.interfaceId,
           capabilities: entry.capabilities,
+          connectionId,
         },
         "subscriber registered (client)",
       );
     } else {
-      log.info("subscriber registered (process)");
+      log.info({ connectionId }, "subscriber registered (process)");
     }
 
     this.subscribers.add(entry);
@@ -230,17 +258,19 @@ export class AssistantEventHub {
               {
                 clientId: entry.clientId,
                 interfaceId: entry.interfaceId,
+                connectionId,
               },
               "subscriber unregistered (client)",
             );
           } else {
-            log.info("subscriber unregistered (process)");
+            log.info({ connectionId }, "subscriber unregistered (process)");
           }
         }
       },
       get active() {
         return entry.active;
       },
+      connectionId,
     };
   }
 
@@ -678,7 +708,7 @@ async function createCanonicalRequestForConfirmation(
       { DAEMON_INTERNAL_ASSISTANT_ID },
       { bridgeConfirmationRequestToGuardian },
     ] = await Promise.all([
-      import("../daemon/conversation-store.js"),
+      import("../daemon/conversation-registry.js"),
       import("../memory/canonical-guardian-store.js"),
       import("../security/secret-scanner.js"),
       import("../tools/tool-input-summary.js"),