@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/plugins/openrouter/adapter.mjs

@@ -0,0 +1,232 @@
+import { IMAGE_OFFLOAD_REQUIRED_CODE, LlmAdapter, LlmError, ReasoningEffortId, attributionHeaders, contentHasImage, offloadedImageText, projectOffloadedImages, requiredImageOffload } from '@deepseek-ai/dsh-llm';
+import { requestImageDimensions } from '@deepseek-ai/dsh-attachment';
+import { listOpenRouterModels, openRouterModel } from './models.mjs';
+import { PROVIDER, effortInfo, errorCode, errorMessage, modelReasoning, requestBody, retryAfterMs, sseData, translate } from './wire.mjs';
+
+export { PROVIDER };
+/** Context assumed for a model the listing does not size. */
+export const DEFAULT_CONTEXT_WINDOW = 262144;
+/** Output cap materialized when a caller names none; OpenRouter reserves credit for it. */
+export const DEFAULT_OUTPUT_CAP = 131072;
+const APP_URL = 'https://github.com/qiz029/dscode';
+const IMAGE_POLICY = Object.freeze({ maxPixels: 2048 * 2048, maxBytes: 1024 * 1024 });
+
+/**
+ * What `/model` offers on this route: the labs DSCODE tunes and tests, plus the current
+ * flagship line of the mainstream Western labs. OpenRouter carries hundreds of tool-calling
+ * models, and an alphabetical wall of them is not a picker, so the list is curated by hand;
+ * an id OpenRouter retires drops out of the picker until this list is edited.
+ * Only the picker narrows: `resolveModel` still serves every id the listing knows, so a
+ * session already on a trimmed model, `exec --model` and provider switches keep working.
+ */
+export const LISTED_MODELS = Object.freeze([
+  'deepseek/deepseek-v4-pro', 'deepseek/deepseek-v4-flash', 'deepseek/deepseek-v4.1-flash',
+  'z-ai/glm-5.3', 'z-ai/glm-5.3-flash', 'z-ai/glm-5.3-flashx',
+  'moonshotai/kimi-k3', 'moonshotai/kimi-k2.7-code', 'moonshotai/kimi-k2.6',
+  'qwen/qwen3.8-max-0902', 'qwen/qwen3.8-flash', 'qwen/qwen3.8-27b', 'qwen/qwen3.7-plus',
+  'xiaomi/mimo-v2.6-pro', 'xiaomi/mimo-v2.6-flash', 'xiaomi/mimo-v2.6-pro-ultraspeed',
+  'anthropic/claude-opus-5', 'anthropic/claude-sonnet-5', 'anthropic/claude-fable-5.1', 'anthropic/claude-haiku-4.5',
+  'openai/gpt-6-astra-pro', 'openai/gpt-6-astra', 'openai/gpt-5.6-luna-pro', 'openai/gpt-5.6-terra-pro',
+  'google/gemini-3.8-flash', 'google/gemini-3.1-pro-preview',
+  'x-ai/grok-4.7', 'x-ai/grok-build-0.1',
+]);
+const LISTED = new Set(LISTED_MODELS);
+
+function modelInfo(provider, id, entry) {
+  return { provider, id, name: entry?.name ?? id, inputModalities: entry?.inputModalities?.length ? [...entry.inputModalities] : ['text'] };
+}
+
+function collectImages(blocks, refs) {
+  for (const block of blocks) {
+    if (block.type === 'image') refs.set(block.attachment.attachmentId, block.attachment);
+    else if (block.type === 'tool-result') collectImages(block.content, refs);
+  }
+}
+
+/**
+ * OpenRouter chat completions as a harness adapter: fetch + SSE with the model
+ * directory, reasoning controls and prices of OpenRouter's live listing. Connection
+ * facts and the key resolve per request, so settings and `/login` changes reach the
+ * next call.
+ */
+export class OpenRouterAdapter extends LlmAdapter {
+  /**
+   * @param config - `options()` connection facts, `resolveApiKey(connection)`, `ensureModels()`,
+   *   optional `resolveAttachments()`, `resolveImageAccess(attachments, ref)` and `fetch`.
+   */
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+
+  providerInfo(provider) {
+    return { id: provider, name: this.config.displayName ?? 'OpenRouter' };
+  }
+
+  providerRetryPolicy() {
+    return this.config.options().retryPolicy;
+  }
+
+  /** The curated picker list, narrowed to entries that can drive an agent: text output and tool calls. */
+  async listModels(provider) {
+    await this.config.ensureModels();
+    return listOpenRouterModels().filter(([id, entry]) => LISTED.has(id) && entry.tools !== false && entry.textOutput !== false).map(([id, entry]) => modelInfo(provider, id, entry));
+  }
+
+  async resolveModel(provider, model) {
+    await this.config.ensureModels();
+    const entry = openRouterModel(model);
+    const reasoning = modelReasoning(model, entry);
+    return {
+      ...modelInfo(provider, model, entry),
+      context: { contextWindow: entry?.contextWindow ?? DEFAULT_CONTEXT_WINDOW },
+      ...(entry?.maxOutput ? { defaultMaxTokens: Math.min(entry.maxOutput, DEFAULT_OUTPUT_CAP) } : {}),
+      ...(reasoning ? { reasoning: {
+        efforts: reasoning.levels.map(id => ({ ...effortInfo(id), id: ReasoningEffortId(id) })),
+        ...(reasoning.defaultEffort ? { defaultEffort: ReasoningEffortId(reasoning.defaultEffort) } : {}),
+      } } : {}),
+    };
+  }
+
+  /** Name in error messages; a subclass serving another route renames it. */
+  get label() {
+    return 'OpenRouter';
+  }
+
+  /** The model's catalog entry, after the catalog is loaded. */
+  async modelEntry(model) {
+    await this.config.ensureModels();
+    return openRouterModel(model);
+  }
+
+  /** The chat-completions body for one prepared request. */
+  requestBody(options, context) {
+    return requestBody(options, context);
+  }
+
+  /** Route headers beyond auth, content type and the user agent. */
+  requestHeaders() {
+    return { 'HTTP-Referer': APP_URL, 'X-OpenRouter-Title': 'DSCODE', 'X-OpenRouter-Categories': 'cli-agent' };
+  }
+
+  /**
+   * Where and how the next request authenticates: the bearer secret, the base URL and any
+   * extra headers. A subclass whose credential carries its own endpoint overrides this.
+   */
+  async resolveAuth(connection) {
+    return { apiKey: await this.config.resolveApiKey(connection), baseURL: connection.baseURL, headers: {} };
+  }
+
+  /** Options for the stream translation: the replay kind and error label. */
+  translateOptions(options) {
+    return { model: options.model };
+  }
+
+  async *stream(options) {
+    const connection = this.config.options();
+    const label = this.label;
+    // The endpoint the request went to, for error messages: the route's own until auth names another.
+    let endpoint = connection.baseURL;
+    const idle = new AbortController(), consumer = new AbortController();
+    let timer;
+    const pulse = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => idle.abort(new Error(`${label} stream idle`)), connection.streamIdleTimeoutMs);
+      timer.unref?.();
+    };
+    const signal = AbortSignal.any([idle.signal, consumer.signal, ...(options.signal ? [options.signal] : [])]);
+    try {
+      const auth = await this.resolveAuth(connection);
+      endpoint = auth.baseURL;
+      const entry = await this.modelEntry(options.model);
+      pulse();
+      const images = await this.prepareImages(options, entry, connection, signal);
+      const body = this.requestBody(images?.options ?? options, { entry, images });
+      const fetchImpl = this.config.fetch ?? globalThis.fetch;
+      let response;
+      try {
+        response = await fetchImpl(`${auth.baseURL}/chat/completions`, {
+          method: 'POST',
+          headers: {
+            authorization: `Bearer ${auth.apiKey}`,
+            'content-type': 'application/json',
+            accept: 'text/event-stream',
+            ...attributionHeaders(),
+            ...this.requestHeaders(options),
+            ...auth.headers,
+          },
+          body: JSON.stringify(body),
+          signal,
+        });
+      } catch (error) {
+        if (signal.aborted) throw error;
+        throw new LlmError(`${label} request to ${endpoint} failed`, 'TRANSPORT', { cause: error });
+      }
+      // A rejected request, or a 200 whose JSON body holds only an error.
+      if (!response.ok || !response.headers.get('content-type')?.includes('text/event-stream')) {
+        const raw = await response.text();
+        let error;
+        try { error = JSON.parse(raw)?.error; } catch { /* not JSON */ }
+        if (response.ok && error === undefined) throw new LlmError(`${label} returned a non-stream response: ${raw.slice(0, 120)}`, 'MALFORMED_RESPONSE');
+        const delay = retryAfterMs(response.headers.get('retry-after'));
+        const status = response.ok ? (Number.isInteger(error?.code) ? error.code : undefined) : response.status;
+        throw new LlmError(errorMessage(error, `${label} API error (HTTP ${response.status})`), errorCode(response.ok ? undefined : response.status, error), {
+          cause: new Error(raw.length > 0 ? raw : `${label} HTTP ${response.status}`),
+          ...(status === undefined ? {} : { status }),
+          ...(delay === undefined ? {} : { providerRetryAfterMs: delay }),
+        });
+      }
+      if (!response.body) throw new LlmError(`${label} returned no response body`, 'EMPTY_RESPONSE');
+      for await (const chunk of translate(sseData(response.body, pulse), this.translateOptions(options))) {
+        // The idle clock measures the provider, not a slow consumer.
+        clearTimeout(timer);
+        yield chunk;
+        pulse();
+      }
+    } catch (error) {
+      if (idle.signal.aborted && !options.signal?.aborted) throw new LlmError(`${label} stream idle timeout after ${connection.streamIdleTimeoutMs}ms`, 'TIMEOUT', { cause: error });
+      if (options.signal?.aborted) throw new LlmError(`${label} request aborted by caller`, 'ABORTED', { cause: error });
+      if (error instanceof LlmError) throw error;
+      throw new LlmError(`${label} API stream from ${endpoint} failed`, 'TRANSPORT', { cause: error });
+    } finally {
+      clearTimeout(timer);
+      consumer.abort(`${label} stream consumer stopped`);
+    }
+  }
+
+  /**
+   * Read request versions of every retained image.
+   *
+   * DSH 0.1.7 made the offloaded set a durable surface fact: a route projects what the
+   * surface already offloaded into text and reports how much more must go with
+   * `IMAGE_OFFLOAD_REQUIRED`, instead of dropping the oldest occurrences itself. The
+   * `compaction-image-offload` executor records that choice and retries, so the decision
+   * survives a route change, resume and replay rather than being remade per request.
+   */
+  async prepareImages(options, entry, connection, signal) {
+    const attachments = this.config.resolveAttachments?.();
+    const access = ref => (attachments === undefined ? undefined : this.config.resolveImageAccess?.(attachments, ref));
+    const messages = projectOffloadedImages(options.messages, ref => offloadedImageText(ref, access(ref)));
+    const withImages = messages.some(message => contentHasImage(message.content));
+    if (!withImages) return messages === options.messages ? undefined : { options: { ...options, messages: [...messages] }, versions: new Map(), access };
+    if (!entry?.inputModalities?.includes('image')) throw new LlmError(`${this.label} model "${options.model}" does not accept image input.`, 'UNSUPPORTED_CONTENT');
+    if (attachments === undefined) throw new LlmError(`${this.label} image input requires the durable attachment service.`, 'UNSUPPORTED_CONTENT');
+    const refs = new Map();
+    for (const message of messages) collectImages(message.content, refs);
+    const versions = new Map(await Promise.all([...refs.values()].map(async ref => [ref.attachmentId, await attachments.readImageRequest(ref,
+      { ...requestImageDimensions(ref.width, ref.height, IMAGE_POLICY.maxPixels), maxBytes: IMAGE_POLICY.maxBytes }, signal)])));
+    const offloadImages = requiredImageOffload(
+      messages,
+      { representation: 'base64', maxBytes: connection.maxRequestImageBytes, byteQuantum: 1 },
+      block => versions.get(block.attachment.attachmentId).bytes,
+    );
+    if (offloadImages > 0) {
+      throw new LlmError(
+        `${this.label} request images exceed ${connection.maxRequestImageBytes} bytes; ${offloadImages} more oldest occurrence(s) must be offloaded.`,
+        IMAGE_OFFLOAD_REQUIRED_CODE,
+        { offloadImages },
+      );
+    }
+    return { options: { ...options, messages: [...messages] }, versions, access };
+  }
+}

package/plugins/openrouter/index.mjs

@@ -0,0 +1,123 @@
+import z from '@deepseek-ai/schemastery';
+import { LlmError, RetryPolicySchema, assertUsableApiKey, resolveImageAttachmentAccess, resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { deepEqualJson } from '@deepseek-ai/dsh-util-values';
+import { plainConfig } from '../cordis-config/plain.mjs';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { OpenRouterAdapter, PROVIDER } from './adapter.mjs';
+import { ensureOpenRouterModels } from './models.mjs';
+import { OpenRouterSearchProvider, RoutedSearchProvider } from './search.mjs';
+import { ExaSearchProvider } from '../opencode-go/search.mjs';
+import { dscodeVersion } from '../opencode-go/version.mjs';
+
+// The `openrouter` route: DSCODE's own OpenRouter adapter over its live model
+// listing, configured by this entry's own profile row, plus web search that
+// follows the session's route (including Exa for an OpenCode Go session).
+export const name = 'dscode-openrouter';
+export const inject = ['llm'];
+const NS = 'llm-openrouter';
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
+
+// DSH 0.1.7 replaced settings sections with volatile configuration: a field marked
+// `.volatile()` reaches the plugin as a reference the Settings form and a profile edit
+// both write, so each read below sees the current value without a change callback.
+export const Config = z.object({
+  providerName: z.union(['openrouter', 'dscode-openrouter']).default('openrouter'),
+  apiKeyEnv: z.string().role('credential-ref').default('OPENROUTER_API_KEY').volatile(),
+  baseURL: z.string().default(DEFAULT_BASE_URL).volatile(),
+  streamIdleTimeoutMs: z.number().min(1).default(300000).volatile(),
+  maxRequestImageBytes: z.number().step(1).min(1).default(20 * 1024 * 1024).volatile(),
+  searchModel: z.string().default('deepseek/deepseek-v4-flash').volatile(),
+  retryPolicy: RetryPolicySchema.volatile(),
+});
+
+
+/** Validated connection facts from one config snapshot. */
+export function resolveOptions(config = {}) {
+  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? 300000;
+  if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0) throw new Error(`${name}: streamIdleTimeoutMs must be a positive number`);
+  const baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  if (!URL.canParse(baseURL)) throw new Error(`${name}: baseURL must be a URL`);
+  return {
+    apiKeyEnv: credentialRef(config.apiKeyEnv || 'OPENROUTER_API_KEY'),
+    baseURL,
+    streamIdleTimeoutMs,
+    maxRequestImageBytes: config.maxRequestImageBytes ?? 20 * 1024 * 1024,
+    searchModel: config.searchModel || 'deepseek/deepseek-v4-flash',
+    retryPolicy: resolveRetryPolicy(config.retryPolicy, `${name}: retryPolicy`),
+  };
+}
+
+export function apply(ctx, config = {}) {
+  const provider = config.providerName ?? PROVIDER;
+  const displayName = provider === 'dscode-openrouter' ? 'DSCODE OpenRouter' : 'OpenRouter';
+  // The TUI renders this route's own page, so Settings must not generate a form for it.
+  ctx.inject(['settings'], settingsCtx => {
+    settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber));
+  });
+  let lastGood;
+  const options = () => {
+    try {
+      lastGood = resolveOptions(plainConfig(config));
+      return lastGood;
+    } catch (error) {
+      if (lastGood === undefined) throw error;
+      ctx.logger.error(`${name}: keeping the last good configuration after an invalid edit`);
+      ctx.logger.error(error);
+      return lastGood;
+    }
+  };
+  options();
+  const resolveKey = async ref => {
+    const credentials = ctx.get('credentials');
+    if (credentials !== undefined) return (await credentials.resolve(ref))?.value || undefined;
+    return launchEnvironmentOf(ctx).get(ref)?.value || undefined;
+  };
+  const home = process.env.DSH_HOME;
+  const ensureModels = () => ensureOpenRouterModels({ home });
+  const adapter = new OpenRouterAdapter({
+    displayName,
+    options,
+    ensureModels,
+    resolveApiKey: async connection => {
+      const key = await resolveKey(connection.apiKeyEnv);
+      if (key !== undefined) return assertUsableApiKey(key, name, connection.apiKeyEnv);
+      throw new LlmError(`${name}: no API key for OpenRouter; run /login openrouter, or export ${connection.apiKeyEnv} in the launching environment`, 'MISSING_CREDENTIAL');
+    },
+    resolveAttachments: () => ctx.get('attachments'),
+    resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, hostPath => ctx.get('fs')?.processPathFromHostPath(hostPath), ref),
+  });
+  ctx.llm.registerConfigurableProviders([{ provider, displayName, settingsNs: ctx.fiber.entry?.options.id ?? NS, settingsPath: [] }]);
+  const registration = ctx.llm.registerAdapter([provider], adapter);
+  // The retry policy is captured at registration, and a reference carries no change
+  // callback: re-register the route when an edit lands on a different policy.
+  let registeredPolicy = options().retryPolicy;
+  ctx.on('loader/volatile-update', () => {
+    let policy;
+    try { policy = options().retryPolicy; } catch (error) { ctx.logger.warn(error); return; }
+    if (deepEqualJson(policy, registeredPolicy)) return;
+    registration.replace([provider]);
+    registeredPolicy = policy;
+  });
+  ctx.inject(['web'], webCtx => {
+    const openrouter = new OpenRouterSearchProvider(() => {
+      const connection = options();
+      return { baseURL: connection.baseURL, model: connection.searchModel, resolveApiKey: () => resolveKey(connection.apiKeyEnv) };
+    });
+    webCtx.web.registerSearchProvider(openrouter);
+    webCtx.web.registerSearchProvider(new RoutedSearchProvider({
+      openrouter,
+      // `ctx.web` keeps no per-call selection; the DeepSeek provider is looked up in its registry.
+      deepseek: () => webCtx.web.searchProviders?.get?.('deepseek-official'),
+      // An OpenCode Go session searches through Exa, as OpenCode's own client does.
+      exa: new ExaSearchProvider(() => ({ resolveApiKey: () => resolveKey(credentialRef('EXA_API_KEY')), userAgent: `dscode/${dscodeVersion() ?? '0.0.0'}` })),
+      currentProvider: () => {
+        const agent = ctx.get('agents')?.currentInitiator?.();
+        return agent?.session?.requestHeader?.()?.config?.provider ?? agent?.options?.provider;
+      },
+      hasKey: async ref => (await resolveKey(credentialRef(ref))) !== undefined,
+    }));
+  });
+  // Warm the listing for an OpenRouter user, so the first /model opens with every model.
+  void resolveKey(options().apiKeyEnv).then(key => key === undefined ? undefined : ensureModels(), () => {});
+}

package/plugins/openrouter/models.mjs

@@ -0,0 +1,157 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// OpenRouter's public model listing: context sizes, input modalities, reasoning
+// controls and list prices for every model it serves. The OpenRouter adapter
+// resolves models from it and the session metrics price calls from it, so one
+// table, kept for a day in DSH_HOME, backs both. The listing quotes USD per
+// token; the table keeps USD per million.
+export const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+/** How long a first model lookup waits for the listing before answering without it. */
+export const FORCED_LOAD_TIMEOUT_MS = 10_000;
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** How long a failed listing (or an unusable cache file) waits before the next attempt. */
+export const RETRY_MS = 10 * 60 * 1000;
+const FILE = 'openrouter-models.json';
+const VERSION = 2;
+const EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+let table = { fetchedAt: 0, models: {} };
+/** When the on-disk cache was last consulted; an unusable file waits, then may retry, like the listing. */
+let cacheReadAt = 0;
+let attemptedAt = 0, pending;
+
+const perMillion = value => {
+  const number = Number(value);
+  return value != null && value !== '' && Number.isFinite(number) && number >= 0 ? number * 1e6 : undefined;
+};
+const positive = value => Number.isSafeInteger(value) && value > 0 ? value : undefined;
+const ratesOf = pricing => {
+  const input = perMillion(pricing?.prompt), output = perMillion(pricing?.completion);
+  if (input === undefined || output === undefined) return undefined;
+  return { input, output, cacheRead: perMillion(pricing.input_cache_read), cacheWrite: perMillion(pricing.input_cache_write) };
+};
+
+function reasoningOf(reasoning) {
+  if (reasoning === null || typeof reasoning !== 'object') return undefined;
+  const offered = Array.isArray(reasoning.supported_efforts) ? EFFORTS.filter(level => reasoning.supported_efforts.includes(level)) : undefined;
+  return {
+    mandatory: reasoning.mandatory === true,
+    ...(offered?.length ? { efforts: offered } : {}),
+    ...(EFFORTS.includes(reasoning.default_effort) ? { defaultEffort: reasoning.default_effort } : {}),
+  };
+}
+
+/**
+ * Models from an OpenRouter `/models` body.
+ * @returns `{ [id]: { input, output, cacheRead?, cacheWrite?, tiers?, name?, contextWindow?, maxOutput?,
+ *   inputModalities?, tools?, textOutput?, reasoning? } }` with prices in USD per million tokens;
+ *   a tier applies once a request's prompt reaches its `minPromptTokens`.
+ */
+export function parseOpenRouterModels(body) {
+  const models = {};
+  for (const model of Array.isArray(body?.data) ? body.data : []) {
+    const base = typeof model?.id === 'string' ? ratesOf(model.pricing) : undefined;
+    if (!base) continue;
+    const tiers = (Array.isArray(model.pricing.overrides) ? model.pricing.overrides : [])
+      .map(tier => ({ minPromptTokens: Number(tier?.min_prompt_tokens), ...ratesOf({ ...model.pricing, ...tier }) }))
+      .filter(tier => Number.isFinite(tier.minPromptTokens) && tier.input !== undefined)
+      .sort((left, right) => left.minPromptTokens - right.minPromptTokens);
+    // The routed endpoint can serve less than the model's nominal context.
+    const windows = [model.context_length, model.top_provider?.context_length].map(positive).filter(Boolean);
+    const input = model.architecture?.input_modalities, output = model.architecture?.output_modalities;
+    const reasoning = reasoningOf(model.reasoning);
+    models[model.id] = {
+      ...base, ...(tiers.length ? { tiers } : {}),
+      ...(typeof model.name === 'string' && model.name.length > 0 ? { name: model.name } : {}),
+      ...(windows.length ? { contextWindow: Math.min(...windows) } : {}),
+      ...(positive(model.top_provider?.max_completion_tokens) ? { maxOutput: model.top_provider.max_completion_tokens } : {}),
+      ...(Array.isArray(input) ? { inputModalities: ['text', 'image'].filter(modality => input.includes(modality)) } : {}),
+      ...(Array.isArray(model.supported_parameters) ? { tools: model.supported_parameters.includes('tools') } : {}),
+      ...(Array.isArray(output) ? { textOutput: output.includes('text') } : {}),
+      ...(reasoning ? { reasoning } : {}),
+    };
+  }
+  return models;
+}
+
+/** One model's entry, or undefined when the table does not list it. */
+export function openRouterModel(id) {
+  return Object.hasOwn(table.models, id) ? table.models[id] : undefined;
+}
+
+/** Every listed model as `[id, entry]` pairs, in listing order. */
+export function listOpenRouterModels() {
+  return Object.entries(table.models);
+}
+
+/** Prices for one model at a request's prompt size, or undefined when the table lists none. */
+export function openRouterRates(model, promptTokens = 0) {
+  const entry = openRouterModel(model);
+  if (!entry) return undefined;
+  return entry.tiers?.findLast(tier => promptTokens >= tier.minPromptTokens) ?? entry;
+}
+
+/** Version stamp for rows priced from the live table: the day it was fetched. */
+export function openRouterPriceVersion() {
+  return table.fetchedAt > 0 ? `openrouter-models-${new Date(table.fetchedAt).toISOString().slice(0, 10)}` : undefined;
+}
+
+/** Replace the table (and forget the last attempt); for tests and cache loads. */
+export function setOpenRouterModels(models, fetchedAt = Date.now()) {
+  table = { fetchedAt, models };
+  cacheReadAt = 0;
+  attemptedAt = 0;
+}
+
+/**
+ * Load the cached table, then refetch it once it is a day old. A failure keeps the
+ * last table and waits ten minutes before trying again; never throws.
+ */
+export async function refreshOpenRouterModels({ home, fetch: fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  const path = home ? join(home, FILE) : undefined;
+  // A version bump or a corrupt body leaves the table empty: parse that file once per throttle window, not per request.
+  if (table.fetchedAt === 0 && path && now - cacheReadAt >= RETRY_MS) {
+    cacheReadAt = now;
+    try {
+      const cached = JSON.parse(readFileSync(path, 'utf8'));
+      if (cached?.version === VERSION && Number.isFinite(cached.fetchedAt) && cached.models && typeof cached.models === 'object') table = { fetchedAt: cached.fetchedAt, models: cached.models };
+    } catch { /* no usable cache */ }
+  }
+  if (now - table.fetchedAt < MAX_AGE_MS || now - attemptedAt < RETRY_MS || typeof fetchImpl !== 'function') return table;
+  if (pending) return pending;
+  attemptedAt = now;
+  pending = (async () => {
+    try {
+      const response = await fetchImpl(OPENROUTER_MODELS_URL, { headers: { Accept: 'application/json' } });
+      if (!response.ok) return table;
+      const models = parseOpenRouterModels(await response.json());
+      if (Object.keys(models).length === 0) return table;
+      table = { fetchedAt: now, models };
+      if (path) {
+        mkdirSync(home, { recursive: true });
+        writeFileSync(`${path}.tmp`, JSON.stringify({ version: VERSION, ...table }));
+        renameSync(`${path}.tmp`, path);
+      }
+      return table;
+    } catch {
+      return table;
+    } finally {
+      pending = undefined;
+    }
+  })();
+  return pending;
+}
+
+/**
+ * The table before a model lookup or a priced call: an empty table waits up to
+ * `timeoutMs` for the listing, a stale one refreshes in the background. Waits at
+ * most once per retry window, so an unreachable listing never stalls every call.
+ */
+export async function ensureOpenRouterModels({ timeoutMs = FORCED_LOAD_TIMEOUT_MS, ...options } = {}) {
+  const refresh = refreshOpenRouterModels(options);
+  if (Object.keys(table.models).length > 0) return table;
+  let timer;
+  await Promise.race([refresh, new Promise(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref?.(); })]);
+  clearTimeout(timer);
+  return table;
+}

package/plugins/openrouter/search.mjs

@@ -0,0 +1,113 @@
+import { WebError } from '@deepseek-ai/dsh-web';
+import { canonicalProvider, isOpenRouterRoute } from '../providers/catalog.mjs';
+
+// Web search through OpenRouter's web plugin, and the provider `ctx.web` is pinned to:
+// it searches with the session's own route, so an OpenRouter session never needs a
+// DeepSeek key and a DeepSeek session never bills OpenRouter.
+export const OPENROUTER_SEARCH_ID = 'openrouter';
+export const ROUTED_SEARCH_ID = 'dscode-web';
+const DEFAULT_MAX_RESULTS = 8;
+
+/** Sources from the `url_citation` annotations of an OpenRouter message, de-duplicated by URL. */
+export function citationSources(message) {
+  const seen = new Set(), sources = [];
+  for (const annotation of Array.isArray(message?.annotations) ? message.annotations : []) {
+    const citation = annotation?.type === 'url_citation' ? annotation.url_citation : undefined;
+    if (typeof citation?.url !== 'string' || citation.url.length === 0 || seen.has(citation.url)) continue;
+    seen.add(citation.url);
+    sources.push({
+      url: citation.url,
+      ...(typeof citation.title === 'string' && citation.title.length > 0 ? { title: citation.title } : {}),
+      ...(typeof citation.content === 'string' && citation.content.length > 0 ? { snippet: citation.content } : {}),
+    });
+  }
+  return sources;
+}
+
+const aborted = (signal, error) => new WebError('OpenRouter search was cancelled', 'WEB_ABORTED', { cause: error ?? signal?.reason });
+
+/** Exa search through OpenRouter's `web` plugin on a small model whose answer is discarded. */
+export class OpenRouterSearchProvider {
+  id = OPENROUTER_SEARCH_ID;
+
+  /** @param resolveOptions - `{ baseURL, model, resolveApiKey(), fetch? }` for the next search. */
+  constructor(resolveOptions) {
+    this.resolveOptions = resolveOptions;
+  }
+
+  available() {
+    return URL.canParse(this.resolveOptions().baseURL);
+  }
+
+  async search(request, signal) {
+    const options = this.resolveOptions();
+    const apiKey = await options.resolveApiKey();
+    if (signal?.aborted) throw aborted(signal);
+    if (!apiKey) throw new WebError('OpenRouter search has no API key: run /login openrouter or set OPENROUTER_API_KEY.', 'WEB_PROVIDER_CREDENTIAL_MISSING');
+    const body = {
+      model: options.model,
+      stream: false,
+      messages: [{ role: 'user', content: `Search the web for: ${request.query}` }],
+      plugins: [{ id: 'web', engine: 'exa', max_results: request.maxResults ?? DEFAULT_MAX_RESULTS }],
+      reasoning: { effort: 'none' },
+      max_tokens: 256,
+    };
+    let response, text;
+    try {
+      response = await (options.fetch ?? globalThis.fetch)(`${options.baseURL}/chat/completions`, {
+        method: 'POST', redirect: 'error', signal,
+        headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', accept: 'application/json', 'HTTP-Referer': 'https://github.com/qiz029/dscode', 'X-OpenRouter-Title': 'DSCODE' },
+        body: JSON.stringify(body),
+      });
+      text = await response.text();
+    } catch (error) {
+      if (signal?.aborted) throw aborted(signal, error);
+      throw new WebError(`OpenRouter search request failed: ${error instanceof Error ? error.message : String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error });
+    }
+    let json;
+    try { json = JSON.parse(text); } catch { /* reported below */ }
+    if (!response.ok || json?.error || !Array.isArray(json?.choices)) {
+      const detail = typeof json?.error?.message === 'string' ? json.error.message : text.slice(0, 200);
+      throw new WebError(`OpenRouter search failed (HTTP ${response.status}): ${detail}`, 'WEB_PROVIDER_ERROR');
+    }
+    return { sources: citationSources(json.choices[0]?.message), truncated: false };
+  }
+}
+
+/**
+ * The pinned search provider: OpenRouter for an OpenRouter session, DeepSeek for a
+ * DeepSeek one, Exa for an OpenCode Go one (Go has no search of its own), and otherwise
+ * whichever provider has a key (DeepSeek first).
+ */
+export class RoutedSearchProvider {
+  id = ROUTED_SEARCH_ID;
+
+  /**
+   * @param routes - `openrouter` provider, `deepseek()` provider lookup, optional `exa` provider,
+   *   `currentProvider()` of the calling session, and `hasKey(ref)` for credential presence.
+   */
+  constructor(routes) {
+    this.routes = routes;
+  }
+
+  available() {
+    return this.routes.openrouter.available() || this.routes.deepseek()?.available() === true;
+  }
+
+  async pick() {
+    const { openrouter, deepseek: lookup, exa, currentProvider, hasKey } = this.routes;
+    const deepseek = lookup();
+    const route = canonicalProvider(currentProvider());
+    if (route?.startsWith('custom-')) throw new WebError('Web search is not configured for Custom. Configure a separate search provider explicitly.', 'WEB_PROVIDER_CREDENTIAL_MISSING');
+    if (isOpenRouterRoute(route)) return openrouter;
+    if (route === 'opencode-go' && exa) return exa;
+    if (route === 'deepseek-official' && deepseek) return deepseek;
+    if (deepseek && await hasKey('DEEPSEEK_API_KEY')) return deepseek;
+    if (await hasKey('OPENROUTER_API_KEY')) return openrouter;
+    return deepseek ?? openrouter;
+  }
+
+  async search(request, signal) {
+    return (await this.pick()).search(request, signal);
+  }
+}