@vellumai/assistant 0.11.5 → 0.11.6-staging.1

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

@@ -405,7 +405,7 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
     expect(assistantMsg.reasoning_content).toBeUndefined();
   });
 
-  test("backfills placeholder content for a reasoning-only assistant turn when enabled", async () => {
+  test("backfills placeholder content for a reasoning-only assistant turn", async () => {
     const { provider, requests } = stubProvider(
       [
         {
@@ -413,10 +413,7 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
           usage: { prompt_tokens: 2, completion_tokens: 1 },
         },
       ],
-      {
-        assistantReasoningField: "reasoning",
-        backfillEmptyAssistantContent: true,
-      },
+      { assistantReasoningField: "reasoning" },
     );
 
     await provider.sendMessage([
@@ -455,53 +452,38 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
     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" },
-    );
+  test("backfills placeholder for a whitespace-only assistant turn", async () => {
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
 
     await provider.sendMessage([
       { role: "user", content: [{ type: "text", text: "question" }] },
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "thinking",
-            thinking: "truncated chain of thought",
-            signature: "",
-          },
-        ],
-      },
+      { role: "assistant", content: [{ type: "text", text: "  \n" }] },
     ]);
 
     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. Fireworks, Together) are unaffected unless they opt in.
-    expect(assistantMsg.content).toBeNull();
+    // Validators that trim before checking presence treat whitespace-only
+    // content as absent, so it needs the same placeholder as empty content.
+    expect(assistantMsg.content).toBe(EMPTY_ASSISTANT_TURN_PLACEHOLDER);
   });
 
   test("backfills placeholder when thinking is dropped and no text was emitted", async () => {
     // Custom openai-compatible endpoints do not set assistantReasoningField, so
-    // a Stop during thinking serializes to { role: "assistant", content: null }
+    // a Stop during thinking serializes to blank content with no tool calls
     // unless the backfill guard runs.
-    const { provider, requests } = stubProvider(
-      [
-        {
-          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
-          usage: { prompt_tokens: 2, completion_tokens: 1 },
-        },
-      ],
-      { backfillEmptyAssistantContent: true },
-    );
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
 
     await provider.sendMessage([
       { role: "user", content: [{ type: "text", text: "question" }] },
@@ -534,15 +516,12 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
   });
 
   test("backfills placeholder for an empty aborted assistant turn", async () => {
-    const { provider, requests } = stubProvider(
-      [
-        {
-          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
-          usage: { prompt_tokens: 2, completion_tokens: 1 },
-        },
-      ],
-      { backfillEmptyAssistantContent: true },
-    );
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
 
     await provider.sendMessage([
       { role: "user", content: [{ type: "text", text: "question" }] },
@@ -557,15 +536,12 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
   });
 
   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 },
-        },
-      ],
-      { backfillEmptyAssistantContent: true },
-    );
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
 
     await provider.sendMessage([
       {
@@ -992,7 +968,9 @@ describe("thinking-mode tool_choice rejection fallback", () => {
 
     expect(requests).toHaveLength(2);
     expect((requests[0] as { tool_choice?: string }).tool_choice).toBe("none");
-    expect((requests[1] as { tool_choice?: string }).tool_choice).toBeUndefined();
+    expect(
+      (requests[1] as { tool_choice?: string }).tool_choice,
+    ).toBeUndefined();
   });
 
   test("does not retry a 4xx that does not name tool_choice", async () => {
@@ -1103,9 +1081,13 @@ describe("missing reasoning_content rejection fallback", () => {
     );
     expect(/reasoning_content/i.test(wrapped.message)).toBe(false);
 
-    const { provider, requests } = stubProviderWithErrors([wrapped], OK_CHUNKS, {
-      assistantReasoningField: "reasoning_content",
-    });
+    const { provider, requests } = stubProviderWithErrors(
+      [wrapped],
+      OK_CHUNKS,
+      {
+        assistantReasoningField: "reasoning_content",
+      },
+    );
 
     await provider.sendMessage(toolCallHistory);
 

package/src/providers/openai/__tests__/connection-error-wrap.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import OpenAI from "openai";
+
+import { ProviderError } from "../../../util/errors.js";
+import { OpenAIChatCompletionsProvider } from "../chat-completions-provider.js";
+
+function providerThatThrows(error: unknown): OpenAIChatCompletionsProvider {
+  const provider = new OpenAIChatCompletionsProvider("test-key", "test-model", {
+    baseURL: "http://127.0.0.1:1/v1",
+    providerName: "openai-compatible",
+    providerLabel: "OpenAI-compatible",
+  });
+  (provider as unknown as { client: unknown }).client = {
+    chat: {
+      completions: {
+        create: async () => {
+          throw error;
+        },
+      },
+    },
+  };
+  return provider;
+}
+
+describe("connection-error wrapping", () => {
+  test("wraps APIConnectionError with reason network_error and the original as cause", async () => {
+    const cause = Object.assign(new Error("connect ECONNREFUSED"), {
+      code: "ECONNREFUSED",
+    });
+    const sdkError = new OpenAI.APIConnectionError({ cause });
+    const thrown = await providerThatThrows(sdkError)
+      .sendMessage([{ role: "user", content: [{ type: "text", text: "hi" }] }])
+      .then(
+        () => null,
+        (e: unknown) => e,
+      );
+    expect(thrown).toBeInstanceOf(ProviderError);
+    const providerError = thrown as ProviderError;
+    expect(providerError.reason).toBe("network_error");
+    expect(providerError.statusCode).toBeUndefined();
+    expect(providerError.cause).toBe(sdkError);
+  });
+});

package/src/providers/openai/__tests__/orphan-tool-result-guard.test.ts

@@ -145,7 +145,7 @@ const ID_SHAPES = [
 ] as const;
 
 /** History whose tool_result is paired with a preceding tool_use. */
-function pairedHistory(id: string): Message[] {
+function pairedHistory(id: string, result = "file contents"): Message[] {
   return [
     { role: "user", content: [{ type: "text", text: "Read the file" }] },
     {
@@ -165,7 +165,7 @@ function pairedHistory(id: string): Message[] {
         {
           type: "tool_result",
           tool_use_id: id,
-          content: "file contents",
+          content: result,
         },
       ],
     },
@@ -383,6 +383,38 @@ describe("OpenAIChatCompletionsProvider orphan tool_result guard", () => {
       },
     ]);
   });
+
+  test("keeps JSON Schema references opaque for Gemini-compatible gateways", async () => {
+    const provider = makeProvider();
+    const stub = stubChatCreate(provider);
+    const schemaResult = JSON.stringify({
+      $defs: { LLMProvider: { type: "string" } },
+      properties: {
+        provider: { $ref: "#/$defs/LLMProvider" },
+      },
+    });
+
+    await provider.sendMessage(pairedHistory("call_schema", schemaResult));
+
+    const sent = stub.messages();
+    const toolMessage = sent.find((message) => message.role === "tool");
+    expect(toolMessage).toBeDefined();
+    expect(JSON.parse(toolMessage!.content as string)).toEqual({
+      output: schemaResult,
+    });
+  });
+
+  test("leaves ordinary JSON tool results unchanged", async () => {
+    const provider = makeProvider();
+    const stub = stubChatCreate(provider);
+    const ordinaryResult = JSON.stringify({ status: "ok", count: 3 });
+
+    await provider.sendMessage(pairedHistory("call_json", ordinaryResult));
+
+    const sent = stub.messages();
+    const toolMessage = sent.find((message) => message.role === "tool");
+    expect(toolMessage?.content).toBe(ordinaryResult);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/providers/openai/api-error-normalization.ts

@@ -1,4 +1,4 @@
-import type OpenAI from "openai";
+import OpenAI from "openai";
 
 import type { ProviderErrorReason } from "../../util/errors.js";
 import {
@@ -238,7 +238,21 @@ export function normalizeOpenAIAPIError(
   if (rawBody) {
     out.rawBody = rawBody;
   }
-  out.reason = deriveReason(out, error.status);
+  // Transport failures never reached the server, so there is no status or
+  // body for deriveReason to read; the SDK's error class is the only signal.
+  // APIUserAbortError (caller cancellation, inner stream deadline) is a
+  // sibling class, not a subclass, so it deliberately does NOT match here:
+  // classifying it as a transient network error would make the retry loop
+  // re-run 30-minute deadline failures. Guarded because test doubles of the
+  // openai module may not define the class.
+  const connectionErrorClass = OpenAI.APIConnectionError as
+    | typeof OpenAI.APIConnectionError
+    | undefined;
+  out.reason =
+    typeof connectionErrorClass === "function" &&
+    error instanceof connectionErrorClass
+      ? "network_error"
+      : deriveReason(out, error.status);
   return out;
 }
 

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

@@ -121,14 +121,15 @@ export function detectVisionNotSupported(
 
 /**
  * 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).
+ * tool calls (e.g. a reasoning-only turn truncated at the output-token limit,
+ * or a Stop mid-stream before any text).
  *
  * 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.
+ * but strict OpenAI-compatible backends do not: DeepSeek 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
@@ -168,14 +169,6 @@ export interface OpenAIChatCompletionsProviderOptions {
    *  tool-call turns. DeepSeek thinking mode that requires the field even when
    *  empty is handled by a one-shot retry. */
   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, or a Stop mid-stream before any text). Off by default; enabled for
-   *  OpenRouter, Vercel AI Gateway, LiteLLM, and custom `openai-compatible`
-   *  endpoints, whose downstream providers (e.g. DeepSeek, vLLM, Portkey)
-   *  reject such messages with `Invalid assistant message: content or
-   *  tool_calls must be set`. See {@link EMPTY_ASSISTANT_TURN_PLACEHOLDER}. */
-  backfillEmptyAssistantContent?: boolean;
   /** Present object-typed tool params to the model as JSON-string params and
    *  decode them back to objects on the response. Works around models whose
    *  function-call serialization collapses nested objects to `{}` (observed
@@ -248,6 +241,60 @@ function isClientErrorStatus(error: unknown): boolean {
   return typeof status === "number" && status >= 400 && status < 500;
 }
 
+/**
+ * True when a parsed tool result contains a local JSON Schema reference.
+ *
+ * Gemini reserves `$ref` fields inside structured function responses for
+ * multimodal part references. OpenAI-compatible gateways can JSON-decode tool
+ * message content before translating it to Gemini, which makes a JSON Schema
+ * result look like one of those references and causes an INVALID_ARGUMENT.
+ */
+function containsLocalJsonSchemaReference(value: unknown): boolean {
+  const pending: unknown[] = [value];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (Array.isArray(current)) {
+      pending.push(...current);
+      continue;
+    }
+    if (current === null || typeof current !== "object") {
+      continue;
+    }
+
+    const record = current as Record<string, unknown>;
+    const ref = record.$ref;
+    if (typeof ref === "string" && (ref === "#" || ref.startsWith("#/"))) {
+      return true;
+    }
+    pending.push(...Object.values(record));
+  }
+  return false;
+}
+
+/**
+ * Keep JSON Schema tool results opaque across OpenAI-compatible gateways.
+ *
+ * The outer object is intentionally valid JSON so gateways that decode tool
+ * content produce `{ output: string }`; the schema's `$ref` remains inside the
+ * string and cannot be interpreted as a Gemini multimodal part reference.
+ */
+function protectJsonSchemaToolResult(payload: string): string {
+  if (!payload.includes('"$ref"')) {
+    return payload;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+
+  return containsLocalJsonSchemaReference(parsed)
+    ? JSON.stringify({ output: payload })
+    : payload;
+}
+
 /**
  * True when the request carried an explicit reasoning opt-out (`"none"` sent
  * as flat `reasoning_effort` or nested `reasoning.effort`) and the provider
@@ -556,7 +603,6 @@ export class OpenAIChatCompletionsProvider implements Provider {
     | "reasoning"
     | "reasoning_content"
     | undefined;
-  private backfillEmptyAssistantContent: boolean;
   private coerceObjectArgsToJsonString: boolean;
   private omitToolChoiceWhenReasoning: boolean;
 
@@ -584,8 +630,6 @@ export class OpenAIChatCompletionsProvider implements Provider {
     this.requestHeaders = options.requestHeaders ?? {};
     this.parseThinkTags = options.parseThinkTags ?? false;
     this.assistantReasoningField = options.assistantReasoningField;
-    this.backfillEmptyAssistantContent =
-      options.backfillEmptyAssistantContent ?? false;
     this.coerceObjectArgsToJsonString =
       options.coerceObjectArgsToJsonString ?? false;
     this.omitToolChoiceWhenReasoning =
@@ -709,8 +753,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
         if (toolChoice !== undefined) {
           const thinkingOn = isThinkingEnabledOnWire(params);
           const skipAutoDefault = thinkingOn && toolChoice === "auto";
-          const skipAllChoices =
-            thinkingOn && this.omitToolChoiceWhenReasoning;
+          const skipAllChoices = thinkingOn && this.omitToolChoiceWhenReasoning;
           if (!skipAutoDefault && !skipAllChoices) {
             params.tool_choice = toolChoice;
           }
@@ -1147,7 +1190,10 @@ export class OpenAIChatCompletionsProvider implements Provider {
           );
         }
         const retryAfterMs = extractRetryAfterMs(error.headers);
+        // `cause` keeps the SDK error's errno-bearing chain reachable for
+        // network-shape classification (`isRetryableNetworkError` walks it).
         const errorOptions: {
+          cause?: unknown;
           retryAfterMs?: number;
           abortReason?: unknown;
           apiErrorCode?: string;
@@ -1156,7 +1202,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
           requestId?: string;
           rawBody?: string;
           reason?: ProviderErrorReason;
-        } = {};
+        } = { cause: error };
         if (retryAfterMs !== undefined) {
           errorOptions.retryAfterMs = retryAfterMs;
         }
@@ -1185,7 +1231,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
           formattedMessage,
           this.name,
           error.status,
-          Object.keys(errorOptions).length > 0 ? errorOptions : undefined,
+          errorOptions,
         );
       }
       throw new ProviderError(
@@ -1300,7 +1346,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
           result.push({
             role: "tool",
             tool_call_id: tr.tool_use_id,
-            content: serialized.payload,
+            content: protectJsonSchemaToolResult(serialized.payload),
           });
         }
 
@@ -1387,16 +1433,16 @@ export class OpenAIChatCompletionsProvider implements Provider {
     }
 
     // An assistant message must carry `content` or `tool_calls`. A turn with
-    // neither (e.g. reasoning-only, or a Stop before any text) 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,
-    // Vercel AI Gateway, LiteLLM, openai-compatible) via
-    // `backfillEmptyAssistantContent`.
+    // neither (e.g. reasoning-only, a Stop before any text, or a turn whose
+    // text arrived as whitespace) would serialize to blank content with no
+    // tool calls, which strict OpenAI-compatible backends reject. Reasoning
+    // lives in a separate field and does not satisfy the constraint, and
+    // whitespace-only content does not survive a validator that trims before
+    // checking presence, so the placeholder covers both.
     if (
-      this.backfillEmptyAssistantContent &&
       !result.tool_calls &&
-      (result.content === null || result.content === "")
+      (result.content === null ||
+        (typeof result.content === "string" && result.content.trim() === ""))
     ) {
       result.content = EMPTY_ASSISTANT_TURN_PLACEHOLDER;
     }

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

@@ -680,7 +680,10 @@ export class OpenAIResponsesProvider implements Provider {
           });
         }
         const retryAfterMs = extractRetryAfterMs(error.headers);
+        // `cause` keeps the SDK error's errno-bearing chain reachable for
+        // network-shape classification (`isRetryableNetworkError` walks it).
         const errorOptions: {
+          cause?: unknown;
           retryAfterMs?: number;
           abortReason?: unknown;
           apiErrorCode?: string;
@@ -689,7 +692,7 @@ export class OpenAIResponsesProvider implements Provider {
           requestId?: string;
           rawBody?: string;
           reason?: ProviderErrorReason;
-        } = {};
+        } = { cause: error };
         if (retryAfterMs !== undefined) {
           errorOptions.retryAfterMs = retryAfterMs;
         }
@@ -718,7 +721,7 @@ export class OpenAIResponsesProvider implements Provider {
           formattedMessage,
           this.name,
           error.status,
-          Object.keys(errorOptions).length > 0 ? errorOptions : undefined,
+          errorOptions,
         );
       }
       throw new ProviderError(

package/src/providers/openrouter/client.ts

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

package/src/providers/provider-send-message.ts

@@ -11,6 +11,7 @@ import {
 import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { getDb } from "../persistence/db-connection.js";
+import type { ProviderRouteAttribution } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import {
   describeSubscriptionModelIncompatibility,
@@ -70,6 +71,16 @@ export class CallSiteConfiguredProvider implements Provider {
   // (callers like the advisor consult gate on it). Fixed at construction.
   public readonly supportsNativeWebSearch?: boolean;
 
+  /**
+   * Route the inner adapter signs with, stamped at connection resolution.
+   * Forwarded live (not snapshotted) so consumers holding this wrapper —
+   * e.g. the save-time probe's billing gate — read the row dispatch
+   * actually selected.
+   */
+  get routeAttribution(): ProviderRouteAttribution | undefined {
+    return this.inner.routeAttribution;
+  }
+
   constructor(
     private readonly inner: Provider,
     private readonly callSite: LLMCallSite,

package/src/providers/retry.ts

@@ -246,6 +246,12 @@ const RETRYABLE_PROVIDER_ERROR_REASONS = new Set<ProviderErrorReason>([
   "rate_limited",
   "overloaded",
   "server_error",
+  // Transport failures that never reached the server (SDK connection
+  // errors, Gemini proxy interception). Deadline and cancellation shapes
+  // never carry this reason — they surface as reason-less aborts and
+  // short-circuit in isRetryableError before the reason check — so a
+  // 30-minute stream deadline failure is never retried through it.
+  "network_error",
 ]);
 
 function isRetryableStreamError(error: unknown): boolean {

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

@@ -76,6 +76,14 @@ export interface SearchProviderCatalogEntry {
   /** Privacy-policy URL surfaced in marketing data-sharing docs.
    *  BYOK providers only. */
   readonly privacyPolicyUrl?: string;
+  /**
+   * When true, settings UIs show an optional API Base field. Empty /
+   * omitted base uses {@link defaultApiBase}.
+   */
+  readonly supportsApiBase?: boolean;
+  /** Cloud default origin when `supportsApiBase` is true and the user
+   *  leaves API Base empty. */
+  readonly defaultApiBase?: string;
 }
 
 export const SEARCH_PROVIDER_CATALOG: readonly SearchProviderCatalogEntry[] = [
@@ -143,6 +151,18 @@ export const SEARCH_PROVIDER_CATALOG: readonly SearchProviderCatalogEntry[] = [
     fallbackOrder: 5,
     privacyPolicyUrl: "https://keenable.ai/privacy",
   },
+  {
+    id: "fastcrw",
+    displayName: "fastCRW",
+    kind: "byok",
+    apiKeyPrefix: "crw_live_...",
+    envVar: "FASTCRW_API_KEY",
+    secretKey: "fastcrw",
+    fallbackOrder: 6,
+    privacyPolicyUrl: "https://fastcrw.com/privacy",
+    supportsApiBase: true,
+    defaultApiBase: "https://api.fastcrw.com",
+  },
 ];
 
 /** Provider ids accepted by the web-search config schema. */

package/src/providers/vercel-ai-gateway/client.ts

@@ -46,7 +46,6 @@ export class VercelAIGatewayProvider extends OpenAIChatCompletionsProvider {
       // Vercel's OpenAI-compat endpoint streams reasoning text in
       // `delta.reasoning` (see its Advanced Configuration docs).
       assistantReasoningField: "reasoning",
-      backfillEmptyAssistantContent: true,
     });
     this.gatewayApiKey = apiKey;
     this.resolvedBaseURL = baseURL;

package/src/runtime/AGENTS.md

@@ -74,6 +74,7 @@ Host CU allows the assistant to proxy computer-use actions (screenshots, mouse/k
 - **Resolution**: Clients execute the CU action on the host and respond via:
   - `POST /v1/host-cu-result` — `{ requestId, axTree?, axDiff?, screenshot?, screenshotWidthPx?, screenshotHeightPx?, screenWidthPt?, screenHeightPt?, executionResult?, executionError?, secondaryWindows?, userGuidance? }`
 - **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_cu"`. Registration happens in `conversation-routes.ts` and the route handler is in `host-cu-routes.ts`.
+- **Conversation-agnostic observation**: `observeHostScreen()` in `host-observe.ts` issues a `computer_use_observe` request with no conversation, for callers outside an agent turn (`HostCuProxy` only exists inside one). It takes the initiating actor's principal id and reaches only that actor's own `host_cu` clients: `pickSameUserAutoResolve` picks the default target and `enforceSameActorOrErrorResult` gates an explicitly named one, both before the request is registered or broadcast. Its pending interaction carries no `conversationId`, so `host-cu-routes.ts` hands the raw observation fields straight to the waiting caller instead of routing through a conversation's CU proxy. On the desktop side the ordinary `host_cu` executor services the request.
 
 ### Host browser (desktop proxy CDP execution)