@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/providers/openai/__tests__/google-thought-signature.test.ts

@@ -7,7 +7,6 @@ import {
   attachGoogleThoughtSignature,
   attachGoogleThoughtSignatureIfNeeded,
   backfillGoogleThoughtSignatures,
-  backfillUnsignedGoogleThoughtSignatures,
   geminiThoughtSignaturesByToolCallId,
   googleThoughtSignatureFromUnknown,
   type GoogleToolCallExtraContent,
@@ -177,7 +176,7 @@ describe("thought signature params helpers", () => {
 
   test("backfills the dummy signature onto unsigned tool_calls", () => {
     const params = structuredClone(unsignedParams);
-    expect(backfillUnsignedGoogleThoughtSignatures(params)).toBe(true);
+    expect(backfillGoogleThoughtSignatures(params)).toBe(true);
     expect(messagesCarryGoogleThoughtSignature(params)).toBe(true);
     expect(
       params.messages[0].tool_calls[0].extra_content?.google?.thought_signature,

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

@@ -355,6 +355,41 @@ function protectJsonSchemaToolResult(payload: string): string {
     : payload;
 }
 
+function carriesReasoningOptOut(params: unknown): boolean {
+  const p = params as {
+    reasoning_effort?: unknown;
+    reasoning?: { effort?: unknown } | null;
+  };
+  return (
+    p.reasoning_effort === "none" ||
+    (typeof p.reasoning === "object" &&
+      p.reasoning !== null &&
+      p.reasoning.effort === "none")
+  );
+}
+
+function stripReasoningParams(params: unknown): void {
+  const p = params as Record<string, unknown>;
+  delete p.reasoning_effort;
+  delete p.reasoning;
+}
+
+/**
+ * `baseURL|model|routing` keys whose request succeeded on the attempt directly
+ * after the opt-out was stripped. Later requests skip the opt-out up front
+ * instead of paying a rejected round-trip on every call. A success that needed
+ * a further compat retry proves nothing about the opt-out, so it is not
+ * recorded. Routing (OpenRouter's `provider` body field) is part of the key
+ * because opt-out support belongs to the upstream backend, not the model slug.
+ * Process-lifetime only: a restart re-learns with one rejected request per key.
+ */
+const reasoningOptOutRejecters = new Set<string>();
+
+/** Test-only: forget learned reasoning opt-out rejections. */
+export function resetReasoningOptOutRejectersForTests(): void {
+  reasoningOptOutRejecters.clear();
+}
+
 /**
  * True when the request carried an explicit reasoning opt-out (`"none"` sent
  * as flat `reasoning_effort` or nested `reasoning.effort`) and the provider
@@ -364,16 +399,7 @@ function protectJsonSchemaToolResult(payload: string): string {
  * model-default reasoning beats a hard failure.
  */
 function isReasoningOptOutRejection(error: unknown, params: unknown): boolean {
-  const p = params as {
-    reasoning_effort?: unknown;
-    reasoning?: { effort?: unknown } | null;
-  };
-  const optedOut =
-    p.reasoning_effort === "none" ||
-    (typeof p.reasoning === "object" &&
-      p.reasoning !== null &&
-      p.reasoning.effort === "none");
-  if (!optedOut) {
+  if (!carriesReasoningOptOut(params)) {
     return false;
   }
   if (!isClientErrorStatus(error)) {
@@ -685,10 +711,7 @@ function classifyOpenAICompatRetry(
       kind: "reasoning-opt-out",
       message:
         "Model rejected the explicit reasoning opt-out; retrying without reasoning params",
-      apply: () => {
-        delete params.reasoning_effort;
-        delete (params as unknown as Record<string, unknown>).reasoning;
-      },
+      apply: () => stripReasoningParams(params),
     };
   }
   if (isThinkingModeToolChoiceRejection(error, params)) {
@@ -788,6 +811,24 @@ const OPENAI_SUPPORTED_IMAGE_TYPES = new Set([
   "image/webp",
 ]);
 
+/**
+ * Persistable view of the chat.completions create params. A `logit_bias`
+ * preset (e.g. `suppress-cjk`) is ~5.3k deterministic entries (~68KB);
+ * summarize it so inspector rows don't balloon. The full map still went
+ * out on the wire.
+ */
+function inspectableChatCompletionsRequest(
+  params: OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming,
+): unknown {
+  if (!params.logit_bias) {
+    return params;
+  }
+  return {
+    ...params,
+    logit_bias: `<${Object.keys(params.logit_bias).length} token biases omitted>`,
+  };
+}
+
 // Think-tag scanning primitives are shared with the TTS reasoning filter
 // (util/think-tag-stream.ts) so the two stream parsers cannot drift. This
 // provider keeps its exact historical behavior: case-sensitive, <think> only.
@@ -883,6 +924,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
     // wire, to be decoded back on the response. Empty unless
     // `coerceObjectArgsToJsonString` is enabled.
     const coercedObjectKeys = new Map<string, string[]>();
+    let inspectableRequest: unknown | undefined;
 
     try {
       const thoughtSignaturesByCallId =
@@ -1125,18 +1167,35 @@ export class OpenAIChatCompletionsProvider implements Provider {
         if (extraBody) {
           Object.assign(params, extraBody);
         }
-        const createStream = () =>
-          this.client.chat.completions.create(params, {
+        const optOutKey = `${this.client.baseURL}|${params.model}|${JSON.stringify(
+          (params as { provider?: unknown }).provider ?? null,
+        )}`;
+        if (
+          reasoningOptOutRejecters.has(optOutKey) &&
+          carriesReasoningOptOut(params)
+        ) {
+          stripReasoningParams(params);
+        }
+        const createStream = () => {
+          // Snapshot after extra-body merge and any in-place compat retries
+          // so inspector rows match the params that actually went on the wire.
+          inspectableRequest = inspectableChatCompletionsRequest(params);
+          return this.client.chat.completions.create(params, {
             signal: timeoutSignal,
             ...(Object.keys(requestHeaders).length > 0
               ? { headers: requestHeaders }
               : {}),
           });
+        };
         const attemptedCompatRetries = new Set<OpenAICompatRetryKind>();
+        let lastCompatRetry: OpenAICompatRetryKind | undefined;
         let stream: Awaited<ReturnType<typeof createStream>>;
         for (;;) {
           try {
             stream = await createStream();
+            if (lastCompatRetry === "reasoning-opt-out") {
+              reasoningOptOutRejecters.add(optOutKey);
+            }
             break;
           } catch (error) {
             const retry = classifyOpenAICompatRetry(
@@ -1148,6 +1207,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
               throw error;
             }
             attemptedCompatRetries.add(retry.kind);
+            lastCompatRetry = retry.kind;
             log.warn(
               {
                 provider: this.name,
@@ -1447,15 +1507,9 @@ export class OpenAIChatCompletionsProvider implements Provider {
         },
         stopReason: finishReason,
         // `rawRequest` is persisted to the request-log DB and inspector on every
-        // call. A `logit_bias` preset (e.g. `suppress-cjk`) is ~5.3k deterministic
-        // entries (~68KB); summarize it here so logs don't balloon. The full map
-        // still went out on the wire above.
-        rawRequest: params.logit_bias
-          ? {
-              ...params,
-              logit_bias: `<${Object.keys(params.logit_bias).length} token biases omitted>`,
-            }
-          : params,
+        // call, including 4xx throws below. A `logit_bias` preset is summarized
+        // so logs don't balloon. The full map still went out on the wire above.
+        rawRequest: inspectableRequest,
         rawResponse,
       };
     } catch (error) {
@@ -1482,6 +1536,9 @@ export class OpenAIChatCompletionsProvider implements Provider {
             maxTokens: overflow.maxTokens,
             statusCode: error.status,
             cause: error,
+            ...(inspectableRequest !== undefined
+              ? { rawRequest: inspectableRequest }
+              : {}),
           });
         }
         if (detectVisionNotSupported(error, normalized.message)) {
@@ -1492,9 +1549,13 @@ export class OpenAIChatCompletionsProvider implements Provider {
             error.status,
             // Stamp the reason so classification is status-independent (a vision
             // rejection returned as 401/403 must not read as an invalid key).
-            abortReason
-              ? { abortReason, reason: "vision_unsupported" }
-              : { reason: "vision_unsupported" },
+            {
+              reason: "vision_unsupported" as const,
+              ...(abortReason ? { abortReason } : {}),
+              ...(inspectableRequest !== undefined
+                ? { rawRequest: inspectableRequest }
+                : {}),
+            },
           );
         }
         const retryAfterMs = extractRetryAfterMs(error.headers);
@@ -1509,6 +1570,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
           apiErrorParam?: string;
           requestId?: string;
           rawBody?: string;
+          rawRequest?: unknown;
           reason?: ProviderErrorReason;
         } = { cause: error };
         if (retryAfterMs !== undefined) {
@@ -1535,6 +1597,9 @@ export class OpenAIChatCompletionsProvider implements Provider {
         if (normalized.reason) {
           errorOptions.reason = normalized.reason;
         }
+        if (inspectableRequest !== undefined) {
+          errorOptions.rawRequest = inspectableRequest;
+        }
         throw new ProviderError(
           formattedMessage,
           this.name,
@@ -1548,7 +1613,13 @@ export class OpenAIChatCompletionsProvider implements Provider {
         }`,
         this.name,
         undefined,
-        abortReason ? { cause: error, abortReason } : { cause: error },
+        {
+          cause: error,
+          ...(abortReason ? { abortReason } : {}),
+          ...(inspectableRequest !== undefined
+            ? { rawRequest: inspectableRequest }
+            : {}),
+        },
       );
     }
   }

package/src/providers/openai/google-thought-signature.ts

@@ -266,12 +266,6 @@ export function backfillGoogleThoughtSignatures(
   return added;
 }
 
-export function backfillUnsignedGoogleThoughtSignatures(
-  params: unknown,
-): boolean {
-  return backfillGoogleThoughtSignatures(params);
-}
-
 const UNKNOWN_EXTRA_CONTENT_REJECTION =
   /unknown|unexpected|unrecognized|additional propert|extra (?:field|property)|not (?:a )?valid|invalid (?:argument|parameter|field|property)/i;
 

package/src/providers/openai/responses-provider.ts

@@ -294,6 +294,7 @@ export class OpenAIResponsesProvider implements Provider {
       configObj.promptCacheKey.length > 0
         ? (configObj.promptCacheKey as string)
         : undefined;
+    let inspectableRequest: unknown | undefined;
 
     try {
       const effectiveModel = modelOverride ?? this.model;
@@ -428,6 +429,7 @@ export class OpenAIResponsesProvider implements Provider {
       }
 
       Object.assign(params, this.buildExtraCreateParams(options));
+      inspectableRequest = params;
 
       const { signal: timeoutSignal, cleanup: cleanupTimeout } =
         createStreamTimeout(this.streamTimeoutMs, signal);
@@ -736,6 +738,9 @@ export class OpenAIResponsesProvider implements Provider {
             maxTokens: overflow.maxTokens,
             statusCode: error.status,
             cause: error,
+            ...(inspectableRequest !== undefined
+              ? { rawRequest: inspectableRequest }
+              : {}),
           });
         }
         const retryAfterMs = extractRetryAfterMs(error.headers);
@@ -750,6 +755,7 @@ export class OpenAIResponsesProvider implements Provider {
           apiErrorParam?: string;
           requestId?: string;
           rawBody?: string;
+          rawRequest?: unknown;
           reason?: ProviderErrorReason;
         } = { cause: error };
         if (retryAfterMs !== undefined) {
@@ -776,6 +782,9 @@ export class OpenAIResponsesProvider implements Provider {
         if (normalized.reason) {
           errorOptions.reason = normalized.reason;
         }
+        if (inspectableRequest !== undefined) {
+          errorOptions.rawRequest = inspectableRequest;
+        }
         throw new ProviderError(
           formattedMessage,
           this.name,
@@ -789,7 +798,20 @@ export class OpenAIResponsesProvider implements Provider {
         }`,
         this.name,
         undefined,
-        abortReason ? { cause: error, abortReason } : { cause: error },
+        abortReason
+          ? {
+              cause: error,
+              abortReason,
+              ...(inspectableRequest !== undefined
+                ? { rawRequest: inspectableRequest }
+                : {}),
+            }
+          : {
+              cause: error,
+              ...(inspectableRequest !== undefined
+                ? { rawRequest: inspectableRequest }
+                : {}),
+            },
       );
     }
   }

package/src/providers/ratelimit.ts

@@ -62,9 +62,7 @@ export class RateLimitProvider implements Provider {
     // calls from bypassing the rate limit during the async gap.
     this.recordRequest();
 
-    const response = await this.inner.sendMessage(messages, options);
-
-    return response;
+    return this.inner.sendMessage(messages, options);
   }
 
   private enforceRequestRate(): void {

package/src/providers/search-provider-catalog.ts

@@ -163,6 +163,30 @@ export const SEARCH_PROVIDER_CATALOG: readonly SearchProviderCatalogEntry[] = [
     supportsApiBase: true,
     defaultApiBase: "https://api.fastcrw.com",
   },
+  {
+    id: "searxng",
+    displayName: "SearXNG",
+    kind: "byok",
+    keyless: true,
+    apiKeyPrefix: "token (optional)",
+    envVar: "SEARXNG_API_KEY",
+    secretKey: "searxng",
+    fallbackOrder: 7,
+    privacyPolicyUrl: "https://docs.searxng.org/own-instance.html",
+    supportsApiBase: true,
+  },
+  {
+    id: "tinyfish",
+    displayName: "TinyFish",
+    kind: "byok",
+    apiKeyPrefix: "TinyFish API key...",
+    envVar: "TINYFISH_API_KEY",
+    secretKey: "tinyfish",
+    fallbackOrder: 8,
+    privacyPolicyUrl: "https://www.tinyfish.ai/privacy-policy",
+    supportsApiBase: true,
+    defaultApiBase: "https://api.search.tinyfish.ai",
+  },
 ];
 
 /** Provider ids accepted by the web-search config schema. */

package/src/providers/speech-to-text/__tests__/deepgram-flux-frames.test.ts

@@ -129,6 +129,30 @@ describe("parseFluxFrame", () => {
     ]);
   });
 
+  test.each(["model", "timeout", "manual"])(
+    "retains the %s turn-end trigger and decoded audio position",
+    (trigger) => {
+      expect(
+        parseFluxFrame({ ...END_OF_TURN, trigger, audio_window_end: 12.5 })[1],
+      ).toMatchObject({
+        type: "turn-end",
+        confidence: 0.88,
+        trigger,
+        audioWindowEndSeconds: 12.5,
+      });
+    },
+  );
+
+  test("omits unknown triggers and malformed audio positions", () => {
+    expect(
+      parseFluxFrame({
+        ...END_OF_TURN,
+        trigger: "future-trigger",
+        audio_window_end: "invalid",
+      }),
+    ).toEqual(parseFluxFrame(END_OF_TURN));
+  });
+
   test("flat frames without a nested event field are accepted", () => {
     expect(parseFluxFrame({ type: "StartOfTurn" })).toEqual([
       { type: "turn-start" },

package/src/providers/speech-to-text/__tests__/deepgram-flux-realtime.test.ts

@@ -334,6 +334,7 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
           type: "turn-end",
           text: "what is the weather",
           confidence: 0.91,
+          audioWindowEndSeconds: 1.5,
           turnIndex: 0,
         },
       ]);
@@ -382,7 +383,12 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
       );
       expect(events).toEqual([
         { type: "final", text: "still here" },
-        { type: "turn-end", text: "still here", turnIndex: 0 },
+        {
+          type: "turn-end",
+          text: "still here",
+          turnIndex: 0,
+          audioWindowEndSeconds: 1.5,
+        },
       ]);
     });
   });

package/src/providers/speech-to-text/__tests__/vellum-managed-realtime.test.ts

@@ -8,6 +8,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { SttError, type SttStreamServerEvent } from "../../../stt/types.js";
+import { VellumManagedFluxRealtimeTranscriber } from "../vellum-managed-flux-realtime.js";
 import { VellumManagedRealtimeTranscriber } from "../vellum-managed-realtime.js";
 import type { SpeechRelayConnection } from "../vellum-speech-relay-connection.js";
 
@@ -99,7 +100,7 @@ const CONNECTION: SpeechRelayConnection = {
 
 const tick = () => new Promise<void>((r) => setTimeout(r, 0));
 
-describe("VellumManagedRealtimeTranscriber", () => {
+describe("Vellum managed realtime transcribers", () => {
   let sockets: MockWebSocket[];
   let originalWebSocket: unknown;
   let originalFetch: unknown;
@@ -262,6 +263,54 @@ describe("VellumManagedRealtimeTranscriber", () => {
     expect(new URL(sockets[1]!.url).searchParams.get("key")).toBe("vk-secret");
   });
 
+  test("Flux turn indices stay in one sequence across relay reconnects", async () => {
+    const adapter = new VellumManagedFluxRealtimeTranscriber(CONNECTION);
+    const { events, onEvent } = collector();
+    const started = adapter.start(onEvent);
+    sockets[0]!.simulateOpen();
+    await started;
+    try {
+      for (let generation = 0; generation < 3; generation += 1) {
+        const socket = sockets[generation]!;
+        const turnIndex = generation === 0 ? 5 : 0;
+        const startFrame = JSON.stringify({
+          type: "TurnInfo",
+          event: "StartOfTurn",
+          turn_index: turnIndex,
+        });
+        socket.simulateMessage(startFrame);
+        socket.simulateMessage(startFrame);
+        socket.simulateMessage(
+          JSON.stringify({
+            type: "TurnInfo",
+            event: "EndOfTurn",
+            // A later end without its start still advances the sequence.
+            turn_index: generation === 1 ? 2 : turnIndex,
+            transcript: "hello",
+          }),
+        );
+        if (generation < 2) {
+          socket.simulateMessage(velayErrorFrame("session_duration_exceeded"));
+          socket.simulateClose(1000, "session_duration_exceeded");
+          await tick();
+          sockets[generation + 1]!.simulateOpen();
+          await tick();
+        }
+      }
+      expect(
+        events.flatMap((event) =>
+          event.type === "turn-start" || event.type === "turn-end"
+            ? [event.turnIndex]
+            : [],
+        ),
+      ).toEqual([5, 5, 5, 6, 6, 8, 9, 9, 9]);
+      expect(events.some((event) => event.type === "closed")).toBe(false);
+    } finally {
+      adapter.stop();
+      sockets.at(-1)!.simulateClose();
+    }
+  });
+
   test("finalize during a re-dial settles immediately", async () => {
     const { adapter, events } = await startAdapter();
 

package/src/providers/speech-to-text/deepgram-flux-frames.ts

@@ -71,6 +71,7 @@ export interface FluxTurnFrame {
   transcript?: string;
   /** Flux's end-of-turn confidence in [0, 1]. */
   end_of_turn_confidence?: number;
+  trigger?: "model" | "manual" | "timeout";
 }
 
 /**
@@ -153,6 +154,8 @@ export function parseFluxFrame(raw: unknown): SttStreamServerEvent[] {
     case "EndOfTurn": {
       const text = readTranscript(frame);
       const confidence = readNumber(frame.end_of_turn_confidence);
+      const trigger = frame.trigger;
+      const audioWindowEndSeconds = readNumber(frame.audio_window_end);
       return [
         { type: "final", text },
         {
@@ -160,6 +163,14 @@ export function parseFluxFrame(raw: unknown): SttStreamServerEvent[] {
           text,
           ...(confidence !== undefined ? { confidence } : {}),
           ...(turnIndex !== undefined ? { turnIndex } : {}),
+          ...(trigger === "model" ||
+          trigger === "manual" ||
+          trigger === "timeout"
+            ? { trigger }
+            : {}),
+          ...(audioWindowEndSeconds !== undefined
+            ? { audioWindowEndSeconds }
+            : {}),
         },
       ];
     }

package/src/providers/speech-to-text/vellum-managed-flux-realtime.ts

@@ -79,6 +79,9 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
   private redialOnClose = false;
   private stopping = false;
   private closedEmitted = false;
+  // Consumers see one stream across relay reconnects, with one turn sequence.
+  private turnIndexOffset = 0;
+  private latestTurnIndex = -1;
 
   constructor(
     connection: SpeechRelayConnection,
@@ -225,6 +228,15 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
       return;
     }
 
+    if (
+      (event.type === "turn-start" || event.type === "turn-end") &&
+      event.turnIndex !== undefined
+    ) {
+      const turnIndex = this.turnIndexOffset + event.turnIndex;
+      this.latestTurnIndex = Math.max(this.latestTurnIndex, turnIndex);
+      this.emit({ ...event, turnIndex });
+      return;
+    }
     this.emit(event);
   }
 
@@ -236,6 +248,7 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
   private beginRedial(): void {
     log.info("Managed Flux relay session hit velay's duration cap, re-dialing");
     this.inner = null;
+    this.turnIndexOffset = this.latestTurnIndex + 1;
     void (async () => {
       try {
         const inner = await this.dial();

package/src/providers/types.ts

@@ -551,6 +551,8 @@ export interface ContextOverflowErrorOptions {
   cause?: unknown;
   /** Semantic reason override; defaults to `context_overflow`. */
   reason?: ProviderErrorReason;
+  /** Inspectable SDK/wire request payload for the overflowing call. */
+  rawRequest?: unknown;
 }
 
 /**
@@ -581,6 +583,9 @@ export class ContextOverflowError extends ProviderError {
     super(message, provider, options.statusCode ?? 400, {
       reason: options.reason ?? "context_overflow",
       ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      ...(options.rawRequest !== undefined
+        ? { rawRequest: options.rawRequest }
+        : {}),
     });
     this.name = "ContextOverflowError";
     this.actualTokens = options.actualTokens;

package/src/routes/control.ts

@@ -44,13 +44,15 @@ function routeHostPidPath(): string {
   return getProcPidPath(ROUTE_HOST_PROC_NAME);
 }
 
+const ROUTE_HOST_ENTRY = new URL("./worker.ts", import.meta.url);
+
 /**
  * Read the PID file and report liveness. A missing or malformed file reports
- * not_running; a file pointing at a dead process is cleaned up and reported as
- * not_running.
+ * not_running; a file pointing at a dead process, or at a live process that
+ * is not this worker, is cleaned up and reported as not_running.
  */
 export function probeRouteHostWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(routeHostPidPath());
+  return probeWorkerPidFile(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 export class RouteHostSpawnError extends WorkerProcessSpawnError {}
@@ -67,7 +69,7 @@ export async function spawnRouteHostWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: routeHostPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: ROUTE_HOST_ENTRY,
       packagedEntry: "routes",
       workerLabel: "Route host",
       options: opts,
@@ -86,7 +88,7 @@ export async function spawnRouteHostWorkerProcess(
  * (e.g. EPERM) — a not-running host is a no-op.
  */
 export function stopRouteHostWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(routeHostPidPath());
+  return stopWorkerProcess(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 /**

package/src/runtime/AGENTS.md

@@ -24,7 +24,7 @@ Queueing remains the fallback, not a legacy path, and every non-`released` outco
 
 A repair that fell back to the queue carries its durable requirement onto the drain that runs the queued message, and `pendingInterruptRepair` is what carries it: the drain reads that flag and asks `repairInterruptedToolUseBlocks` for `requireDurable`, so a second persist failure leaves the flag armed and the message queued instead of persisting the prompt behind an unmatched durable `tool_use`. Only a steered drain settles for an in-memory repair, because it has no row of its own to persist behind it.
 
-**The model has to be told its turn was cut off, once.** An interrupt caught mid-tool says so through the synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`). An interrupt caught during the provider call has no `tool_use` to answer, so `repairInterruptedToolUseBlocks` reports `preemptedToolResultOnTail: false` and the handover arms `pendingInterruptNote`. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a second annotation for the same interrupt; one notice per cut-off turn.
+**The two interrupt texts are split by job, and the behavior instruction lives in exactly one of them.** A synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`) states the fact about the one call it answers: the call stopped early and may have taken effect anyway. It is repeated once per stopped call in a parallel batch, so it holds no instruction. Every completed handover arms `pendingInterruptNote`, whether or not a tool call was stopped. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. That note is the single place the behavior after an interrupt is written, it leads with the short acknowledgement the user is waiting for, and it sits after the user's words instead of before them. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a third annotation, and do not put instructions back in the tool result.
 
 Two ordering rules a change here must not break. The synthetic `tool_result` is persisted BEFORE the caller writes the interrupting user row, because a user message between a `tool_use` and its result is a sequence every provider rejects. And the `thinking` / `message_interrupted` activity state is emitted by the agent loop at the head of the replacement turn, never at the handover: activity states are cached in `lastActivityStateMsg` and replayed to reconnecting clients, so a send that fails before its turn starts would otherwise strand every client on a busy conversation that is running nothing.
 
@@ -163,7 +163,7 @@ In the CDP factory the bridge is the internal `"host-bridge"` candidate kind (`I
 
 ### Browser CLI surface defaults
 
-The browser execute and tab routes share `browser/virtual-desktop-target.ts`. Platform-hosted web guardian conversations use installed, enabled virtual desktop Chrome by default. The shared `isVirtualDesktopEnabled` gate requires both `IS_PLATFORM` and `IS_CONTAINERIZED` alongside the `assistant-desktop` flag. Native renderer turns also use the `web` transport, so the frozen turn `clientOs` excludes native apps from automatic streamed-browser selection. Native apps retain their existing backend selection and fallback behavior. Explicit desktop/backend/client targets and existing personal-browser sessions override the surface default. Disabled or uninstalled desktop support retains the existing browser path; selection never triggers installation.
+The browser execute and tab routes share `browser/virtual-desktop-target.ts`. Platform-hosted web guardian conversations use image-provided virtual desktop Chrome by default when enabled. The shared `isVirtualDesktopEnabled` gate requires both `IS_PLATFORM` and `IS_CONTAINERIZED` alongside the `assistant-desktop` flag. Native renderer turns also use the `web` transport, so the frozen turn `clientOs` excludes native apps from automatic streamed-browser selection. Native apps retain their existing backend selection and fallback behavior. Explicit desktop/backend/client targets and existing personal-browser sessions override the surface default. Disabled desktop support retains the existing browser path. Missing image components fail the managed operation without installing dependencies or falling back to a personal browser.
 
 ### Per-tool `browser_mode` override
 
@@ -277,6 +277,8 @@ Verification SESSION state (sessions, secrets, rate limits, validate+consume) AN
 
 The daemon relays session lifecycle operations over the `verification_sessions_*` IPC routes via `assistant/src/channels/gateway-verification-sessions.ts` and keeps what is presentation: message composition and channel delivery (`channel-verification-routes.ts`, `verification-outbound-actions.ts`). `channel-verification-service.ts` retains only guardian-delivery reads (`getGuardianBinding`, `isGuardian`, `isGuardianBoundForChannel`).
 
+The gateway answers a code (or an invite) it consumed at ingress with a reply it composes itself, and delivers it through the daemon's IPC-only `deliver_gateway_reply` method (`ipc/routes/channel-reply-ipc-routes.ts`), which hands it to the channel transport the inbound message's callback URL names. The gateway never sends to a provider itself: the transports are the one outbound path per channel, whoever composed the text. The reply is not recorded in a conversation, since the message it answers never entered one.
+
 The verified outcome is written in-process by the gateway: the HTTP guardian-attest handler calls `ContactStore.markChannelVerified` directly (verifiedVia "manual"); the code-match paths (text and the `verification_sessions_validate_consume` engine route) apply role side effects in-engine — guardian phone binding commits in the same gateway transaction as the consume. The revoke/downgrade outcome is relayed from the daemon via `ipcCallPersistent("mark_channel_revoked", …)` to `ContactStore.markChannelRevoked`.
 
 ## Rate Limiting & Diagnostics

package/src/runtime/actor-trust-resolver.ts

@@ -42,9 +42,9 @@ const log = getLogger("actor-trust-resolver");
 // ---------------------------------------------------------------------------
 
 /**
- * Trust classification for an inbound actor. Defined once in `./trust-class.ts`
- * (shared with the persistence metadata schema) and re-exported here, the
- * canonical import site for the resolver's consumers.
+ * Trust classification for an inbound actor. Declared in
+ * `@vellumai/gateway-client` and re-exported here for the resolver's
+ * consumers.
  */
 export type { TrustClass };