DeepSeek Harness Plugin

MoRanYue/dsh-openrouter-providers

Stars ★ 7 Downloads (30d) 3,833 Category Models & Providers Added 2026-08-23 npm dsh-openrouter-providers

Route OpenRouter requests through a configured provider list and quantization cap, injected as provider.only/order with allow_fallbacks, plus provider.quantizations.

Install

# from npm (prebuilt)

dsh plugin --profile web add dsh-openrouter-providers

# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)

dsh plugin --profile web add github:MoRanYue/dsh-openrouter-providers

Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).

README

中文 | English

A DeepSeek Harness plugin: pick the providers OpenRouter requests may use from the official directory, or scope that per model rule, and set a quantization cap and a service tier (service_tier); the plugin injects them as provider.only / provider.order / provider.quantizations routing parameters (plus a top-level service_tier) into every OpenRouter model request (multimodal requests carrying images pass through). It can optionally route those requests through the billion-context compression proxy. The plugin owns its configuration and writes it to $DSH_HOME/openrouter-providers.json (~/.dsh/openrouter-providers.json when DSH_HOME is unset); it is restored after a restart.

Compatible DSH versions: 0.1.5-rc.1 through 0.2.2-rc.1 (engines.dsh: >=0.1.5-rc.1 <0.3.0). This plugin imports no @deepseek-ai/dsh-* package at all — its only peer is @deepseek-ai/cordis — so neither the 0.1.7 nor the 0.2.x breaking changes reach it; the 0.2 major-version crossing was re-verified item by item on a real 0.2.0-rc.2, 0.2.1-alpha.1, 0.2.1-alpha.2, 0.2.1-alpha.4, 0.2.1-rc.2, 0.2.1-rc.3 and 0.2.2-rc.1 (config round-trip, llm/stream reroute, real OpenRouter routing, billion-context proxy routing, Plugins-page title and icon, settings-page form rendering, adapter contract, service-tier injection). The 0.2.2-rc.1 row was a contract review plus a live load: the host half activates normally (state endpoint and catalog fetch both work), and the eight LlmAdapter members, the llm/stream event signature, the client bundle protocol and the plugins.bundle.config slot contract are unchanged (that release's badge, llm/models-updated, purpose generics and content.ts tool-projection refactor are all additive); the reroute path (provider restriction, proxy) has not yet issued a real request on that version. Note: since 0.2.1-alpha.3 DSH treats engines.dsh as a real gate (taking precedence over peerDependencies, refusing to load on a mismatch), so raising the upper bound is a prerequisite for any 0.3.x upgrade.

Why the settings service is no longer used: DSH 0.1.7 removed settings namespace registration (settings.register / SettingsScope / watch) and now enumerates only .volatile() fields on profile entry Configs. A plugin built on the old API fails silently on 0.1.7: apply returns early, so neither the HTTP route nor the llm/stream reroute is registered, the settings page reports "Cannot read the current state (Host half unavailable)", and request injection never takes effect. This plugin owns its configuration document instead and treats the old namespace as an optional, capability-detected enhancement (below), so behavior is identical on old and new hosts.

Configuration entry points (dual-stack): DSH 0.1.6-alpha.2 moved plugin configuration out of Settings onto the new sidebar Plugins page and retired settings.plugin.item. This plugin registers both slots and lets the host's declarations decide which one applies (the undeclared one simply never fires — no error either way):

Host Slot Where
DSH ≥ 0.1.6-alpha.2 plugins.bundle.config (keyed by package name) Sidebar Plugins → this bundle's page → configuration form
DSH < 0.1.6-alpha.2 settings.plugin.item Settings → Plugins → Plugin configuration → collapsible card

On old hosts that card is dispatched per settings namespace the Host serves, so the plugin probes for settings.register and registers an empty pass-through namespace only when it exists — purely so the card can be dispatched; it carries no values. From 0.1.7 on, that API is gone, the namespace is skipped, and nothing else is affected.

Features

  • Checkbox provider picker: the Host half fetches the official OpenRouter directory (https://openrouter.ai/api/v1/providers, cached for 24 hours) and the form renders a searchable checkbox list, while keeping a field for hand-typed custom slugs. Selected entries stay visible even when they are absent from the directory, so an incomplete offline snapshot never drops an existing selection. If the directory cannot be fetched the form falls back to the built-in snapshot, labels it clearly as "offline or not refreshed", and retries after 60 seconds rather than waiting out the full day.
  • Configuration form: pick the routing mode and the quantization cap:
    • Only these providers → the request body carries provider: { only: [...], allow_fallbacks: false }
    • Try in order → injects provider: { order: [...], allow_fallbacks: true }
    • Quantization cap → injects provider: { quantizations: ['int4' | 'int8' | ...] } (optional, unrestricted by default; valid values in OpenRouter Quantization)
    • The whole feature has a master switch; saving writes the plugin-owned configuration file ($DSH_HOME/openrouter-providers.json). On the new Plugins page only a save writes and leaving the page drops staged edits; the legacy card additionally offers a Discard button and an unsaved badge.
  • Per-model rules (optional): a modelRules array in the configuration file lets different models use different provider restrictions — pin makora/xiaomi for xiaomi/mimo* while leaving every other model unrestricted, for example. Rules are evaluated top-down and the first match wins; unmatched models keep the global configuration. pattern is a case-insensitive glob (a * makes it a wildcard), and without a * it matches a namespace prefix (xiaomi already covers xiaomi/mimo-v2.6-flash). mode is inherit (follow the global mode) / only / order / off (skip injection for that model). An empty rule providers inherits the global list. Resolution happens in both buildBody() and the llm/stream reroute gate, each against the request's own model, so a model that resolves to no restriction is never forced through the plugin's adapter.
  • Localized UI: copy comes from the plugin's openrouter-providers locale namespace (zh / en); switching the language re-renders the UI live with no page reload. On hosts without the locale service it falls back to Chinese copy.
  • Display name and icon on the Plugins page: meta.title / meta.description in the packaged locale/zh.json and locale/en.json provide the localized display name (OpenRouter Providers in English, 「OpenRouter 提供商列表」in Chinese), so the plugin list shows a readable name instead of the bare package name dsh-openrouter-providers; icon: "./icon.svg" in package.json supplies the card and row artwork (three fading rounded bars, suggesting a provider list narrowing step by step). Both follow the DSH interface language. Note that exports must include "./locale/*.json": "./locale/*.json", otherwise Node's exports resolution throws ERR_PACKAGE_PATH_NOT_EXPORTED and the display name silently falls back to the package name; icon must be a relative path with a .svg/.png/.jpg/.jpeg/.webp extension, inside the manifest directory and at most 256 KiB — a violation is reported rather than ignored, but only the icon is lost and the name still applies.
  • Route detection does not look at the name: a provider in the profile can be renamed freely (to aaaa, say) and still counts as an OpenRouter route as long as its baseURL host is openrouter.ai (subdomains included) or its apiKeyEnv is OPENROUTER_API_KEY — the result is cached for 30 seconds, so a rename needs no restart. The built-in openrouter always counts, and extra route names can be listed in the configuration file's routes array. The test deliberately anchors on the URL's host rather than a substring match: /openrouter\.ai/ also matches a path fragment on an unrelated domain.
  • Image input: images in a multimodal request are converted to OpenRouter image_url parts (a data: URL) instead of being rejected outright. Bytes come from the host path the attachments service hands out; an image already moved out of context (offloaded) degrades to a text placeholder rather than re-sending bytes that are no longer part of the history. The per-request image budget honours the host's IMAGE_OFFLOAD_REQUIRED contract — when exceeded, compaction-image-offload moves the oldest images out of context and retries, so the user never sees a failure — and it is enforced against the provider's actual maxRequestImageBytes rather than a hardcoded 20 MiB.
  • Service tier (optional): injects the top-level service_tier, one of default / flex / priority / ultrafast (OpenRouter Service Tiers). Two things are easy to conflate: "not injected" is not the same as default — omitting the field defers to the workspace default and still lets the :nitro / :floor variants admit tier endpoints, whereas sending default pins the standard tier and closes that door. ultrafast needs an adequate max_tokens, otherwise it degrades to priority. fast is not offered — it is a synonym for priority. The form also reports which tier and provider served the last request (the service_tier from the response), because OpenRouter falls back silently when a tier cannot be met; without that feedback you cannot tell whether the setting did anything.
  • Request injection: the plugin listens on the llm/stream waterfall — when the requested provider route is recognised as OpenRouter (enabled, with a non-empty list, or a quantization cap, or a service tier, or the proxy on), the request is rerouted to the plugin's own chat-completions adapter, which builds the request body and injects the provider field; reasoning.effort (off/low/medium/high/max, all valid OpenRouter values) passes through unchanged. The session log and UI still show the original route name.
  • billion-context compression proxy (optional): with the proxy switch set to Auto, the plugin detects a running local billion-context proxy and, when found, sends requests through its /bili/ entry point (<origin>/bili/https://openrouter.ai/api/v1/chat/completions) to gain its context compression; when no proxy is detected it goes direct, so installing this plugin can never break generation. The proxy switch and the provider-restriction master switch are independent: to get compression alone, turn the provider restriction off and enable the proxy by itself.
  • Credentials: reuses the existing OPENROUTER_API_KEY — resolved through the credentials service first (matching llm-pi-ai's apiKeyEnv), falling back to the same-named environment variable of the shell that launched dsh web, so there is no need to enter it again in the UI.
  • App attribution: requests carry HTTP-Referer: https://github.com/deepseek-ai/deepseek-harness, X-OpenRouter-Title: DeepSeek Harness OpenRouter, and X-OpenRouter-Categories: cli-agent, so OpenRouter's UI and leaderboards show DeepSeek Harness OpenRouter instead of Unknown (OpenRouter App Attribution).

Installation (bundle mount)

The plugin mounts as a bundle package, like other plugins (dshmarket, dsh-recall-plugin, …): its cordis.patch.yml insert row is merged into the profile composition automatically.

Option A: install from npm (recommended)

In the profile directory (for example ~/.dsh/profiles/web/):

pnpm add dsh-openrouter-providers@latest

Then add the package to the profile package.json's dsh.profile.bundles list:

"dsh": { "profile": { "bundles": [ ..., "dsh-openrouter-providers" ] } }

Restart dsh web. The bundle coordinator merges the package's cordis.patch.yml (insert row: id: openrouter-providers) on its own.

Option B: install from GitHub

pnpm add dsh-openrouter-providers@github:MoRanYue/dsh-openrouter-providers

The remaining steps are the same as Option A (add to dsh.profile.bundles and restart).

Option C: local path

pnpm add dsh-openrouter-providers@file:D:\\path\\to\\dsh-openrouter-providers
# then add the package name to dsh.profile.bundles and restart

Manual mount (without the bundle)

Append to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: openrouter-providers
      name: 'dsh-openrouter-providers'

Then add the package to the profile package.json's dependencies and dsh.profile.bundles, run pnpm install, and restart.

Usage

  1. Make sure the model's provider route is OpenRouter — the built-in openrouter route, or any provider in the profile whose baseURL host is openrouter.ai or whose apiKeyEnv is OPENROUTER_API_KEY (see "Route detection does not look at the name" above).
  2. Open the configuration entry for your host (see the table above: sidebar Plugins → this bundle's page on DSH ≥ 0.1.6-alpha.2, or Settings → Plugins → Plugin configuration on older hosts), check providers in the directory (or type a slug the directory does not list), choose the routing mode, quantization cap and service tier, and save. To scope by model, add rules under Per-model rules.
  3. Every later OpenRouter request carries the injected provider routing parameters.
  4. For context compression: start the billion-context proxy (bili) first, then set this plugin's Proxy field to Auto and save. The line under the field reports whether it is connected (Proxy in use: http://127.0.0.1:18790) or not detected; once detected it takes effect immediately, with no DSH restart.

Per-model rules look like this in the configuration file (the form edits the same thing):

{
  "enabled": true,
  "mode": "only",
  "providers": ["deepinfra", "novita"],
  "quantization": "off",
  "serviceTier": "off",
  "proxy": "auto",
  "modelRules": [
    { "pattern": "xiaomi/mimo*", "mode": "only", "providers": ["makora", "xiaomi"] },
    { "pattern": "anthropic/*", "mode": "off", "providers": [] }
  ]
}

Provider slug format: see the OpenRouter Provider Routing docs (order/only fields).

How it works (brief)

  • Transport: the dynamic plugin environment has no built-in fetch, so the adapter spawns a node -e child process through the subprocess service to perform HTTP + SSE streaming parsing (text/reasoning/tool-call deltas, usage, [DONE], error classification such as AUTH/RATE_LIMIT/INVALID_REQUEST/SERVER).
  • Image assembly and budgets: serializeMessages() turns image blocks into data: URLs and measures them the way DSH itself does — the base64 length is ceil(bytes/3)*4, excluding the data: prefix (counting the prefix would trip the budget about 22 bytes per image early, effectively moving one more image out of context than the host would). The three budgets have different origins: maxRequestImageBytes (the per-request hard ceiling) comes from that provider's configuration and is genuinely enforced; requestImageMaxBytes (single-image raw bytes) and requestImagePixelBudget (single-image pixels) are only re-encoding targets in the host — pi-ai satisfies them by downscaling through a quality ladder — and since this plugin carries no image codec they are not enforced at their defaults (doing so would degrade most screenshots to placeholders for no benefit); they are enforced only when the user explicitly configures them, and an over-budget image degrades to a text placeholder with the reason. Image bytes are read with node:fs straight from attachment storage: that is DSH-owned data living outside any workspace, and the path comes from the trusted attachments service rather than from user or model input, so the workspace sandbox policy does not apply to it (the same path the plugin already uses to read and write its own configuration file).
  • Locating a provider's image budget: the adapter only ever sees PLUGIN_ROUTE, while the budget hangs off the provider the user configured. The reroute records the real route in a WeakMap keyed by the request's AbortSignal, and stream() reads it back — the signal is the only object that survives every layer's option spread with its identity intact, so no non-standard field has to be threaded through the option bag.
  • State persistence: the plugin owns its configuration and writes $DSH_HOME/openrouter-providers.json (~/.dsh/… when DSH_HOME is unset), independent of the settings service. On first start, while the file still holds shipped defaults, the plugin tries each legacy location once, in order: <workspaceRoot>/.dsh-plugins/openrouter-providers.json (v1.0.4 and earlier), then $DSH_HOME/settings.yaml.imported (the renamed settings document 0.1.7 left behind, whose section for this plugin could not be imported because it declares no Config). The first source that holds values wins, and an existing configuration is never overwritten afterwards.
  • Client communication: the configuration card reads and writes state over the HTTP API GET/POST /api/openrouter-providers/state (registered on the Host half through webServer). The client now shows the status code and response excerpt for a non-2xx response instead of reporting every failure as "Host half unavailable".
  • Provider directory: the same state route also returns catalog ([{slug, name}]) and catalogSource (live / builtin). The directory is fetched with node:https directly — for the same reason as the proxy probe, it must not go through globalThis.fetch, or a host with billion-context mounted would rewrite the fetch into a proxied request. It is cached for 24 hours; a failed refresh keeps the last successful list with catalogSource still live (stale but genuinely official), and only a fetch that has never succeeded falls back to the built-in snapshot with builtin, which the UI labels as "offline or not refreshed". The settings page waits at most 1.5 seconds for a refresh, so an offline host never blocks the form.
  • Adapter contract: the plugin registers a plain object adapter (not an LlmAdapter subclass), so it has no base-class defaults to fall back on and must implement every member the host calls. Besides stream, LlmRuntime calls providerInfo / providerRetryPolicy / imageRequestPricing / imageRequestTarget / listModels / resolveModel / prepareCall — omit any one and that call site throws TypeError: adapter.<name> is not a function. This plugin's listModels() returns an empty array, so the synthetic route never appears in the model catalog (it is reachable only internally, from llm/stream); imageRequestPricing() returns undefined, leaving the token meter and spill policy on their own neutral estimates; imageRequestTarget() echoes the normalized width, height and byte ceiling, matching the base-class default (that member arrived in DSH 0.2.1-alpha.3 and is currently called only by the CUA screenshot path).
  • Service tier: service_tier is a top-level field, not something inside provider. It has three states rather than two: "not injected" (off), default, and flex/priority/ultrafast. default looks like "nothing chosen" but is an active pin to the standard tier — omitting the field leaves the :nitro / :floor variants free to admit tier endpoints, while sending default closes that door. OpenRouter does not validate this field: probing showed every string (even bogus) answers 200 and is silently ignored, so the legal set is enforced by a whitelist in the plugin and an out-of-range value is dropped when the configuration is written. The service_tier in the response is the only signal that a tier actually applied (null means a non-tier endpoint served the request); the child process surfaces it alongside provider as a served event, the Host remembers the most recent one and returns it on the state route, and the form renders "which tier served the last request" from it.
  • billion-context proxy integration: the proxy address is never a hardcoded port; it is resolved in billion-context's own discovery order: the BILI_MCP_PROXY environment variable → $XDG_STATE_HOME/billion-context/proxy-origin (both a bare URL and the instance JSON are supported) → lanes.dsh in port-zone.json beside it → the http://127.0.0.1:8787 fallback. Every candidate is confirmed by requesting /__bili/health and requiring ok: true. The probe deliberately uses node:http/node:https rather than globalThis.fetch: once billion-context is mounted it patches the host fetch to rewrite every URL to <origin>/bili/<original>, so a fetch-based probe would have its own request rewritten into a request the proxy makes to itself — and would then "succeed" forever. The result is cached for 30 seconds and refreshed in the background; the request path only reads that cache, so it never blocks generation on a socket. The settings page re-probes on every load and shows whether the proxy is actually in use. Requests carry an x-acp-session: <sessionId> header so the proxy buckets its compression state per conversation and the compression actually accumulates (the value comes from the session identity the host stamps on GenerateOptions.sessionId for exactly this kind of transport metadata).

Limitations

  • Images are not re-encoded: this plugin carries no image codec, so the attachment's original bytes go out as a data: URL. The host's requestImageMaxBytes / requestImagePixelBudget defaults are only re-encoding targets (pi-ai meets them by downscaling through a quality ladder), so they are not enforced by default; the user has to configure them explicitly, and over-budget images then degrade to text placeholders. The trade-off is that a very large original is sent as-is and may hit the provider's own per-image limit.
  • Image bytes are read with node:fs straight from attachment storage, bypassing the workspace sandbox (see "How it works").
  • With the global "enable provider restriction" switch off, all per-model rules are inactive too (the form greys out the rules section), because that switch is the master gate.
  • In only mode allow_fallbacks=false: the request fails when none of the listed providers is available (OpenRouter behavior).
  • Proxy routing is decided per request: if the proxy stops, requests fall back to a direct connection within 30 seconds (the probe cache TTL); if it starts, they pick it up within the same window, or immediately on opening the settings page once.
  • The service tier is best effort: OpenRouter does not error when it cannot satisfy a tier, it just falls back, so setting flex and seeing "no tier endpoint matched" is a normal outcome rather than a plugin failure. ultrafast additionally needs an adequate max_tokens, otherwise it degrades to priority.
  • The proxy and the provider restriction share one transport (this plugin's adapter), so with the proxy on, requests bypass the host's native openrouter route. If another plugin (such as billion-context's dsh-native) relies on intercepting the host globalThis.fetch, those interceptors do not apply to this plugin's traffic — an inherent consequence of owning the transport.

License

MIT

Content from the project README on GitHub ↗

Links

More in this category

View the whole category →

Community comments

Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.