@combycode/llm-sdk 2.2.2 → 3.0.0

package/dist/llm/types/request.d.ts

@@ -8,6 +8,49 @@ import type { AudioOptions } from './audio';
 import type { Message } from './messages';
 import type { ServiceTier } from './tiers';
 import type { Tool, ToolChoice } from './tools';
+/** Provider-specific request options that have no unified equivalent.
+ *
+ *  This was `Record<string, unknown>` — the one untyped hole in the request, and
+ *  therefore the one place a typo produced silence rather than an error:
+ *  `promtCacheOptions` type-checked and was simply never sent.
+ *
+ *  Every key below is one an adapter actually reads; the list is derived from
+ *  the read sites, not invented. The index signature stays so a caller can still
+ *  pass something the SDK does not know about yet — a provider ships a parameter
+ *  before we model it, and refusing it would make the escape hatch useless. What
+ *  changed is that the keys we DO know are checked and discoverable.
+ *
+ *  Keys are grouped by the provider that consumes them; sending one to a
+ *  different provider is ignored, not an error. */
+export interface ProviderOptions {
+    /** Forwarded as the `anthropic-user-profile-id` header: identifies the end
+     *  user a request acts on behalf of. Needs the account-level
+     *  `user-profiles` beta. */
+    userProfileId?: string;
+    /** Native moderation policy, sent alongside the `moderation` request field. */
+    moderationPolicy?: Record<string, unknown>;
+    /** `prompt_cache_options` — OpenAI-only prompt-cache controls. */
+    promptCacheOptions?: Record<string, unknown>;
+    /** `reasoning.mode` on the Responses API. */
+    reasoningMode?: 'standard' | 'pro';
+    /** Overrides `generationConfig.responseModalities`, e.g. for image or audio
+     *  generation. Wins over the modality implied by `outputModalities`. */
+    responseModalities?: string[];
+    /** `generationConfig.speechConfig` — voice selection for audio output. */
+    speechConfig?: Record<string, unknown>;
+    /** `generationConfig.imageConfig` — aspect ratio / size for image output. */
+    imageConfig?: Record<string, unknown>;
+    /** `generationConfig.translationConfig`. */
+    translationConfig?: Record<string, unknown>;
+    /** Name of a cached-content handle to reuse. Forwarded only when it is a
+     *  non-empty string. */
+    cachedContent?: string;
+    /** Routing options merged into the request body (provider order, transforms,
+     *  and the rest of OpenRouter's routing surface). */
+    openrouter?: Record<string, unknown>;
+    /** Anything the SDK does not model yet. Adapters ignore what they do not read. */
+    [key: string]: unknown;
+}
 export interface NormalizedRequest {
     /** From LLMClientConfig.model — fixed at construction. */
     model: string;
@@ -47,7 +90,12 @@ export interface NormalizedRequest {
     cache?: CacheConfig;
     serviceTier?: ServiceTier;
     moderation?: ModerationRequest;
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
+    /** Which wire spec builds this request, from the catalog's `ModelInfo.wireSpec`
+     *  and resolved by `LLMClient`. Absent when the engine runs without a catalog or
+     *  the model is not catalogued, in which case the adapter derives the spec from
+     *  the model id — the same fallback `wire` has. */
+    wireSpec?: string;
     audio?: AudioOptions;
     outputModalities?: Array<'text' | 'audio'>;
     previousResponseId?: string;

package/dist/llm/wire-multipart.d.ts

@@ -0,0 +1,26 @@
+/** Turn a spec's multipart DESCRIPTOR into a real FormData.
+ *
+ *  A spec can say that a request is multipart and which fields it carries, but not
+ *  what the bytes are — those come from a `FileAttachment` the caller holds. So the
+ *  interpreter emits `{ name, kind: 'file' | 'value', value? }` and this fills in
+ *  the one part it cannot: the file itself.
+ *
+ *  Kept out of `src/wire/` deliberately. The wire layer has no outbound imports and
+ *  no notion of an attachment; this is the seam where spec data meets the caller's
+ *  bytes, which makes it llm-layer glue rather than part of the interpreter.
+ */
+import type { MultipartField } from './../wire/interpreter';
+export interface MultipartFile {
+    /** The bytes, already read. */
+    data: Uint8Array;
+    filename: string;
+    mimeType: string;
+}
+/** Build the FormData a multipart spec describes.
+ *
+ *  Field ORDER follows the spec, because multipart is an ordered format and some
+ *  servers care. A `file` field with no file supplied is an error rather than an
+ *  omission: a silently fileless upload would be accepted by the type checker and
+ *  rejected by the provider, which is the exact failure mode the specs exist to
+ *  remove. */
+export declare function toFormData(fields: MultipartField[], file: MultipartFile): FormData;

package/dist/llm/wire-transforms.d.ts

@@ -0,0 +1,28 @@
+/** The named-code registry the wire specs delegate to.
+ *
+ *  Everything here is bound to the REAL library internals, never reimplemented —
+ *  if the interpreter's output matches the adapter's, it is because the spec
+ *  drove the same code, not because I wrote a second copy that happens to agree.
+ *
+ *  What lands in this file is the honest answer to "what cannot be data":
+ *  structural message/content transformation, schema-shape rules, and one
+ *  variant rule that is arithmetic rather than a pattern.
+ */
+import type { Registry } from '../wire/interpreter';
+/** Adapters whose private message builders we reuse. Instantiated once; the
+ *  builders are pure with respect to the request. */
+/** The hand-written adapter methods the specs cannot express as data.
+ *
+ *  All optional: a registry built by ONE adapter to drive its own spec carries only
+ *  its own handle, and each transform below is reached only from that provider's
+ *  spec. Requiring the full set would force every adapter to import every other
+ *  adapter just to build its own request. */
+export interface AdapterHandles {
+    anthropic?: any;
+    google?: any;
+    openaiResponses?: any;
+    openaiCompletions?: any;
+    googleInteractions?: any;
+    openrouterMedia?: any;
+}
+export declare function makeRegistry(a: AdapterHandles): Registry;

package/dist/plugins/context-measurer/counter/count-api.d.ts

@@ -1,14 +1,14 @@
 /** Count API adapter — exact token counting via provider endpoints. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { FetchFn } from '../../../network/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { EngineFetch } from '../../../network/types';
+import type { ModelCatalog } from '../../../catalog/catalog';
 /** Anthropic count endpoint: POST /v1/messages/count_tokens */
 export declare class AnthropicCountApi {
     private readonly apiKey;
     private readonly fetchFn;
     private readonly baseURL;
-    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
     countMessages(model: string, messages: Array<{
         role: string;
         content: unknown;
@@ -20,18 +20,52 @@ export declare class GoogleCountApi {
     private readonly apiKey;
     private readonly fetchFn;
     private readonly baseURL;
-    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
     countText(model: string, text: string): Promise<number>;
 }
-/** TokenCounter backed by Anthropic/Google count APIs. Falls back to heuristic
- *  for fast estimates and unknown providers. */
+/** xAI tokenizer: POST /v1/tokenize-text
+ *
+ *  Their own SDK reaches this over gRPC (`xai_api.Tokenize/TokenizeText`), which
+ *  is why it looked for a while like exact counting on xAI would cost a protobuf
+ *  dependency. It does not: the REST host answers the same call with the same
+ *  token list, so this is one more spec-built request and the library stays
+ *  zero-dependency.
+ *
+ *  What it counts is TEXT, not a chat request. Anthropic's and Google's endpoints
+ *  take the message array a completion would send, so their answer matches what
+ *  the completion is billed for; this one tokenizes the string you hand it, so it
+ *  is exact for that string and excludes the framing the chat template adds
+ *  around it. Still the right answer to "how many tokens is this content", and
+ *  vastly better than four-chars-per-token — on one Cyrillic line the heuristic
+ *  says 9 where the tokenizer says 19.
+ *
+ *  The response names the list `token_ids` (the proto calls it `tokens`); the
+ *  count is its length. */
+export declare class XAICountApi {
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly baseURL;
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
+    countText(model: string, text: string): Promise<number>;
+}
+/** TokenCounter backed by Anthropic/Google/xAI count APIs. Falls back to
+ *  heuristic for fast estimates and unknown providers. */
 export declare class CountApiCounter implements TokenCounter {
     private readonly providers;
     private heuristic;
+    private readonly catalog;
     constructor(catalog: ModelCatalog | null, providers?: {
         anthropic?: AnthropicCountApi;
         google?: GoogleCountApi;
+        xai?: XAICountApi;
     });
+    /** The id to SEND. `ctx.model` is our canonical slug — `claude-haiku-4.5` —
+     *  which is not what the provider answers to: its callable id is the dated
+     *  `claude-haiku-4-5-20251001`. The chat path translates through the catalog;
+     *  this one did not, so the moment a model's slug and api id differed the count
+     *  endpoint returned 404. Nothing noticed while the strategy was never
+     *  selected. */
+    private apiModel;
     estimate(text: string, ctx?: TokenCountContext): number;
     estimateMessage(msg: Message, ctx?: TokenCountContext): number;
     measure(text: string, ctx?: TokenCountContext): Promise<number>;

package/dist/plugins/context-measurer/counter/heuristic.d.ts

@@ -1,7 +1,7 @@
 /** Heuristic token counter — chars-per-token with optional calibration. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 import type { CalibrationStore } from '../types';
 /** Count chars across a message's content parts. */
 export declare function messageChars(msg: Message): number;

package/dist/plugins/context-measurer/counter/hybrid.d.ts

@@ -1,7 +1,8 @@
 /** HybridTokenCounter — selects strategy per model based on catalog config. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
+import type { EngineFetch } from '../../../network/types';
 import type { CalibrationStore } from '../types';
 export interface HybridCounterConfig {
     catalog?: ModelCatalog;
@@ -9,7 +10,14 @@ export interface HybridCounterConfig {
     countApiKeys?: {
         anthropic?: string;
         google?: string;
+        xai?: string;
     };
+    /** Required to use the exact count APIs: they are HTTP calls, and every HTTP
+     *  call in this library goes through the engine's fetch. Without it the exact
+     *  strategies are unavailable and counting falls back to the heuristic — which
+     *  is said out loud rather than done quietly, because a silent downgrade from
+     *  exact to estimated is invisible in the only place it matters: the number. */
+    fetch?: EngineFetch;
 }
 /**
  * HybridTokenCounter routes based on catalog's tokenizer.strategy:
@@ -24,6 +32,8 @@ export declare class HybridTokenCounter implements TokenCounter {
      *  counter. See CONSTITUTION.md standing decisions (2026-08-08). */
     private _tiktoken?;
     private countApi;
+    /** Said once per counter, not once per call. */
+    private warnedNoTiktoken;
     private readonly _config;
     constructor(config: HybridCounterConfig);
     warmCache(): Promise<void>;
@@ -31,6 +41,29 @@ export declare class HybridTokenCounter implements TokenCounter {
     estimateMessage(msg: Message, ctx?: TokenCountContext): number;
     measure(text: string, ctx?: TokenCountContext): Promise<number>;
     measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    /** Run the chosen strategy, falling back to the heuristic if — and ONLY if —
+     *  the optional `tiktoken` peer is not installed.
+     *
+     *  The catalog can name `tiktoken` for a model without the consumer having
+     *  installed it: it is an optional PEER dependency precisely so that most
+     *  people do not carry its 5.6 MB of wasm. Without this, marking OpenAI models
+     *  as exactly-countable would turn a number into a thrown error for everyone
+     *  who did not opt in — and the guide has always promised the opposite
+     *  ("without it everything still works").
+     *
+     *  Only THAT error is caught. A network failure inside the count API, or a
+     *  genuine tokenizer fault, still surfaces: silently answering with an estimate
+     *  when an exact count was asked for and was possible is how a wrong number
+     *  gets believed. */
+    private withoutOptionalPeer;
     learn(input: LearnInput): void;
+    /** Which strategy a context resolves to, without running it.
+     *
+     *  Public because a caller has to be able to ASK. `countTokens()` records a
+     *  zero-cost ledger entry for a count-API call, and it was deciding that from
+     *  the provider and the presence of a key — that is intent, not evidence. It now
+     *  asks what actually ran, so the ledger cannot claim a provider call that never
+     *  left the process. */
+    strategyNameFor(ctx?: TokenCountContext): 'tiktoken' | 'count_api' | 'heuristic';
     private strategyFor;
 }

package/dist/plugins/context-measurer/counter/tiktoken.d.ts

@@ -6,8 +6,15 @@
  */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+/** Marks the one error a caller is allowed to treat as "use something else". */
+export declare const TIKTOKEN_MISSING: unique symbol;
 /** Build the error thrown when the optional peer is missing. Exported for tests; not public API. */
 export declare function tiktokenUnavailableError(cause: unknown): Error;
+/** Is this the "tiktoken is not installed" error, rather than any other failure?
+ *
+ *  Matched on the marker below rather than on the message text, so rewording the
+ *  message cannot silently turn a graceful fallback into a thrown error. */
+export declare function isTiktokenUnavailable(err: unknown): boolean;
 export declare class TiktokenCounter implements TokenCounter {
     private encodings;
     estimate(text: string, ctx?: TokenCountContext): number;

package/dist/plugins/context-measurer/measurer.d.ts

@@ -4,7 +4,7 @@ import type { HookBus } from '../../bus/hook-bus';
 import type { Message } from '../../llm/types/messages';
 import type { TokenCounter } from '../../agent/types';
 import type { ConversationHistory } from '../../agent/history';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { Persistence } from '../persistence/types';
 import type { CalibrationStore, ContextThresholds, CalibrationConfig } from './types';
 export interface ContextMeasurerConfig {

package/dist/plugins/cost-collector/collector.d.ts

@@ -2,7 +2,7 @@
  *  pricing or provider-reported totals, emits onCostEntry/onBudgetWarning/
  *  onBudgetExceeded. */
 import type { CostEntry } from '../../bus/hook-map';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { Budget, CostCollectorConfig, CostFilter, CostSummary } from './cost-collector-types';
 export declare class CostCollector {
     private ledger;

package/dist/plugins/cost-collector/cost-collector-internal.d.ts

@@ -1,7 +1,7 @@
 /** CostCollector internals — pure cost-math + filtering helpers, split out of
  *  the class so each is independently testable. */
 import type { CostEntry } from '../../bus/hook-map';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import type { CostFilter, CostSummary } from './cost-collector-types';
 /** Pull provider-reported cost evidence out of a raw response body. */
 export declare function extractProviderCost(provider: string, raw: unknown): Record<string, unknown>;

package/dist/plugins/cost-collector/cost-collector-types.d.ts

@@ -1,6 +1,6 @@
 /** CostCollector public types: config, budgets, filters, summaries. */
 import type { HookBus } from '../../bus/hook-bus';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 export interface CostCollectorConfig {
     hooks: HookBus;
     catalog: ModelCatalog;

package/dist/plugins/files/registry.d.ts

@@ -3,7 +3,7 @@
  *  parts (provider_ref / inline base64 / url). */
 import type { HookBus } from '../../bus/hook-bus';
 import type { EngineFetch } from '../../network/types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import { FileAttachment, type FileContent } from './attachment';
 import type { FileProviderAdapter, RemoteFileInfo } from './provider-adapter';
 import { type FileStrategy } from './strategy';

package/dist/plugins/files/strategy.d.ts

@@ -1,5 +1,5 @@
 /** FileStrategy — pluggable decision maker for how to attach files. */
-import type { ModelInfo } from '../model-catalog/catalog';
+import type { ModelInfo } from '../../catalog/catalog';
 import type { FileAttachment } from './attachment';
 export interface FileStrategyContext {
     file: FileAttachment;

package/dist/plugins/internal-tools/registry.d.ts

@@ -1,6 +1,6 @@
 /** ToolRegistry — unified access across multiple backends with caching, search, filtering. */
 import type { InternalTool, ToolBackend, ToolFilter, SearchOptions } from './types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 export declare class ToolRegistry {
     private backends;
     private cache;

package/dist/plugins/internal-tools/runner/types.d.ts

@@ -3,7 +3,7 @@ import type { HookBus } from '../../../bus/hook-bus';
 import type { LLMClientConfig } from '../../../llm/client-config';
 import type { ProviderName } from '../../../llm/types/provider';
 import type { JsonSchema } from '../../../llm/types/tools';
-import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ModelCatalog } from '../../../catalog/catalog';
 import type { ToolRegistry } from '../registry';
 import type { CompatFile, ModelPreference } from '../types';
 import type { TokenCounter } from '../../../agent/types';

package/dist/plugins/mcp/sampling.d.ts

@@ -4,6 +4,7 @@
  *  custom handler or a model id to auto-wire. */
 import type { EngineHandle } from '../../helpers/engine';
 import type { ProviderName } from '../../llm/types/provider';
+import type { Message } from '../../llm/types/messages';
 import type { McpCreateMessageParams, McpCreateMessageResult } from './types';
 export type McpSamplingHandler = (params: McpCreateMessageParams) => Promise<McpCreateMessageResult>;
 /** Auto-wire sampling to our LLM. */
@@ -13,5 +14,26 @@ export interface McpSamplingViaLLM {
     engine?: EngineHandle;
 }
 export type McpSamplingConfig = McpSamplingHandler | McpSamplingViaLLM;
+/** The one thing this module needs from the ergonomic layer: run a completion.
+ *
+ *  Taken as a parameter rather than imported, because `plugins` importing
+ *  `helpers` closed a cycle (`helpers` already imports most of `plugins`). The
+ *  public `samplingHandler` lives in `helpers/mcp` and supplies `complete`; the
+ *  mapping between MCP's message shape and ours stays here, where it belongs. */
+export type McpCompleteFn = (args: {
+    model: string;
+    provider?: ProviderName;
+    engine?: EngineHandle;
+    system?: string;
+    prompt: Message[];
+    maxTokens?: number;
+    temperature?: number;
+}) => Promise<{
+    text: string;
+    response: {
+        model: string;
+        finishReason: string;
+    };
+}>;
 /** Build a sampling handler: pass-through a custom function, or auto-wire a model. */
-export declare function samplingHandler(config: McpSamplingConfig): McpSamplingHandler;
+export declare function samplingHandlerWith(complete: McpCompleteFn, config: McpSamplingConfig): McpSamplingHandler;

package/dist/plugins/mcp/transport-http.d.ts

@@ -62,13 +62,19 @@ export declare class HttpTransport extends BaseJsonRpcTransport implements McpTr
      *  two. The eventual JSON-RPC response has no pending entry to settle — its only meaning is "the
      *  stream ended", which is reported through `onEnd`. */
     sendLongLivedRequest(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<number>;
-    private headers;
-    /** Modern-era routing headers: `Mcp-Method` on every request, plus `Mcp-Name` carrying the
-     *  method's subject (tool name / prompt name / resource URI) so a gateway can route and
-     *  authorize without parsing the body. No-op on the handshake wire. */
-    private routingHeaders;
-    /** Base headers + any OAuth bearer + per-call extras. */
-    private authedHeaders;
+    /** The shared registry plus the two rules only MCP has. */
+    private readonly wireRegistry;
+    /** Build one MCP request from its spec.
+     *
+     *  Everything that varies — the negotiated era, the session, the declared
+     *  protocol version, a resolved bearer, the resumption cursor — is passed IN, so
+     *  the spec decides which headers those facts produce. That decision used to be
+     *  spread across three private helpers and the order in which their results were
+     *  spread into an object literal.
+     *
+     *  `provider` / `model` route and queue the call inside the NetworkEngine and are
+     *  not part of the wire, so they wrap the spec's output. */
+    private request0;
     private post;
 }
 /** Extract the JSON-RPC response matching `id` from a JSON or SSE body. */

package/dist/plugins/mcp/wire-rules.d.ts

@@ -0,0 +1,21 @@
+/** The two MCP rules a spec cannot express as data, and where they live.
+ *
+ *  Every other named spec rule sits in `src/llm/wire-transforms.ts`, but these
+ *  cannot: `llm -> plugins` is a forbidden edge (the layer test names it), and MCP
+ *  is a plugin. So the transport composes its own registry from the shared one
+ *  rather than the shared one reaching down into MCP.
+ *
+ *  Both are genuinely code rather than data:
+ *
+ *  `mcpModern` — era is set only AFTER discovery succeeds, so a request has to be
+ *  judged by the version it DECLARES as well. Keying on era alone left the
+ *  `server/discover` probe itself half-modern, which a modern server rejects.
+ *
+ *  `mcpNameHeader` — the subject lives under a different param per method (`name`
+ *  for tools/call and prompts/get, `uri` for resources/read), so this is a lookup
+ *  followed by a read at the key that lookup returned. A template can express a
+ *  fixed path, not a computed one.
+ */
+import type { Registry } from '../../wire/interpreter';
+/** Add the MCP rules to a base registry, leaving the base untouched. */
+export declare function mcpWireRegistry(base: Registry): Registry;

package/dist/plugins/media/output.d.ts

@@ -7,7 +7,7 @@
  *  by core LLM adapters + an onCompletion subscriber, NOT this class. */
 import type { HookBus } from '../../bus/hook-bus';
 import type { EngineFetch } from '../../network/types';
-import type { ModelCatalog } from '../model-catalog/catalog';
+import type { ModelCatalog } from '../../catalog/catalog';
 import { type AudioGenRequest, type ImageEditRequest, type ImageGenRequest, type MediaOutputConfig, type MediaProviderAdapter, type MediaResult, type MediaStore, type VideoGenRequest } from './types';
 export interface MediaOutputInit {
     hooks: HookBus;

package/dist/plugins/retrieval/document-file.d.ts

@@ -0,0 +1,15 @@
+/** The upload part for a document: its bytes, and a name for them.
+ *
+ *  All three hosted backends upload a document the same way — the text as a
+ *  `text/plain` file — and all three had their own copy of this, which is how they
+ *  came to disagree about nothing yet still had to be fixed three times.
+ *
+ *  The fallback name is derived from the CONTENT. It used to be a random UUID,
+ *  which made the request unreproducible: it could not be asserted in a test,
+ *  frozen in a fixture, or matched against a log, and a retried upload arrived
+ *  under a different name every time. A content hash keeps a retry idempotent
+ *  while still separating two different documents.
+ */
+import type { MultipartFile } from '../../llm/wire-multipart';
+import type { DocumentSource } from './types';
+export declare function documentFile(source: DocumentSource): MultipartFile;

package/dist/plugins/retrieval/hosted-google.d.ts

@@ -38,9 +38,14 @@ export declare class HostedGoogleRetrievalBackend implements RetrievalBackend {
     private readonly fetch;
     private readonly baseURL;
     constructor(config: HostedGoogleRetrievalConfig);
-    private authHeaders;
-    /** Auth headers for multipart/form-data file upload (no content-type override). */
-    private authHeadersNoContentType;
+    /** File-search rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one file-search request from its spec, then add the engine metadata.
+     *
+     *  `provider` / `model` / `responseType` route and queue the call inside the
+     *  NetworkEngine; they are not part of the wire, so they wrap the spec's output
+     *  rather than being described by it. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     /** Poll a long-running Operation until done: true.

package/dist/plugins/retrieval/hosted-openai.d.ts

@@ -29,7 +29,15 @@ export declare class HostedOpenAIRetrievalBackend implements RetrievalBackend {
     private readonly fetch;
     private readonly baseURL;
     constructor(config: HostedOpenAIRetrievalConfig);
-    private bearer;
+    /** Vector-store rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one vector-store request from its spec, then add the engine metadata.
+     *
+     *  `provider` / `model` / `responseType` are how the NetworkEngine routes and
+     *  queues the call — they are not part of the wire, so they are wrapped around
+     *  the spec's output rather than described by it. A multipart spec names the
+     *  fields but not the bytes, so an upload passes its file in here. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     indexStatus(corpus: CorpusRef): Promise<IndexStatus>;

package/dist/plugins/retrieval/hosted-xai.d.ts

@@ -41,8 +41,14 @@ export declare class HostedXaiRetrievalBackend implements RetrievalBackend {
     private readonly baseURL;
     private readonly managementBaseURL;
     constructor(config: HostedXaiRetrievalConfig);
-    private stdBearer;
-    private mgmtBearer;
+    /** Collection rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one collections request from its spec, then add the engine metadata.
+     *
+     *  BOTH planes are handed to every spec: which host and which key a call uses is
+     *  a property of the ENDPOINT, so the spec decides it rather than the caller
+     *  picking a bearer helper and hoping it matches the URL it typed. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     indexStatus(corpus: CorpusRef): Promise<IndexStatus>;