@combycode/llm-sdk 1.0.0-rc.0

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

@@ -0,0 +1,146 @@
+/** Media subsystem types — storage, generation requests, results,
+ *  and provider adapter contract. */
+import type { DataSource } from '../../llm/types/messages';
+import type { Usage } from '../../llm/types/response';
+export type MediaType = 'image' | 'audio' | 'video';
+export interface MediaMeta {
+    id: string;
+    type: MediaType;
+    mimeType: string;
+    size: number;
+    createdAt: number;
+    provider: string;
+    model?: string;
+    prompt?: string;
+    revisedPrompt?: string;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    sampleRate?: number;
+    params?: Record<string, unknown>;
+}
+export interface MediaStore {
+    save(id: string, data: Uint8Array, meta: MediaMeta): Promise<void>;
+    load(id: string): Promise<{
+        data: Uint8Array;
+        meta: MediaMeta;
+    } | null>;
+    getMeta(id: string): Promise<MediaMeta | null>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        type?: MediaType;
+        provider?: string;
+    }): Promise<string[]>;
+    has(id: string): Promise<boolean>;
+}
+export interface ImageGenRequest {
+    provider: string;
+    model?: string;
+    prompt: string;
+    params?: {
+        n?: number;
+        size?: string;
+        aspectRatio?: string;
+        /** Google `sampleImageSize` / Gemini `imageSize` (e.g. "1K", "2K"). */
+        imageSize?: string;
+        resolution?: string;
+        quality?: string;
+        /** OpenAI gpt-image `background` (transparent|opaque|auto). */
+        background?: string;
+        /** OpenAI gpt-image `output_format` (png|jpeg|webp). */
+        outputFormat?: string;
+        style?: string;
+        /** OpenRouter image-to-image strength (0–1; lower = closer to the input). */
+        strength?: number;
+        responseFormat?: 'b64_json' | 'url';
+    };
+}
+export interface ImageEditRequest extends ImageGenRequest {
+    sourceImage: DataSource;
+    mask?: DataSource;
+}
+export interface AudioGenRequest {
+    provider: string;
+    model?: string;
+    input: string;
+    params?: {
+        voice?: string;
+        format?: string;
+        speed?: number;
+        instructions?: string;
+        sampleRate?: number;
+        language?: string;
+    };
+}
+export interface VideoGenRequest {
+    provider: string;
+    model?: string;
+    prompt: string;
+    sourceImage?: DataSource;
+    params?: {
+        duration?: number;
+        aspectRatio?: string;
+        resolution?: string;
+        /** OpenAI Sora literal pixel `size` (e.g. "720x1280"). */
+        size?: string;
+    };
+}
+export interface MediaResult {
+    id: string;
+    type: MediaType;
+    mimeType: string;
+    meta: MediaMeta;
+}
+export interface RawMediaResult {
+    data: Uint8Array;
+    mimeType: string;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    sampleRate?: number;
+    revisedPrompt?: string;
+    /** Token usage the provider reported (token-priced media: gpt-image,
+     *  gemini-tts). Drives accurate cost via the catalog's per-token rates. */
+    usage?: Usage;
+    providerMeta?: Record<string, unknown>;
+}
+export interface VideoStatus {
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    progress?: number;
+    error?: string;
+}
+import type { EngineFetch } from '../../network/types';
+export interface MediaCapabilities {
+    imageGeneration: boolean;
+    imageEditing: boolean;
+    audioGeneration: boolean;
+    videoGeneration: boolean;
+    audioStreaming: boolean;
+}
+/** All MediaProviderAdapter HTTP calls now go through the NetworkEngine
+ *  queue (rate limits, retries, hooks, observability) instead of holding a
+ *  private `fetchFn`. The adapter receives an EngineFetch per call from
+ *  MediaOutput, which in turn was given engine.fetch by the caller.
+ *
+ *  Adapter responsibilities:
+ *    - Build the right URL / headers / body for a provider operation.
+ *    - Choose the correct response shape via HttpRequest.responseType
+ *      ('json' for image-gen / video-status, 'arraybuffer' for binary
+ *      audio / video downloads).
+ *    - Parse the response body returned by EngineFetch into RawMediaResult. */
+export interface MediaProviderAdapter {
+    readonly name: string;
+    capabilities(): MediaCapabilities;
+    generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    editImage?(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
+    submitVideo?(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
+    getVideoStatus?(operationId: string, fetch: EngineFetch): Promise<VideoStatus>;
+    downloadVideo?(operationId: string, fetch: EngineFetch): Promise<RawMediaResult>;
+    cancelVideo?(operationId: string, fetch: EngineFetch): Promise<void>;
+}
+export interface MediaOutputConfig {
+    pollIntervalMs?: number;
+    maxPollWaitMs?: number;
+}
+export declare const MEDIA_OUTPUT_DEFAULTS: Required<MediaOutputConfig>;

package/dist/plugins/model-catalog/catalog.d.ts

@@ -0,0 +1,152 @@
+/** ModelCatalog — pricing, capabilities, and model info. Loaded from JSON. */
+export type ApiType = 'responses' | 'completions' | 'interactions' | 'generate' | 'messages';
+export interface ModelPricing {
+    inputPerMTok?: number;
+    outputPerMTok?: number;
+    cacheReadPerMTok?: number;
+    cacheWritePerMTok?: number;
+    /** Audio token rates (realtime / audio models), per 1M tokens. */
+    audioInputPerMTok?: number;
+    audioOutputPerMTok?: number;
+    perImage?: number;
+    perSecond?: number;
+    /** Speech-to-text transcription rate (USD per minute of audio). Used by
+     *  whisper-class and gpt-4o-transcribe when the provider bills by duration,
+     *  not by token. The cost engine multiplies by audio duration in minutes. */
+    perMinute?: number;
+    perMChars?: number;
+    /** Per-unit rates keyed by a quality/resolution tier (e.g. video
+     *  `{"720p":0.1,"1080p":0.12}`, image `{"1k":0.002,"2k":0.02}`). When the
+     *  selected resolution matches a key, it overrides the flat perImage/perSecond. */
+    perUnit?: Record<string, number>;
+    /** Per-service-tier rate overrides, keyed by the provider's OWN billed tier
+     *  name (the value the provider returns: anthropic `standard|priority|batch`,
+     *  openai `flex|scale|priority|batch`). The flat fields above are the implicit
+     *  `standard` tier. Cost looks up `tiers[usage.pricingTier]`, falling back to
+     *  the flat fields — so models without tiers behave exactly as before. */
+    tiers?: Record<string, TierRates>;
+}
+/** One service tier's rate overrides — same shape as the flat rates, no nesting. */
+export type TierRates = Omit<ModelPricing, 'tiers'>;
+export interface ModelCapabilities {
+    toolUse: boolean;
+    builtinTools?: string[];
+    streaming: boolean;
+    structuredOutput: boolean;
+    vision: boolean;
+    audio: boolean;
+    video: boolean;
+    imageGeneration: boolean;
+    audioGeneration: boolean;
+    videoGeneration: boolean;
+}
+/** One generation parameter a media model accepts, with its allowed values.
+ *  Either an enum (`values` + `default`) or a numeric range (`min`/`max`).
+ *  Keys are normalized (e.g. `aspectRatio`, `size`, `voice`, `duration`); each
+ *  provider adapter maps the normalized key to its own wire param name. */
+export interface MediaParamSpec {
+    /** Enumerated allowed values for a string param. */
+    values?: string[];
+    /** Numeric bounds for an integer param (e.g. duration seconds, image count). */
+    min?: number;
+    max?: number;
+    /** Default value (blank/omitted means "let the provider decide"). */
+    default?: string | number;
+    /** Where the allowed values came from + when last verified. */
+    source?: string;
+    verifiedOn?: string;
+}
+export interface ModelReasoning {
+    supported: boolean;
+    automatic: boolean;
+    effortControl: boolean;
+    effortValues?: string[];
+    encryptedContent: boolean;
+    summaryAvailable: boolean;
+}
+export interface TokenizerInfo {
+    strategy: 'heuristic' | 'tiktoken' | 'count_api';
+    charsPerTokenDefault: number;
+    countApiAvailable: boolean;
+    tiktokenEncoding?: string;
+}
+export interface ModelInfo {
+    provider: string;
+    /** Catalog key — our canonical (normalised) slug, e.g. `claude-opus-4.8`. */
+    model: string;
+    pricing: ModelPricing;
+    preferredApi: ApiType;
+    supportedApis: ApiType[];
+    contextWindow?: number;
+    maxOutput?: number;
+    capabilities: ModelCapabilities;
+    reasoning: ModelReasoning;
+    mediaOnly?: boolean;
+    tokenizer?: TokenizerInfo;
+    requiresDedicatedClient?: boolean;
+    supportsPreviousResponseId?: boolean;
+    /** Exact id to SEND to the provider API (may differ from the slug + carry
+     *  dates). When set, the SDK sends this; otherwise it sends `model`. */
+    providerModelName?: string;
+    /** Other callable ids that resolve to this model (dated snapshots, the bare
+     *  callable form). Indexed for lookup + accepted as model strings. */
+    aliases?: string[];
+    /** Model role/modality: chat | code | image | video | tts | stt | embedding | … */
+    type?: string;
+    /** Content kinds the model ACCEPTS as input: text | image | audio | video |
+     *  pdf. Use to decide whether prior media can be replayed to this model. */
+    inputModalities?: string[];
+    /** Content kinds the model PRODUCES: text | image | audio | video. */
+    outputModalities?: string[];
+    /** For media models: the generation params this model accepts + allowed
+     *  values, keyed by normalized param name. Drives UI + validation. */
+    mediaParams?: Record<string, MediaParamSpec>;
+    family?: string;
+    version?: string;
+    /** Lifecycle: stable | preview | legacy. */
+    status?: string;
+    /** Callable from this account/SDK now (probe-verified). false = don't call. */
+    active?: boolean;
+    /** End-of-life signalled by a source. */
+    deprecation?: {
+        date?: string;
+        shutdownDate?: string;
+        source: string;
+    };
+    /** Server-side state retention as a duration string ("30d", "72h"). null = none. */
+    stateRetentionDuration?: string | null;
+    /** Whether server-state continuation requires the SAME model (true) or works
+     *  across models of the same provider (false). Safe default: true. */
+    stateModelBound?: boolean;
+}
+export declare class ModelCatalog {
+    private models;
+    /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
+     *  accept any callable id (providerModelName, dated snapshot) AND the slug. */
+    private aliasIndex;
+    private key;
+    set(provider: string, model: string, info: Partial<Omit<ModelInfo, 'provider' | 'model'>> & {
+        pricing: ModelPricing;
+    }): void;
+    get(provider: string, model: string): ModelInfo | null;
+    /** The exact id to SEND to the provider for a given model string. Translates
+     *  our slug → providerModelName; passes an already-callable id (alias) through
+     *  verbatim (respects an explicit choice); unknown model → verbatim passthrough. */
+    resolveModelId(provider: string, model: string): string;
+    getPricing(provider: string, model: string): ModelPricing | null;
+    getPreferredApi(provider: string, model: string): ApiType | null;
+    supportsApi(provider: string, model: string, api: ApiType): boolean;
+    supportsTools(provider: string, model: string): boolean;
+    supportsPreviousResponseId(provider: string, model: string): boolean;
+    /** Server-state retention as a duration string ("30d", "72h"), or null if unsupported. */
+    getStateRetention(provider: string, model: string): string | null;
+    /** Whether server-state continuation requires the same model (true) or works
+     *  across models of the same provider (false). Safe default: true. */
+    isStateModelBound(provider: string, model: string): boolean;
+    list(provider?: string): ModelInfo[];
+    load(data: Record<string, unknown>): void;
+    /** Load every provider's `catalog.json` shipped with the SDK. Synchronous —
+     *  the JSON files are bundled via static import so no I/O at runtime. */
+    loadProviderDefaults(): void;
+    get size(): number;
+}

package/dist/plugins/permissions/glob.d.ts

@@ -0,0 +1,6 @@
+/** Minimal glob → regex compiler for permission target matching. */
+export interface GlobOptions {
+    loose?: boolean;
+}
+export declare function globToRegex(pattern: string, options?: GlobOptions): RegExp;
+export declare function compileGlobs(patterns: readonly string[], options?: GlobOptions): (s: string) => boolean;

package/dist/plugins/permissions/matchers.d.ts

@@ -0,0 +1,7 @@
+/** Built-in TargetMatcher factories. */
+import type { TargetMatcher } from './types';
+export declare function memoryCategory(...categories: string[]): TargetMatcher;
+export declare function fsGlob(...patterns: string[]): TargetMatcher;
+export declare function shellGlob(...patterns: string[]): TargetMatcher;
+export declare function urlPattern(...patterns: string[]): TargetMatcher;
+export declare function anyOfKind(...kinds: string[]): TargetMatcher;

package/dist/plugins/permissions/policy.d.ts

@@ -0,0 +1,10 @@
+/** PermissionPolicy — walk rules in declaration order, first match wins.
+ *  No matching rule → default-deny. */
+import type { PermissionDecision, PermissionTarget, Rule } from './types';
+export declare class PermissionPolicy {
+    private readonly rules;
+    constructor(rules: readonly Rule[]);
+    check(source: string, target: PermissionTarget, action: string): PermissionDecision;
+    withAdditional(extra: readonly Rule[]): PermissionPolicy;
+    get size(): number;
+}

package/dist/plugins/permissions/types.d.ts

@@ -0,0 +1,22 @@
+/** Permissions — pure rule evaluator for `(source, target, action)` tuples. */
+export interface PermissionTarget {
+    kind: string;
+    [key: string]: unknown;
+}
+export type TargetMatcher = (target: PermissionTarget) => boolean;
+export interface Rule {
+    source?: string | string[];
+    target?: TargetMatcher;
+    action?: string | string[];
+    /** 'allow' — proceed; 'deny' — block; 'ask' — suspend for human approval. */
+    effect: 'allow' | 'deny' | 'ask';
+    reason?: string;
+}
+export interface PermissionDecision {
+    /** True when effect is 'allow'. False for 'deny' and 'ask'. */
+    allow: boolean;
+    /** True when effect is 'ask' — caller must request human approval. */
+    ask?: boolean;
+    reason?: string;
+    matchedRule?: number;
+}

package/dist/plugins/persistence/file.d.ts

@@ -0,0 +1,25 @@
+/** FilePersistence — stores each key as a JSON file in a directory.
+ *
+ *  Key encoding: chars outside `[A-Za-z0-9_.-]` are %-escaped (URL-style)
+ *  so any key works on Windows/Unix filesystems.
+ *
+ *  Concurrency: writes are not atomic. For a multi-process scenario,
+ *  callers should layer their own locking on top. Single-process,
+ *  single-thread use is safe. */
+import type { Persistence } from './types';
+export interface FilePersistenceConfig {
+    /** Directory in which JSON files are stored. Created on first write. */
+    dir: string;
+}
+export declare class FilePersistence implements Persistence {
+    private readonly dir;
+    private readonly ready;
+    constructor(config: FilePersistenceConfig | string);
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+    has(key: string): Promise<boolean>;
+    private keyPath;
+    private ensureDir;
+}

package/dist/plugins/persistence/memory.d.ts

@@ -0,0 +1,23 @@
+/** MemoryPersistence — in-process Map-backed Persistence implementation.
+ *
+ *  Use cases:
+ *    - Unit tests (no temp dirs).
+ *    - Ephemeral runs where state should not outlive the process.
+ *    - Default fallback in createEngine when no persistence is configured.
+ *
+ *  Values are deep-copied via structuredClone on get/set to prevent callers
+ *  from mutating stored objects through retained references. This matches
+ *  FilePersistence semantics (JSON serialize/parse round-trip). */
+import type { Persistence } from './types';
+export declare class MemoryPersistence implements Persistence {
+    private store;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+    has(key: string): Promise<boolean>;
+    /** Test affordance: number of stored entries. Not part of Persistence iface. */
+    get size(): number;
+    /** Test affordance: drop everything. Not part of Persistence iface. */
+    clear(): void;
+}

package/dist/plugins/persistence/types.d.ts

@@ -0,0 +1,21 @@
+/** Persistence interface — unified key-value storage.
+ *
+ *  Implementations:
+ *    - `MemoryPersistence` — in-process Map (tests, ephemeral state).
+ *    - `FilePersistence`   — JSON files per key on disk.
+ *    - (future) DbPersistence, RedisPersistence, ...
+ *
+ *  Used by: ConfigurationPlugin, Cache (FileCacheStore), Scheduler,
+ *  ResponseStore, ConversationPersistence, Batcher (pending jobs). */
+export interface Persistence {
+    /** Get a value by key. Returns null if not found. */
+    get<T>(key: string): Promise<T | null>;
+    /** Set a value. Overwrites if exists. */
+    set<T>(key: string, value: T): Promise<void>;
+    /** Delete a key. No-op if not found. */
+    delete(key: string): Promise<void>;
+    /** List all keys, optionally filtered by prefix. */
+    list(prefix?: string): Promise<string[]>;
+    /** Check if a key exists. */
+    has(key: string): Promise<boolean>;
+}

package/dist/plugins/retrieval/chunker.d.ts

@@ -0,0 +1,28 @@
+/** Text chunker — splits text into overlapping windows of approximate token size.
+ *
+ *  Uses a character-based approximation for token counting (no external dep,
+ *  works in the browser). The `countTokensFn` injection point lets callers
+ *  swap in a more accurate counter without changing the chunker contract.
+ *
+ *  Named constants govern all defaults — no magic values. */
+/** Default maximum chunk size in tokens (approximate). */
+export declare const DEFAULT_CHUNK_MAX_TOKENS = 512;
+/** Default overlap between consecutive chunks in tokens. */
+export declare const DEFAULT_CHUNK_OVERLAP_TOKENS = 64;
+export interface ChunkOptions {
+    maxTokens?: number;
+    overlapTokens?: number;
+}
+export interface TextChunk {
+    /** The chunk content. */
+    text: string;
+    /** Byte offset of the chunk start in the source text. */
+    offset: number;
+    /** 0-based chunk index within the document. */
+    index: number;
+}
+/** Optional injected token counter (synchronous estimate only; no I/O path). */
+export type EstimateTokensFn = (text: string) => number;
+/** Split `text` into overlapping windows based on approximate token count.
+ *  Splits on whitespace boundaries to avoid cutting words mid-token. */
+export declare function chunkText(text: string, opts?: ChunkOptions, estimateTokens?: EstimateTokensFn): TextChunk[];

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

@@ -0,0 +1,60 @@
+/** Hosted Google (Gemini) File Search backend.
+ *
+ *  Maps the unified RetrievalBackend interface to the Gemini File Search API:
+ *    createCorpus   -> POST  {base}/v1beta/fileSearchStores
+ *    addDocument    -> POST  {upload}/upload/v1beta/files (Files API)
+ *                   -> POST  {base}/v1beta/{store}:importFile
+ *    indexStatus    -> GET   {base}/v1beta/{store}  (normalized from count fields)
+ *    removeDocument -> DELETE {base}/v1beta/{fileName}
+ *    deleteCorpus   -> DELETE {base}/v1beta/{store}?force=true
+ *    listCorpora    -> GET   {base}/v1beta/fileSearchStores
+ *    asTool         -> returns ProviderToolSpec { fileSearch: { fileSearchStoreNames, ... } }
+ *    search         -> not supported; use asTool
+ *
+ *  Auth: x-goog-api-key REQUEST HEADER (NOT ?key= query param) to avoid telemetry key-leak.
+ *  See SEC-C1 in the readiness audit for why ?key= was fixed in the google provider adapter.
+ *
+ *  ALL HTTP flows through the injected EngineFetch (NetworkEngine queue).
+ *  Never globalThis.fetch.
+ *
+ *  Note: the asTool() emitter produces the Gemini-native generateContent tool shape:
+ *    { fileSearch: { fileSearchStoreNames: [...], metadataFilter? } }
+ *  This diverges from the OpenAI/xAI `file_search` + `vector_store_ids` family on purpose.
+ *  Google's File Search API uses its own AIP-160 filter and camelCase field names.
+ *
+ *  Provider behavior note: raw uploaded Files API files expire ~48h after upload.
+ *  The fileSearchStore ITSELF persists until deleted. This asymmetry is provider-managed;
+ *  callers should not depend on re-downloading the source file from Files API after 48h. */
+import type { EngineFetch } from '../../network/types';
+import type { AddDocumentOptions, AsToolOptions, CorpusRef, CreateCorpusOptions, DocumentRef, DocumentSource, IndexStatus, ProviderToolSpec, RetrievalBackend, RetrievalCapabilities, RetrievalHit, RetrievalSearchOptions } from './types';
+export interface HostedGoogleRetrievalConfig {
+    apiKey: string;
+    fetch: EngineFetch;
+    baseURL?: string;
+}
+export declare class HostedGoogleRetrievalBackend implements RetrievalBackend {
+    readonly capabilities: RetrievalCapabilities;
+    private readonly apiKey;
+    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;
+    createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
+    addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
+    /** Poll a long-running Operation until done: true.
+     *  Returns the operation body when complete. */
+    pollOperation(operationName: string): Promise<Record<string, unknown>>;
+    indexStatus(corpus: CorpusRef): Promise<IndexStatus>;
+    removeDocument(corpus: CorpusRef, docId: string): Promise<void>;
+    deleteCorpus(corpus: CorpusRef): Promise<void>;
+    listCorpora(): Promise<CorpusRef[]>;
+    /** Returns a Gemini-native `fileSearch` ProviderToolSpec for splicing into a generateContent call.
+     *  NOTE: this spec shape diverges from the OpenAI/xAI `file_search` + `vector_store_ids` family.
+     *  Gemini uses camelCase `fileSearch` / `fileSearchStoreNames` with AIP-160 metadataFilter. */
+    asTool(corpora: CorpusRef[], opts?: AsToolOptions): ProviderToolSpec;
+    /** Direct search is not supported for server-side Gemini file search stores.
+     *  Use `asTool()` and splice the spec into a generateContent call instead. */
+    search(_corpora: CorpusRef[], _query: string, _opts?: RetrievalSearchOptions): Promise<RetrievalHit[]>;
+}

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

@@ -0,0 +1,45 @@
+/** Hosted OpenAI Vector Stores backend.
+ *
+ *  Maps the unified RetrievalBackend interface to the OpenAI Vector Stores API:
+ *    createCorpus  -> POST /v1/vector_stores
+ *    addDocument   -> POST /v1/files  then  POST /v1/vector_stores/{id}/files
+ *    indexStatus   -> GET  /v1/vector_stores/{id}  (normalized)
+ *    removeDocument-> DELETE /v1/vector_stores/{id}/files/{file_id}
+ *    deleteCorpus  -> DELETE /v1/vector_stores/{id}
+ *    listCorpora   -> GET  /v1/vector_stores
+ *    asTool        -> returns ProviderToolSpec (splice into a Responses call)
+ *    search        -> not supported server-side; use asTool
+ *
+ *  ALL HTTP flows through the injected EngineFetch (NetworkEngine queue).
+ *  Never globalThis.fetch.
+ *
+ *  Note: xAI will reuse the `asTool` emitter shape (same file_search spec) —
+ *  the divergence point for xAI will be the base URL and any auth differences.
+ *  // future: hostedXai — subclass or factory: pass baseURL, different auth header. */
+import type { EngineFetch } from '../../network/types';
+import type { AddDocumentOptions, AsToolOptions, CorpusRef, CreateCorpusOptions, DocumentRef, DocumentSource, IndexStatus, ProviderToolSpec, RetrievalBackend, RetrievalCapabilities, RetrievalHit, RetrievalSearchOptions } from './types';
+export interface HostedOpenAIRetrievalConfig {
+    apiKey: string;
+    fetch: EngineFetch;
+    baseURL?: string;
+}
+export declare class HostedOpenAIRetrievalBackend implements RetrievalBackend {
+    readonly capabilities: RetrievalCapabilities;
+    private readonly apiKey;
+    private readonly fetch;
+    private readonly baseURL;
+    constructor(config: HostedOpenAIRetrievalConfig);
+    private bearer;
+    createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
+    addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
+    indexStatus(corpus: CorpusRef): Promise<IndexStatus>;
+    removeDocument(corpus: CorpusRef, docId: string): Promise<void>;
+    deleteCorpus(corpus: CorpusRef): Promise<void>;
+    listCorpora(): Promise<CorpusRef[]>;
+    /** Returns a `file_search` ProviderToolSpec for splicing into a Responses call.
+     *  // future: hostedXai will reuse this same tool spec shape. */
+    asTool(corpora: CorpusRef[], opts?: AsToolOptions): ProviderToolSpec;
+    /** Direct search is not supported for server-side vector stores.
+     *  Use `asTool()` and splice the spec into a Responses API call instead. */
+    search(_corpora: CorpusRef[], _query: string, _opts?: RetrievalSearchOptions): Promise<RetrievalHit[]>;
+}

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

@@ -0,0 +1,57 @@
+/** Hosted xAI (Grok Collections) retrieval backend.
+ *
+ *  Two API planes, two keys, two Bearer auths:
+ *    Management API base  https://management-api.x.ai/v1  -- managementApiKey
+ *    Standard API base    https://api.x.ai/v1             -- apiKey
+ *
+ *  Maps the unified RetrievalBackend interface:
+ *    createCorpus   -> POST  {mgmt}/collections          body { collection_name }
+ *    addDocument    -> POST  {std}/files (multipart)     then
+ *                   -> POST  {mgmt}/collections/{id}/documents/{file_id}
+ *    indexStatus    -> GET   {mgmt}/collections/{id}     (normalised from documents_count)
+ *    removeDocument -> DELETE {mgmt}/collections/{id}/documents/{fileId}
+ *    deleteCorpus   -> DELETE {mgmt}/collections/{id}
+ *    listCorpora    -> GET   {mgmt}/collections
+ *    search         -> POST  {std}/documents/search      (hybrid/keyword/semantic)
+ *    asTool         -> ProviderToolSpec { type: 'file_search', vector_store_ids: [...] }
+ *
+ *  asTool reuses the OpenAI file_search spec shape because xAI /responses is OpenAI-compatible
+ *  for file_search; a native collections_search shape is NOT accepted (verified 422).
+ *
+ *  ALL HTTP flows through the injected EngineFetch (NetworkEngine queue).
+ *  Never globalThis.fetch. */
+import type { EngineFetch } from '../../network/types';
+import type { AddDocumentOptions, AsToolOptions, CorpusRef, CreateCorpusOptions, DocumentRef, DocumentSource, IndexStatus, ProviderToolSpec, RetrievalBackend, RetrievalCapabilities, RetrievalHit, RetrievalSearchOptions } from './types';
+export interface HostedXaiRetrievalConfig {
+    /** Standard API key (api.x.ai) — used for file uploads and search. */
+    apiKey: string;
+    /** Management API key (management-api.x.ai) — used for collection management. */
+    managementApiKey: string;
+    fetch: EngineFetch;
+    /** Override for the standard API base URL. */
+    baseURL?: string;
+    /** Override for the management API base URL. */
+    managementBaseURL?: string;
+}
+export declare class HostedXaiRetrievalBackend implements RetrievalBackend {
+    readonly capabilities: RetrievalCapabilities;
+    private readonly apiKey;
+    private readonly managementApiKey;
+    private readonly fetch;
+    private readonly baseURL;
+    private readonly managementBaseURL;
+    constructor(config: HostedXaiRetrievalConfig);
+    private stdBearer;
+    private mgmtBearer;
+    createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
+    addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
+    indexStatus(corpus: CorpusRef): Promise<IndexStatus>;
+    removeDocument(corpus: CorpusRef, fileId: string): Promise<void>;
+    deleteCorpus(corpus: CorpusRef): Promise<void>;
+    listCorpora(): Promise<CorpusRef[]>;
+    search(corpora: CorpusRef[], query: string, opts?: RetrievalSearchOptions): Promise<RetrievalHit[]>;
+    /** Returns a `file_search` ProviderToolSpec for splicing into a Responses call.
+     *  xAI Responses is OpenAI-compatible for file_search; native collections_search
+     *  is NOT accepted (verified 422). */
+    asTool(corpora: CorpusRef[], opts?: AsToolOptions): ProviderToolSpec;
+}