llmist 18.2.0 → 18.4.0

package/dist/index.cjs

@@ -40,6 +40,8 @@ var init_execution_tree_aggregator = __esm({
         this.nodes = nodes;
         this.getDescendants = getDescendants;
       }
+      nodes;
+      getDescendants;
       // ===========================================================================
       // Private helpers
       // ===========================================================================
@@ -2516,21 +2518,39 @@ function createLogger(options = {}) {
     prettyLogTemplate: LOG_TEMPLATE,
     // Use overwrite to redirect tslog's formatted output to file instead of console
     overwrite: useFileLogging ? {
-      transportFormatted: (logMetaMarkup, logArgs, _logErrors) => {
+      transportFormatted: (logMetaMarkup, logArgs, logErrors) => {
         const args = logArgs.map(
           (arg) => typeof arg === "string" ? arg : JSON.stringify(arg)
         );
         if (sharedLogFileStream) {
           const meta = stripAnsi(logMetaMarkup);
           const fileArgs = args.map((a) => stripAnsi(a));
-          sharedLogFileStream.write(`${meta}${fileArgs.join(" ")}
+          const errTail = logErrors.length ? `
+${logErrors.map((e) => stripAnsi(e)).join("\n")}` : "";
+          sharedLogFileStream.write(`${meta}${fileArgs.join(" ")}${errTail}
 `);
         }
         if (teeToConsole) {
-          process.stdout.write(`${logMetaMarkup}${args.join(" ")}
+          const errTail = logErrors.length ? `
+${logErrors.join("\n")}` : "";
+          process.stdout.write(`${logMetaMarkup}${args.join(" ")}${errTail}
 `);
         }
       }
+    } : defaultType === "pretty" ? {
+      // Diagnostics go to stderr (POSIX convention). tslog's default
+      // pretty transport uses console.log, which pollutes stdout —
+      // breaking consumers whose stdout is content or machine-readable
+      // (piped CLI output, --json/NDJSON modes, --background job refs).
+      transportFormatted: (logMetaMarkup, logArgs, logErrors) => {
+        const args = logArgs.map(
+          (arg) => typeof arg === "string" ? arg : JSON.stringify(arg)
+        );
+        const errTail = logErrors.length ? `
+${logErrors.join("\n")}` : "";
+        process.stderr.write(`${logMetaMarkup}${args.join(" ")}${errTail}
+`);
+      }
     } : void 0
   });
   return logger2;
@@ -3258,6 +3278,18 @@ async function runWithHandlers(agentGenerator, handlers) {
           });
         }
         break;
+      case "gadget_args_partial":
+        if (handlers.onGadgetArgsPartial) {
+          await handlers.onGadgetArgsPartial({
+            gadgetName: event.gadgetName,
+            invocationId: event.invocationId,
+            fieldPath: event.fieldPath,
+            value: event.value,
+            delta: event.delta,
+            isFieldComplete: event.isFieldComplete
+          });
+        }
+        break;
       case "gadget_result":
         if (handlers.onGadgetResult) {
           await handlers.onGadgetResult(event.result);
@@ -5039,7 +5071,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);
@@ -7690,6 +7722,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.
@@ -8059,6 +8092,7 @@ var init_gemini_cache_manager = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       activeCache = null;
       /**
        * Get or create a cache for the given content.
@@ -8601,6 +8635,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_errors2 = __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_errors();
+    init_retry();
+    init_constants3();
+    init_errors2();
+    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);
@@ -8798,6 +9447,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 = {
@@ -9017,6 +9668,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);
@@ -10243,17 +10915,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) {
@@ -11130,53 +11802,596 @@ var init_openai_models = __esm({
   }
 });
 
-// src/providers/openai-speech-models.ts
-function getOpenAISpeechModelSpec(modelId) {
-  return openaiSpeechModels.find((m) => m.modelId === modelId);
+// 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 isOpenAISpeechModel(modelId) {
-  return openaiSpeechModels.some((m) => m.modelId === modelId);
+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 calculateOpenAISpeechCost(modelId, characterCount, estimatedMinutes) {
-  const spec = getOpenAISpeechModelSpec(modelId);
-  if (!spec) return void 0;
-  if (spec.pricing.perCharacter !== void 0) {
-    return characterCount * spec.pricing.perCharacter;
+function mapEffort(effort) {
+  switch (effort) {
+    case "maximum":
+      return "xhigh";
+    case "low":
+    case "medium":
+    case "high":
+      return effort;
+    default:
+      return "medium";
   }
-  if (spec.pricing.perMinute !== void 0 && estimatedMinutes !== void 0) {
-    return estimatedMinutes * spec.pricing.perMinute;
+}
+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);
+      }
+    }
   }
-  if (spec.pricing.perMinute !== void 0) {
-    const approxMinutes = characterCount / 750;
-    return approxMinutes * spec.pricing.perMinute;
+  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 void 0;
+  return searches;
 }
-var OPENAI_TTS_VOICES, OPENAI_TTS_EXTENDED_VOICES, OPENAI_TTS_FORMATS, openaiSpeechModels;
-var init_openai_speech_models = __esm({
-  "src/providers/openai-speech-models.ts"() {
-    "use strict";
-    OPENAI_TTS_VOICES = ["alloy", "echo", "fable", "onyx", "nova", "shimmer"];
-    OPENAI_TTS_EXTENDED_VOICES = [
-      ...OPENAI_TTS_VOICES,
-      "ash",
-      "ballad",
-      "coral",
-      "sage",
-      "verse"
-    ];
-    OPENAI_TTS_FORMATS = ["mp3", "opus", "aac", "flac", "wav", "pcm"];
-    openaiSpeechModels = [
-      // Standard TTS models (character-based pricing)
-      {
-        provider: "openai",
-        modelId: "tts-1",
-        displayName: "TTS-1",
-        pricing: {
-          // $15 per 1M characters = $0.000015 per character
-          perCharacter: 15e-6
-        },
-        voices: [...OPENAI_TTS_VOICES],
+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_errors();
+    init_retry();
+    init_constants3();
+    init_errors2();
+    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);
+}
+function isOpenAISpeechModel(modelId) {
+  return openaiSpeechModels.some((m) => m.modelId === modelId);
+}
+function calculateOpenAISpeechCost(modelId, characterCount, estimatedMinutes) {
+  const spec = getOpenAISpeechModelSpec(modelId);
+  if (!spec) return void 0;
+  if (spec.pricing.perCharacter !== void 0) {
+    return characterCount * spec.pricing.perCharacter;
+  }
+  if (spec.pricing.perMinute !== void 0 && estimatedMinutes !== void 0) {
+    return estimatedMinutes * spec.pricing.perMinute;
+  }
+  if (spec.pricing.perMinute !== void 0) {
+    const approxMinutes = characterCount / 750;
+    return approxMinutes * spec.pricing.perMinute;
+  }
+  return void 0;
+}
+var OPENAI_TTS_VOICES, OPENAI_TTS_EXTENDED_VOICES, OPENAI_TTS_FORMATS, openaiSpeechModels;
+var init_openai_speech_models = __esm({
+  "src/providers/openai-speech-models.ts"() {
+    "use strict";
+    OPENAI_TTS_VOICES = ["alloy", "echo", "fable", "onyx", "nova", "shimmer"];
+    OPENAI_TTS_EXTENDED_VOICES = [
+      ...OPENAI_TTS_VOICES,
+      "ash",
+      "ballad",
+      "coral",
+      "sage",
+      "verse"
+    ];
+    OPENAI_TTS_FORMATS = ["mp3", "opus", "aac", "flac", "wav", "pcm"];
+    openaiSpeechModels = [
+      // Standard TTS models (character-based pricing)
+      {
+        provider: "openai",
+        modelId: "tts-1",
+        displayName: "TTS-1",
+        pricing: {
+          // $15 per 1M characters = $0.000015 per character
+          perCharacter: 15e-6
+        },
+        voices: [...OPENAI_TTS_VOICES],
         formats: OPENAI_TTS_FORMATS,
         maxInputLength: 4096,
         defaultVoice: "alloy",
@@ -11285,6 +12500,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 = {
@@ -11388,6 +12605,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;
@@ -12115,6 +13358,217 @@ var init_openrouter_models = __esm({
   }
 });
 
+// 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_errors2();
+  }
+});
+
+// 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."
+        }
+      },
+      {
+        provider: "openrouter",
+        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: {
+          // 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]));
+  }
+});
+
 // src/providers/openrouter-speech-models.ts
 function getOpenRouterSpeechModelSpec(modelId) {
   return openrouterSpeechModels.find((m) => m.modelId === modelId);
@@ -12242,8 +13696,11 @@ var init_openrouter = __esm({
     import_openai4 = __toESM(require("openai"), 1);
     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" });
@@ -12263,12 +13720,72 @@ var init_openrouter = __esm({
       getModelSpecs() {
         return OPENROUTER_MODELS;
       }
-      /**
-       * Override buildApiRequest to inject reasoning parameters and cache_control breakpoints.
-       * OpenRouter normalizes reasoning into the standard OpenAI format,
-       * and supports cache_control on message content blocks for both
-       * Anthropic Claude and Google Gemini 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,
+       * and supports cache_control on message content blocks for both
+       * Anthropic Claude and Google Gemini models.
+       */
       buildApiRequest(options, descriptor, spec, messages) {
         const request = super.buildApiRequest(options, descriptor, spec, messages);
         if (options.reasoning?.enabled !== void 0) {
@@ -12381,150 +13898,764 @@ Original error: ${error.message}`
 Original error: ${error.message}`
           );
         }
-        if (message.includes("503") || message.includes("unavailable")) {
-          return new Error(
-            `OpenRouter: Model temporarily unavailable. Try a different model or use the 'models' fallback option for automatic retry.
-Original error: ${error.message}`
+        if (message.includes("503") || message.includes("unavailable")) {
+          return new Error(
+            `OpenRouter: Model temporarily unavailable. Try a different model or use the 'models' fallback option for automatic retry.
+Original error: ${error.message}`
+          );
+        }
+        if (message.includes("400") || message.includes("bad request")) {
+          const enhanced = new Error(
+            `OpenRouter: Provider returned error (400). This may indicate the request exceeded the model's limits, or a model-specific rejection.
+Original error: ${error.message}`
+          );
+          const originalStatus = error.status;
+          Object.assign(enhanced, {
+            status: typeof originalStatus === "number" ? originalStatus : 400
+          });
+          return enhanced;
+        }
+        if (message.includes("401") || message.includes("unauthorized") || message.includes("invalid api key") || message.includes("invalid key") || message.includes("invalid_api_key")) {
+          return new Error(
+            `OpenRouter: Authentication failed. Check that OPENROUTER_API_KEY is set correctly.
+Original error: ${error.message}`
+          );
+        }
+        return error;
+      }
+      // =========================================================================
+      // Speech Generation (TTS via Chat Completions with Audio Modality)
+      // =========================================================================
+      /**
+       * Get speech model specifications for OpenRouter.
+       */
+      getSpeechModelSpecs() {
+        return openrouterSpeechModels;
+      }
+      /**
+       * Check if this provider supports speech generation for a given model.
+       * Handles both prefixed (openrouter:openai/gpt-audio-mini) and unprefixed model IDs.
+       */
+      supportsSpeechGeneration(modelId) {
+        const bareModelId = getModelId(modelId);
+        return isOpenRouterSpeechModel(bareModelId);
+      }
+      /**
+       * Generate speech audio from text using OpenRouter's audio-capable models.
+       *
+       * OpenRouter TTS works via chat completions with audio modality, not a
+       * dedicated TTS endpoint. The model receives a prompt asking it to say
+       * the text, and returns audio data via streaming.
+       *
+       * @param options - Speech generation options
+       * @returns Promise resolving to the generation result with audio and cost
+       * @throws Error if model is unknown, voice/format are invalid, or no audio is returned
+       */
+      async generateSpeech(options) {
+        const client = this.client;
+        const bareModelId = getModelId(options.model);
+        const spec = getOpenRouterSpeechModelSpec(bareModelId);
+        if (!spec) {
+          throw new Error(`Unknown OpenRouter TTS model: ${options.model}`);
+        }
+        const voice = options.voice ?? spec.defaultVoice ?? "alloy";
+        if (!spec.voices.includes(voice)) {
+          throw new Error(
+            `Invalid voice "${voice}" for ${options.model}. Valid voices: ${spec.voices.join(", ")}`
+          );
+        }
+        const format2 = options.responseFormat ?? spec.defaultFormat ?? "mp3";
+        if (!spec.formats.includes(format2)) {
+          throw new Error(
+            `Invalid format "${format2}" for ${options.model}. Valid formats: ${spec.formats.join(", ")}`
+          );
+        }
+        logger.debug("TTS request", {
+          model: bareModelId,
+          voice,
+          format: format2,
+          inputLength: options.input.length
+        });
+        try {
+          const response = await client.chat.completions.create({
+            model: bareModelId,
+            messages: [
+              {
+                role: "user",
+                content: `Please say the following text exactly: "${options.input}"`
+              }
+            ],
+            // OpenRouter-specific parameters for audio output
+            // Note: OpenRouter TTS via chat completions does NOT support the speed parameter
+            // (unlike OpenAI's dedicated /audio/speech endpoint which does)
+            modalities: ["text", "audio"],
+            audio: {
+              voice,
+              format: format2
+            },
+            stream: true
+          });
+          const audioChunks = [];
+          for await (const chunk of response) {
+            const delta = chunk.choices[0]?.delta;
+            if (!delta || typeof delta !== "object") continue;
+            const audioObj = delta.audio;
+            if (!audioObj || typeof audioObj !== "object") continue;
+            const audioData = audioObj.data;
+            if (typeof audioData !== "string" || audioData.length === 0) continue;
+            const decoded = Buffer.from(audioData, "base64");
+            if (decoded.length === 0) {
+              throw new Error("Invalid base64 audio data received from OpenRouter");
+            }
+            audioChunks.push(decoded);
+          }
+          const audioBuffer = Buffer.concat(audioChunks);
+          if (audioBuffer.length === 0) {
+            throw new Error(
+              "OpenRouter TTS returned no audio data. The model may have failed to generate audio or the stream was interrupted."
+            );
+          }
+          const cost = calculateOpenRouterSpeechCost(bareModelId, options.input.length);
+          return {
+            // Use Uint8Array for clean ArrayBuffer extraction (safer than buffer.slice for Node.js Buffer)
+            audio: new Uint8Array(audioBuffer).buffer,
+            model: options.model,
+            usage: {
+              characterCount: options.input.length
+            },
+            cost,
+            format: format2
+          };
+        } catch (error) {
+          const err = error;
+          const apiError = err.error?.message || err.error?.code || "";
+          const bodyInfo = err.body ? JSON.stringify(err.body) : "";
+          const details = apiError || bodyInfo || err.message || "Unknown error";
+          logger.debug("TTS error", {
+            model: bareModelId,
+            voice,
+            format: format2,
+            status: err.status,
+            error: err.error,
+            body: err.body,
+            message: err.message
+          });
+          throw new Error(
+            `OpenRouter TTS failed for model ${bareModelId}: ${details}` + (err.status ? ` (HTTP ${err.status})` : "")
+          );
+        }
+      }
+    };
+  }
+});
+
+// src/providers/discovery.ts
+function discoverProviderAdapters() {
+  const adapters = [];
+  for (const discover of DISCOVERERS) {
+    const adapter = discover();
+    if (adapter) {
+      adapters.push(adapter);
+    }
+  }
+  return adapters;
+}
+var DISCOVERERS;
+var init_discovery = __esm({
+  "src/providers/discovery.ts"() {
+    "use strict";
+    init_anthropic();
+    init_gemini();
+    init_huggingface();
+    init_openai();
+    init_openrouter();
+    DISCOVERERS = [
+      createOpenAIProviderFromEnv,
+      createAnthropicProviderFromEnv,
+      createGeminiProviderFromEnv,
+      createHuggingFaceProviderFromEnv,
+      createOpenRouterProviderFromEnv
+    ];
+  }
+});
+
+// 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_errors();
+    init_collector();
+    init_constants3();
+    init_errors2();
+    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_errors2();
+    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.`
           );
         }
-        if (message.includes("400") || message.includes("bad request")) {
-          const enhanced = new Error(
-            `OpenRouter: Provider returned error (400). This may indicate the request exceeded the model's limits, or a model-specific rejection.
-Original error: ${error.message}`
+        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.`
           );
-          const originalStatus = error.status;
-          Object.assign(enhanced, {
-            status: typeof originalStatus === "number" ? originalStatus : 400
-          });
-          return enhanced;
         }
-        if (message.includes("401") || message.includes("unauthorized") || message.includes("invalid api key") || message.includes("invalid key") || message.includes("invalid_api_key")) {
-          return new Error(
-            `OpenRouter: Authentication failed. Check that OPENROUTER_API_KEY is set correctly.
-Original error: ${error.message}`
+        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 error;
+        return adapter.cancelResearch(ref);
       }
-      // =========================================================================
-      // Speech Generation (TTS via Chat Completions with Audio Modality)
-      // =========================================================================
-      /**
-       * Get speech model specifications for OpenRouter.
-       */
-      getSpeechModelSpecs() {
-        return openrouterSpeechModels;
+      /** All research-capable models/agents across registered providers. */
+      listModels() {
+        const specs = [];
+        for (const adapter of this.adapters) {
+          specs.push(...adapter.getResearchModelSpecs?.() ?? []);
+        }
+        return specs;
       }
-      /**
-       * Check if this provider supports speech generation for a given model.
-       * Handles both prefixed (openrouter:openai/gpt-audio-mini) and unprefixed model IDs.
-       */
-      supportsSpeechGeneration(modelId) {
-        const bareModelId = getModelId(modelId);
-        return isOpenRouterSpeechModel(bareModelId);
+      /** 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(", ");
       }
       /**
-       * Generate speech audio from text using OpenRouter's audio-capable models.
-       *
-       * OpenRouter TTS works via chat completions with audio modality, not a
-       * dedicated TTS endpoint. The model receives a prompt asking it to say
-       * the text, and returns audio data via streaming.
-       *
-       * @param options - Speech generation options
-       * @returns Promise resolving to the generation result with audio and cost
-       * @throws Error if model is unknown, voice/format are invalid, or no audio is returned
+       * Pre-flight validation against the catalog spec — fails fast before any
+       * network call and applies spec-driven defaults.
        */
-      async generateSpeech(options) {
-        const client = this.client;
-        const bareModelId = getModelId(options.model);
-        const spec = getOpenRouterSpeechModelSpec(bareModelId);
-        if (!spec) {
-          throw new Error(`Unknown OpenRouter TTS model: ${options.model}`);
-        }
-        const voice = options.voice ?? spec.defaultVoice ?? "alloy";
-        if (!spec.voices.includes(voice)) {
-          throw new Error(
-            `Invalid voice "${voice}" for ${options.model}. Valid voices: ${spec.voices.join(", ")}`
+      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.`
           );
         }
-        const format2 = options.responseFormat ?? spec.defaultFormat ?? "mp3";
-        if (!spec.formats.includes(format2)) {
-          throw new Error(
-            `Invalid format "${format2}" for ${options.model}. Valid formats: ${spec.formats.join(", ")}`
+        if (options.previousJobId && !spec.capabilities.followUps) {
+          throw new ResearchValidationError(
+            `Model "${spec.modelId}" does not support follow-up research runs (previousJobId).`
           );
         }
-        logger.debug("TTS request", {
-          model: bareModelId,
-          voice,
-          format: format2,
-          inputLength: options.input.length
-        });
-        try {
-          const response = await client.chat.completions.create({
-            model: bareModelId,
-            messages: [
-              {
-                role: "user",
-                content: `Please say the following text exactly: "${options.input}"`
-              }
-            ],
-            // OpenRouter-specific parameters for audio output
-            // Note: OpenRouter TTS via chat completions does NOT support the speed parameter
-            // (unlike OpenAI's dedicated /audio/speech endpoint which does)
-            modalities: ["text", "audio"],
-            audio: {
-              voice,
-              format: format2
-            },
-            stream: true
-          });
-          const audioChunks = [];
-          for await (const chunk of response) {
-            const delta = chunk.choices[0]?.delta;
-            if (!delta || typeof delta !== "object") continue;
-            const audioObj = delta.audio;
-            if (!audioObj || typeof audioObj !== "object") continue;
-            const audioData = audioObj.data;
-            if (typeof audioData !== "string" || audioData.length === 0) continue;
-            const decoded = Buffer.from(audioData, "base64");
-            if (decoded.length === 0) {
-              throw new Error("Invalid base64 audio data received from OpenRouter");
-            }
-            audioChunks.push(decoded);
-          }
-          const audioBuffer = Buffer.concat(audioChunks);
-          if (audioBuffer.length === 0) {
-            throw new Error(
-              "OpenRouter TTS returned no audio data. The model may have failed to generate audio or the stream was interrupted."
+        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 cost = calculateOpenRouterSpeechCost(bareModelId, options.input.length);
-          return {
-            // Use Uint8Array for clean ArrayBuffer extraction (safer than buffer.slice for Node.js Buffer)
-            audio: new Uint8Array(audioBuffer).buffer,
-            model: options.model,
-            usage: {
-              characterCount: options.input.length
-            },
-            cost,
-            format: format2
-          };
-        } catch (error) {
-          const err = error;
-          const apiError = err.error?.message || err.error?.code || "";
-          const bodyInfo = err.body ? JSON.stringify(err.body) : "";
-          const details = apiError || bodyInfo || err.message || "Unknown error";
-          logger.debug("TTS error", {
-            model: bareModelId,
-            voice,
-            format: format2,
-            status: err.status,
-            error: err.error,
-            body: err.body,
-            message: err.message
+        }
+        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
           });
-          throw new Error(
-            `OpenRouter TTS failed for model ${bareModelId}: ${details}` + (err.status ? ` (HTTP ${err.status})` : "")
+        }
+        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}".` : ".")
           );
         }
       }
@@ -12532,36 +14663,6 @@ Original error: ${error.message}`
   }
 });
 
-// src/providers/discovery.ts
-function discoverProviderAdapters() {
-  const adapters = [];
-  for (const discover of DISCOVERERS) {
-    const adapter = discover();
-    if (adapter) {
-      adapters.push(adapter);
-    }
-  }
-  return adapters;
-}
-var DISCOVERERS;
-var init_discovery = __esm({
-  "src/providers/discovery.ts"() {
-    "use strict";
-    init_anthropic();
-    init_gemini();
-    init_huggingface();
-    init_openai();
-    init_openrouter();
-    DISCOVERERS = [
-      createOpenAIProviderFromEnv,
-      createAnthropicProviderFromEnv,
-      createGeminiProviderFromEnv,
-      createHuggingFaceProviderFromEnv,
-      createOpenRouterProviderFromEnv
-    ];
-  }
-});
-
 // src/core/model-registry.ts
 var ModelRegistry;
 var init_model_registry = __esm({
@@ -12786,6 +14887,8 @@ var init_image = __esm({
         this.adapters = adapters;
         this.defaultProvider = defaultProvider;
       }
+      adapters;
+      defaultProvider;
       /**
        * Generate images from a text prompt.
        *
@@ -12838,6 +14941,8 @@ var init_speech = __esm({
         this.adapters = adapters;
         this.defaultProvider = defaultProvider;
       }
+      adapters;
+      defaultProvider;
       /**
        * Generate speech audio from text.
        *
@@ -12933,6 +15038,7 @@ var init_text = __esm({
       constructor(client) {
         this.client = client;
       }
+      client;
       /**
        * Generate a complete text response.
        *
@@ -12968,6 +15074,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.
@@ -13094,6 +15201,7 @@ var init_options = __esm({
       constructor(defaultProvider = "openai") {
         this.defaultProvider = defaultProvider;
       }
+      defaultProvider;
       parse(identifier) {
         const trimmed = identifier.trim();
         if (!trimmed) {
@@ -13125,6 +15233,7 @@ var init_client = __esm({
     "use strict";
     init_builder();
     init_discovery();
+    init_namespace();
     init_constants();
     init_model_registry();
     init_image();
@@ -13143,6 +15252,12 @@ var init_client = __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;
@@ -13194,6 +15309,7 @@ var init_client = __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);
@@ -13460,8 +15576,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. */
@@ -13590,10 +15706,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. */
@@ -14294,6 +16410,8 @@ var init_cost_reporting_client = __esm({
           }
         };
       }
+      client;
+      reportCost;
       image;
       speech;
       /**
@@ -14570,13 +16688,22 @@ var init_parser2 = __esm({
     GadgetCallParser = class {
       buffer = "";
       lastEmittedTextOffset = 0;
+      /** Non-null only while a single trailing gadget block is mid-stream. */
+      currentPartial = null;
       startPrefix;
       endPrefix;
       argPrefix;
+      /** Length of the longest marker; `maxMarkerLength - 1` is the scan-resume overlap. */
+      maxMarkerLength;
       constructor(options = {}) {
         this.startPrefix = options.startPrefix ?? GADGET_START_PREFIX;
         this.endPrefix = options.endPrefix ?? GADGET_END_PREFIX;
         this.argPrefix = options.argPrefix ?? GADGET_ARG_PREFIX;
+        this.maxMarkerLength = Math.max(
+          this.startPrefix.length,
+          this.endPrefix.length,
+          this.argPrefix.length
+        );
       }
       /**
        * Extract and consume text up to the given index.
@@ -14663,12 +16790,13 @@ var init_parser2 = __esm({
           const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
           if (metadataEndIndex === -1) break;
           const headerLine = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-          const { gadgetName, invocationId, dependencies } = this.parseInvocationMetadata(headerLine);
+          const { gadgetName, invocationId, dependencies } = this.currentPartial ? this.currentPartial : this.parseInvocationMetadata(headerLine);
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
           let endMarkerLength = 0;
-          const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
-          const endPos = this.buffer.indexOf(this.endPrefix, contentStartIndex);
+          const bodySearchStart = this.currentPartial ? contentStartIndex + Math.max(0, this.currentPartial.bodyScannedLen - (this.maxMarkerLength - 1)) : contentStartIndex;
+          const nextStartPos = this.buffer.indexOf(this.startPrefix, bodySearchStart);
+          const endPos = this.buffer.indexOf(this.endPrefix, bodySearchStart);
           if (nextStartPos !== -1 && (endPos === -1 || nextStartPos < endPos)) {
             partEndIndex = nextStartPos;
             endMarkerLength = 0;
@@ -14676,9 +16804,22 @@ var init_parser2 = __esm({
             partEndIndex = endPos;
             endMarkerLength = this.endPrefix.length;
           } else {
+            if (!this.currentPartial) {
+              this.currentPartial = this.newPartialState(gadgetName, invocationId, dependencies);
+            }
+            yield* this.emitArgPartials(
+              this.currentPartial,
+              contentStartIndex,
+              this.buffer.length,
+              false
+            );
             break;
           }
-          const parametersRaw = this.buffer.substring(contentStartIndex, partEndIndex).trim();
+          const rawSlice = this.buffer.substring(contentStartIndex, partEndIndex);
+          if (this.currentPartial) {
+            yield* this.emitArgPartials(this.currentPartial, contentStartIndex, partEndIndex, true);
+          }
+          const parametersRaw = rawSlice.trim();
           const { parameters, parseError } = this.parseParameters(parametersRaw);
           yield {
             type: "gadget_call",
@@ -14691,6 +16832,7 @@ var init_parser2 = __esm({
               dependencies
             }
           };
+          this.currentPartial = null;
           startIndex = partEndIndex + endMarkerLength;
           this.lastEmittedTextOffset = startIndex;
         }
@@ -14699,6 +16841,117 @@ var init_parser2 = __esm({
           this.lastEmittedTextOffset = 0;
         }
       }
+      /** Create fresh partial-tracking state for a newly-started streaming gadget. */
+      newPartialState(gadgetName, invocationId, dependencies) {
+        return {
+          gadgetName,
+          invocationId,
+          dependencies,
+          emittedFieldLengths: /* @__PURE__ */ new Map(),
+          completedFields: /* @__PURE__ */ new Set(),
+          bodyScannedLen: 0,
+          lastArgRelOffset: -1
+        };
+      }
+      /**
+       * Emit per-field "growing value" partials for an in-progress (or, when
+       * `allComplete`, a just-completed) gadget body delimited by [bodyStart, bodyEnd).
+       *
+       * Incremental by design: each call resumes the `!!!ARG:` scan near where the last
+       * one stopped (backing off by one marker's worth so a marker split across a chunk
+       * boundary is still found) and only re-touches the in-progress field, so a long
+       * streamed body costs O(new bytes) per feed instead of O(body). Every field except
+       * the in-progress (last) one is complete — a following `!!!ARG:` terminated it; the
+       * last field is tentative unless `allComplete`. The tentative field holds back any
+       * suffix that is a partial prefix of a gadget marker so it never leaks into a value.
+       *
+       * We deliberately do NOT run stripMarkdownFences here: an unbalanced opening fence
+       * sits before the first `!!!ARG:` (never emitted) and the authoritative gadget_call
+       * still strips fences from the full raw parameters.
+       */
+      *emitArgPartials(state, bodyStart, bodyEnd, allComplete) {
+        const argLen = this.argPrefix.length;
+        let searchAbs = bodyStart + Math.max(0, state.bodyScannedLen - (this.maxMarkerLength - 1));
+        if (state.lastArgRelOffset >= 0) {
+          searchAbs = Math.max(searchAbs, bodyStart + state.lastArgRelOffset + argLen);
+        }
+        while (true) {
+          const argAbs = this.buffer.indexOf(this.argPrefix, searchAbs);
+          if (argAbs === -1 || argAbs >= bodyEnd) break;
+          if (state.lastArgRelOffset >= 0) {
+            yield* this.emitFieldRange(state, bodyStart + state.lastArgRelOffset, argAbs, true);
+          }
+          state.lastArgRelOffset = argAbs - bodyStart;
+          searchAbs = argAbs + argLen;
+        }
+        if (state.lastArgRelOffset >= 0) {
+          yield* this.emitFieldRange(state, bodyStart + state.lastArgRelOffset, bodyEnd, allComplete);
+        }
+        state.bodyScannedLen = bodyEnd - bodyStart;
+      }
+      /**
+       * Emit a single field whose `!!!ARG:` marker starts at `markerAbs` and whose value
+       * runs to `valueEndAbs` (the next marker, or the body end). Mirrors the per-field
+       * semantics of the old split-based emitter: field-path line, hold-back for a
+       * tentative value, single trailing-newline strip.
+       */
+      *emitFieldRange(state, markerAbs, valueEndAbs, complete2) {
+        const pathStart = markerAbs + this.argPrefix.length;
+        const newlineAbs = this.buffer.indexOf("\n", pathStart);
+        if (newlineAbs === -1 || newlineAbs >= valueEndAbs) {
+          if (!complete2) return;
+          const pointer = this.buffer.substring(pathStart, valueEndAbs).trim();
+          if (pointer) yield* this.emitFieldDelta(state, pointer, "", true);
+          return;
+        }
+        const fieldPath = this.buffer.substring(pathStart, newlineAbs).trim();
+        if (!fieldPath) return;
+        let value = this.buffer.substring(newlineAbs + 1, valueEndAbs);
+        if (!complete2) {
+          const hold = this.trailingPartialMarkerLength(value);
+          if (hold > 0) value = value.slice(0, value.length - hold);
+        }
+        if (value.endsWith("\n")) value = value.slice(0, -1);
+        yield* this.emitFieldDelta(state, fieldPath, value, complete2);
+      }
+      /**
+       * Emit a single partial for a field, but only when its value grew or it newly
+       * completed — keeping event volume proportional to field growth, not characters.
+       */
+      *emitFieldDelta(state, fieldPath, value, fieldComplete) {
+        const previousLength = state.emittedFieldLengths.get(fieldPath) ?? -1;
+        const grew = value.length > previousLength;
+        const newlyComplete = fieldComplete && !state.completedFields.has(fieldPath);
+        if (!grew && !newlyComplete) return;
+        const delta = previousLength < 0 ? value : value.slice(Math.min(previousLength, value.length));
+        state.emittedFieldLengths.set(fieldPath, value.length);
+        if (fieldComplete) state.completedFields.add(fieldPath);
+        yield {
+          type: "gadget_args_partial",
+          invocationId: state.invocationId,
+          gadgetName: state.gadgetName,
+          fieldPath,
+          value,
+          delta,
+          isFieldComplete: fieldComplete
+        };
+      }
+      /**
+       * Length of the longest suffix of `value` that is a proper prefix of any gadget
+       * marker (start/end/arg). Used to hold back the beginning of an incoming marker
+       * so it never appears inside a streamed value.
+       */
+      trailingPartialMarkerLength(value) {
+        const markers = [this.startPrefix, this.endPrefix, this.argPrefix];
+        const limit = Math.min(this.maxMarkerLength - 1, value.length);
+        for (let len = limit; len >= 1; len--) {
+          const suffix = value.slice(value.length - len);
+          for (const marker of markers) {
+            if (suffix.length < marker.length && marker.startsWith(suffix)) return len;
+          }
+        }
+        return 0;
+      }
       // Finalize parsing and return remaining text or incomplete gadgets
       *finalize() {
         const startIndex = this.buffer.indexOf(this.startPrefix, this.lastEmittedTextOffset);
@@ -14711,9 +16964,18 @@ var init_parser2 = __esm({
           const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
           if (metadataEndIndex !== -1) {
             const headerLine = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-            const { gadgetName, invocationId, dependencies } = this.parseInvocationMetadata(headerLine);
+            const { gadgetName, invocationId, dependencies } = this.currentPartial ? this.currentPartial : this.parseInvocationMetadata(headerLine);
             const contentStartIndex = metadataEndIndex + 1;
-            const parametersRaw = this.buffer.substring(contentStartIndex).trim();
+            const contentRaw = this.buffer.substring(contentStartIndex);
+            if (this.currentPartial) {
+              yield* this.emitArgPartials(
+                this.currentPartial,
+                contentStartIndex,
+                this.buffer.length,
+                true
+              );
+            }
+            const parametersRaw = contentRaw.trim();
             const { parameters, parseError } = this.parseParameters(parametersRaw);
             yield {
               type: "gadget_call",
@@ -14726,6 +16988,7 @@ var init_parser2 = __esm({
                 dependencies
               }
             };
+            this.currentPartial = null;
             return;
           }
         }
@@ -14738,6 +17001,7 @@ var init_parser2 = __esm({
       reset() {
         this.buffer = "";
         this.lastEmittedTextOffset = 0;
+        this.currentPartial = null;
       }
     };
   }
@@ -15663,6 +17927,29 @@ async function notifyGadgetStart(ctx) {
     await safeObserve(() => hookFn(context), ctx.logger);
   }
 }
+async function notifyGadgetArgsPartial(ctx) {
+  if (!ctx.hooks?.onGadgetArgsPartial && !ctx.parentObservers?.onGadgetArgsPartial) return;
+  const subagentContext = ctx.tree && ctx.parentNodeId ? getSubagentContextForNode(ctx.tree, ctx.parentNodeId) : void 0;
+  const context = {
+    iteration: ctx.iteration,
+    invocationId: ctx.event.invocationId,
+    gadgetName: ctx.event.gadgetName,
+    fieldPath: ctx.event.fieldPath,
+    value: ctx.event.value,
+    delta: ctx.event.delta,
+    isFieldComplete: ctx.event.isFieldComplete,
+    logger: ctx.logger,
+    subagentContext
+  };
+  if (ctx.hooks?.onGadgetArgsPartial) {
+    const hookFn = ctx.hooks.onGadgetArgsPartial;
+    await safeObserve(() => hookFn(context), ctx.logger);
+  }
+  if (ctx.parentObservers?.onGadgetArgsPartial) {
+    const hookFn = ctx.parentObservers.onGadgetArgsPartial;
+    await safeObserve(() => hookFn(context), ctx.logger);
+  }
+}
 async function notifyGadgetComplete(ctx) {
   const gadgetNode = ctx.tree?.getNodeByInvocationId(ctx.invocationId);
   const subagentContext = ctx.tree && gadgetNode ? getSubagentContextForNode(ctx.tree, gadgetNode.id) : void 0;
@@ -16471,6 +18758,7 @@ var init_stream_processor = __esm({
     init_gadget_dispatcher();
     init_gadget_hook_lifecycle();
     init_gadget_limit_guard();
+    init_observer_notifier();
     init_safe_observe();
     StreamProcessor = class {
       iteration;
@@ -16479,6 +18767,10 @@ var init_stream_processor = __esm({
       parser;
       // Execution Tree context
       tree;
+      /** LLM-call node these gadgets hang off; used to derive subagentContext for partials. */
+      parentNodeId;
+      /** Parent agent observers (subagent visibility) — also notified for arg partials. */
+      parentObservers;
       responseText = "";
       // Dependency resolution is delegated to GadgetDependencyResolver
       dependencyResolver;
@@ -16492,6 +18784,8 @@ var init_stream_processor = __esm({
         this.hooks = options.hooks ?? {};
         this.logger = options.logger ?? createLogger({ name: "llmist:stream-processor" });
         this.tree = options.tree;
+        this.parentNodeId = options.parentNodeId;
+        this.parentObservers = options.parentObservers;
         this.dependencyResolver = new GadgetDependencyResolver({
           priorCompletedInvocations: options.priorCompletedInvocations,
           priorFailedInvocations: options.priorFailedInvocations
@@ -16693,6 +18987,17 @@ var init_stream_processor = __esm({
           for await (const e of this.dispatcher.dispatch(event.call)) {
             yield e;
           }
+        } else if (event.type === "gadget_args_partial") {
+          await notifyGadgetArgsPartial({
+            tree: this.tree,
+            hooks: this.hooks.observers,
+            parentObservers: this.parentObservers,
+            logger: this.logger,
+            iteration: this.iteration,
+            parentNodeId: this.parentNodeId,
+            event
+          });
+          yield event;
         } else {
           yield event;
         }
@@ -16864,7 +19169,7 @@ var init_stream_processor_factory = __esm({
 
 // src/mcp/errors.ts
 var McpError, McpUntrustedCommandError, McpConnectError, McpToolCallError, McpTimeoutError, JsonSchemaConversionError;
-var init_errors2 = __esm({
+var init_errors3 = __esm({
   "src/mcp/errors.ts"() {
     "use strict";
     McpError = class extends Error {
@@ -16950,7 +19255,7 @@ var init_allowlist = __esm({
   "src/mcp/allowlist.ts"() {
     "use strict";
     import_node_path6 = __toESM(require("path"), 1);
-    init_errors2();
+    init_errors3();
     DEFAULT_MCP_COMMAND_ALLOWLIST = /* @__PURE__ */ new Set([
       "npx",
       "node",
@@ -16988,7 +19293,7 @@ var init_client2 = __esm({
   "src/mcp/client.ts"() {
     "use strict";
     init_allowlist();
-    init_errors2();
+    init_errors3();
     cachedSdk = null;
     DEFAULT_CLIENT_INFO = { name: "llmist", version: "0.0.0" };
     McpClient = class {
@@ -16997,6 +19302,7 @@ var init_client2 = __esm({
         this.injectedTransport = opts?.transport;
         this.clientInfo = opts?.clientInfo ?? DEFAULT_CLIENT_INFO;
       }
+      spec;
       sdkClient = null;
       spawnedPid = null;
       closed = false;
@@ -17570,7 +19876,7 @@ var init_json_schema_to_zod = __esm({
   "src/mcp/json-schema-to-zod.ts"() {
     "use strict";
     import_zod4 = require("zod");
-    init_errors2();
+    init_errors3();
   }
 });
 
@@ -18610,7 +20916,17 @@ __export(index_exports, {
   OpenAIChatProvider: () => OpenAIChatProvider,
   OpenAICompatibleProvider: () => OpenAICompatibleProvider,
   OpenRouterProvider: () => OpenRouterProvider,
+  RESEARCH_DATA_SOURCE_TOOL_TYPES: () => RESEARCH_DATA_SOURCE_TOOL_TYPES,
   RateLimitTracker: () => RateLimitTracker,
+  ResearchDeprecatedModelError: () => ResearchDeprecatedModelError,
+  ResearchJobNotResumableError: () => ResearchJobNotResumableError,
+  ResearchNamespace: () => ResearchNamespace,
+  ResearchNotPollableError: () => ResearchNotPollableError,
+  ResearchNotSupportedError: () => ResearchNotSupportedError,
+  ResearchResultCollector: () => ResearchResultCollector,
+  ResearchStreamConsumedError: () => ResearchStreamConsumedError,
+  ResearchTimeoutError: () => ResearchTimeoutError,
+  ResearchValidationError: () => ResearchValidationError,
   SimpleSessionManager: () => SimpleSessionManager,
   Skill: () => Skill,
   SkillRegistry: () => SkillRegistry,
@@ -18644,6 +20960,7 @@ __export(index_exports, {
   detectImageMimeType: () => detectImageMimeType,
   discoverProviderAdapters: () => discoverProviderAdapters,
   discoverSkills: () => discoverSkills,
+  estimateResearchCost: () => estimateResearchCost,
   extractMessageText: () => extractMessageText,
   extractRetryAfterMs: () => extractRetryAfterMs,
   filterByDepth: () => filterByDepth,
@@ -18923,7 +21240,7 @@ init_typed_gadget();
 // src/mcp/index.ts
 init_allowlist();
 init_client2();
-init_errors2();
+init_errors3();
 
 // src/mcp/gadget-exporter.ts
 init_schema_to_json();
@@ -19164,6 +21481,14 @@ init_tool_adapter();
 // src/index.ts
 init_constants2();
 
+// src/research/index.ts
+init_collector();
+init_constants3();
+init_cost();
+init_errors2();
+init_namespace();
+init_types();
+
 // src/utils/config-resolver.ts
 function resolveValue(ctx, gadgetName, options) {
   const { runtime, subagentKey, parentKey, defaultValue, handleInherit } = options;
@@ -19462,11 +21787,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) {
@@ -19606,7 +21931,17 @@ function getHostExports2(ctx) {
   OpenAIChatProvider,
   OpenAICompatibleProvider,
   OpenRouterProvider,
+  RESEARCH_DATA_SOURCE_TOOL_TYPES,
   RateLimitTracker,
+  ResearchDeprecatedModelError,
+  ResearchJobNotResumableError,
+  ResearchNamespace,
+  ResearchNotPollableError,
+  ResearchNotSupportedError,
+  ResearchResultCollector,
+  ResearchStreamConsumedError,
+  ResearchTimeoutError,
+  ResearchValidationError,
   SimpleSessionManager,
   Skill,
   SkillRegistry,
@@ -19640,6 +21975,7 @@ function getHostExports2(ctx) {
   detectImageMimeType,
   discoverProviderAdapters,
   discoverSkills,
+  estimateResearchCost,
   extractMessageText,
   extractRetryAfterMs,
   filterByDepth,