@vellumai/assistant 0.6.6 → 0.7.1

package/src/providers/retry.ts

@@ -1,5 +1,9 @@
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import { getConfig } from "../config/loader.js";
+import {
+  resolveUsageAttribution,
+  sanitizeUsageMetadataValue,
+} from "../usage/attribution.js";
 import { ProviderError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import {
@@ -9,6 +13,10 @@ import {
   isRetryableNetworkError,
   sleep,
 } from "../util/retry.js";
+import {
+  isThinkingConfigDisabled,
+  normalizeThinkingConfigForWire,
+} from "./thinking-config.js";
 import {
   isContextOverflowError,
   type Message,
@@ -20,6 +28,14 @@ import {
 
 const log = getLogger("retry");
 
+const USAGE_ATTRIBUTION_HEADER_NAMES = {
+  callSite: "X-Vellum-LLM-Call-Site",
+  inferenceProfile: "X-Vellum-Inference-Profile",
+  inferenceProfileSource: "X-Vellum-Inference-Profile-Source",
+  resolvedProvider: "X-Vellum-Resolved-Provider",
+  resolvedModel: "X-Vellum-Resolved-Model",
+} as const;
+
 /** Providers that support the `effort` config (extended thinking / reasoning). */
 const EFFORT_SUPPORTED_PROVIDERS = new Set([
   "anthropic",
@@ -30,11 +46,17 @@ const EFFORT_SUPPORTED_PROVIDERS = new Set([
 
 /**
  * Providers that consume the `thinking` config. Anthropic uses it directly on
- * the wire; OpenRouter translates it into its unified `reasoning` parameter so
- * users can control extended thinking on Anthropic models served via OpenRouter.
+ * the wire; OpenRouter either forwards it to its Anthropic-compatible path or
+ * translates it into the unified `reasoning` parameter on OpenAI-compat calls.
  */
 const THINKING_AWARE_PROVIDERS = new Set(["anthropic", "openrouter"]);
 
+/**
+ * Providers that consume the `verbosity` config. Currently OpenAI (mapped to
+ * `text.verbosity` on the Responses API — a GPT-5-series parameter).
+ */
+const VERBOSITY_SUPPORTED_PROVIDERS = new Set(["openai"]);
+
 /** Patterns that indicate a transient streaming corruption from the SDK. */
 const RETRYABLE_STREAM_PATTERNS = [
   "Unexpected event order",
@@ -88,43 +110,73 @@ function isRetryableError(error: unknown): boolean {
  * Normalize per-call options before handing them to the wrapped provider.
  *
  * When `config.callSite` is set, resolves model/maxTokens/effort/speed/
- * temperature/thinking via `resolveCallSiteConfig` and writes them into
- * `nextConfig` using the wire-format names that downstream provider clients
- * consume (`max_tokens` snake-case for the token cap; camelCase for the rest,
- * which matches the resolver's shape). Per-call explicit overrides on the
- * original `config` object win over the resolved values, so callers can pin
- * a model or other parameter for a single request. `contextWindow` and
+ * verbosity/temperature/thinking via `resolveCallSiteConfig` and writes them
+ * into `nextConfig` using the wire-format names that downstream provider
+ * clients consume (`max_tokens` snake-case for the token cap; camelCase for
+ * the rest, which matches the resolver's shape). Per-call explicit overrides
+ * on the original `config` object win over the resolved values, so callers can
+ * pin a model or other parameter for a single request. `contextWindow` and
  * `provider` are intentionally excluded from the written fields — they are
  * server-side routing/overflow concerns, not provider request parameters,
  * and forwarding them would leak unknown fields into provider request bodies
  * (strict-schema clients like Anthropic reject the request).
  *
  * Whether or not `callSite` is set, this function applies per-provider
- * stripping (`thinking`/`effort`/`speed`) based on the wrapped provider's
- * name — agent-loop callers that pre-resolve provider/model still need this
- * stripping so they don't accidentally send Anthropic-only knobs to OpenAI
- * etc.
+ * stripping (`thinking`/`effort`/`speed`/`verbosity`) based on the wrapped
+ * provider's name — agent-loop callers that pre-resolve provider/model still
+ * need this stripping so they don't accidentally send Anthropic-only knobs to
+ * OpenAI etc.
  */
 function normalizeSendMessageOptions(
   providerName: string,
   options?: SendMessageOptions,
+  normalizeOptions: { forwardUsageAttributionHeaders?: boolean } = {},
 ): SendMessageOptions | undefined {
   const config = options?.config;
   if (!config) return options;
 
   const nextConfig: Record<string, unknown> = { ...config };
 
+  // Internal metadata must be derived here, not accepted from callers, and it
+  // must never leak into provider JSON request bodies.
+  delete nextConfig.usageAttributionHeaders;
+  delete nextConfig.usageTracking;
+
+  // `overrideProfile` is a routing/resolution-time concern (consumed by the
+  // resolver below and `CallSiteRoutingProvider`'s provider selection); it is
+  // not a wire-format field. Strip unconditionally so it never leaks into
+  // provider request bodies even when callers set it without a `callSite`.
+  delete nextConfig.overrideProfile;
+
   if (config.callSite !== undefined) {
-    const resolved = resolveCallSiteConfig(config.callSite, getConfig().llm);
+    const resolved = resolveCallSiteConfig(config.callSite, getConfig().llm, {
+      overrideProfile: config.overrideProfile,
+    });
+    const attribution = resolveUsageAttribution({
+      callSite: config.callSite,
+      overrideProfile: config.overrideProfile,
+    });
 
     const explicitModel =
       typeof config.model === "string" && config.model.trim().length > 0
         ? config.model.trim()
         : undefined;
 
-    // Routing key is consumed by the RetryProvider layer and must not leak
-    // downstream.
+    // Routing key is consumed by the resolver above and must not leak
+    // downstream as a wire-format field.
     delete nextConfig.callSite;
+    if (normalizeOptions.forwardUsageAttributionHeaders === true) {
+      const usageAttributionHeaders = buildUsageAttributionHeaders({
+        callSite: attribution.callSite,
+        appliedProfile: attribution.appliedProfile,
+        profileSource: attribution.profileSource,
+        resolvedProvider: attribution.resolvedProvider,
+        resolvedModel: attribution.resolvedModel,
+      });
+      if (Object.keys(usageAttributionHeaders).length > 0) {
+        nextConfig.usageAttributionHeaders = usageAttributionHeaders;
+      }
+    }
 
     // Apply resolved values, letting per-call explicit fields win where set.
     nextConfig.model = explicitModel ?? resolved.model;
@@ -137,6 +189,9 @@ function normalizeSendMessageOptions(
     if (nextConfig.speed === undefined) {
       nextConfig.speed = resolved.speed;
     }
+    if (nextConfig.verbosity === undefined) {
+      nextConfig.verbosity = resolved.verbosity;
+    }
     // `temperature` defaults to `null` in the LLM schema (meaning "no opinion
     // — let the provider pick its own default"). Only forward when the
     // resolved value is an actual number; passing `temperature: null` to
@@ -151,16 +206,14 @@ function normalizeSendMessageOptions(
       nextConfig.temperature = resolved.temperature;
     }
     if (nextConfig.thinking === undefined) {
-      // Convert the schema-shape `{ enabled, streamThinking }` into the
-      // Anthropic wire-format `{ type: "adaptive" }` (or omit when disabled).
-      // Mirrors the non-callSite path in `agent/loop.ts` which sets
-      // `providerConfig.thinking = { type: "adaptive" }` only when enabled.
+      // Convert the schema-shape `{ enabled, streamThinking }` into Anthropic's
+      // discriminated wire-format (`{ type: "adaptive" | "disabled" }`).
       // Without this conversion, `thinking` arrives at `AnthropicProvider`
       // with a shape the SDK doesn't accept (`ThinkingConfigParam` requires
-      // a `type` discriminator), and OpenRouter's truthy check would treat
-      // a disabled config as enabled.
-      if (resolved.thinking?.enabled === true) {
-        nextConfig.thinking = { type: "adaptive" };
+      // a `type` discriminator).
+      const thinking = normalizeThinkingConfigForWire(resolved.thinking);
+      if (thinking !== undefined) {
+        nextConfig.thinking = thinking;
       }
     }
     // Forward OpenRouter-only routing preferences so `OpenRouterProvider` can
@@ -175,12 +228,11 @@ function normalizeSendMessageOptions(
       nextConfig.openrouter = { only: resolved.openrouter.only };
     }
     // `contextWindow` and `provider` are server-side concerns, not provider
-    // request parameters: `contextWindow` is consumed by the agent loop's
-    // overflow recovery and the conversation manager directly from
-    // `config.llm.default.contextWindow.*`; `provider` selection is handled
-    // by `CallSiteRoutingProvider` upstream. Forwarding them as per-call
-    // config leaks unknown fields into provider request bodies — Anthropic
-    // (and other strict-schema clients) reject the request with
+    // request parameters: effective context is resolved per call site/profile
+    // by the agent/conversation path, while `provider` selection is handled by
+    // `CallSiteRoutingProvider` upstream. Forwarding them as per-call config
+    // leaks unknown fields into provider request bodies — Anthropic (and other
+    // strict-schema clients) reject the request with
     // "Extra inputs are not permitted".
   }
 
@@ -206,6 +258,7 @@ function normalizeSendMessageOptions(
   // and may support reasoning with forced tool_choice.
   const isThinkingForcedToolConflict = (() => {
     if (nextConfig.thinking == null) return false;
+    if (isThinkingConfigDisabled(nextConfig.thinking)) return false;
     const tc = nextConfig.tool_choice as Record<string, unknown> | undefined;
     if (tc == null || (tc.type !== "tool" && tc.type !== "any")) return false;
     if (providerName === "anthropic") return true;
@@ -233,6 +286,15 @@ function normalizeSendMessageOptions(
     delete nextConfig.speed;
   }
 
+  // verbosity maps to OpenAI's `text.verbosity` (Responses API); strip for
+  // providers that don't accept it to avoid leaking unknown fields on the wire.
+  if (
+    !VERBOSITY_SUPPORTED_PROVIDERS.has(providerName) &&
+    nextConfig.verbosity !== undefined
+  ) {
+    delete nextConfig.verbosity;
+  }
+
   // `openrouter.only` is OpenRouter-specific routing; strip for other
   // providers so strict-schema clients don't see an unknown field.
   if (providerName !== "openrouter" && nextConfig.openrouter !== undefined) {
@@ -245,6 +307,55 @@ function normalizeSendMessageOptions(
   };
 }
 
+function buildUsageAttributionHeaders(input: {
+  callSite: string | null;
+  appliedProfile: string | null;
+  profileSource: string;
+  resolvedProvider: string;
+  resolvedModel: string;
+}): Record<string, string> {
+  const headers: Record<string, string> = {};
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.callSite,
+    input.callSite,
+  );
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.inferenceProfile,
+    input.appliedProfile,
+  );
+  if (input.appliedProfile) {
+    addSanitizedHeader(
+      headers,
+      USAGE_ATTRIBUTION_HEADER_NAMES.inferenceProfileSource,
+      input.profileSource,
+    );
+  }
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.resolvedProvider,
+    input.resolvedProvider,
+  );
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.resolvedModel,
+    input.resolvedModel,
+  );
+  return headers;
+}
+
+function addSanitizedHeader(
+  headers: Record<string, string>,
+  name: string,
+  value: unknown,
+): void {
+  const sanitized = sanitizeUsageMetadataValue(value);
+  if (sanitized != null) {
+    headers[name] = sanitized;
+  }
+}
+
 /**
  * `RetryProvider` sets `retriesExhausted = true` on the final thrown error
  * when the retry loop burned through all attempts against a retryable error
@@ -260,7 +371,10 @@ export class RetryProvider implements Provider {
     return this.inner.tokenEstimationProvider;
   }
 
-  constructor(private readonly inner: Provider) {
+  constructor(
+    private readonly inner: Provider,
+    private readonly options: { forwardUsageAttributionHeaders?: boolean } = {},
+  ) {
     this.name = inner.name;
   }
 
@@ -273,7 +387,10 @@ export class RetryProvider implements Provider {
     let lastError: unknown;
     let didRetry = false;
 
-    const normalizedOptions = normalizeSendMessageOptions(this.name, options);
+    const normalizedOptions = normalizeSendMessageOptions(this.name, options, {
+      forwardUsageAttributionHeaders:
+        this.options.forwardUsageAttributionHeaders === true,
+    });
 
     for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
       try {

package/src/providers/speech-to-text/openai-whisper-stream.ts

@@ -50,7 +50,7 @@ const log = getLogger("openai-whisper-stream");
  * OpenAI Whisper remains incremental-batch (not true token streaming), but
  * a tighter poll cadence reduces perceived latency for partial updates.
  */
-export const POLL_INTERVAL_MS = 400;
+const POLL_INTERVAL_MS = 400;
 
 /**
  * Timeout per incremental poll request (ms).

package/src/providers/speech-to-text/openai-whisper.ts

@@ -1,13 +1,13 @@
 import type { SttTranscribeResult } from "../../stt/types.js";
 
-export const WHISPER_API_URL = "https://api.openai.com/v1/audio/transcriptions";
+const WHISPER_API_URL = "https://api.openai.com/v1/audio/transcriptions";
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
  * Derive a filename extension from a MIME type so the Whisper API can detect
  * the audio format. Falls back to "audio" when the MIME type is unrecognised.
  */
-export function extensionFromMime(mimeType: string): string {
+function extensionFromMime(mimeType: string): string {
   const map: Record<string, string> = {
     "audio/wav": "wav",
     "audio/x-wav": "wav",
@@ -30,10 +30,7 @@ export function extensionFromMime(mimeType: string): string {
  * Shared between the batch provider and the streaming adapter to avoid
  * duplicating request construction logic.
  */
-export function buildWhisperFormData(
-  audio: Buffer,
-  mimeType: string,
-): FormData {
+function buildWhisperFormData(audio: Buffer, mimeType: string): FormData {
   const ext = extensionFromMime(mimeType);
 
   const formData = new FormData();

package/src/providers/speech-to-text/provider-catalog.ts

@@ -79,6 +79,20 @@ export interface TelephonyRouting {
   readonly twilioNativeMapping?: TwilioNativeMapping;
 }
 
+// ---------------------------------------------------------------------------
+// Client display metadata
+// ---------------------------------------------------------------------------
+
+/** How the provider's credentials are configured by the user. */
+export type SttSetupMode = "api-key" | "cli";
+
+/** Guide for obtaining API credentials from a provider. */
+export interface SttCredentialsGuide {
+  readonly description: string;
+  readonly url: string;
+  readonly linkLabel: string;
+}
+
 // ---------------------------------------------------------------------------
 // Catalog entry
 // ---------------------------------------------------------------------------
@@ -90,6 +104,18 @@ export interface SttProviderEntry {
   /** Canonical provider identifier (must match an {@link SttProviderId} variant). */
   readonly id: SttProviderId;
 
+  /** Human-readable name for display in settings UI. */
+  readonly displayName: string;
+
+  /** Short description shown below the provider selector. */
+  readonly subtitle: string;
+
+  /** How the provider's credentials are configured. */
+  readonly setupMode: SttSetupMode;
+
+  /** Brief help text guiding the user through setup. */
+  readonly setupHint: string;
+
   /**
    * Name of the credential provider used by `getProviderKeyAsync` to
    * retrieve the API key. Multiple STT providers may share a credential
@@ -141,6 +167,9 @@ export interface SttProviderEntry {
    * strategy selection and Twilio-native mapping details.
    */
   readonly telephonyRouting: TelephonyRouting;
+
+  /** Guide for obtaining API credentials from this provider. */
+  readonly credentialsGuide?: SttCredentialsGuide;
 }
 
 // ---------------------------------------------------------------------------
@@ -164,6 +193,11 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
     "deepgram",
     {
       id: "deepgram",
+      displayName: "Deepgram",
+      subtitle:
+        "Fast, real-time speech-to-text with streaming support. Requires a Deepgram API key.",
+      setupMode: "api-key",
+      setupHint: "Enter your Deepgram API key to enable speech-to-text.",
       credentialProvider: "deepgram",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -179,12 +213,24 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
           defaultSpeechModel: "nova-3",
         },
       },
+      credentialsGuide: {
+        description:
+          "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
+        url: "https://console.deepgram.com/",
+        linkLabel: "Open Deepgram Console",
+      },
     },
   ],
   [
     "google-gemini",
     {
       id: "google-gemini",
+      displayName: "Google Gemini",
+      subtitle:
+        "Multimodal speech-to-text powered by Google Gemini. Requires a Gemini API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your Gemini API key to enable Google Gemini transcription.",
       credentialProvider: "gemini",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -200,12 +246,24 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
           defaultSpeechModel: undefined,
         },
       },
+      credentialsGuide: {
+        description:
+          "Visit Google AI Studio, sign in with your Google account, and create an API key.",
+        url: "https://aistudio.google.com/apikey",
+        linkLabel: "Open Google AI Studio",
+      },
     },
   ],
   [
     "openai-whisper",
     {
       id: "openai-whisper",
+      displayName: "OpenAI Whisper",
+      subtitle:
+        "High-accuracy speech-to-text powered by OpenAI Whisper. Requires an OpenAI API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your OpenAI API key to enable Whisper transcription.",
       credentialProvider: "openai",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -217,12 +275,23 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyRouting: {
         strategyKind: "media-stream-custom",
       },
+      credentialsGuide: {
+        description:
+          "Log in to the OpenAI platform, go to API Keys, and generate a new secret key.",
+        url: "https://platform.openai.com/api-keys",
+        linkLabel: "Open OpenAI Platform",
+      },
     },
   ],
   [
     "xai",
     {
       id: "xai",
+      displayName: "xAI",
+      subtitle:
+        "Real-time speech-to-text powered by xAI. Requires an xAI API key.",
+      setupMode: "api-key",
+      setupHint: "Enter your xAI API key to enable xAI transcription.",
       credentialProvider: "xai",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -234,6 +303,12 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyRouting: {
         strategyKind: "media-stream-custom",
       },
+      credentialsGuide: {
+        description:
+          "Sign in to the xAI console, navigate to API Keys, and create a new key.",
+        url: "https://console.x.ai/",
+        linkLabel: "Open xAI Console",
+      },
     },
   ],
 ]);

package/src/providers/speech-to-text/xai.ts

@@ -1,13 +1,13 @@
 import type { SttTranscribeResult } from "../../stt/types.js";
 
-export const XAI_STT_URL = "https://api.x.ai/v1/stt";
-export const DEFAULT_TIMEOUT_MS = 60_000;
+const XAI_STT_URL = "https://api.x.ai/v1/stt";
+const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
  * Derive a filename extension from a MIME type so the xAI STT API can detect
  * the audio format. Falls back to "audio" when the MIME type is unrecognised.
  */
-export function extensionFromMime(mimeType: string): string {
+function extensionFromMime(mimeType: string): string {
   const map: Record<string, string> = {
     "audio/wav": "wav",
     "audio/x-wav": "wav",
@@ -31,7 +31,7 @@ export function extensionFromMime(mimeType: string): string {
  * `file` field to be appended LAST in the multipart body, so we only append
  * the file here (no other fields in v1).
  */
-export function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
+function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
   const ext = extensionFromMime(mimeType);
 
   const formData = new FormData();
@@ -51,7 +51,7 @@ export function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
  * xAI returns a richer shape (`{ text, language, duration, words }`) — we only
  * consume `text`.
  */
-export async function xaiTranscribe(
+async function xaiTranscribe(
   apiKey: string,
   audio: Buffer,
   mimeType: string,

package/src/providers/thinking-config.ts

@@ -0,0 +1,34 @@
+type ThinkingConfigRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is ThinkingConfigRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeThinkingConfigForWire(
+  thinking: unknown,
+): ThinkingConfigRecord | undefined {
+  if (!isRecord(thinking)) return undefined;
+
+  if (typeof thinking.type === "string") {
+    return thinking;
+  }
+
+  if (thinking.enabled === true) {
+    return { type: "adaptive" };
+  }
+
+  if (thinking.enabled === false) {
+    return { type: "disabled" };
+  }
+
+  return undefined;
+}
+
+export function isThinkingConfigDisabled(thinking: unknown): boolean {
+  return normalizeThinkingConfigForWire(thinking)?.type === "disabled";
+}
+
+export function isThinkingConfigEnabled(thinking: unknown): boolean {
+  const normalized = normalizeThinkingConfigForWire(thinking);
+  return normalized !== undefined && normalized.type !== "disabled";
+}

package/src/providers/types.ts

@@ -1,3 +1,6 @@
+import type { ToolDefinition } from "@vellumai/skill-host-contracts";
+export type { ToolDefinition };
+
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { ProviderError } from "../util/errors.js";
 
@@ -31,6 +34,11 @@ export interface ToolUseContent {
   id: string;
   name: string;
   input: Record<string, unknown>;
+  providerMetadata?: {
+    gemini?: {
+      thoughtSignature?: string;
+    };
+  };
 }
 
 export interface ThinkingContent {
@@ -82,12 +90,6 @@ export interface Message {
   content: ContentBlock[];
 }
 
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  input_schema: object;
-}
-
 export type ModelIntent =
   | "latency-optimized"
   | "quality-optimized"
@@ -140,13 +142,36 @@ export interface SendMessageConfig {
   model?: string;
   /**
    * LLM call-site identifier. `RetryProvider` resolves
-   * provider/model/maxTokens/effort/speed/temperature/thinking/contextWindow
-   * via `resolveCallSiteConfig(callSite, config.llm)`, falling back to
-   * `llm.default` when no callSite-specific entry is present.
+   * provider/model/maxTokens/effort/speed/verbosity/temperature/thinking/
+   * contextWindow via `resolveCallSiteConfig(callSite, config.llm)`, falling
+   * back to `llm.default` when no callSite-specific entry is present.
    */
   callSite?: LLMCallSite;
-  effort?: "low" | "medium" | "high" | "xhigh" | "max";
+  /**
+   * Optional ad-hoc profile override applied per request. When set, the
+   * resolver layers `llm.profiles[overrideProfile]` between the workspace's
+   * `activeProfile` and the call-site's named profile (see
+   * `resolveCallSiteConfig`). Used by per-conversation pinned profiles to
+   * override the workspace default for a single send. Missing profile names
+   * silently fall through.
+   */
+  overrideProfile?: string;
+  /**
+   * Internal per-request HTTP headers for managed-proxy usage attribution.
+   * Provider clients may pass these through SDK request options only when the
+   * transport is Vellum-managed, and must never include this object in provider
+   * JSON request bodies.
+   */
+  usageAttributionHeaders?: Record<string, string>;
+  /**
+   * Controls local usage-ledger writes for attributed provider calls.
+   * Defaults to `auto`; conversation paths that aggregate usage separately
+   * set `manual` to avoid double-counting.
+   */
+  usageTracking?: "auto" | "manual";
+  effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
+  verbosity?: "low" | "medium" | "high";
   [key: string]: unknown;
 }