llmist 18.3.0 → 18.4.0

package/dist/index.js

@@ -81,7 +81,7 @@ import {
   toBase64,
   validateGadgetSchema,
   withErrorHandling
-} from "./chunk-DNB4DPM4.js";
+} from "./chunk-I4KQ7U7F.js";
 
 // src/core/execution-tree-aggregator.ts
 var ExecutionTreeAggregator;
@@ -93,6 +93,8 @@ var init_execution_tree_aggregator = __esm({
         this.nodes = nodes;
         this.getDescendants = getDescendants;
       }
+      nodes;
+      getDescendants;
       // ===========================================================================
       // Private helpers
       // ===========================================================================
@@ -3636,7 +3638,7 @@ var init_gadget_output_store = __esm({
           charCount: content.length,
           byteSize: encoder.encode(content).length,
           lineCount: lines.length,
-          maxLineLength: lines.reduce((max, line) => Math.max(max, line.length), 0),
+          maxLineLength: lines.reduce((max2, line) => Math.max(max2, line.length), 0),
           timestamp: /* @__PURE__ */ new Date()
         };
         this.outputs.set(id, stored);
@@ -6286,6 +6288,7 @@ var init_base_provider = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       /**
        * Template method that defines the skeleton of the streaming algorithm.
        * This orchestrates the four-step process without dictating provider-specific details.
@@ -6655,6 +6658,7 @@ var init_gemini_cache_manager = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       activeCache = null;
       /**
        * Get or create a cache for the given content.
@@ -7197,6 +7201,621 @@ var init_gemini_models = __esm({
   }
 });
 
+// src/research/constants.ts
+var RESEARCH_DEFAULT_TIMEOUT_MS, GEMINI_RESEARCH_MAX_DURATION_MS, OPENAI_RESEARCH_HTTP_TIMEOUT_MS, OPENROUTER_RESEARCH_HTTP_TIMEOUT_MS, RESEARCH_POLL_INTERVAL_MS, RESEARCH_POLL_MAX_INTERVAL_MS, RESEARCH_POLL_BACKOFF_FACTOR, RESEARCH_STREAM_RECONNECT_MAX_ATTEMPTS, RESEARCH_SHUTDOWN_WARNING_WINDOW_DAYS, RESEARCH_COST_DECIMALS, TOKENS_PER_MILLION, SEARCHES_PER_THOUSAND, MS_PER_DAY;
+var init_constants3 = __esm({
+  "src/research/constants.ts"() {
+    "use strict";
+    RESEARCH_DEFAULT_TIMEOUT_MS = 36e5;
+    GEMINI_RESEARCH_MAX_DURATION_MS = 36e5;
+    OPENAI_RESEARCH_HTTP_TIMEOUT_MS = 36e5;
+    OPENROUTER_RESEARCH_HTTP_TIMEOUT_MS = 36e5;
+    RESEARCH_POLL_INTERVAL_MS = 1e4;
+    RESEARCH_POLL_MAX_INTERVAL_MS = 6e4;
+    RESEARCH_POLL_BACKOFF_FACTOR = 1.5;
+    RESEARCH_STREAM_RECONNECT_MAX_ATTEMPTS = 5;
+    RESEARCH_SHUTDOWN_WARNING_WINDOW_DAYS = 30;
+    RESEARCH_COST_DECIMALS = 6;
+    TOKENS_PER_MILLION = 1e6;
+    SEARCHES_PER_THOUSAND = 1e3;
+    MS_PER_DAY = 864e5;
+  }
+});
+
+// src/research/errors.ts
+var ResearchNotSupportedError, ResearchJobNotResumableError, ResearchNotPollableError, ResearchTimeoutError, ResearchDeprecatedModelError, ResearchValidationError, ResearchStreamConsumedError;
+var init_errors3 = __esm({
+  "src/research/errors.ts"() {
+    "use strict";
+    ResearchNotSupportedError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ResearchNotSupportedError";
+      }
+    };
+    ResearchJobNotResumableError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ResearchJobNotResumableError";
+      }
+    };
+    ResearchNotPollableError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ResearchNotPollableError";
+      }
+    };
+    ResearchTimeoutError = class extends Error {
+      timeoutMs;
+      constructor(timeoutMs) {
+        super(
+          `Research run exceeded the client-side time budget of ${timeoutMs}ms. A background job keeps running server-side \u2014 re-attach via its ref.`
+        );
+        this.name = "ResearchTimeoutError";
+        this.timeoutMs = timeoutMs;
+      }
+    };
+    ResearchDeprecatedModelError = class extends Error {
+      modelId;
+      shutdownDate;
+      replacement;
+      constructor(params) {
+        super(
+          `Research model "${params.modelId}" was shut down by its provider on ${params.shutdownDate}.` + (params.replacement ? ` Use "${params.replacement}" instead.` : "")
+        );
+        this.name = "ResearchDeprecatedModelError";
+        this.modelId = params.modelId;
+        this.shutdownDate = params.shutdownDate;
+        this.replacement = params.replacement;
+      }
+    };
+    ResearchValidationError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ResearchValidationError";
+      }
+    };
+    ResearchStreamConsumedError = class extends Error {
+      constructor() {
+        super(
+          "This research job's event stream was already consumed. Iterate events() (or the job itself) once; use result() for the aggregated outcome."
+        );
+        this.name = "ResearchStreamConsumedError";
+      }
+    };
+  }
+});
+
+// src/providers/gemini-research.ts
+function buildGeminiResearchRequest(options, agentId) {
+  if (options.background === false) {
+    throw new ResearchValidationError(
+      "Gemini deep research requires background execution \u2014 background: false is not supported."
+    );
+  }
+  return {
+    agent: agentId,
+    input: options.query,
+    background: true,
+    store: true,
+    agent_config: {
+      type: "deep-research",
+      thinking_summaries: options.reasoning?.includeThinking === false ? "none" : "auto"
+    },
+    ...options.systemPrompt ? { system_instruction: options.systemPrompt } : {},
+    ...options.previousJobId ? { previous_interaction_id: options.previousJobId } : {},
+    ...options.extra ?? {}
+  };
+}
+function mapInteractionStatus(status) {
+  if (status && GEMINI_STATUS_VALUES.has(status)) {
+    return status;
+  }
+  return "in_progress";
+}
+function annotationToCitation(annotation) {
+  if (annotation.type !== "url_citation" || !annotation.url) return void 0;
+  return {
+    url: annotation.url,
+    title: annotation.title,
+    startIndex: annotation.start_index,
+    endIndex: annotation.end_index
+  };
+}
+function extractReportFromInteraction(interaction) {
+  const parts = [];
+  const citations = [];
+  for (const step of interaction.steps ?? []) {
+    if (step.type !== "model_output") continue;
+    for (const content of step.content ?? []) {
+      if (content.type !== "text") continue;
+      parts.push(content.text);
+      for (const annotation of content.annotations ?? []) {
+        const citation = annotationToCitation(annotation);
+        if (citation) citations.push(citation);
+      }
+    }
+  }
+  return { report: parts.join(""), citations };
+}
+function countSearchesInSteps(interaction) {
+  let searches = 0;
+  for (const step of interaction.steps ?? []) {
+    if (step.type === "google_search_call") {
+      searches += step.arguments?.queries?.length ?? 1;
+    }
+  }
+  return searches;
+}
+function usageFromInteraction(interaction, streamedSearches) {
+  const usage = interaction.usage;
+  const searches = streamedSearches ?? countSearchesInSteps(interaction);
+  return {
+    inputTokens: usage?.total_input_tokens ?? 0,
+    outputTokens: usage?.total_output_tokens ?? 0,
+    totalTokens: usage?.total_tokens ?? 0,
+    cachedInputTokens: usage?.total_cached_tokens,
+    reasoningTokens: usage?.total_thought_tokens,
+    ...searches > 0 ? { searches } : {}
+  };
+}
+function doneEventFromInteraction(interaction, streamedSearches) {
+  const { report, citations } = extractReportFromInteraction(interaction);
+  return {
+    type: "done",
+    result: {
+      status: mapInteractionStatus(interaction.status),
+      report,
+      citations,
+      usage: usageFromInteraction(interaction, streamedSearches),
+      raw: interaction
+    }
+  };
+}
+async function* normalizeInteractionsStream(stream2, fetchFinal) {
+  let streamedSearches = 0;
+  const countedSearchSteps = /* @__PURE__ */ new Set();
+  let interactionId;
+  for await (const event of stream2) {
+    const cursor = event.event_id;
+    switch (event.event_type) {
+      case "interaction.created": {
+        const interaction = event.interaction;
+        interactionId = interaction.id;
+        yield { type: "created", jobId: interaction.id, cursor, rawEvent: event };
+        yield { type: "status", status: mapInteractionStatus(interaction.status), cursor };
+        break;
+      }
+      case "interaction.status_update":
+        yield {
+          type: "status",
+          status: mapInteractionStatus(event.status),
+          cursor,
+          rawEvent: event
+        };
+        break;
+      case "step.start": {
+        const step = event.step;
+        if (step.type === "thought") {
+          yield { type: "phase", phase: "reasoning", cursor, rawEvent: event };
+        } else if (step.type === "model_output") {
+          yield { type: "phase", phase: "writing", cursor, rawEvent: event };
+        } else if (step.type === "google_search_call") {
+          if (!countedSearchSteps.has(event.index)) {
+            countedSearchSteps.add(event.index);
+            streamedSearches += step.arguments?.queries?.length ?? 1;
+          }
+          yield { type: "phase", phase: "searching", cursor, rawEvent: event };
+          yield {
+            type: "search",
+            action: "search",
+            status: "started",
+            query: step.arguments?.queries?.join("; "),
+            cursor
+          };
+        } else if (step.type === "google_search_result") {
+          yield { type: "search", action: "search", status: "completed", cursor, rawEvent: event };
+        }
+        break;
+      }
+      case "step.delta":
+        yield* normalizeDelta(event, cursor, (queries) => {
+          if (!countedSearchSteps.has(event.index)) {
+            countedSearchSteps.add(event.index);
+            streamedSearches += queries;
+          }
+        });
+        break;
+      case "step.stop":
+        break;
+      case "interaction.completed": {
+        let interaction = event.interaction;
+        const finalId = interaction.id ?? interactionId;
+        if (fetchFinal && finalId !== void 0 && !interaction.usage?.total_tokens) {
+          try {
+            interaction = await fetchFinal(finalId);
+          } catch {
+          }
+        }
+        const searches = streamedSearches > 0 ? streamedSearches : void 0;
+        yield {
+          type: "usage",
+          usage: usageFromInteraction(interaction, searches),
+          cursor,
+          rawEvent: event
+        };
+        yield { ...doneEventFromInteraction(interaction, searches), cursor };
+        break;
+      }
+      case "error":
+        if (event.error?.code === "client_closed_request") break;
+        yield {
+          type: "error",
+          error: {
+            message: event.error?.message ?? "Gemini interaction error",
+            code: event.error?.code !== void 0 ? String(event.error.code) : void 0,
+            retryable: isRetryableError(new Error(event.error?.message ?? ""))
+          },
+          cursor,
+          rawEvent: event
+        };
+        break;
+      default: {
+        const type = event.event_type ?? "";
+        if (type.endsWith("error")) {
+          const err = event.error;
+          if (err?.code === "client_closed_request") break;
+          yield {
+            type: "error",
+            error: { message: err?.message ?? "Gemini interaction error", retryable: false },
+            cursor,
+            rawEvent: event
+          };
+        }
+        break;
+      }
+    }
+  }
+}
+function* normalizeDelta(event, cursor, onSearchCall) {
+  const delta = event.delta;
+  switch (delta.type) {
+    case "text": {
+      const textDelta = delta;
+      yield { type: "text", delta: textDelta.text, cursor, rawEvent: event };
+      break;
+    }
+    // Citations arrive as dedicated annotation deltas in the current schema.
+    case "text_annotation_delta": {
+      const annotationDelta = delta;
+      for (const annotation of annotationDelta.annotations ?? []) {
+        const citation = annotationToCitation(annotation);
+        if (citation) {
+          yield { type: "citation", citation, cursor, rawEvent: event };
+        }
+      }
+      break;
+    }
+    // The SDK emits "thought_summary"; some preview docs show "thought" —
+    // handle both defensively.
+    case "thought_summary":
+    case "thought": {
+      const thought = delta;
+      const text3 = thought.content?.type === "text" ? thought.content.text ?? "" : "";
+      if (text3.length > 0) {
+        yield { type: "thinking", delta: text3, cursor, rawEvent: event };
+      }
+      break;
+    }
+    case "thought_signature":
+      break;
+    case "google_search_call": {
+      const call = delta;
+      onSearchCall(call.arguments?.queries?.length ?? 1);
+      yield {
+        type: "search",
+        action: "search",
+        status: "started",
+        query: call.arguments?.queries?.join("; "),
+        cursor,
+        rawEvent: event
+      };
+      break;
+    }
+    case "google_search_result": {
+      const result = delta;
+      yield {
+        type: "search",
+        action: "search",
+        status: "completed",
+        url: result.result?.[0]?.url,
+        cursor,
+        rawEvent: event
+      };
+      break;
+    }
+    case "url_context_call": {
+      const call = delta;
+      yield {
+        type: "search",
+        action: "open_page",
+        status: "started",
+        url: call.arguments?.urls?.[0],
+        cursor,
+        rawEvent: event
+      };
+      break;
+    }
+    case "url_context_result":
+      yield { type: "search", action: "open_page", status: "completed", cursor, rawEvent: event };
+      break;
+    case "code_execution_call":
+      yield { type: "tool", tool: "code_interpreter", status: "started", cursor, rawEvent: event };
+      break;
+    case "code_execution_result":
+      yield {
+        type: "tool",
+        tool: "code_interpreter",
+        status: "completed",
+        cursor,
+        rawEvent: event
+      };
+      break;
+    case "file_search_call":
+      yield { type: "tool", tool: "file_search", status: "started", cursor, rawEvent: event };
+      break;
+    case "file_search_result":
+      yield { type: "tool", tool: "file_search", status: "completed", cursor, rawEvent: event };
+      break;
+    case "mcp_server_tool_call":
+      yield { type: "tool", tool: "mcp", status: "started", cursor, rawEvent: event };
+      break;
+    case "mcp_server_tool_result":
+      yield { type: "tool", tool: "mcp", status: "completed", cursor, rawEvent: event };
+      break;
+    default:
+      break;
+  }
+}
+function abortError() {
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    timer.unref?.();
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function withRetries(fn, maxRetries, signal) {
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (isAbortError(err) || !isRetryableError(err) || attempt >= maxRetries) {
+        throw err;
+      }
+      attempt += 1;
+      await sleep(extractRetryAfterMs(err) ?? RESEARCH_POLL_INTERVAL_MS, signal);
+    }
+  }
+}
+async function* withTerminalReconciliation(events, client, jobIdHint, signal) {
+  let jobId = jobIdHint;
+  let sawDone = false;
+  for await (const event of events) {
+    if (event.type === "created" && event.jobId !== null) jobId = event.jobId;
+    if (event.type === "done") sawDone = true;
+    yield event;
+  }
+  if (sawDone || jobId === void 0) return;
+  const fetchInteraction = finalInteractionFetcher(client, signal);
+  while (true) {
+    const interaction = await fetchInteraction(jobId);
+    const status = mapInteractionStatus(interaction.status);
+    yield { type: "status", status };
+    if (isTerminalStatus(status)) {
+      yield { type: "usage", usage: usageFromInteraction(interaction) };
+      yield doneEventFromInteraction(interaction);
+      return;
+    }
+    await sleep(RESEARCH_POLL_INTERVAL_MS, signal);
+  }
+}
+function startGeminiResearch(client, options, agentId, _spec) {
+  const request = buildGeminiResearchRequest(options, agentId);
+  return (async function* () {
+    const interaction = await withRetries(
+      () => client.interactions.create(request, requestOptions(options.signal)),
+      GEMINI_RESEARCH_CREATE_MAX_RETRIES,
+      options.signal
+    );
+    if (interaction.id === void 0) {
+      throw new Error(
+        "Gemini interactions.create returned no interaction id \u2014 cannot stream events."
+      );
+    }
+    yield { type: "created", jobId: interaction.id, rawEvent: interaction };
+    yield { type: "status", status: mapInteractionStatus(interaction.status) };
+    const stream2 = await client.interactions.get(
+      interaction.id,
+      { stream: true },
+      requestOptions(options.signal)
+    );
+    for await (const event of withTerminalReconciliation(
+      normalizeInteractionsStream(stream2, finalInteractionFetcher(client, options.signal)),
+      client,
+      interaction.id,
+      options.signal
+    )) {
+      if (event.type === "created") continue;
+      yield event;
+    }
+  })();
+}
+function isTerminalStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled" || status === "incomplete" || status === "budget_exceeded";
+}
+function resumeGeminiResearch(client, ref, signal) {
+  return (async function* () {
+    const current = await client.interactions.get(
+      ref.jobId,
+      void 0,
+      requestOptions(signal)
+    );
+    const status = mapInteractionStatus(current.status);
+    if (isTerminalStatus(status)) {
+      yield { type: "status", status };
+      const { report, citations } = extractReportFromInteraction(current);
+      if (report.length > 0) {
+        yield { type: "text", delta: report };
+      }
+      for (const citation of citations) {
+        yield { type: "citation", citation };
+      }
+      yield { type: "usage", usage: usageFromInteraction(current) };
+      yield doneEventFromInteraction(current);
+      return;
+    }
+    const stream2 = await client.interactions.get(
+      ref.jobId,
+      { stream: true, ...ref.cursor !== void 0 ? { last_event_id: ref.cursor } : {} },
+      requestOptions(signal)
+    );
+    yield* withTerminalReconciliation(
+      normalizeInteractionsStream(stream2, finalInteractionFetcher(client, signal)),
+      client,
+      ref.jobId,
+      signal
+    );
+  })();
+}
+async function getGeminiResearchStatus(client, ref) {
+  const interaction = await client.interactions.get(
+    ref.jobId
+  );
+  const status = mapInteractionStatus(interaction.status);
+  if (!isTerminalStatus(status)) {
+    return { status };
+  }
+  const { report, citations } = extractReportFromInteraction(interaction);
+  return {
+    status,
+    result: {
+      jobId: interaction.id,
+      provider: "gemini",
+      model: ref.model,
+      status,
+      report,
+      citations,
+      usage: usageFromInteraction(interaction),
+      raw: interaction
+    }
+  };
+}
+async function cancelGeminiResearch(client, ref) {
+  await client.interactions.cancel(ref.jobId);
+}
+var GEMINI_RESEARCH_CREATE_MAX_RETRIES, GEMINI_STATUS_VALUES, requestOptions, finalInteractionFetcher;
+var init_gemini_research = __esm({
+  "src/providers/gemini-research.ts"() {
+    "use strict";
+    init_errors2();
+    init_retry();
+    init_constants3();
+    init_errors3();
+    GEMINI_RESEARCH_CREATE_MAX_RETRIES = 3;
+    GEMINI_STATUS_VALUES = /* @__PURE__ */ new Set([
+      "queued",
+      "in_progress",
+      "requires_action",
+      "completed",
+      "failed",
+      "cancelled",
+      "incomplete",
+      "budget_exceeded"
+    ]);
+    requestOptions = (signal) => ({
+      timeout: GEMINI_RESEARCH_MAX_DURATION_MS,
+      signal,
+      // The SDK's own retries would fight llmist's retry policy.
+      maxRetries: 0
+    });
+    finalInteractionFetcher = (client, signal) => (id) => client.interactions.get(
+      id,
+      void 0,
+      requestOptions(signal)
+    );
+  }
+});
+
+// src/providers/gemini-research-models.ts
+function geminiResearchAgent(params) {
+  return {
+    provider: "gemini",
+    modelId: params.agentId,
+    kind: "agent",
+    displayName: params.displayName,
+    // Gemini 3.1 Pro base-tier token rates; >200K-context tier is higher.
+    pricing: { input: 2, output: 12, perThousandSearches: 14 },
+    capabilities: {
+      streaming: true,
+      // The Interactions API requires background execution for deep research.
+      background: true,
+      resumable: true,
+      followUps: true,
+      // Research tools are agent-managed — the tools option is not accepted.
+      tools: []
+    },
+    // Interactions enforces a 60-minute research cap server-side.
+    maxDurationMs: GEMINI_RESEARCH_MAX_DURATION_MS,
+    metadata: params.notes ? { notes: params.notes } : void 0
+  };
+}
+function isGeminiResearchModel(agentId) {
+  return byId.has(agentId);
+}
+var geminiResearchModels, byId;
+var init_gemini_research_models = __esm({
+  "src/providers/gemini-research-models.ts"() {
+    "use strict";
+    init_constants3();
+    geminiResearchModels = [
+      geminiResearchAgent({
+        agentId: "deep-research-preview-04-2026",
+        displayName: "Gemini Deep Research (preview 04-2026)",
+        notes: "Speed-optimized deep research agent on a Gemini 3.1 Pro core."
+      }),
+      geminiResearchAgent({
+        agentId: "deep-research-max-preview-04-2026",
+        displayName: "Gemini Deep Research Max (preview 04-2026)",
+        notes: "Maximum-comprehensiveness variant; roughly 2x the searches and tokens per run."
+      }),
+      geminiResearchAgent({
+        agentId: "deep-research-pro-preview-12-2025",
+        displayName: "Gemini Deep Research Pro (preview 12-2025)",
+        notes: "Original deep research agent (Gemini 3 Pro core); prefer the 04-2026 agents."
+      })
+    ];
+    byId = new Map(geminiResearchModels.map((spec) => [spec.modelId, spec]));
+  }
+});
+
 // src/providers/gemini-speech-models.ts
 function getGeminiSpeechModelSpec(modelId) {
   return geminiSpeechModels.find((m) => m.modelId === modelId);
@@ -7394,6 +8013,8 @@ var init_gemini = __esm({
     init_gemini_cache_manager();
     init_gemini_image_models();
     init_gemini_models();
+    init_gemini_research();
+    init_gemini_research_models();
     init_gemini_speech_models();
     init_utils();
     GEMINI3_PRO_THINKING_LEVEL = {
@@ -7613,6 +8234,27 @@ var init_gemini = __esm({
           format: spec?.defaultFormat ?? "wav"
         };
       }
+      // =========================================================================
+      // Deep Research (Interactions API)
+      // =========================================================================
+      getResearchModelSpecs() {
+        return geminiResearchModels;
+      }
+      supportsResearch(agentId) {
+        return isGeminiResearchModel(agentId);
+      }
+      startResearch(options, descriptor, spec) {
+        return startGeminiResearch(this.client, options, descriptor.name, spec);
+      }
+      resumeResearch(ref, signal) {
+        return resumeGeminiResearch(this.client, ref, signal);
+      }
+      getResearchStatus(ref) {
+        return getGeminiResearchStatus(this.client, ref);
+      }
+      cancelResearch(ref) {
+        return cancelGeminiResearch(this.client, ref);
+      }
       buildApiRequest(options, descriptor, _spec, messages) {
         const contents = this.convertMessagesToContents(messages);
         return this.buildApiRequestFromContents(options, descriptor, _spec, contents, null, 0);
@@ -8839,17 +9481,17 @@ var init_openai_compatible_provider = __esm({
       async executeStreamRequest(payload, signal) {
         const client = this.client;
         const headers = this.getCustomHeaders();
-        const requestOptions = {};
+        const requestOptions3 = {};
         if (signal) {
-          requestOptions.signal = signal;
+          requestOptions3.signal = signal;
         }
         if (Object.keys(headers).length > 0) {
-          requestOptions.headers = headers;
+          requestOptions3.headers = headers;
         }
         try {
           const stream2 = await client.chat.completions.create(
             payload,
-            Object.keys(requestOptions).length > 0 ? requestOptions : void 0
+            Object.keys(requestOptions3).length > 0 ? requestOptions3 : void 0
           );
           return stream2;
         } catch (error) {
@@ -9726,6 +10368,549 @@ var init_openai_models = __esm({
   }
 });
 
+// src/providers/openai-research.ts
+function buildTools(options) {
+  const tools = [];
+  for (const tool of options.tools ?? []) {
+    switch (tool.type) {
+      case "web_search":
+        tools.push({ type: "web_search_preview" });
+        break;
+      case "file_search":
+        if (tool.vectorStoreIds.length > OPENAI_FILE_SEARCH_MAX_VECTOR_STORES) {
+          throw new ResearchValidationError(
+            `OpenAI file_search accepts at most ${OPENAI_FILE_SEARCH_MAX_VECTOR_STORES} vector stores (got ${tool.vectorStoreIds.length}).`
+          );
+        }
+        tools.push({ type: "file_search", vector_store_ids: tool.vectorStoreIds });
+        break;
+      case "mcp":
+        tools.push({
+          type: "mcp",
+          server_label: tool.serverLabel,
+          server_url: tool.serverUrl,
+          require_approval: tool.requireApproval ?? "never"
+        });
+        break;
+      case "code_interpreter":
+        tools.push({ type: "code_interpreter", container: { type: "auto" } });
+        break;
+    }
+  }
+  return tools;
+}
+function buildResponsesResearchRequest(options, spec, modelId) {
+  const tools = buildTools(options);
+  const hasDataSource = (options.tools ?? []).some(
+    (tool) => ["web_search", "file_search", "mcp"].includes(tool.type)
+  );
+  if (!hasDataSource) {
+    throw new ResearchValidationError(
+      "OpenAI deep research requires at least one data-source tool (web_search, file_search, or mcp)."
+    );
+  }
+  const background = options.background ?? spec?.capabilities.background ?? true;
+  const input = options.systemPrompt ? `${options.systemPrompt}
+
+${options.query}` : options.query;
+  const request = {
+    model: modelId,
+    input,
+    background,
+    // Background mode requires stored responses; polling/resume need them too.
+    ...background ? { store: true } : {},
+    reasoning: {
+      summary: "auto",
+      ...options.reasoning?.effort && options.reasoning.effort !== "none" ? { effort: mapEffort(options.reasoning.effort) } : {}
+    },
+    tools,
+    ...options.maxToolCalls !== void 0 ? { max_tool_calls: options.maxToolCalls } : {},
+    ...options.extra ?? {}
+  };
+  return request;
+}
+function mapEffort(effort) {
+  switch (effort) {
+    case "maximum":
+      return "xhigh";
+    case "low":
+    case "medium":
+    case "high":
+      return effort;
+    default:
+      return "medium";
+  }
+}
+function extractReportFromResponse(response) {
+  const citations = [];
+  const parts = [];
+  for (const item of response.output ?? []) {
+    if (item.type !== "message") continue;
+    for (const content of item.content ?? []) {
+      if (content.type !== "output_text") continue;
+      parts.push(content.text);
+      for (const annotation of content.annotations ?? []) {
+        const citation = annotationToCitation2(annotation);
+        if (citation) citations.push(citation);
+      }
+    }
+  }
+  return { report: parts.join(""), citations };
+}
+function annotationToCitation2(annotation) {
+  if (typeof annotation !== "object" || annotation === null) return void 0;
+  const a = annotation;
+  if (a.type !== "url_citation" || typeof a.url !== "string") return void 0;
+  return {
+    url: a.url,
+    title: typeof a.title === "string" ? a.title : void 0,
+    startIndex: typeof a.start_index === "number" ? a.start_index : void 0,
+    endIndex: typeof a.end_index === "number" ? a.end_index : void 0
+  };
+}
+function countSearches(response) {
+  let searches = 0;
+  for (const item of response.output ?? []) {
+    if (item.type === "web_search_call") searches += 1;
+  }
+  return searches;
+}
+function usageFromResponse(response) {
+  const usage = response.usage;
+  return {
+    inputTokens: usage?.input_tokens ?? 0,
+    outputTokens: usage?.output_tokens ?? 0,
+    totalTokens: usage?.total_tokens ?? 0,
+    cachedInputTokens: usage?.input_tokens_details?.cached_tokens,
+    reasoningTokens: usage?.output_tokens_details?.reasoning_tokens,
+    searches: countSearches(response)
+  };
+}
+function mapResponseStatus(status) {
+  return status && STATUS_MAP[status] || "in_progress";
+}
+function doneEventFromResponse(response) {
+  const { report, citations } = extractReportFromResponse(response);
+  return {
+    type: "done",
+    result: {
+      status: mapResponseStatus(response.status),
+      report,
+      citations,
+      usage: usageFromResponse(response),
+      raw: response
+    }
+  };
+}
+async function* normalizeResponsesStream(stream2) {
+  const searchStarted = /* @__PURE__ */ new Set();
+  for await (const event of stream2) {
+    const cursor = String(event.sequence_number);
+    switch (event.type) {
+      case "response.created":
+        yield { type: "created", jobId: event.response.id, cursor, rawEvent: event };
+        yield { type: "status", status: mapResponseStatus(event.response.status), cursor };
+        break;
+      case "response.queued":
+        yield { type: "status", status: "queued", cursor, rawEvent: event };
+        break;
+      case "response.in_progress":
+        yield { type: "status", status: "in_progress", cursor, rawEvent: event };
+        break;
+      case "response.output_item.added": {
+        const item = event.item;
+        if (item.type === "reasoning") {
+          yield { type: "phase", phase: "reasoning", cursor, rawEvent: event };
+        } else if (item.type === "web_search_call") {
+          const action = "action" in item ? item.action : void 0;
+          searchStarted.add(item.id);
+          yield {
+            type: "search",
+            action: action?.type ?? "search",
+            status: "started",
+            query: action && "query" in action ? action.query ?? void 0 : void 0,
+            url: action && "url" in action ? action.url ?? void 0 : void 0,
+            cursor,
+            rawEvent: event
+          };
+        } else if (item.type === "code_interpreter_call") {
+          yield {
+            type: "tool",
+            tool: "code_interpreter",
+            status: "started",
+            cursor,
+            rawEvent: event
+          };
+        } else if (item.type === "file_search_call") {
+          yield { type: "tool", tool: "file_search", status: "started", cursor, rawEvent: event };
+        } else if (item.type === "mcp_call") {
+          yield { type: "tool", tool: "mcp", status: "started", cursor, rawEvent: event };
+        } else if (item.type === "message") {
+          yield { type: "phase", phase: "writing", cursor, rawEvent: event };
+        }
+        break;
+      }
+      case "response.web_search_call.in_progress":
+      case "response.web_search_call.searching":
+        if (!searchStarted.has(event.item_id)) {
+          searchStarted.add(event.item_id);
+          yield { type: "search", action: "search", status: "started", cursor, rawEvent: event };
+        }
+        break;
+      case "response.web_search_call.completed":
+        yield { type: "search", action: "search", status: "completed", cursor, rawEvent: event };
+        break;
+      case "response.code_interpreter_call.completed":
+        yield {
+          type: "tool",
+          tool: "code_interpreter",
+          status: "completed",
+          cursor,
+          rawEvent: event
+        };
+        break;
+      case "response.file_search_call.completed":
+        yield { type: "tool", tool: "file_search", status: "completed", cursor, rawEvent: event };
+        break;
+      case "response.mcp_call.completed":
+        yield { type: "tool", tool: "mcp", status: "completed", cursor, rawEvent: event };
+        break;
+      case "response.reasoning_summary_text.delta":
+        yield { type: "thinking", delta: event.delta, cursor, rawEvent: event };
+        break;
+      case "response.output_text.delta":
+        yield { type: "text", delta: event.delta, cursor, rawEvent: event };
+        break;
+      case "response.output_text.annotation.added": {
+        const citation = annotationToCitation2(event.annotation);
+        if (citation) {
+          yield { type: "citation", citation, cursor, rawEvent: event };
+        }
+        break;
+      }
+      case "response.completed":
+      case "response.failed":
+      case "response.incomplete": {
+        const response = event.response;
+        yield { type: "usage", usage: usageFromResponse(response), cursor, rawEvent: event };
+        if (event.type === "response.failed") {
+          const message = response.error?.message ?? "OpenAI research run failed";
+          yield {
+            type: "error",
+            error: { message, code: response.error?.code ?? void 0, retryable: false },
+            cursor
+          };
+        }
+        yield { ...doneEventFromResponse(response), cursor };
+        break;
+      }
+      case "error": {
+        const err = new Error(event.message ?? "OpenAI stream error");
+        yield {
+          type: "error",
+          error: {
+            message: event.message ?? "OpenAI stream error",
+            code: event.code ?? void 0,
+            retryable: isRetryableError(err)
+          },
+          cursor,
+          rawEvent: event
+        };
+        break;
+      }
+      default: {
+        const type = event.type;
+        if (type === "response.cancelled") {
+          const response = event.response;
+          yield { type: "usage", usage: usageFromResponse(response), cursor, rawEvent: event };
+          yield { ...doneEventFromResponse(response), cursor };
+        }
+        break;
+      }
+    }
+  }
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    if (signal?.aborted) {
+      reject(abortError2());
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    timer.unref?.();
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError2());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function abortError2() {
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+async function withRetries2(fn, maxRetries, signal) {
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (isAbortError(err) || !isRetryableError(err) || attempt >= maxRetries) {
+        throw err;
+      }
+      attempt += 1;
+      const retryAfter = extractRetryAfterMs(err);
+      await sleep2(retryAfter ?? RESEARCH_POLL_INTERVAL_MS, signal);
+    }
+  }
+}
+function startOpenAIResearch(client, options, modelId, spec) {
+  const request = buildResponsesResearchRequest(options, spec, modelId);
+  const streaming = spec?.capabilities.streaming ?? true;
+  if (streaming) {
+    return (async function* () {
+      const stream2 = await withRetries2(
+        () => client.responses.create(
+          { ...request, stream: true },
+          requestOptions2(options.signal)
+        ),
+        OPENAI_RESEARCH_CREATE_MAX_RETRIES,
+        options.signal
+      );
+      yield* normalizeResponsesStream(stream2);
+    })();
+  }
+  return (async function* () {
+    const created = await withRetries2(
+      () => client.responses.create(
+        { ...request, background: true, store: true, stream: false },
+        requestOptions2(options.signal)
+      ),
+      OPENAI_RESEARCH_CREATE_MAX_RETRIES,
+      options.signal
+    );
+    yield { type: "created", jobId: created.id, rawEvent: created };
+    yield* pollResponseToCompletion(client, created.id, created, options.signal);
+  })();
+}
+function* emitTerminalResponse(response) {
+  const status = mapResponseStatus(response.status);
+  const { report, citations } = extractReportFromResponse(response);
+  if (report.length > 0) {
+    yield { type: "text", delta: report };
+  }
+  for (const citation of citations) {
+    yield { type: "citation", citation };
+  }
+  yield { type: "usage", usage: usageFromResponse(response) };
+  if (status === "failed") {
+    yield {
+      type: "error",
+      error: {
+        message: response.error?.message ?? "OpenAI research run failed",
+        code: response.error?.code ?? void 0,
+        retryable: false
+      }
+    };
+  }
+  yield doneEventFromResponse(response);
+}
+async function* pollResponseToCompletion(client, responseId, initial, signal) {
+  let interval = RESEARCH_POLL_INTERVAL_MS;
+  let current = initial;
+  while (true) {
+    const status = mapResponseStatus(current?.status);
+    yield { type: "status", status, rawEvent: current };
+    if (current && isTerminalStatus2(status)) {
+      yield* emitTerminalResponse(current);
+      return;
+    }
+    await sleep2(interval, signal);
+    interval = Math.min(interval * RESEARCH_POLL_BACKOFF_FACTOR, RESEARCH_POLL_MAX_INTERVAL_MS);
+    current = await withRetries2(
+      () => client.responses.retrieve(responseId, {}, requestOptions2(signal)),
+      OPENAI_RESEARCH_POLL_MAX_RETRIES,
+      signal
+    );
+  }
+}
+function isTerminalStatus2(status) {
+  return status === "completed" || status === "failed" || status === "cancelled" || status === "incomplete";
+}
+function resumeOpenAIResearch(client, ref, spec, signal) {
+  const streaming = spec?.capabilities.streaming ?? true;
+  if (streaming) {
+    return (async function* () {
+      const current = await withRetries2(
+        () => client.responses.retrieve(ref.jobId, {}, requestOptions2(signal)),
+        OPENAI_RESEARCH_POLL_MAX_RETRIES,
+        signal
+      );
+      if (isTerminalStatus2(mapResponseStatus(current.status))) {
+        yield { type: "status", status: mapResponseStatus(current.status) };
+        yield* emitTerminalResponse(current);
+        return;
+      }
+      const stream2 = await client.responses.retrieve(
+        ref.jobId,
+        {
+          stream: true,
+          ...ref.cursor !== void 0 ? { starting_after: Number(ref.cursor) } : {}
+        },
+        requestOptions2(signal)
+      );
+      yield* normalizeResponsesStream(stream2);
+    })();
+  }
+  return pollResponseToCompletion(client, ref.jobId, void 0, signal);
+}
+async function getOpenAIResearchStatus(client, ref) {
+  const response = await client.responses.retrieve(ref.jobId, {});
+  const status = mapResponseStatus(response.status);
+  if (!isTerminalStatus2(status)) {
+    return { status };
+  }
+  const { report, citations } = extractReportFromResponse(response);
+  return {
+    status,
+    result: {
+      jobId: response.id,
+      provider: "openai",
+      model: ref.model,
+      status,
+      report,
+      citations,
+      usage: usageFromResponse(response),
+      raw: response
+    }
+  };
+}
+async function cancelOpenAIResearch(client, ref) {
+  await client.responses.cancel(ref.jobId);
+}
+var OPENAI_FILE_SEARCH_MAX_VECTOR_STORES, OPENAI_RESEARCH_CREATE_MAX_RETRIES, OPENAI_RESEARCH_POLL_MAX_RETRIES, STATUS_MAP, requestOptions2;
+var init_openai_research = __esm({
+  "src/providers/openai-research.ts"() {
+    "use strict";
+    init_errors2();
+    init_retry();
+    init_constants3();
+    init_errors3();
+    OPENAI_FILE_SEARCH_MAX_VECTOR_STORES = 2;
+    OPENAI_RESEARCH_CREATE_MAX_RETRIES = 3;
+    OPENAI_RESEARCH_POLL_MAX_RETRIES = 5;
+    STATUS_MAP = {
+      queued: "queued",
+      in_progress: "in_progress",
+      completed: "completed",
+      failed: "failed",
+      cancelled: "cancelled",
+      incomplete: "incomplete"
+    };
+    requestOptions2 = (signal) => ({
+      timeout: OPENAI_RESEARCH_HTTP_TIMEOUT_MS,
+      signal
+    });
+  }
+});
+
+// src/providers/openai-research-models.ts
+function o3DeepResearch(modelId) {
+  return {
+    provider: "openai",
+    modelId,
+    kind: "model",
+    displayName: "o3 Deep Research",
+    contextWindow: 2e5,
+    maxOutputTokens: 1e5,
+    pricing: { input: 10, cachedInput: 2.5, output: 40, perThousandSearches: 10 },
+    capabilities: {
+      streaming: true,
+      background: true,
+      resumable: true,
+      tools: DEEP_RESEARCH_TOOLS
+    },
+    requiredTools: [{ type: "web_search" }],
+    metadata: { releaseDate: "2025-06-26", ...DEEP_RESEARCH_SHUTDOWN }
+  };
+}
+function o4MiniDeepResearch(modelId) {
+  return {
+    provider: "openai",
+    modelId,
+    kind: "model",
+    displayName: "o4-mini Deep Research",
+    contextWindow: 2e5,
+    maxOutputTokens: 1e5,
+    pricing: { input: 2, cachedInput: 0.5, output: 8, perThousandSearches: 10 },
+    capabilities: {
+      streaming: true,
+      background: true,
+      resumable: true,
+      tools: DEEP_RESEARCH_TOOLS
+    },
+    requiredTools: [{ type: "web_search" }],
+    metadata: { releaseDate: "2025-06-26", ...DEEP_RESEARCH_SHUTDOWN }
+  };
+}
+function getOpenAIResearchModelSpec(modelId) {
+  return byId2.get(modelId);
+}
+function isOpenAIResearchModel(modelId) {
+  return byId2.has(modelId);
+}
+var DEEP_RESEARCH_TOOLS, DEEP_RESEARCH_SHUTDOWN, openaiResearchModels, byId2;
+var init_openai_research_models = __esm({
+  "src/providers/openai-research-models.ts"() {
+    "use strict";
+    DEEP_RESEARCH_TOOLS = [
+      "web_search",
+      "file_search",
+      "mcp",
+      "code_interpreter"
+    ];
+    DEEP_RESEARCH_SHUTDOWN = {
+      deprecationDate: "2026-04-22",
+      shutdownDate: "2026-07-23",
+      replacement: "gpt-5.5-pro"
+    };
+    openaiResearchModels = [
+      o3DeepResearch("o3-deep-research"),
+      o3DeepResearch("o3-deep-research-2025-06-26"),
+      o4MiniDeepResearch("o4-mini-deep-research"),
+      o4MiniDeepResearch("o4-mini-deep-research-2025-06-26"),
+      {
+        provider: "openai",
+        modelId: "gpt-5.5-pro",
+        kind: "model",
+        displayName: "GPT-5.5 Pro (research)",
+        contextWindow: 105e4,
+        maxOutputTokens: 128e3,
+        pricing: { input: 30, output: 180, perThousandSearches: 10 },
+        capabilities: {
+          // No live streaming — runs execute via background create + poll.
+          streaming: false,
+          background: true,
+          // Resumable in the attach sense: the poll loop re-attaches by job id.
+          resumable: true,
+          tools: DEEP_RESEARCH_TOOLS
+        },
+        requiredTools: [{ type: "web_search" }],
+        metadata: {
+          releaseDate: "2026-04-24",
+          notes: "Designated replacement for the o3/o4-mini deep research models."
+        }
+      }
+    ];
+    byId2 = new Map(openaiResearchModels.map((spec) => [spec.modelId, spec]));
+  }
+});
+
 // src/providers/openai-speech-models.ts
 function getOpenAISpeechModelSpec(modelId) {
   return openaiSpeechModels.find((m) => m.modelId === modelId);
@@ -9881,6 +11066,8 @@ var init_openai = __esm({
     init_constants2();
     init_openai_image_models();
     init_openai_models();
+    init_openai_research();
+    init_openai_research_models();
     init_openai_speech_models();
     init_utils();
     ROLE_MAP2 = {
@@ -9984,6 +11171,32 @@ var init_openai = __esm({
           format: format2
         };
       }
+      // =========================================================================
+      // Deep Research (Responses API)
+      // =========================================================================
+      getResearchModelSpecs() {
+        return openaiResearchModels;
+      }
+      supportsResearch(modelId) {
+        return isOpenAIResearchModel(modelId);
+      }
+      startResearch(options, descriptor, spec) {
+        return startOpenAIResearch(this.client, options, descriptor.name, spec);
+      }
+      resumeResearch(ref, signal) {
+        return resumeOpenAIResearch(
+          this.client,
+          ref,
+          getOpenAIResearchModelSpec(ref.model),
+          signal
+        );
+      }
+      getResearchStatus(ref) {
+        return getOpenAIResearchStatus(this.client, ref);
+      }
+      cancelResearch(ref) {
+        return cancelOpenAIResearch(this.client, ref);
+      }
       buildApiRequest(options, descriptor, spec, messages) {
         const { maxTokens, temperature, topP, stopSequences, extra, reasoning } = options;
         const supportsTemperature = spec?.metadata?.supportsTemperature !== false;
@@ -10679,35 +11892,246 @@ var init_openrouter_models = __esm({
           vision: false
         },
         metadata: {
-          family: "Mixtral",
-          notes: "Mixtral 8x22B via OpenRouter. Sparse MoE architecture."
+          family: "Mixtral",
+          notes: "Mixtral 8x22B via OpenRouter. Sparse MoE architecture."
+        }
+      },
+      // ============================================================
+      // Qwen Models (via OpenRouter)
+      // ============================================================
+      {
+        provider: "openrouter",
+        modelId: "qwen/qwen-2.5-72b-instruct",
+        displayName: "Qwen 2.5 72B Instruct (OpenRouter)",
+        contextWindow: 131072,
+        maxOutputTokens: 8192,
+        pricing: {
+          input: 0.35,
+          output: 0.4
+        },
+        knowledgeCutoff: "2024-09",
+        features: {
+          streaming: true,
+          functionCalling: true,
+          vision: false
+        },
+        metadata: {
+          family: "Qwen 2.5",
+          notes: "Qwen 2.5 72B via OpenRouter. Strong coding and math."
+        }
+      }
+    ];
+  }
+});
+
+// src/providers/openrouter-research.ts
+function buildOpenRouterResearchMessages(options) {
+  if (options.background === true) {
+    throw new ResearchValidationError(
+      "OpenRouter has no background mode for research runs \u2014 the stream must stay open."
+    );
+  }
+  if (options.tools !== void 0 && options.tools.length > 0) {
+    throw new ResearchValidationError(
+      "OpenRouter research models manage their tools server-side \u2014 omit the tools option."
+    );
+  }
+  const messages = [];
+  if (options.systemPrompt) {
+    messages.push({ role: "system", content: options.systemPrompt });
+  }
+  messages.push({ role: "user", content: options.query });
+  return { messages };
+}
+function citationKey(citation) {
+  return `${citation.url}#${citation.startIndex ?? ""}`;
+}
+function mapFinishReason(reason) {
+  switch (reason) {
+    case "length":
+      return "incomplete";
+    case "error":
+      return "failed";
+    default:
+      return "completed";
+  }
+}
+async function* normalizeOpenRouterResearchStream(stream2) {
+  let createdEmitted = false;
+  const seenCitations = /* @__PURE__ */ new Set();
+  const seenCitationUrls = /* @__PURE__ */ new Set();
+  const bufferedLegacyCitations = [];
+  let usage;
+  let terminalStatus;
+  let lastRaw;
+  for await (const chunk of stream2) {
+    lastRaw = chunk;
+    if (!createdEmitted) {
+      createdEmitted = true;
+      yield { type: "created", jobId: null, rawEvent: chunk };
+      yield { type: "status", status: "in_progress" };
+    }
+    const choice = chunk.choices?.[0];
+    const delta = choice?.delta ?? {};
+    const detailTexts = (delta.reasoning_details ?? []).filter((detail) => typeof detail.text === "string" && detail.text.length > 0).map((detail) => detail.text);
+    if (detailTexts.length > 0) {
+      for (const text3 of detailTexts) {
+        yield { type: "thinking", delta: text3, rawEvent: chunk };
+      }
+    } else if (typeof delta.reasoning === "string" && delta.reasoning.length > 0) {
+      yield { type: "thinking", delta: delta.reasoning, rawEvent: chunk };
+    }
+    if (typeof delta.content === "string" && delta.content.length > 0) {
+      yield { type: "text", delta: delta.content, rawEvent: chunk };
+    }
+    const annotationSources = [
+      ...delta.annotations ?? [],
+      ...choice?.message?.annotations ?? []
+    ];
+    for (const annotation of annotationSources) {
+      if (annotation.type !== "url_citation" || !annotation.url_citation?.url) continue;
+      const citation = {
+        url: annotation.url_citation.url,
+        title: annotation.url_citation.title,
+        content: annotation.url_citation.content,
+        startIndex: annotation.url_citation.start_index,
+        endIndex: annotation.url_citation.end_index
+      };
+      const key = citationKey(citation);
+      if (!seenCitations.has(key)) {
+        seenCitations.add(key);
+        seenCitationUrls.add(citation.url);
+        yield { type: "citation", citation, rawEvent: chunk };
+      }
+    }
+    const legacyCitations = chunk.citations;
+    if (Array.isArray(legacyCitations)) {
+      for (const url of legacyCitations) {
+        bufferedLegacyCitations.push({ url, rawEvent: chunk });
+      }
+    }
+    if (choice?.finish_reason) {
+      terminalStatus = mapFinishReason(choice.finish_reason);
+    }
+    const chunkUsage = chunk.usage;
+    if (chunkUsage) {
+      usage = {
+        inputTokens: chunkUsage.prompt_tokens ?? 0,
+        outputTokens: chunkUsage.completion_tokens ?? 0,
+        totalTokens: chunkUsage.total_tokens ?? 0,
+        cachedInputTokens: chunkUsage.prompt_tokens_details?.cached_tokens ?? void 0,
+        reasoningTokens: chunkUsage.completion_tokens_details?.reasoning_tokens ?? void 0,
+        searches: chunkUsage.num_search_queries ?? chunkUsage.server_tool_use?.web_search_requests ?? void 0,
+        // Authoritative billed cost from OpenRouter usage accounting —
+        // preferred over the catalog estimate (collector keeps it).
+        costUSD: typeof chunkUsage.cost === "number" ? chunkUsage.cost : void 0
+      };
+    }
+  }
+  for (const { url, rawEvent } of bufferedLegacyCitations) {
+    if (seenCitationUrls.has(url)) continue;
+    seenCitationUrls.add(url);
+    yield { type: "citation", citation: { url }, rawEvent };
+  }
+  if (usage) {
+    yield { type: "usage", usage };
+  }
+  yield {
+    type: "done",
+    result: {
+      status: terminalStatus ?? "completed",
+      // Report text was streamed as deltas; the collector joins them.
+      report: "",
+      usage,
+      raw: lastRaw
+    }
+  };
+}
+var init_openrouter_research = __esm({
+  "src/providers/openrouter-research.ts"() {
+    "use strict";
+    init_errors3();
+  }
+});
+
+// src/providers/openrouter-research-models.ts
+function isOpenRouterResearchModel(modelId) {
+  return byId3.has(modelId);
+}
+var OPENROUTER_STREAM_ONLY, openrouterResearchModels, byId3;
+var init_openrouter_research_models = __esm({
+  "src/providers/openrouter-research-models.ts"() {
+    "use strict";
+    OPENROUTER_STREAM_ONLY = {
+      streaming: true,
+      background: false,
+      resumable: false,
+      tools: []
+    };
+    openrouterResearchModels = [
+      {
+        provider: "openrouter",
+        modelId: "perplexity/sonar-deep-research",
+        kind: "model",
+        displayName: "Perplexity Sonar Deep Research",
+        contextWindow: 128e3,
+        pricing: {
+          input: 2,
+          output: 8,
+          // Internal reasoning tokens are priced separately from output.
+          internalReasoning: 3,
+          perThousandSearches: 5
+        },
+        capabilities: OPENROUTER_STREAM_ONLY,
+        metadata: {
+          notes: "R1-style think-then-write: expect a long reasoning stream (100k+ tokens) before report text."
         }
       },
-      // ============================================================
-      // Qwen Models (via OpenRouter)
-      // ============================================================
       {
         provider: "openrouter",
-        modelId: "qwen/qwen-2.5-72b-instruct",
-        displayName: "Qwen 2.5 72B Instruct (OpenRouter)",
-        contextWindow: 131072,
-        maxOutputTokens: 8192,
-        pricing: {
-          input: 0.35,
-          output: 0.4
-        },
-        knowledgeCutoff: "2024-09",
-        features: {
-          streaming: true,
-          functionCalling: true,
-          vision: false
-        },
+        modelId: "perplexity/sonar-pro-search",
+        kind: "model",
+        displayName: "Perplexity Sonar Pro Search",
+        contextWindow: 2e5,
+        pricing: { input: 3, output: 15, perThousandSearches: 18 },
+        capabilities: OPENROUTER_STREAM_ONLY,
+        metadata: { notes: "Agentic multi-step Pro Search \u2014 lighter than full deep research." }
+      },
+      {
+        provider: "openrouter",
+        modelId: "openai/o3-deep-research",
+        kind: "model",
+        displayName: "OpenAI o3 Deep Research (via OpenRouter)",
+        contextWindow: 2e5,
+        maxOutputTokens: 1e5,
+        pricing: { input: 10, cachedInput: 2.5, output: 40, perThousandSearches: 10 },
+        capabilities: OPENROUTER_STREAM_ONLY,
         metadata: {
-          family: "Qwen 2.5",
-          notes: "Qwen 2.5 72B via OpenRouter. Strong coding and math."
+          // Upstream OpenAI shutdown propagates through OpenRouter.
+          deprecationDate: "2026-04-22",
+          shutdownDate: "2026-07-23",
+          replacement: "perplexity/sonar-deep-research",
+          notes: "Tools are managed upstream \u2014 requests carry no tools param via OpenRouter."
+        }
+      },
+      {
+        provider: "openrouter",
+        modelId: "openai/o4-mini-deep-research",
+        kind: "model",
+        displayName: "OpenAI o4-mini Deep Research (via OpenRouter)",
+        contextWindow: 2e5,
+        maxOutputTokens: 1e5,
+        pricing: { input: 2, cachedInput: 0.5, output: 8, perThousandSearches: 10 },
+        capabilities: OPENROUTER_STREAM_ONLY,
+        metadata: {
+          deprecationDate: "2026-04-22",
+          shutdownDate: "2026-07-23",
+          replacement: "perplexity/sonar-deep-research",
+          notes: "Tools are managed upstream \u2014 requests carry no tools param via OpenRouter."
         }
       }
     ];
+    byId3 = new Map(openrouterResearchModels.map((spec) => [spec.modelId, spec]));
   }
 });
 
@@ -10838,8 +12262,11 @@ var init_openrouter = __esm({
     "use strict";
     init_model_shortcuts();
     init_logger();
+    init_constants3();
     init_openai_compatible_provider();
     init_openrouter_models();
+    init_openrouter_research();
+    init_openrouter_research_models();
     init_openrouter_speech_models();
     init_utils();
     logger = createLogger({ name: "openrouter" });
@@ -10859,6 +12286,66 @@ var init_openrouter = __esm({
       getModelSpecs() {
         return OPENROUTER_MODELS;
       }
+      // =========================================================================
+      // Deep Research (chat-completions surface)
+      //
+      // Stream-only: no background mode, no job id, no resume. resumeResearch /
+      // getResearchStatus / cancelResearch are deliberately NOT implemented — the
+      // research job surfaces typed errors for those operations, and a dropped
+      // stream is never silently re-run (a multi-dollar research run).
+      // =========================================================================
+      getResearchModelSpecs() {
+        return openrouterResearchModels;
+      }
+      supportsResearch(modelId) {
+        return isOpenRouterResearchModel(modelId);
+      }
+      startResearch(options, descriptor, _spec) {
+        const { messages } = buildOpenRouterResearchMessages(options);
+        const client = this.client;
+        const request = {
+          model: descriptor.name,
+          messages,
+          // Mandatory: multi-minute runs hit idle disconnects without streaming.
+          stream: true,
+          stream_options: { include_usage: true },
+          // OpenRouter usage accounting: report the authoritative billed cost
+          // (covers per-search fees that token-based estimation cannot see).
+          usage: { include: true }
+        };
+        if (options.reasoning?.enabled !== void 0) {
+          request.reasoning = {
+            effort: OPENROUTER_EFFORT_MAP[options.reasoning.effort ?? "medium"]
+          };
+        }
+        const protectedKeys = /* @__PURE__ */ new Set(["model", "messages", "stream", "stream_options", "usage"]);
+        Object.assign(request, this.buildProviderSpecificParams(options.extra));
+        for (const [key, value] of Object.entries(options.extra ?? {})) {
+          if (!this.isProviderSpecificKey(key) && !protectedKeys.has(key)) {
+            request[key] = value;
+          }
+        }
+        const headers = this.getCustomHeaders();
+        const requestOptions3 = {
+          signal: options.signal,
+          // Research runs take minutes — override the client's default timeout.
+          timeout: OPENROUTER_RESEARCH_HTTP_TIMEOUT_MS,
+          ...Object.keys(headers).length > 0 ? { headers } : {}
+        };
+        const enhance = (error) => this.enhanceError(error);
+        return (async function* () {
+          let stream2;
+          try {
+            stream2 = await client.chat.completions.create(
+              request,
+              requestOptions3
+            );
+          } catch (error) {
+            throw enhance(error);
+          }
+          yield* normalizeOpenRouterResearchStream(stream2);
+        })();
+      }
       /**
        * Override buildApiRequest to inject reasoning parameters and cache_control breakpoints.
        * OpenRouter normalizes reasoning into the standard OpenAI format,
@@ -11158,6 +12645,590 @@ var init_discovery = __esm({
   }
 });
 
+// src/research/cost.ts
+function estimateResearchCost(pricing, usage) {
+  const cachedTokens = usage.cachedInputTokens ?? 0;
+  const freshInputTokens = Math.max(0, usage.inputTokens - cachedTokens);
+  const cachedRate = pricing.cachedInput ?? pricing.input;
+  let outputTokens = usage.outputTokens;
+  let reasoningCost = 0;
+  if (pricing.internalReasoning !== void 0 && usage.reasoningTokens !== void 0) {
+    outputTokens = Math.max(0, outputTokens - usage.reasoningTokens);
+    reasoningCost = usage.reasoningTokens * pricing.internalReasoning / TOKENS_PER_MILLION;
+  }
+  const searchCost = pricing.perThousandSearches !== void 0 && usage.searches !== void 0 ? usage.searches * pricing.perThousandSearches / SEARCHES_PER_THOUSAND : 0;
+  const total = freshInputTokens * pricing.input / TOKENS_PER_MILLION + cachedTokens * cachedRate / TOKENS_PER_MILLION + outputTokens * pricing.output / TOKENS_PER_MILLION + reasoningCost + searchCost;
+  return Number(total.toFixed(RESEARCH_COST_DECIMALS));
+}
+var init_cost = __esm({
+  "src/research/cost.ts"() {
+    "use strict";
+    init_constants3();
+  }
+});
+
+// src/research/collector.ts
+function citationKey2(citation) {
+  return `${citation.url}#${citation.startIndex ?? ""}`;
+}
+function max(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return Math.max(a, b);
+}
+var EMPTY_USAGE, TERMINAL_STATUSES, ResearchResultCollector;
+var init_collector = __esm({
+  "src/research/collector.ts"() {
+    "use strict";
+    init_cost();
+    EMPTY_USAGE = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+      "completed",
+      "failed",
+      "cancelled",
+      "incomplete",
+      "budget_exceeded"
+    ]);
+    ResearchResultCollector = class {
+      constructor(spec, now = Date.now) {
+        this.spec = spec;
+        this.now = now;
+      }
+      spec;
+      now;
+      reportParts = [];
+      citations = /* @__PURE__ */ new Map();
+      usage;
+      lastStatus;
+      doneReport = "";
+      doneRaw;
+      hasDone = false;
+      firstEventAt;
+      terminalAt;
+      /**
+       * Terminal error info from an `error` event.
+       * @internal Read by tests only — not part of the public consumer contract.
+       */
+      terminalError;
+      ingest(event) {
+        this.firstEventAt ??= this.now();
+        switch (event.type) {
+          case "text":
+            this.reportParts.push(event.delta);
+            break;
+          case "citation":
+            this.addCitation(event.citation);
+            break;
+          case "usage":
+            this.mergeUsage(event.usage);
+            break;
+          case "status":
+            this.lastStatus = event.status;
+            break;
+          case "error":
+            this.terminalError = event.error;
+            this.terminalAt = this.now();
+            break;
+          case "done": {
+            this.hasDone = true;
+            this.lastStatus = event.result.status;
+            this.doneReport = event.result.report;
+            this.doneRaw = event.result.raw;
+            for (const citation of event.result.citations ?? []) {
+              this.addCitation(citation);
+            }
+            if (event.result.usage) {
+              this.mergeUsage(event.result.usage);
+            }
+            this.terminalAt = this.now();
+            break;
+          }
+          default:
+            break;
+        }
+      }
+      toResult(context) {
+        const usage = { ...this.usage ?? EMPTY_USAGE };
+        if (usage.costUSD === void 0 && this.spec) {
+          usage.costUSD = estimateResearchCost(this.spec.pricing, usage);
+        }
+        const status = this.lastStatus ?? (this.terminalError ? "failed" : "in_progress");
+        const lastIsTerminal = this.lastStatus !== void 0 && TERMINAL_STATUSES.has(this.lastStatus);
+        return {
+          jobId: context.jobId,
+          provider: context.provider,
+          model: context.model,
+          // An error fails the run only when no explicit terminal status preceded
+          // it (a timeout's "incomplete" is a partial, not a failure).
+          status: this.terminalError && !this.hasDone && !lastIsTerminal ? "failed" : status,
+          report: this.doneReport !== "" ? this.doneReport : this.reportParts.join(""),
+          citations: [...this.citations.values()],
+          usage,
+          durationMs: this.firstEventAt !== void 0 && this.terminalAt !== void 0 ? this.terminalAt - this.firstEventAt : void 0,
+          raw: this.doneRaw
+        };
+      }
+      /** Whether a terminal event (`done` or `error`) was ingested. */
+      get isTerminal() {
+        return this.hasDone || this.terminalError !== void 0;
+      }
+      addCitation(citation) {
+        const key = citationKey2(citation);
+        if (!this.citations.has(key)) {
+          this.citations.set(key, citation);
+        }
+      }
+      mergeUsage(incoming) {
+        const current = this.usage ?? { ...EMPTY_USAGE };
+        this.usage = {
+          ...current,
+          ...incoming,
+          // Cumulative counters may be re-reported; never let them regress.
+          searches: max(current.searches, incoming.searches)
+        };
+      }
+    };
+  }
+});
+
+// src/research/job.ts
+var ResearchJobImpl;
+var init_job = __esm({
+  "src/research/job.ts"() {
+    "use strict";
+    init_errors2();
+    init_collector();
+    init_constants3();
+    init_errors3();
+    ResearchJobImpl = class {
+      adapter;
+      descriptor;
+      spec;
+      options;
+      resumeFrom;
+      collector;
+      controller = new AbortController();
+      timeoutMs;
+      state = "idle";
+      currentJobId;
+      cursor;
+      startedAt;
+      timedOut = false;
+      cancelRequested = false;
+      finalResult;
+      failure;
+      completion;
+      constructor(init) {
+        this.adapter = init.adapter;
+        this.descriptor = init.descriptor;
+        this.spec = init.spec;
+        this.options = init.options;
+        this.resumeFrom = init.resumeFrom;
+        this.collector = new ResearchResultCollector(init.spec);
+        this.currentJobId = init.resumeFrom?.jobId ?? null;
+        this.cursor = init.resumeFrom?.cursor;
+        this.startedAt = init.resumeFrom?.startedAt;
+        const specCap = init.spec?.maxDurationMs ?? Number.POSITIVE_INFINITY;
+        this.timeoutMs = init.options?.timeoutMs ?? Math.min(RESEARCH_DEFAULT_TIMEOUT_MS, specCap);
+        if (init.options?.signal) {
+          const external = init.options.signal;
+          if (external.aborted) {
+            this.controller.abort(external.reason);
+          } else {
+            external.addEventListener("abort", () => this.controller.abort(external.reason), {
+              once: true
+            });
+          }
+        }
+      }
+      get jobId() {
+        return this.currentJobId;
+      }
+      get provider() {
+        return this.adapter.providerId;
+      }
+      get model() {
+        return this.descriptor.name;
+      }
+      [Symbol.asyncIterator]() {
+        return this.events()[Symbol.asyncIterator]();
+      }
+      events() {
+        if (this.state !== "idle") {
+          throw new ResearchStreamConsumedError();
+        }
+        this.state = "streaming";
+        let resolveCompletion = () => {
+        };
+        const promise = new Promise((resolve2) => {
+          resolveCompletion = resolve2;
+        });
+        this.completion = { promise, resolve: resolveCompletion };
+        return this.run();
+      }
+      async result() {
+        if (this.state === "idle") {
+          for await (const _event of this.events()) {
+          }
+        } else if (this.state === "streaming" && this.completion) {
+          await this.completion.promise;
+        }
+        if (this.failure) {
+          throw this.failure;
+        }
+        this.finalResult ??= this.collector.toResult(this.resultContext());
+        return this.finalResult;
+      }
+      async status() {
+        if (!this.adapter.getResearchStatus) {
+          throw new ResearchNotPollableError(
+            `Provider "${this.provider}" does not support research status polling.`
+          );
+        }
+        if (this.currentJobId === null) {
+          throw new ResearchNotPollableError(
+            `Research run on "${this.provider}" has no server-side job id to poll.`
+          );
+        }
+        const snapshot = await this.adapter.getResearchStatus(this.buildRef());
+        return snapshot.status;
+      }
+      async cancel() {
+        this.cancelRequested = true;
+        if (this.adapter.cancelResearch && this.currentJobId !== null) {
+          await this.adapter.cancelResearch(this.buildRef());
+        }
+        this.controller.abort();
+      }
+      toRef() {
+        if (this.currentJobId === null) {
+          throw new ResearchJobNotResumableError(
+            `Research run on "${this.provider}" has no server-side job id \u2014 the provider does not support background jobs, so it cannot be re-attached.`
+          );
+        }
+        return this.buildRef();
+      }
+      buildRef() {
+        if (this.currentJobId === null) {
+          throw new ResearchJobNotResumableError("Research job has no server-side job id.");
+        }
+        return {
+          provider: this.provider,
+          model: this.descriptor.name,
+          jobId: this.currentJobId,
+          cursor: this.cursor,
+          startedAt: this.startedAt
+        };
+      }
+      resultContext() {
+        return { provider: this.provider, model: this.descriptor.name, jobId: this.currentJobId };
+      }
+      openStream(resume) {
+        if (resume) {
+          if (!this.adapter.resumeResearch) {
+            throw new ResearchJobNotResumableError(
+              `Provider "${this.provider}" does not support resuming research jobs.`
+            );
+          }
+          return this.adapter.resumeResearch(this.buildRef(), this.controller.signal);
+        }
+        if (!this.adapter.startResearch || !this.options) {
+          throw new ResearchJobNotResumableError(
+            `Provider "${this.provider}" cannot start this research job.`
+          );
+        }
+        return this.adapter.startResearch(
+          { ...this.options, signal: this.controller.signal },
+          this.descriptor,
+          this.spec
+        );
+      }
+      observe(event) {
+        if (event.cursor !== void 0) {
+          this.cursor = event.cursor;
+        }
+        if (event.type === "created") {
+          if (event.jobId !== null) {
+            this.currentJobId = event.jobId;
+          }
+          this.startedAt ??= (/* @__PURE__ */ new Date()).toISOString();
+        }
+        this.collector.ingest(event);
+      }
+      canResume() {
+        if (this.adapter.resumeResearch === void 0 || this.currentJobId === null) {
+          return false;
+        }
+        return this.spec ? this.spec.capabilities.resumable : true;
+      }
+      async *run() {
+        const timer = setTimeout(() => {
+          this.timedOut = true;
+          this.controller.abort(new ResearchTimeoutError(this.timeoutMs));
+        }, this.timeoutMs);
+        timer.unref?.();
+        let reconnectAttempts = 0;
+        let source = this.openStream(this.resumeFrom !== void 0);
+        try {
+          while (true) {
+            const iterator = source[Symbol.asyncIterator]();
+            try {
+              while (true) {
+                const next = await iterator.next();
+                if (next.done) {
+                  return;
+                }
+                reconnectAttempts = 0;
+                this.observe(next.value);
+                yield next.value;
+                if (this.collector.isTerminal) {
+                  return;
+                }
+              }
+            } catch (error) {
+              const err = error instanceof Error ? error : new Error(String(error));
+              if (this.timedOut) {
+                const statusEvent = { type: "status", status: "incomplete" };
+                this.collector.ingest(statusEvent);
+                yield statusEvent;
+                const info2 = {
+                  message: new ResearchTimeoutError(this.timeoutMs).message,
+                  code: "timeout",
+                  retryable: false
+                };
+                this.collector.ingest({ type: "error", error: info2 });
+                yield { type: "error", error: info2 };
+                return;
+              }
+              if (this.cancelRequested && isAbortError(err)) {
+                const event = { type: "status", status: "cancelled" };
+                this.observe(event);
+                yield event;
+                return;
+              }
+              if (isAbortError(err)) {
+                this.failure = err;
+                throw err;
+              }
+              if (this.canResume() && reconnectAttempts < RESEARCH_STREAM_RECONNECT_MAX_ATTEMPTS) {
+                reconnectAttempts += 1;
+                source = this.openStream(true);
+                continue;
+              }
+              const info = { message: err.message, retryable: false };
+              this.collector.ingest({ type: "error", error: info });
+              yield { type: "error", error: info };
+              return;
+            }
+          }
+        } finally {
+          clearTimeout(timer);
+          this.state = "finished";
+          this.finalResult = this.collector.toResult(this.resultContext());
+          this.completion?.resolve();
+        }
+      }
+    };
+  }
+});
+
+// src/research/types.ts
+var RESEARCH_DATA_SOURCE_TOOL_TYPES;
+var init_types = __esm({
+  "src/research/types.ts"() {
+    "use strict";
+    RESEARCH_DATA_SOURCE_TOOL_TYPES = [
+      "web_search",
+      "file_search",
+      "mcp"
+    ];
+  }
+});
+
+// src/research/namespace.ts
+var ResearchNamespace;
+var init_namespace = __esm({
+  "src/research/namespace.ts"() {
+    "use strict";
+    init_logger();
+    init_constants3();
+    init_errors3();
+    init_job();
+    init_types();
+    ResearchNamespace = class {
+      constructor(adapters, parser, now = Date.now, logger2) {
+        this.adapters = adapters;
+        this.parser = parser;
+        this.now = now;
+        this.logger = logger2 ?? createLogger({ name: "llmist:research" });
+      }
+      adapters;
+      parser;
+      now;
+      logger;
+      /**
+       * Start a research run. Returns immediately; the provider stream opens
+       * lazily on first iteration (or on `result()`).
+       */
+      start(options) {
+        const descriptor = this.parser.parse(options.model);
+        const adapter = this.findResearchAdapter(descriptor);
+        if (!adapter) {
+          throw new ResearchNotSupportedError(
+            `No provider supports deep research for model "${options.model}". Research-capable models: ${this.describeAvailableModels()}`
+          );
+        }
+        const spec = this.findSpec(adapter, descriptor.name);
+        const validated = spec ? this.validate(options, spec) : options;
+        return new ResearchJobImpl({ adapter, descriptor, spec, options: validated });
+      }
+      /**
+       * Re-attach to a background research job from a serialized ref.
+       * No network happens until the returned job is iterated.
+       */
+      attach(ref) {
+        const adapter = this.findAdapterByProviderId(ref.provider);
+        if (!adapter) {
+          throw new ResearchNotSupportedError(
+            `No registered provider with id "${ref.provider}" to attach research job "${ref.jobId}".`
+          );
+        }
+        if (!adapter.resumeResearch) {
+          throw new ResearchJobNotResumableError(
+            `Provider "${ref.provider}" does not support resuming research jobs.`
+          );
+        }
+        const descriptor = { provider: ref.provider, name: ref.model };
+        const spec = this.findSpec(adapter, ref.model);
+        return new ResearchJobImpl({ adapter, descriptor, spec, resumeFrom: ref });
+      }
+      /** One-shot status poll for a job ref. */
+      async get(ref) {
+        const adapter = this.findAdapterByProviderId(ref.provider);
+        if (!adapter) {
+          throw new ResearchNotSupportedError(`No registered provider with id "${ref.provider}".`);
+        }
+        if (!adapter.getResearchStatus) {
+          throw new ResearchNotPollableError(
+            `Provider "${ref.provider}" does not support research status polling.`
+          );
+        }
+        return adapter.getResearchStatus(ref);
+      }
+      /** Cancel a background job server-side. */
+      async cancel(ref) {
+        const adapter = this.findAdapterByProviderId(ref.provider);
+        if (!adapter) {
+          throw new ResearchNotSupportedError(`No registered provider with id "${ref.provider}".`);
+        }
+        if (!adapter.cancelResearch) {
+          throw new ResearchNotSupportedError(
+            `Provider "${ref.provider}" does not support cancelling research jobs.`
+          );
+        }
+        return adapter.cancelResearch(ref);
+      }
+      /** All research-capable models/agents across registered providers. */
+      listModels() {
+        const specs = [];
+        for (const adapter of this.adapters) {
+          specs.push(...adapter.getResearchModelSpecs?.() ?? []);
+        }
+        return specs;
+      }
+      /** Whether any registered provider supports research for this model. */
+      supportsModel(model) {
+        try {
+          return this.findResearchAdapter(this.parser.parse(model)) !== void 0;
+        } catch {
+          return false;
+        }
+      }
+      findResearchAdapter(descriptor) {
+        return this.adapters.find(
+          (adapter) => adapter.supports(descriptor) && (adapter.supportsResearch?.(descriptor.name) ?? false)
+        );
+      }
+      findAdapterByProviderId(providerId) {
+        return this.adapters.find((adapter) => adapter.providerId === providerId);
+      }
+      findSpec(adapter, modelId) {
+        return adapter.getResearchModelSpecs?.().find((spec) => spec.modelId === modelId);
+      }
+      describeAvailableModels() {
+        const models = this.listModels();
+        if (models.length === 0) {
+          return "(none registered)";
+        }
+        return models.map((spec) => `${spec.provider}:${spec.modelId}`).join(", ");
+      }
+      /**
+       * Pre-flight validation against the catalog spec — fails fast before any
+       * network call and applies spec-driven defaults.
+       */
+      validate(options, spec) {
+        this.enforceLifecycle(spec);
+        const background = options.background ?? spec.capabilities.background;
+        if (background && !spec.capabilities.background) {
+          throw new ResearchValidationError(
+            `Model "${spec.modelId}" does not support background research jobs.`
+          );
+        }
+        if (options.previousJobId && !spec.capabilities.followUps) {
+          throw new ResearchValidationError(
+            `Model "${spec.modelId}" does not support follow-up research runs (previousJobId).`
+          );
+        }
+        const tools = this.resolveTools(options, spec);
+        return { ...options, background, tools };
+      }
+      resolveTools(options, spec) {
+        if (options.tools === void 0) {
+          return spec.requiredTools;
+        }
+        for (const tool of options.tools) {
+          if (!spec.capabilities.tools.includes(tool.type)) {
+            throw new ResearchValidationError(
+              `Model "${spec.modelId}" does not accept the "${tool.type}" tool. ` + (spec.capabilities.tools.length > 0 ? `Accepted tools: ${spec.capabilities.tools.join(", ")}.` : "This model manages its research tools itself \u2014 omit the tools option.")
+            );
+          }
+        }
+        const hasDataSource = options.tools.some(
+          (tool) => RESEARCH_DATA_SOURCE_TOOL_TYPES.includes(tool.type)
+        );
+        if (!hasDataSource && spec.requiredTools) {
+          return [...spec.requiredTools, ...options.tools];
+        }
+        return options.tools;
+      }
+      enforceLifecycle(spec) {
+        const shutdownDate = spec.metadata?.shutdownDate;
+        if (!shutdownDate) {
+          return;
+        }
+        const shutdownMs = Date.parse(shutdownDate);
+        if (Number.isNaN(shutdownMs)) {
+          return;
+        }
+        const nowMs = this.now();
+        if (nowMs >= shutdownMs) {
+          throw new ResearchDeprecatedModelError({
+            modelId: spec.modelId,
+            shutdownDate,
+            replacement: spec.metadata?.replacement
+          });
+        }
+        const warningStartMs = shutdownMs - RESEARCH_SHUTDOWN_WARNING_WINDOW_DAYS * MS_PER_DAY;
+        if (nowMs >= warningStartMs) {
+          this.logger.warn(
+            `Research model "${spec.modelId}" shuts down on ${shutdownDate}` + (spec.metadata?.replacement ? ` \u2014 migrate to "${spec.metadata.replacement}".` : ".")
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/core/model-registry.ts
 var ModelRegistry;
 var init_model_registry = __esm({
@@ -11382,6 +13453,8 @@ var init_image = __esm({
         this.adapters = adapters;
         this.defaultProvider = defaultProvider;
       }
+      adapters;
+      defaultProvider;
       /**
        * Generate images from a text prompt.
        *
@@ -11434,6 +13507,8 @@ var init_speech = __esm({
         this.adapters = adapters;
         this.defaultProvider = defaultProvider;
       }
+      adapters;
+      defaultProvider;
       /**
        * Generate speech audio from text.
        *
@@ -11529,6 +13604,7 @@ var init_text = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       /**
        * Generate a complete text response.
        *
@@ -11564,6 +13640,7 @@ var init_vision = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       /**
        * Build a message builder with the image content attached.
        * Handles URLs, data URLs, base64 strings, and binary buffers.
@@ -11690,6 +13767,7 @@ var init_options = __esm({
       constructor(defaultProvider = "openai") {
         this.defaultProvider = defaultProvider;
       }
+      defaultProvider;
       parse(identifier) {
         const trimmed = identifier.trim();
         if (!trimmed) {
@@ -11721,6 +13799,7 @@ var init_client2 = __esm({
     "use strict";
     init_builder();
     init_discovery();
+    init_namespace();
     init_constants();
     init_model_registry();
     init_image();
@@ -11739,6 +13818,12 @@ var init_client2 = __esm({
       image;
       speech;
       vision;
+      /**
+       * 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.
+       */
+      research;
       constructor(...args) {
         let adapters = [];
         let defaultProvider;
@@ -11790,6 +13875,7 @@ var init_client2 = __esm({
         this.image = new ImageNamespace(this.adapters, this.defaultProvider);
         this.speech = new SpeechNamespace(this.adapters, this.defaultProvider);
         this.vision = new VisionNamespace(this);
+        this.research = new ResearchNamespace(this.adapters, this.parser);
       }
       stream(options) {
         const descriptor = this.parser.parse(options.model);
@@ -12056,8 +14142,8 @@ var init_builder = __esm({
         return this;
       }
       /** Set maximum iterations. */
-      withMaxIterations(max) {
-        this.core.maxIterations = max;
+      withMaxIterations(max2) {
+        this.core.maxIterations = max2;
         return this;
       }
       /** Set the budget limit in USD. */
@@ -12186,10 +14272,10 @@ var init_builder = __esm({
         return this;
       }
       /** Set the maximum number of gadgets to execute per LLM response. */
-      withMaxGadgetsPerResponse(max) {
-        if (max < 0) throw new Error("maxGadgetsPerResponse must be a non-negative number");
-        if (!Number.isInteger(max)) throw new Error("maxGadgetsPerResponse must be an integer");
-        this.gadgets.maxGadgetsPerResponse = max;
+      withMaxGadgetsPerResponse(max2) {
+        if (max2 < 0) throw new Error("maxGadgetsPerResponse must be a non-negative number");
+        if (!Number.isInteger(max2)) throw new Error("maxGadgetsPerResponse must be an integer");
+        this.gadgets.maxGadgetsPerResponse = max2;
         return this;
       }
       /** Enable or disable gadget output limiting. */
@@ -12890,6 +14976,8 @@ var init_cost_reporting_client = __esm({
           }
         };
       }
+      client;
+      reportCost;
       image;
       speech;
       /**
@@ -16046,7 +18134,7 @@ var init_agent = __esm({
         }
         const unsubscribeBridge = bridgeTreeToHooks(this.tree, this.hooks, this.logger);
         if (this.mcpSpecs.length > 0) {
-          const { setupMcpServers } = await import("./runtime-KB7US2FQ.js");
+          const { setupMcpServers } = await import("./runtime-IUKW77QX.js");
           this.mcpLifecycle = await setupMcpServers({
             specs: this.mcpSpecs,
             registry: this.registry,
@@ -16871,6 +18959,14 @@ init_tool_adapter();
 // src/index.ts
 init_constants2();
 
+// src/research/index.ts
+init_collector();
+init_constants3();
+init_cost();
+init_errors3();
+init_namespace();
+init_types();
+
 // src/utils/config-resolver.ts
 function resolveValue(ctx, gadgetName, options) {
   const { runtime, subagentKey, parentKey, defaultValue, handleInherit } = options;
@@ -17169,11 +19265,11 @@ var format = {
 };
 
 // src/utils/timing.ts
-function randomDelay(min, max) {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
+function randomDelay(min, max2) {
+  return Math.floor(Math.random() * (max2 - min + 1)) + min;
 }
-async function humanDelay(min = 50, max = 150) {
-  const delay = randomDelay(min, max);
+async function humanDelay(min = 50, max2 = 150) {
+  const delay = randomDelay(min, max2);
   return new Promise((resolve2) => setTimeout(resolve2, delay));
 }
 async function withTimeout(fn, timeoutMs, signal) {
@@ -17312,7 +19408,17 @@ export {
   OpenAIChatProvider,
   OpenAICompatibleProvider,
   OpenRouterProvider,
+  RESEARCH_DATA_SOURCE_TOOL_TYPES,
   RateLimitTracker,
+  ResearchDeprecatedModelError,
+  ResearchJobNotResumableError,
+  ResearchNamespace,
+  ResearchNotPollableError,
+  ResearchNotSupportedError,
+  ResearchResultCollector,
+  ResearchStreamConsumedError,
+  ResearchTimeoutError,
+  ResearchValidationError,
   SimpleSessionManager,
   Skill,
   SkillRegistry,
@@ -17346,6 +19452,7 @@ export {
   detectImageMimeType,
   discoverProviderAdapters,
   discoverSkills,
+  estimateResearchCost,
   extractMessageText,
   extractRetryAfterMs,
   filterByDepth,