dsh-plugin-adapter

dsh-plugin-adapter

Free OpenCode Zen models, natively inside DSH (DeepSeek Harness).

No API key. No registration. No extra process.

English | 简体中文

dsh-plugin-adapter registers a native DSH LlmAdapter that streams directly from OpenCode Zen's anonymous free lane — the same models OpenCode's own CLI uses without an account, served to your DSH model picker as a regular provider called zen-free (opencode2dsh stays registered as a legacy alias so old sessions keep working).

Requests leave your machine looking exactly like traffic from the OpenCode CLI (same user agent, same correlation headers), and the model catalog stays fresh through a three-tier fallback chain. There is nothing to log into and nothing to host.

Highlights

• Zero credential, zero setup — the anonymous lane needs no key; install, restart, chat
• Native adapter, no sidecar — one npm package, no child process, no binary, no local port (the legacy Go sidecar is not part of the published package; see legacy/)
• CLI-identical disguise — requests carry the OpenCode CLI user agent and its session/request/project header set, derived per conversation
• Selectable thinking levels — reasoning-capable free models expose an effort picker in DSH's model selector (declared ladders where the model metadata provides them, Off/Minimal/Low/Medium/High otherwise); Off sends reasoning_effort: "none" upstream to actually stop thinking, and no selection keeps the provider default
• Live catalog with a fallback chain — live upstream list ∩ free verdict (models.dev price 0, or a -free id the lane itself serves free), falling back to offline cache and a verified static list
• Self-healing — fast startup retries, periodic refresh, and a written health snapshot for diagnostics
• Proper error surfaces — upstream failures (rate limit, auth, timeout, transport) arrive in DSH as classified finish reasons, and retries stay owned by DSH

Install

From the plugin market (recommended, once listed): in DSH open Settings → Plugin Market, search dsh-plugin-adapter, one-click install.

From GitHub:

dsh plugin --profile web add github:1624318455/dsh-plugin-adapter

From npm:

dsh plugin --profile web add @memef1f1y/dsh-plugin-adapter

From source (build the tarball yourself):

git clone https://github.com/1624318455/dsh-plugin-adapter.git
cd dsh-plugin-adapter/packages/plugin
pnpm install && pnpm pack
dsh plugin --profile web add ./memef1f1y-dsh-plugin-adapter-<version>.tgz

Verify: restart dsh web, open the model picker, and pick a model from the zen-free group.

Requires DSH (DeepSeek Harness) with a web profile; Node.js ≥ 20 (already present if DSH runs); outbound HTTPS to opencode.ai and models.dev.

Configuration

Defaults work out of the box. Override via the profile's cordis.patch.yml:

- id: dsh-plugin-adapter
  name: '@memef1f1y/dsh-plugin-adapter'
  config:
    mode: adapter        # adapter (default) | sidecar
    providerId: zen-free
    refreshSeconds: 300  # catalog refresh cadence

Upgrading from ≤ 0.3.x: the plugin id changed from opencode2dsh to

dsh-plugin-adapter in 0.4.0. DSH attaches the config block to the plugin

by that id, so rename the - id: line in your live cordis.patch.yml in

the same step — otherwise the config (e.g. a pinned gatewaySession) is

silently dropped. The data directory moved with it (~/.opencode2dsh →

~/.dsh-plugin-adapter): the plugin copies the old one over on first

start and parks it as ~/.opencode2dsh.bak-, which you can delete

once the new setup works.

Option · Default · Description mode · adapter · adapter: native LlmAdapter streaming straight from Zen. sidecar: legacy local-agent mode, not bundled — build the agent from legacy/agent and pass agentPath. providerId · zen-free · Provider name shown in DSH (opencode2dsh stays registered as a legacy alias). refreshSeconds · 300 · Live catalog refresh interval. Pricing metadata refreshes every 24 h. gatewaySession · — · Fixed session id sent as x-opencode-session for every request. Leave unset unless you need the escape hatch: the Zen free lane meters its quota per *session id*, so a pinned id makes every conversation share one bucket (one 429 then breaks the whole app until the id changes). Unpinned, the adapter derives a canonical id per conversation from its first user turn — stable across turns, distinct per conversation, so each conversation gets its own quota pool. Escape hatch for a conversation stuck on a sick upstream replica: pin a live OpenCode CLI session id here and restart DSH. watchdog.firstEventMs · 60000 · Time-to-first-token budget. The Zen lane holds the response head back until the upstream emits its first token, so this window is about a slow first answer, not a dead exit. watchdog.reasoningFirstEventMs · 90000 · Same budget for reasoning models (they compose longer before the first token). watchdog.bodyIdleMs · 120000 · Body-silence budget after content started flowing (300 s for Responses models). contextWindow · — · Cap for the context window the adapter advertises to DSH (tokens). DSH compacts against the window the provider reports, and the free models declare 1,000,000 — so a long session never compacts and every turn re-sends the whole growing surface (measured: 404 K surface tokens, 205 K read back from the prompt cache per step). Capping it (e.g. 262144, the free lane's real window) makes DSH compact earlier: smaller prompts, faster first token, less quota burnt. Unset = advertise the model's own window. The advertised output limit follows this window: it is min(model limit, window / 4), because DSH's compactor reserves the request's maxTokens *inside* the window (messageBudget = contextWindow - maxTokens) and silently skips compaction when that budget is not positive. transport.proxyUrl · — · Proxy URI for the Zen lane, e.g. http://127.0.0.1:10808. Gives the lane its own dispatcher with a fresh CONNECT tunnel per request, so a proxy that silently closed the previous tunnel cannot kill the turn with UND_ERR_SOCKET / ECONNRESET. Other hosts keep the ambient dispatcher. transport.noReuse · true · Set false to keep connection reuse on the Zen lane. agentPath · auto-resolved · Sidecar only: path to the agent binary. agentArgs · — · Sidecar only: extra CLI args for the agent. restartDelayMs / restartMaxDelayMs / maxConsecutiveCrashes · 1000 / 60000 / 5 · Sidecar only: restart backoff and circuit breaker.

How it works

DSH session
   │  harness chunks (block-start / text-delta / usage / finish …)
   ▼
ZenAdapter (registered LlmAdapter)
   │  pi-ai openai-completions stream
   ▼
https://opencode.ai/zen/v1        ← Authorization: Bearer public
   with CLI-identical headers:
     user-agent: opencode/…
     x-opencode-client, x-opencode-session, x-session-affinity,
     X-Session-Id, x-opencode-request, x-opencode-project

• Session correlation — session/project ids are SHA-256 derived from the

conversation's first user turn (stable per conversation, non-reversible), and each request gets a fresh random id, mirroring the CLI.

• Catalog fallback chain — S1: live GET /v1/models; S2: models.dev

pricing metadata decides "free"; S3: a compile-time verified static list. A disk cache (~7-day TTL) covers upstream outages.

• Resilience — the adapter registers immediately at startup; if the first

catalog fetch races your network (VPN/TUN reconnects, DNS), the plugin retries on a short cadence (~1 min) before settling into the periodic refresh.

• Sidecar mode (mode: sidecar, legacy) — spawns a local Go agent (a

single-tenant port of opencode2api) on 127.0.0.1:, token-authenticated, and registers a standard llm-pi-ai route. Not part of the published package; build it from legacy/agent (go build ./cmd/agent) and point agentPath at the binary.

Gateway compatibility (Zen gate tracking)

Zen's free lane gates third-party clients and moves models between APIs without notice. Two mechanisms matter here:

• Canonical sessions (upstream) — the gateway only serves

x-opencode-session ids shaped ses_; every identity is hashed into that shape, so plain DSH conversations pass with no setup.

• Responses-only models (this fork) — muse-spark-* return a bare 500 on

/chat/completions but 200 on /responses. The adapter routes them to pi-ai openai-responses (wider 300 s body-idle watchdog for bursty reasoning); everything else stays on openai-completions.

Health & troubleshooting

The plugin writes a health snapshot after every refresh round:

~/.dsh-plugin-adapter/adapter-status.json

{
  "status": "ready",
  "total": 64,
  "exposed": 9,
  "lastError": "",
  "writtenAt": "2026-08-29T07:01:54.915Z"
}

Symptom · Likely cause & fix Boot screen shows Failed to load plugins … list slot "settings.plugin.item" requires options.id · Your DSH is too old (≤ 0.1.0-rc.6): the settings-slot contract predates the plugin 0.3.0 browser half. Upgrade DSH to ≥ 0.1.0-rc.7 (latest recommended). Plugin ≥ 0.3.1 registers in either slot shape, so on old DSH you lose at most the settings card — model routing is unaffected. Only 3 models · Startup fetch raced your network; retries land within ~1 min. Check adapter-status.json for lastError. lastError: "fetch failed" persisting · Outbound HTTPS to opencode.ai blocked; check proxy/VPN rules. Rate-limit errors in chat · The anonymous lane is quota-per-IP; switch network node or wait. 500 on muse-spark-* via chat · Responses-only model; this fork routes it to /responses automatically. 403 FreeTierError: free tier can only be used from within OpenCode · Update past 0.3.2 (canonical sessions + gate-tools body shaping); non-streaming probes always 403 — diagnose with stream:true. stream body idle timeout on reasoning models · Bursty chain-of-thought tripped the 120 s watchdog; this fork uses 300 s for Responses models. first stream event timeout · A time-to-first-token timeout, not a dead exit: the Zen lane holds the response head back until the upstream emits its first token, so a slow first answer used to be reported as a silent exit. The window is 60 s (90 s for reasoning models) and configurable via watchdog.*; the IP pool rotates the exit when one is available. Old session fails every turn, new sessions work · That conversation's session is pinned to a sick upstream replica — see gatewaySession above. 429 … "Upstream request failed: Endpoint is unavailable." · The gateway's backing model instance is down — not a quota error and not exit-specific. The adapter re-rolls the session id once (the lane pins an instance per session), which moves the request to another instance. Request timed out. · The OpenAI SDK's request bound fired before any response header. The adapter now passes an explicit bound (watchdog window + 30 s) so a wedged upstream cannot hang for the SDK's 10-minute default, and the watchdog's diagnostic message wins instead of this bare one. 400 … requires adaptive thinking; reasoning effort none is not allowed · The model refuses to stop thinking (minimax-m3.1*). Asking for off is mapped to the cheapest accepted level (low) instead of failing the turn. Connection error to 127.0.0.1:* · A stale sidecar route shadows the adapter; plugin ≥ 0.2.1 removes it at startup. Install fails with ERR_PNPM_IGNORED_BUILDS · A transitive dependency of pi-ai (@google/genai, protobufjs) has build scripts that are not needed at runtime. Approve-or-decline them via the plugin market, or set both to false under allowBuilds: in the profile's pnpm-workspace.yaml.

Security

• No secrets involved: the anonymous lane's key is the literal string public; nothing is stored, nothing telemetry.
• Install paths restricted to lib/ only; no build scripts run from dependencies.
• All requests go directly from your machine to opencode.ai / models.dev.

Development

git clone https://github.com/1624318455/dsh-plugin-adapter.git
cd dsh-plugin-adapter/packages/plugin
pnpm install
pnpm typecheck && pnpm test
pnpm build                    # bundle to lib/

The legacy Go sidecar lives in legacy/agent (go test ./...). Architecture notes and the porting record live in docs/.

Releasing: push a v* tag (the tag must equal the version in packages/plugin/package.json). The publish workflow tests on Node 22/24 and then publishes packages/plugin to npm with provenance through npm's Trusted Publisher (GitHub Actions OIDC, no long-lived token). Locally, pnpm pack in packages/plugin still works (prepack builds and syncs the docs).

Acknowledgments

• opencode2dsh by

FishBottle7 — this project is a maintained fork of it; the adapter, catalog and IP-pool design originate there.

• opencode2api by

@jasonxu114514 — the legacy Go sidecar in legacy/agent is a port of its anonymous-lane implementation, and the catalog fallback chain and request-disguise details are derived from it. This project stands on its shoulders.

• OpenCode — for running the free anonymous Zen lane.
• @earendil-works/pi-ai — the wire layer used by adapter mode.
• DeepSeek Harness and the

dsh-market community.

Friends

LinuxDo — 新的理想型社区 / a new ideal community

License

MIT © FishBottle7