llmist 18.3.0 → 18.4.0

package/dist/index.d.ts

@@ -1534,6 +1534,12 @@ interface ModelFeatures {
     structuredOutputs?: boolean;
     /** Supports fine-tuning */
     fineTuning?: boolean;
+    /**
+     * Discoverability flag: the model can also run deep research via
+     * `client.research` (see the research model catalog for capabilities
+     * and research-specific pricing).
+     */
+    research?: boolean;
 }
 interface ModelSpec {
     /** Provider identifier (e.g., 'openai', 'anthropic', 'gemini') */
@@ -2694,6 +2700,375 @@ interface SpeechModelSpec {
     };
 }
 
+/**
+ * Deep Research — normalized types.
+ *
+ * Deep research runs are long-lived (minutes to an hour), server-side agentic
+ * jobs that browse the web and return cited reports. This module defines the
+ * provider-independent surface: options, the normalized event union, the final
+ * result, and the serializable job reference used to re-attach to a running
+ * background job after a disconnect or process restart.
+ */
+
+/**
+ * Lifecycle status of a research job.
+ *
+ * Superset of provider statuses:
+ * - OpenAI Responses: `queued | in_progress | completed | failed | cancelled | incomplete`
+ * - Gemini Interactions adds `requires_action` and `budget_exceeded`
+ */
+type ResearchStatus = "queued" | "in_progress" | "requires_action" | "completed" | "failed" | "cancelled" | "incomplete" | "budget_exceeded";
+/**
+ * Data-source / auxiliary tools a research run may use.
+ *
+ * Providers map these to their native tool shapes (e.g. `web_search` becomes
+ * OpenAI's `web_search_preview`). Which types a given model accepts is
+ * declared in {@link ResearchModelSpec.capabilities.tools}.
+ */
+type ResearchToolConfig = {
+    type: "web_search";
+} | {
+    type: "file_search";
+    vectorStoreIds: string[];
+} | {
+    type: "mcp";
+    serverLabel: string;
+    serverUrl: string;
+    requireApproval?: "never";
+} | {
+    type: "code_interpreter";
+};
+/** Union of the tool type discriminators. */
+type ResearchToolType = ResearchToolConfig["type"];
+/** Tool types that count as a data source (OpenAI requires at least one). */
+declare const RESEARCH_DATA_SOURCE_TOOL_TYPES: readonly ResearchToolType[];
+/**
+ * Options for starting a research run.
+ */
+interface ResearchOptions {
+    /**
+     * Model identifier, optionally provider-prefixed:
+     * `"openai:gpt-5.5-pro"`, `"gemini:deep-research-preview-04-2026"`,
+     * `"openrouter:perplexity/sonar-deep-research"`.
+     */
+    model: string;
+    /** The research question / brief. */
+    query: string;
+    /**
+     * System-level guidance. Folded into the input on providers without a
+     * system slot (OpenAI deep research), mapped to `system_instruction`
+     * (Gemini) or a system message (OpenRouter) elsewhere.
+     */
+    systemPrompt?: string;
+    /**
+     * Run as a server-side background job (survives disconnects; enables
+     * {@link ResearchJob.toRef} / attach). Defaults to the model's
+     * `capabilities.background`. Requesting `true` on a provider without
+     * background support is a validation error.
+     */
+    background?: boolean;
+    /**
+     * Data-source / auxiliary tools. Defaults to the model's
+     * `requiredTools`. Tools outside the model's `capabilities.tools`
+     * are rejected before any network call.
+     */
+    tools?: ResearchToolConfig[];
+    /** Cap on total built-in tool calls (cost control; OpenAI `max_tool_calls`). */
+    maxToolCalls?: number;
+    /** Reasoning configuration (mapped per provider: summaries, effort, thinking). */
+    reasoning?: ReasoningConfig;
+    /**
+     * Continue from a previous **completed** research job (Gemini
+     * `previous_interaction_id`). Rejected on models without follow-up support.
+     */
+    previousJobId?: string;
+    /**
+     * Overall time budget for the run as observed by this client. Expiry aborts
+     * the transport (the server-side job keeps running and stays attachable) and
+     * surfaces a `ResearchTimeoutError`. Defaults to
+     * `min(RESEARCH_DEFAULT_TIMEOUT_MS, spec.maxDurationMs)`.
+     */
+    timeoutMs?: number;
+    /**
+     * Aborts the transport only — a background job keeps running server-side
+     * and can be re-attached via its ref. Use {@link ResearchJob.cancel} to stop
+     * the job on the server.
+     */
+    signal?: AbortSignal;
+    /** Provider-specific passthrough (same spirit as `LLMGenerationOptions.extra`). */
+    extra?: Record<string, unknown>;
+}
+/** A citation attached to the research report. */
+interface ResearchCitation {
+    url: string;
+    title?: string;
+    /** Start offset of the cited span in the report text, when provided. */
+    startIndex?: number;
+    /** End offset of the cited span in the report text, when provided. */
+    endIndex?: number;
+    /** Excerpt of the cited source content, when provided (OpenRouter). */
+    content?: string;
+}
+/** Token usage extended with research-specific dimensions. */
+interface ResearchUsage extends TokenUsage {
+    /** Number of web searches performed, when the provider reports it. */
+    searches?: number;
+    /** Estimated cost in USD, computed from catalog pricing when available. */
+    costUSD?: number;
+}
+/** Error payload carried by `error` events. */
+interface ResearchErrorInfo {
+    message: string;
+    code?: string;
+    /** Whether retrying (or resuming) may succeed. */
+    retryable: boolean;
+}
+/**
+ * Normalized research event union.
+ *
+ * Every event may carry a `cursor` (provider stream position: OpenAI
+ * `sequence_number`, Gemini `event_id`) used for lossless resume, and a
+ * `rawEvent` escape hatch with the provider's original payload.
+ */
+type ResearchEvent = {
+    cursor?: string;
+    rawEvent?: unknown;
+} & ({
+    type: "created";
+    /** Server-side job id; `null` on providers without job handles (OpenRouter). */
+    jobId: string | null;
+} | {
+    type: "status";
+    status: ResearchStatus;
+} | {
+    type: "phase";
+    /** Coarse activity phase. Providers may emit additional phase strings. */
+    phase: "planning" | "searching" | "reasoning" | "writing" | (string & {});
+} | {
+    type: "thinking";
+    delta: string;
+} | {
+    type: "search";
+    action: "search" | "open_page" | "find_in_page";
+    status: "started" | "completed";
+    query?: string;
+    url?: string;
+} | {
+    type: "tool";
+    tool: "code_interpreter" | "file_search" | "mcp";
+    status: "started" | "completed";
+    detail?: string;
+} | {
+    type: "text";
+    delta: string;
+} | {
+    type: "citation";
+    citation: ResearchCitation;
+} | {
+    type: "usage";
+    usage: ResearchUsage;
+} | {
+    type: "error";
+    error: ResearchErrorInfo;
+} | {
+    type: "done";
+    result: ResearchDoneInfo;
+});
+/**
+ * Terminal payload emitted by provider normalizers on `done`.
+ *
+ * Providers fill what they know; the job's collector merges it with
+ * accumulated stream state (text deltas, citations, usage) into the final
+ * {@link ResearchResult}. `report` may be empty when the report was fully
+ * streamed as `text` deltas.
+ */
+interface ResearchDoneInfo {
+    status: ResearchStatus;
+    /** Full report text when the provider returns it wholesale (else ""). */
+    report: string;
+    citations?: ResearchCitation[];
+    usage?: ResearchUsage;
+    /** Final provider object (response / interaction / last chunk). */
+    raw?: unknown;
+}
+/** Final result of a research run. */
+interface ResearchResult {
+    /** Server-side job id, or `null` on providers without job handles. */
+    jobId: string | null;
+    /** Adapter provider id that ran the job (e.g. "openai", "mock"). */
+    provider: string;
+    /** Model / agent id (unprefixed). */
+    model: string;
+    status: ResearchStatus;
+    /** The research report text. */
+    report: string;
+    /** Deduplicated citations. */
+    citations: ResearchCitation[];
+    usage: ResearchUsage;
+    /** Wall-clock duration observed by this client, when measurable. */
+    durationMs?: number;
+    /** Final provider payload, when available. */
+    raw?: unknown;
+}
+/**
+ * JSON-serializable reference to a background research job.
+ *
+ * Round-trip contract: `JSON.parse(JSON.stringify(ref))` is a valid ref, and
+ * `client.research.attach(ref)` resumes the event stream from `cursor` —
+ * across process restarts.
+ */
+interface ResearchJobRef {
+    /** Adapter provider id (e.g. "openai", "gemini", "mock"). */
+    provider: string;
+    /** Model / agent id (unprefixed). */
+    model: string;
+    /** Server-side job id. */
+    jobId: string;
+    /** Last observed stream cursor; resume yields events strictly after it. */
+    cursor?: string;
+    /** ISO timestamp of job creation, when known. */
+    startedAt?: string;
+}
+/** Snapshot returned by status polls. */
+interface ResearchStatusSnapshot {
+    status: ResearchStatus;
+    /** Present when the job reached a terminal state and the result is available. */
+    result?: ResearchResult;
+}
+/**
+ * Handle to a research run.
+ *
+ * The job is itself async-iterable (equivalent to iterating
+ * {@link ResearchJob.events}). The event stream may be consumed **once**.
+ */
+interface ResearchJob extends AsyncIterable<ResearchEvent> {
+    /** Server-side job id once known (`created` event), else `null`. */
+    readonly jobId: string | null;
+    /** Adapter provider id. */
+    readonly provider: string;
+    /** Model / agent id (unprefixed). */
+    readonly model: string;
+    /**
+     * Live event stream. Auto-reconnects with the last cursor on transient
+     * stream drops when the model is resumable. Single consumption only.
+     */
+    events(): AsyncIterable<ResearchEvent>;
+    /**
+     * Final result. Drains the event stream internally when not already
+     * consumed; otherwise resolves when iteration completes.
+     */
+    result(): Promise<ResearchResult>;
+    /**
+     * One-shot server-side status poll.
+     * @throws ResearchNotPollableError on providers without status polling.
+     */
+    status(): Promise<ResearchStatus>;
+    /**
+     * Cancel the job server-side where supported; otherwise aborts the
+     * transport. See {@link ResearchOptions.signal} for the abort-vs-cancel
+     * distinction.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Serializable reference for later {@link ResearchNamespaceLike.attach}.
+     * @throws ResearchJobNotResumableError when the job has no server-side id.
+     */
+    toRef(): ResearchJobRef;
+}
+
+/**
+ * Research model catalog types.
+ *
+ * Research-capable models get their own catalog (mirroring the image/speech
+ * media catalogs) instead of overloading `ModelSpec`: Gemini research "agents"
+ * have no chat/context-window semantics, and research pricing has dimensions
+ * (`perThousandSearches`, `internalReasoning`) that `ModelPricing` lacks.
+ *
+ * Research capability is **catalog-driven** — nothing outside a catalog file
+ * should test model-id strings.
+ */
+
+/**
+ * Research pricing. Token rates are USD per 1M tokens.
+ */
+interface ResearchPricing {
+    /** USD per 1M input tokens. */
+    input: number;
+    /** USD per 1M output tokens. */
+    output: number;
+    /** USD per 1M cached input tokens (defaults to `input` when omitted). */
+    cachedInput?: number;
+    /**
+     * USD per 1M internal reasoning tokens, when the provider prices them
+     * separately from output (Perplexity sonar-deep-research: 3.0). When set,
+     * reasoning tokens are billed at this rate and excluded from `output`.
+     */
+    internalReasoning?: number;
+    /**
+     * USD per 1,000 web searches (OpenAI web search: 10, Perplexity
+     * sonar-deep-research: 5, sonar-pro-search: 18, Gemini: 14 post-free-tier).
+     */
+    perThousandSearches?: number;
+}
+/** Capability flags for a research model/agent. */
+interface ResearchCapabilities {
+    /** Whether live event streaming is supported (gpt-5.5-pro: false → create+poll). */
+    streaming: boolean;
+    /** Whether server-side background jobs are supported. */
+    background: boolean;
+    /** Whether a dropped stream can resume from a cursor. */
+    resumable: boolean;
+    /** Whether follow-up runs can reference a previous job (Gemini). */
+    followUps?: boolean;
+    /** Tool types accepted by this model (empty = tools are provider-managed). */
+    tools: ResearchToolType[];
+}
+/** Lifecycle metadata for a research model/agent. */
+interface ResearchModelMetadata {
+    releaseDate?: string;
+    /** Date the provider announced deprecation. */
+    deprecationDate?: string;
+    /**
+     * Date the provider removes the model (ISO date). Starting a run past this
+     * date throws `ResearchDeprecatedModelError`; within the warning window a
+     * warning is logged.
+     */
+    shutdownDate?: string;
+    /** Recommended replacement model id, surfaced in deprecation errors. */
+    replacement?: string;
+    notes?: string;
+}
+/**
+ * A research-capable model, agent, or preset.
+ */
+interface ResearchModelSpec {
+    /** Provider adapter id (e.g. "openai", "gemini", "openrouter"). */
+    provider: string;
+    /** Model id, agent id, or preset id (unprefixed). */
+    modelId: string;
+    /**
+     * - `"model"` — a regular model doing research via tools (OpenAI, OpenRouter)
+     * - `"agent"` — a provider-managed research agent (Gemini Interactions)
+     * - `"preset"` — an llmist-orchestrated research preset (reserved; future Anthropic track)
+     */
+    kind: "model" | "agent" | "preset";
+    displayName: string;
+    /** Context window in tokens (undefined for agents/presets). */
+    contextWindow?: number;
+    /** Max output tokens (undefined for agents/presets). */
+    maxOutputTokens?: number;
+    pricing: ResearchPricing;
+    capabilities: ResearchCapabilities;
+    /**
+     * Tools injected when the caller supplies none (e.g. OpenAI research
+     * requires at least one data source → `[{type: "web_search"}]`).
+     */
+    requiredTools?: ResearchToolConfig[];
+    /** Provider-enforced maximum run duration (Gemini: 60 minutes). */
+    maxDurationMs?: number;
+    metadata?: ResearchModelMetadata;
+}
+
 interface ProviderAdapter {
     readonly providerId: string;
     /**
@@ -2758,6 +3133,43 @@ interface ProviderAdapter {
      * @returns Promise resolving to the generation result with audio and cost
      */
     generateSpeech?(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+    /**
+     * Get research model/agent specifications for this provider.
+     * Returns undefined if the provider doesn't support research.
+     */
+    getResearchModelSpecs?(): ResearchModelSpec[];
+    /**
+     * Check if this provider supports deep research for a given model/agent id.
+     * @param modelId - Model or agent identifier (unprefixed)
+     */
+    supportsResearch?(modelId: string): boolean;
+    /**
+     * Start a research run as a normalized event stream.
+     *
+     * Contract:
+     * - The first emitted event MUST be `created` (with the server-side job id,
+     *   or `null` on providers without job handles).
+     * - Providers without live streaming implement create + poll internally,
+     *   emitting `status` heartbeats and a final `text` + `done`.
+     * - Events SHOULD carry a `cursor` when the provider supports resume.
+     *
+     * @param options - Research options (validated by the namespace before this call)
+     * @param descriptor - Parsed model descriptor
+     * @param spec - Catalog spec when the model is cataloged
+     */
+    startResearch?(options: ResearchOptions, descriptor: ModelDescriptor, spec?: ResearchModelSpec): AsyncIterable<ResearchEvent>;
+    /**
+     * Re-attach to a background research job, yielding events strictly after
+     * `ref.cursor` (or all events when no cursor is set).
+     */
+    resumeResearch?(ref: ResearchJobRef, signal?: AbortSignal): AsyncIterable<ResearchEvent>;
+    /**
+     * One-shot status poll for a background research job. Returns the terminal
+     * result when the job has completed.
+     */
+    getResearchStatus?(ref: ResearchJobRef): Promise<ResearchStatusSnapshot>;
+    /** Cancel a background research job server-side. */
+    cancelResearch?(ref: ResearchJobRef): Promise<void>;
 }
 
 /**
@@ -5473,6 +5885,52 @@ declare class AgentBuilder {
     build(): Agent;
 }
 
+/**
+ * Research namespace — `client.research`.
+ *
+ * Mirrors the image/speech capability namespaces: dispatches to the first
+ * adapter (in priority order) that supports the model, after validating the
+ * request against the model's catalog spec. Providers plug in via the
+ * optional research methods on {@link ProviderAdapter}.
+ */
+
+declare class ResearchNamespace {
+    private readonly adapters;
+    private readonly parser;
+    private readonly now;
+    private readonly logger;
+    constructor(adapters: ProviderAdapter[], parser: ModelIdentifierParser, now?: () => number, logger?: Logger<ILogObj>);
+    /**
+     * Start a research run. Returns immediately; the provider stream opens
+     * lazily on first iteration (or on `result()`).
+     */
+    start(options: ResearchOptions): ResearchJob;
+    /**
+     * Re-attach to a background research job from a serialized ref.
+     * No network happens until the returned job is iterated.
+     */
+    attach(ref: ResearchJobRef): ResearchJob;
+    /** One-shot status poll for a job ref. */
+    get(ref: ResearchJobRef): Promise<ResearchStatusSnapshot>;
+    /** Cancel a background job server-side. */
+    cancel(ref: ResearchJobRef): Promise<void>;
+    /** All research-capable models/agents across registered providers. */
+    listModels(): ResearchModelSpec[];
+    /** Whether any registered provider supports research for this model. */
+    supportsModel(model: string): boolean;
+    private findResearchAdapter;
+    private findAdapterByProviderId;
+    private findSpec;
+    private describeAvailableModels;
+    /**
+     * Pre-flight validation against the catalog spec — fails fast before any
+     * network call and applies spec-driven defaults.
+     */
+    private validate;
+    private resolveTools;
+    private enforceLifecycle;
+}
+
 /**
  * Image Generation Namespace
  *
@@ -5764,6 +6222,12 @@ declare class LLMist {
     readonly image: ImageNamespace;
     readonly speech: SpeechNamespace;
     readonly vision: VisionNamespace;
+    /**
+     * Deep research — long-running, server-side research jobs with cited
+     * reports (OpenAI Responses, Gemini Interactions, OpenRouter research
+     * models). See docs/specs/002-deep-research.md.
+     */
+    readonly research: ResearchNamespace;
     constructor();
     constructor(adapters: ProviderAdapter[]);
     constructor(adapters: ProviderAdapter[], defaultProvider: string);
@@ -9277,6 +9741,118 @@ declare function mcpToolToGadget(tool: McpToolDescriptor, client: McpClient, opt
  */
 declare const FALLBACK_CHARS_PER_TOKEN = 2;
 
+/**
+ * Aggregates a research event stream into a final {@link ResearchResult}.
+ *
+ * Provider normalizers emit what they know; the collector merges streamed
+ * state (text deltas, citations, usage) with the terminal `done` payload:
+ * - report: `done.report` wins when non-empty, else accumulated text deltas
+ * - citations: union of streamed + done citations, deduplicated
+ * - usage: last-write-wins for token fields, max for cumulative counters
+ * - costUSD: computed from catalog pricing when a spec is provided
+ */
+
+interface ResearchResultContext {
+    provider: string;
+    model: string;
+    jobId: string | null;
+}
+declare class ResearchResultCollector {
+    private readonly spec?;
+    private readonly now;
+    private reportParts;
+    private citations;
+    private usage;
+    private lastStatus;
+    private doneReport;
+    private doneRaw;
+    private hasDone;
+    private firstEventAt;
+    private terminalAt;
+    /**
+     * Terminal error info from an `error` event.
+     * @internal Read by tests only — not part of the public consumer contract.
+     */
+    terminalError: ResearchErrorInfo | undefined;
+    constructor(spec?: ResearchModelSpec | undefined, now?: () => number);
+    ingest(event: ResearchEvent): void;
+    toResult(context: ResearchResultContext): ResearchResult;
+    /** Whether a terminal event (`done` or `error`) was ingested. */
+    get isTerminal(): boolean;
+    private addCitation;
+    private mergeUsage;
+}
+
+/**
+ * Research cost estimation.
+ *
+ * Separate from `ModelRegistry.estimateCost` because research pricing has
+ * dimensions the chat cost model lacks: per-search fees and separately-priced
+ * internal reasoning tokens (see {@link ResearchPricing}).
+ */
+
+/**
+ * Estimate the USD cost of a research run.
+ *
+ * Semantics:
+ * - `cachedInputTokens` are a subset of `inputTokens` and billed at
+ *   `cachedInput` (falling back to `input` when unset).
+ * - `reasoningTokens` are a subset of `outputTokens`. When
+ *   `internalReasoning` is priced, reasoning tokens are billed at that rate
+ *   and excluded from the output rate; otherwise they remain part of output.
+ * - `searches` are billed at `perThousandSearches / 1000` each.
+ */
+declare function estimateResearchCost(pricing: ResearchPricing, usage: ResearchUsage): number;
+
+/**
+ * Typed errors for the research surface.
+ *
+ * Follows the core error convention (plain `Error` subclasses with `name`
+ * set) — see `core/errors.ts`.
+ */
+/** Thrown when no registered provider supports research for the given model. */
+declare class ResearchNotSupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a job cannot produce a serializable ref (no server-side job id —
+ * e.g. OpenRouter research runs) or a ref cannot be resumed on its provider.
+ */
+declare class ResearchJobNotResumableError extends Error {
+    constructor(message: string);
+}
+/** Thrown when status polling is requested on a provider without it. */
+declare class ResearchNotPollableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the client-side time budget expires. The transport is aborted;
+ * a background job keeps running server-side and its ref stays valid.
+ */
+declare class ResearchTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** Thrown when starting a run on a model past its announced shutdown date. */
+declare class ResearchDeprecatedModelError extends Error {
+    readonly modelId: string;
+    readonly shutdownDate: string;
+    readonly replacement?: string;
+    constructor(params: {
+        modelId: string;
+        shutdownDate: string;
+        replacement?: string;
+    });
+}
+/** Thrown when options fail pre-flight validation against the model's spec. */
+declare class ResearchValidationError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a job's event stream is consumed more than once. */
+declare class ResearchStreamConsumedError extends Error {
+    constructor();
+}
+
 /**
  * Subagent creation helper for gadget authors.
  *
@@ -10008,6 +10584,12 @@ declare class GeminiGenerativeProvider extends BaseProviderAdapter {
     getSpeechModelSpecs(): SpeechModelSpec[];
     supportsSpeechGeneration(modelId: string): boolean;
     generateSpeech(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+    getResearchModelSpecs(): ResearchModelSpec[];
+    supportsResearch(agentId: string): boolean;
+    startResearch(options: ResearchOptions, descriptor: ModelDescriptor, spec?: ResearchModelSpec): AsyncIterable<ResearchEvent>;
+    resumeResearch(ref: ResearchJobRef, signal?: AbortSignal): AsyncIterable<ResearchEvent>;
+    getResearchStatus(ref: ResearchJobRef): Promise<ResearchStatusSnapshot>;
+    cancelResearch(ref: ResearchJobRef): Promise<void>;
     protected buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, _spec: ModelSpec | undefined, messages: LLMMessage[]): {
         model: string;
         contents: GeminiContent[];
@@ -10289,6 +10871,12 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
     getSpeechModelSpecs(): SpeechModelSpec[];
     supportsSpeechGeneration(modelId: string): boolean;
     generateSpeech(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+    getResearchModelSpecs(): ResearchModelSpec[];
+    supportsResearch(modelId: string): boolean;
+    startResearch(options: ResearchOptions, descriptor: ModelDescriptor, spec?: ResearchModelSpec): AsyncIterable<ResearchEvent>;
+    resumeResearch(ref: ResearchJobRef, signal?: AbortSignal): AsyncIterable<ResearchEvent>;
+    getResearchStatus(ref: ResearchJobRef): Promise<ResearchStatusSnapshot>;
+    cancelResearch(ref: ResearchJobRef): Promise<void>;
     protected buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): Parameters<OpenAI["chat"]["completions"]["create"]>[0];
     /**
      * Convert an LLMMessage to OpenAI's ChatCompletionMessageParam.
@@ -10412,6 +11000,9 @@ declare class OpenRouterProvider extends OpenAICompatibleProvider<OpenRouterConf
     protected readonly providerAlias = "or";
     constructor(client: OpenAI, config?: OpenRouterConfig);
     getModelSpecs(): ModelSpec[];
+    getResearchModelSpecs(): ResearchModelSpec[];
+    supportsResearch(modelId: string): boolean;
+    startResearch(options: ResearchOptions, descriptor: ModelDescriptor, _spec?: ResearchModelSpec): AsyncIterable<ResearchEvent>;
     /**
      * Override buildApiRequest to inject reasoning parameters and cache_control breakpoints.
      * OpenRouter normalizes reasoning into the standard OpenAI format,
@@ -11265,4 +11856,4 @@ declare const timing: {
  */
 declare function getHostExports(ctx: ExecutionContext): HostExports;
 
-export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, type CreateMcpServerOptions, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_MCP_COMMAND_ALLOWLIST, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, EmptyCompletionError, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetArgsPartialEvent, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, type HttpMcpServerSpec, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type JSONSchemaLike, JsonSchemaConversionError, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, LOAD_SKILL_GADGET_NAME, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, McpClient, type McpClientOptions, McpConnectError, type McpContentBlock, McpError, McpLifecycle, type McpServerCapabilities, type McpServerHandle, type McpServerSpec, type McpToolAdapterOptions, McpToolCallError, type McpToolDescriptor, type McpToolResult, McpUntrustedCommandError, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetArgsPartialContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StdioMcpServerSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, assertCommandAllowed, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLoadSkillGadget, createLogger, createMcpServer, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetResultToMcpContent, gadgetSuccess, gadgetToMcpTool, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, jsonSchemaToZod, listPresets, listSubagents, loadSkillsFromDirectory, mcpToolToGadget, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, renderSkillForMcpPrompt, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runGadgetForMcp, runWithHandlers, scanResources, schemaToJSONSchema, skillToMcpPrompt, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };
+export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, type CreateMcpServerOptions, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_MCP_COMMAND_ALLOWLIST, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, EmptyCompletionError, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetArgsPartialEvent, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, type HttpMcpServerSpec, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type JSONSchemaLike, JsonSchemaConversionError, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, LOAD_SKILL_GADGET_NAME, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, McpClient, type McpClientOptions, McpConnectError, type McpContentBlock, McpError, McpLifecycle, type McpServerCapabilities, type McpServerHandle, type McpServerSpec, type McpToolAdapterOptions, McpToolCallError, type McpToolDescriptor, type McpToolResult, McpUntrustedCommandError, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetArgsPartialContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, RESEARCH_DATA_SOURCE_TOOL_TYPES, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResearchCapabilities, type ResearchCitation, ResearchDeprecatedModelError, type ResearchDoneInfo, type ResearchErrorInfo, type ResearchEvent, type ResearchJob, ResearchJobNotResumableError, type ResearchJobRef, type ResearchModelMetadata, type ResearchModelSpec, ResearchNamespace, ResearchNotPollableError, ResearchNotSupportedError, type ResearchOptions, type ResearchPricing, type ResearchResult, ResearchResultCollector, type ResearchStatus, type ResearchStatusSnapshot, ResearchStreamConsumedError, ResearchTimeoutError, type ResearchToolConfig, type ResearchToolType, type ResearchUsage, ResearchValidationError, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StdioMcpServerSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, assertCommandAllowed, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLoadSkillGadget, createLogger, createMcpServer, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, estimateResearchCost, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetResultToMcpContent, gadgetSuccess, gadgetToMcpTool, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, jsonSchemaToZod, listPresets, listSubagents, loadSkillsFromDirectory, mcpToolToGadget, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, renderSkillForMcpPrompt, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runGadgetForMcp, runWithHandlers, scanResources, schemaToJSONSchema, skillToMcpPrompt, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };