@vellumai/assistant 0.8.0 → 0.8.2

package/src/providers/anthropic/client.ts

@@ -390,9 +390,11 @@ function isServerToolUseBlock(
 }
 
 /** Type-guard for web_search_tool_result blocks. */
-function isWebSearchToolResultBlock(
-  block: unknown,
-): block is { type: "web_search_tool_result"; tool_use_id: string } {
+function isWebSearchToolResultBlock(block: unknown): block is {
+  type: "web_search_tool_result";
+  tool_use_id: string;
+  content: unknown;
+} {
   return (
     typeof block === "object" &&
     block != null &&
@@ -401,52 +403,85 @@ function isWebSearchToolResultBlock(
 }
 
 /**
- * Repair orphaned server_tool_use blocks within assistant messages.
- * Server-side tools (e.g. web_search) are self-paired: the assistant message
- * should contain both server_tool_use and its matching web_search_tool_result.
- * When the stream is interrupted or the API returns a partial response, the
- * web_search_tool_result may be missing. This function injects a synthetic
- * error result for any orphaned server_tool_use block.
+ * Repair orphaned server-side tool blocks within assistant messages. Server-
+ * side tools (e.g. web_search) are self-paired: the assistant message should
+ * contain both server_tool_use and its matching web_search_tool_result. Either
+ * side can go missing — a partial stream may drop the result, or a downstream
+ * step (history reload, message split, compaction) may drop the use block.
+ * Both cases trigger an Anthropic 400 on the next request, so this function
+ * handles both directions:
+ *
+ *   - server_tool_use without paired result: inject a synthetic error result.
+ *   - web_search_tool_result without paired server_tool_use: downgrade to a
+ *     text block describing what was found so the model retains context.
  */
-function repairOrphanedServerToolUse(
+function repairOrphanedServerToolBlocks(
   messages: Anthropic.MessageParam[],
 ): Anthropic.MessageParam[] {
   return messages.map((msg) => {
     if (msg.role !== "assistant") return msg;
     const content = Array.isArray(msg.content) ? msg.content : [];
 
-    // Collect server_tool_use IDs and web_search_tool_result IDs in this message
     const serverToolUseIds = new Set<string>();
-    const pairedResultIds = new Set<string>();
+    const webSearchResultIds = new Set<string>();
     for (const block of content) {
       if (isServerToolUseBlock(block)) {
         serverToolUseIds.add(block.id);
       }
       if (isWebSearchToolResultBlock(block)) {
-        pairedResultIds.add(block.tool_use_id);
+        webSearchResultIds.add(block.tool_use_id);
       }
     }
 
-    // Find orphaned server_tool_use blocks (no matching web_search_tool_result)
-    const orphanedIds: string[] = [];
+    const orphanServerToolUseIds = new Set<string>();
     for (const id of serverToolUseIds) {
-      if (!pairedResultIds.has(id)) {
-        orphanedIds.push(id);
-      }
+      if (!webSearchResultIds.has(id)) orphanServerToolUseIds.add(id);
+    }
+    const orphanWebSearchResultIds = new Set<string>();
+    for (const id of webSearchResultIds) {
+      if (!serverToolUseIds.has(id)) orphanWebSearchResultIds.add(id);
     }
 
-    if (orphanedIds.length === 0) return msg;
+    if (
+      orphanServerToolUseIds.size === 0 &&
+      orphanWebSearchResultIds.size === 0
+    ) {
+      return msg;
+    }
 
-    log.warn(
-      { orphanedIds, blockCount: content.length },
-      "Injecting synthetic web_search_tool_result for orphaned server_tool_use blocks",
-    );
+    if (orphanServerToolUseIds.size > 0) {
+      log.warn(
+        {
+          orphanedIds: Array.from(orphanServerToolUseIds),
+          blockCount: content.length,
+        },
+        "Injecting synthetic web_search_tool_result for orphaned server_tool_use blocks",
+      );
+    }
+    if (orphanWebSearchResultIds.size > 0) {
+      log.warn(
+        {
+          orphanedIds: Array.from(orphanWebSearchResultIds),
+          blockCount: content.length,
+        },
+        "Downgrading orphaned web_search_tool_result blocks to text",
+      );
+    }
 
-    // Insert a synthetic error web_search_tool_result after each orphaned server_tool_use
     const repairedContent: Anthropic.ContentBlockParam[] = [];
     for (const block of content) {
+      if (
+        isWebSearchToolResultBlock(block) &&
+        orphanWebSearchResultIds.has(block.tool_use_id)
+      ) {
+        repairedContent.push({
+          type: "text",
+          text: formatOrphanedWebSearchResultAsText(block),
+        });
+        continue;
+      }
       repairedContent.push(block);
-      if (isServerToolUseBlock(block) && orphanedIds.includes(block.id)) {
+      if (isServerToolUseBlock(block) && orphanServerToolUseIds.has(block.id)) {
         repairedContent.push({
           type: "web_search_tool_result",
           tool_use_id: block.id,
@@ -462,6 +497,38 @@ function repairOrphanedServerToolUse(
   });
 }
 
+function formatOrphanedWebSearchResultAsText(block: {
+  tool_use_id: string;
+  content: unknown;
+}): string {
+  const header = `[Orphaned web_search results (tool_use_id=${block.tool_use_id}):`;
+  if (!Array.isArray(block.content)) {
+    return `${header} (results unavailable)]`;
+  }
+  const entries: string[] = [];
+  for (const r of block.content) {
+    if (
+      typeof r !== "object" ||
+      r == null ||
+      (r as { type?: string }).type !== "web_search_result"
+    ) {
+      continue;
+    }
+    const title =
+      typeof (r as { title?: unknown }).title === "string"
+        ? (r as { title: string }).title
+        : "(untitled)";
+    const url =
+      typeof (r as { url?: unknown }).url === "string"
+        ? (r as { url: string }).url
+        : "";
+    const idx = entries.length + 1;
+    entries.push(url ? `${idx}. ${title}\n   ${url}` : `${idx}. ${title}`);
+  }
+  const body = entries.length > 0 ? entries.join("\n") : "(no results)";
+  return `${header}\n${body}]`;
+}
+
 /**
  * Last-line-of-defense fix that ensures every assistant message with tool_use
  * blocks has matching tool_result blocks in the immediately following user
@@ -648,6 +715,7 @@ export class AnthropicProvider implements Provider {
   private model: string;
   private useNativeWebSearch: boolean;
   private streamTimeoutMs: number;
+  private requestHeaders: Record<string, string>;
 
   constructor(
     apiKey: string,
@@ -663,9 +731,12 @@ export class AnthropicProvider implements Provider {
        * positional `apiKey` argument is ignored on the wire.
        */
       authToken?: string;
+      /** Provider-level request headers merged into every API request. */
+      requestHeaders?: Record<string, string>;
     } = {},
   ) {
     this.streamTimeoutMs = options.streamTimeoutMs ?? 1_800_000;
+    this.requestHeaders = options.requestHeaders ?? {};
     // Pass the same deadline to the SDK so its per-request timeout can't
     // fire before `createStreamTimeout` does. The SDK's default is 10 min,
     // which truncates any request we intend to run longer than that. We add
@@ -859,7 +930,9 @@ export class AnthropicProvider implements Provider {
       // assistant messages have original thinking with valid signatures
       // — the API accepts them. No provider-side stripping needed.
 
-      sentMessages = ensureToolPairing(repairOrphanedServerToolUse(formatted));
+      sentMessages = ensureToolPairing(
+        repairOrphanedServerToolBlocks(formatted),
+      );
       const {
         effort,
         speed,
@@ -934,18 +1007,16 @@ export class AnthropicProvider implements Provider {
           const dynamicBlock = systemPrompt.slice(
             boundaryIdx + SYSTEM_PROMPT_CACHE_BOUNDARY.length,
           );
-          params.system = [
-            {
+          const systemBlocks = [staticBlock, dynamicBlock]
+            .filter((text) => text.length > 0)
+            .map((text) => ({
               type: "text" as const,
-              text: staticBlock,
+              text,
               cache_control: cacheControl,
-            },
-            {
-              type: "text" as const,
-              text: dynamicBlock,
-              cache_control: cacheControl,
-            },
-          ];
+            }));
+          if (systemBlocks.length > 0) {
+            params.system = systemBlocks;
+          }
         } else {
           params.system = [
             {
@@ -1132,6 +1203,16 @@ export class AnthropicProvider implements Provider {
 
       let response: Anthropic.Message;
       try {
+        const requestHeaders = {
+          ...this.requestHeaders,
+          ...(usageAttributionHeaders ?? {}),
+        };
+        const requestOptions = {
+          signal: timeoutSignal,
+          ...(Object.keys(requestHeaders).length > 0
+            ? { headers: requestHeaders }
+            : {}),
+        };
         const stream: UnifiedStream = useFastMode
           ? (this.client.beta.messages.stream(
               {
@@ -1140,12 +1221,7 @@ export class AnthropicProvider implements Provider {
                 betas,
               } as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming &
                 Anthropic.Beta.Messages.MessageCreateParamsStreaming,
-              {
-                signal: timeoutSignal,
-                ...(usageAttributionHeaders
-                  ? { headers: usageAttributionHeaders }
-                  : {}),
-              },
+              requestOptions,
             ) as unknown as UnifiedStream)
           : betas.length > 0
             ? (this.client.beta.messages.stream(
@@ -1154,19 +1230,12 @@ export class AnthropicProvider implements Provider {
                   betas,
                 } as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming &
                   Anthropic.Beta.Messages.MessageCreateParamsStreaming,
-                {
-                  signal: timeoutSignal,
-                  ...(usageAttributionHeaders
-                    ? { headers: usageAttributionHeaders }
-                    : {}),
-                },
+                requestOptions,
               ) as unknown as UnifiedStream)
-            : (this.client.messages.stream(params, {
-                signal: timeoutSignal,
-                ...(usageAttributionHeaders
-                  ? { headers: usageAttributionHeaders }
-                  : {}),
-              }) as unknown as UnifiedStream);
+            : (this.client.messages.stream(
+                params,
+                requestOptions,
+              ) as unknown as UnifiedStream);
 
         // Buffer streaming text until it's clear the accumulated text isn't
         // going to form a placeholder sentinel. Sentinels are injected into

package/src/providers/call-site-routing.ts

@@ -1,7 +1,8 @@
 /**
  * Provider wrapper that routes each `sendMessage` call to a different
  * underlying provider transport when the per-call `options.config.callSite`
- * resolves to a provider name that differs from the default.
+ * resolves to a profile that names a `provider_connection` distinct from
+ * the default's.
  *
  * Without this wrapper the conversation-level provider transport is fixed at
  * construction time, so a per-call-site `llm.callSites.<id>.provider`
@@ -11,18 +12,22 @@
  * though the main agent runs on Anthropic" silently fail.
  *
  * `CallSiteRoutingProvider` consults `resolveCallSiteConfig` per call. When
- * the resolved provider name differs from the default's name and the
- * registry can produce a Provider for it, the call is delegated to that
- * provider; otherwise it falls back to the default. Other Provider interface
- * surface area (`name`, `tokenEstimationProvider`) is delegated to the
- * default so wrappers further out (e.g. `RateLimitProvider`) still see a
- * stable identity.
+ * the resolved profile names a `provider_connection`, the wrapper resolves
+ * that connection and delegates the call to its bound Provider. Other
+ * Provider interface surface area (`name`, `tokenEstimationProvider`) is
+ * delegated to the default so wrappers further out (e.g. `RateLimitProvider`)
+ * still see a stable identity.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import { getConfig } from "../config/loader.js";
+import {
+  ConnectionResolutionError,
+  tryResolveProviderForConnectionName,
+} from "./connection-resolution.js";
+import type { ProvidersConfig } from "./registry.js";
 import type {
   Message,
   Provider,
@@ -52,7 +57,25 @@ export class CallSiteRoutingProvider implements Provider {
 
   constructor(
     private readonly defaultProvider: Provider,
-    private readonly getProviderByName: (name: string) => Provider | undefined,
+    /**
+     * Async hook invoked when the resolved profile names a
+     * `provider_connection`. Returning a Provider routes the call through
+     * that connection's auth; returning null signals a soft credential
+     * failure (no usable adapter) and the wrapper falls back to the
+     * default Provider for graceful per-call degradation. Hard config
+     * errors (lookup_failed / not_found / provider_mismatch) throw
+     * `ConnectionResolutionError` and propagate to the caller — those
+     * are misconfigurations that need to be fixed, not silently routed
+     * around.
+     *
+     * `expectedProvider` is the provider name the resolved profile
+     * declared. The hook verifies the connection's provider matches
+     * and throws on mismatch.
+     */
+    private readonly resolveByConnection: (
+      connectionName: string,
+      expectedProvider: string,
+    ) => Promise<Provider | null>,
   ) {
     this.tokenEstimationProvider = defaultProvider.tokenEstimationProvider;
   }
@@ -63,7 +86,7 @@ export class CallSiteRoutingProvider implements Provider {
     systemPrompt?: string,
     options?: SendMessageOptions,
   ): Promise<ProviderResponse> {
-    const target = this.selectProvider(options);
+    const target = await this.selectProvider(options);
     const isRouted = target !== this.defaultProvider;
 
     const doSend = async (): Promise<ProviderResponse> => {
@@ -91,12 +114,26 @@ export class CallSiteRoutingProvider implements Provider {
   }
 
   /**
-   * Pick the provider to route this call through. The default provider wins
-   * unless the per-call `callSite` (layered with any `overrideProfile`)
-   * resolves to a different provider name and the registry can produce a
-   * Provider for it.
+   * Pick the provider to route this call through.
+   *
+   * Resolution order:
+   *   1. No callSite → default provider (legacy short-circuit; no
+   *      resolution work needed).
+   *   2. Resolved profile names a `provider_connection` → resolve through
+   *      that connection's auth. Hard config errors propagate as throws.
+   *      Soft credential failures fall back to the default Provider so
+   *      a transient credential blip does not take a conversation
+   *      offline.
+   *   3. Resolved profile's `provider` matches the default's name → reuse
+   *      the default provider instance (no connection-aware lookup
+   *      needed; the default IS the connection-aware route).
+   *   4. Resolved profile's `provider` differs from the default but no
+   *      `provider_connection` is set → throw. This is a configuration
+   *      bug: alternate-provider routing requires a connection.
    */
-  private selectProvider(options?: SendMessageOptions): Provider {
+  private async selectProvider(
+    options?: SendMessageOptions,
+  ): Promise<Provider> {
     const callSite = options?.config?.callSite;
     if (!callSite) return this.defaultProvider;
 
@@ -104,11 +141,52 @@ export class CallSiteRoutingProvider implements Provider {
     const resolved = resolveCallSiteConfig(callSite, getConfig().llm, {
       overrideProfile,
     });
+
+    if (resolved.provider_connection) {
+      const connectionProvider = await this.resolveByConnection(
+        resolved.provider_connection,
+        resolved.provider,
+      );
+      if (connectionProvider) return connectionProvider;
+      // Soft credential failure — the connection-resolution helper
+      // returned null because the underlying auth bundle yields no
+      // usable adapter (or threw transiently). Reuse the default for
+      // graceful per-call degradation.
+      return this.defaultProvider;
+    }
+
     if (resolved.provider === this.defaultProvider.name) {
       return this.defaultProvider;
     }
 
-    const alternative = this.getProviderByName(resolved.provider);
-    return alternative ?? this.defaultProvider;
+    throw new ConnectionResolutionError(
+      "<resolved-callsite>",
+      "missing_connection",
+      `call-site "${callSite}" resolves to provider "${resolved.provider}" but no provider_connection is set — alternate-provider routing requires a connection`,
+    );
   }
 }
+
+/**
+ * Wrap a base Provider with `CallSiteRoutingProvider` configured to route
+ * `provider_connection` references through the shared connection-resolution
+ * helper.
+ *
+ * `config` is threaded through to the connection lookup so the resolved
+ * connection's auth can read provider-config metadata (e.g. timeouts, model
+ * names).
+ */
+export function wrapWithCallSiteRouting(
+  base: Provider,
+  config: ProvidersConfig,
+): Provider {
+  return new CallSiteRoutingProvider(
+    base,
+    (connectionName, expectedProvider) =>
+      tryResolveProviderForConnectionName(
+        connectionName,
+        config,
+        expectedProvider,
+      ),
+  );
+}

package/src/providers/connection-resolution.ts

@@ -0,0 +1,170 @@
+/**
+ * Connection-aware provider resolution helpers.
+ *
+ * These wrap `resolveProviderFromConnection` (in `registry.ts`) with the
+ * DB lookup and lifecycle of a `provider_connection` reference. The
+ * canonical dispatch path (`provider-send-message.ts`) and each satellite
+ * site (subagent manager, daemon conversation/approval/guardian generators,
+ * rollup producer) use these helpers so that connection-awareness behaves
+ * identically across the codebase.
+ *
+ * Resolution policy:
+ *   1. The profile MUST name a `provider_connection`. The boot-time
+ *      backfill ensures every profile has one; a missing connection name
+ *      is a configuration bug.
+ *   2. Hard config errors (DB lookup throws, row not found, provider
+ *      mismatch with the resolving profile) throw so misconfigurations
+ *      surface immediately rather than silently rerouting.
+ *   3. Soft credential issues (`resolveProviderFromConnection` returns
+ *      null because the credential isn't set in the vault, or the
+ *      auth bundle yields no usable adapter) return null. Callers are
+ *      free to treat null as "no provider available" and fall back to
+ *      a graceful no-op (e.g. rollup producer skips, satellite throw
+ *      with their own actionable message).
+ *   4. Transient failures inside the resolver (managed-proxy context
+ *      lookup, credential read I/O) are caught and treated like a soft
+ *      credential issue (return null). A transient blip should not take
+ *      a conversation offline.
+ */
+
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { getDb } from "../memory/db-connection.js";
+import { getLogger } from "../util/logger.js";
+import { getConnection } from "./inference/connections.js";
+import type { ProvidersConfig } from "./registry.js";
+import { resolveProviderFromConnection } from "./registry.js";
+import type { Provider } from "./types.js";
+
+const log = getLogger("providers/connection-resolution");
+
+/**
+ * Error raised when a `provider_connection` reference cannot be resolved
+ * because the configuration is broken (DB lookup throws, no such row, or
+ * the connection's provider does not match the resolving profile's
+ * declared provider). These are deterministic configuration bugs that
+ * should fail loudly rather than silently rerouting.
+ */
+export class ConnectionResolutionError extends Error {
+  constructor(
+    public readonly connectionName: string,
+    public readonly reason:
+      | "lookup_failed"
+      | "not_found"
+      | "provider_mismatch"
+      | "missing_connection",
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "ConnectionResolutionError";
+  }
+}
+
+/**
+ * Resolve a Provider through a named `provider_connection`.
+ *
+ * Throws `ConnectionResolutionError` on hard config errors:
+ *   - DB lookup throws (`lookup_failed`)
+ *   - No connection row with this name (`not_found`)
+ *   - Connection row's provider does not match `expectedProvider`
+ *     (`provider_mismatch`) — protects against silent misroutes when a
+ *     profile names provider X with a connection bound to provider Y.
+ *
+ * Returns null on soft credential issues:
+ *   - `resolveProviderFromConnection` returned null (credential missing
+ *     from vault, platform auth unavailable, adapter creation failure).
+ *   - The resolver threw a transient failure (caught and downgraded to
+ *     null). Callers handle null as "no provider available right now".
+ *
+ * `expectedProvider` is the provider name the resolving profile declared.
+ * Pass `undefined` to skip the mismatch check (callers that don't yet
+ * know the expected provider).
+ */
+export async function tryResolveProviderForConnectionName(
+  connectionName: string,
+  config: ProvidersConfig,
+  expectedProvider?: string,
+): Promise<Provider | null> {
+  let connection;
+  try {
+    connection = getConnection(getDb(), connectionName);
+  } catch (err) {
+    throw new ConnectionResolutionError(
+      connectionName,
+      "lookup_failed",
+      `provider_connection lookup failed for "${connectionName}"`,
+      err,
+    );
+  }
+  if (!connection) {
+    throw new ConnectionResolutionError(
+      connectionName,
+      "not_found",
+      `provider_connection "${connectionName}" not found in DB — check your config or run the boot-time backfill`,
+    );
+  }
+  if (expectedProvider && connection.provider !== expectedProvider) {
+    throw new ConnectionResolutionError(
+      connectionName,
+      "provider_mismatch",
+      `provider_connection "${connectionName}" has provider="${connection.provider}" but resolving profile declared provider="${expectedProvider}" — set the profile's provider_connection to a row matching its provider`,
+    );
+  }
+  if (connection.status === "disabled") {
+    log.debug(
+      { connectionName },
+      "provider_connection is disabled — returning null",
+    );
+    return null;
+  }
+  // `resolveProviderFromConnection` reaches into auth resolution (credential
+  // reads, managed-proxy context). A transient failure there is a soft
+  // miss — log and return null so the caller can treat it the same as
+  // "no usable credentials". Hard config errors are thrown above; this
+  // catch is specifically for in-flight failures that should not take
+  // dispatch offline.
+  try {
+    return await resolveProviderFromConnection(connection, config);
+  } catch (err) {
+    log.warn(
+      { err, connectionName },
+      "provider_connection auth resolution failed transiently — returning null",
+    );
+    return null;
+  }
+}
+
+/**
+ * Resolve the connection-aware default provider for the satellite
+ * construction-time path (subagent manager, conversation store,
+ * approval/guardian generators, rollup producer).
+ *
+ * Reads `config.llm.default.{provider, provider_connection}`.
+ *
+ *   - Throws `ConnectionResolutionError` if the default profile has no
+ *     `provider_connection` (boot-time backfill should have set one;
+ *     a missing connection name is a configuration bug).
+ *   - Throws on hard connection errors (lookup_failed, not_found,
+ *     provider_mismatch).
+ *   - Returns null on soft credential issues so satellites can early-
+ *     out gracefully (rollup producer skips, others throw with their
+ *     own message).
+ */
+export async function resolveDefaultProvider(
+  config: ProvidersConfig,
+): Promise<Provider | null> {
+  const resolved = resolveCallSiteConfig("mainAgent", config.llm);
+  const connectionName = resolved.provider_connection;
+  if (!connectionName) {
+    throw new ConnectionResolutionError(
+      "<llm.default>",
+      "missing_connection",
+      `llm.default.provider_connection is unset — every profile must declare a provider_connection. The boot-time backfill in lifecycle.ts populates this field; if you see this error, the backfill did not run or the field was manually cleared.`,
+    );
+  }
+  return tryResolveProviderForConnectionName(
+    connectionName,
+    config,
+    resolved.provider,
+  );
+}