@goodandready/dsh-opencode-provider 0.0.0-stage → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 0.5.0
+
+- **Parity release**: TUI settings section, Models-page key card, plan-aware Go picker, request-wide image budget and tool-schema normalization.
+- Package identity is now scoped: `@goodandready/dsh-opencode-provider` (unscoped npm name belongs to an unrelated package).
+- Custom composer cost pill and custom analytics cost columns removed; cost is shown only by DSH's native display.
+- One-click plugin update in Settings → OpenCode: registry status, badge, exact `dsh plugin add`, restart notice, loopback/same-origin POST guard.
+- English, Chinese and Russian READMEs and a visual-verification asset ship in the package and GitHub tree.
+- **Usage analytics dashboard** in the quota panel: KPI grid, 7/30/90 window, and Models / Days / Sessions tables; success/errors show `—` because the local projection does not expose failed attempts. Cost is not duplicated: DSH's native display is the only cost surface.
+- **Tool limit fix**: tools are deduplicated by name and capped at OpenCode's 128-item maximum before every transport, fixing `HTTP 400: maximum number of items is 128` in tool-heavy profiles.
+- **Test connection** button in the key card: pick a model, run a minimal real request, see latency and the reply.
+- `POST /dsh-opencode/test` Host route with a 60-second budget.
+- Sidebar quota bars now change color at 75% (warning) and 90% (critical).
+- Write routes require a literal loopback `Host` (not just a loopback socket) in addition to same-origin and JSON checks, closing DNS-rebinding key exfiltration.
+- Analytics no longer fabricates `100%` success / `0` errors; the local projection returns `null` and the UI shows `—`.
+- Go plan filtering now fails open for models that exist only in the live catalog; known Console models stay hidden.
+- Tool truncation at the 128-item provider limit logs a one-time warning instead of failing silently.
+- TUI settings refresh after `/config` account changes; analytics requests have an error state and a generation guard against the 7/30/90 race.
+- Projection analytics reads run with bounded parallelism; `.commandcode/` is ignored; provider registration logs at boot.
+- Tool-result images are replaced with an offload placeholder instead of failing the whole request in every transport.
+- Core harness tools (`read`, `write`, `edit`, `bash`, `glob`, `grep`, …) survive the 128-tool cap even when a large MCP set is present.
+- `GET /dsh-opencode/health` reports provider registration, account count and model count for startup diagnostics.
+- The TUI settings section polls live config, so accounts/allowlist changes made from the terminal refresh without a restart.
+- Client colors moved to DSH theme variables; the `zh` dictionary is a real translation; draft/route/widget helpers moved to `settings-draft.ts`, `settings-widgets.tsx`, `routes-public.ts` and `routes-values.ts`; quota triggers expose real `aria-expanded` panel state.
+- Tests grew to 84, including TUI polling, health, core-tool preservation and tool-result image placeholders.
+- Rotation now also triggers on quota/usage-limit bodies (400/402/403/429), with a 10-minute or `Retry-After` cooldown for quota rejections.
+- The last account is marked on rejection as well; account rows expose `mark`/`coolingUntil`, show a cooldown badge, and the active marker follows the first non-cooling key.
+- Per-account quota reads: `/state.accounts[].usage` is fetched for each distinct key (`UsageReader` caches per key), the active account drives the sidebar and quota panel, Accounts rows show 5h/week/month chips, and the panel has an accounts table. Verified live: `default` 1/5/2 and `Go #2` 9/4/100 with `rate-limited` monthly until 22 Oct 08:21.
+- Request heatmap (Monday-first weekday × local hour) in the quota panel. The adapter appends `{at, provider, model, purpose?}` to `~/.dsh/storages/dsh-opencode/requests.jsonl` and `/analytics` merges the aggregate; prompts, responses and keys are never stored. Live: two `/test` calls produced `Tue 13:00 = 2`.
+- Heatmap accuracy: `session-title` / `compaction` calls are excluded and exact duplicate records collapse. Live after two real chat messages: analytics shows 2 OpenCode sessions (`deepseek-v4.1-flash` ≈$0.00079, `beam-free` Free), while the heatmap counts 6 main requests instead of 8 raw records.
+- A 24-hour aggregate strip under the heatmap sums the selected window by hour across all days; its bars use the same intensity scale and tooltips.
+- Per-model heatmap: `/analytics` returns a `models[]` series (provider/model, total, hours, grid), and the panel offers an **All models / model** selector when more than one model has traffic. Live: `deepseek-v4.1-flash` 2, `minimax-m3.1-flash-free` 1.
+- Account cooldowns persist across restarts in `~/.dsh/storages/dsh-opencode/cooldowns.json`, keyed by a SHA-256 fingerprint (raw keys are never written). Expired entries are dropped and the file is capped at 50. Live: after a restart, `Go #2` kept its `quota` mark until 22 Oct 08:21 while the restored default key was active.
+- Model → account rules: first matching glob (case-insensitive `*`/`?`) pins a preferred account for that model, with the other accounts kept as fallbacks. Config is normalized and exposed through `/state`; Settings has an editor. Live: `*free* → Go #2` round-tripped through `/config` and `/state`, then cleared.
+- Sidebar quota card redesigned to match the clinebot meter: theme-native ring, active account name, highest-window percent, and 5-hour / weekly / monthly rows with remaining quota, reset countdown and thin bars. Uses DSH CSS variables and has a narrow rail variant. The header percentage is right-aligned with the row values.
+- Quota panel now has its own vertical scroll (`height: 100%`, viewport max-height, `overflow-y: auto`), so content below the fold is reachable; verified in Desktop by opening the panel and scrolling to **Usage by model**.
+- Quota panel polish: the badge now says **Active account** (not "Pinned account" when `activeAccount` is empty), Accounts rows show persisted cooldown / provider rate-limit badges (for example `Quota cooldown · 2d`), and the 5-hour/weekly/monthly bars show date+time with a relative reset (`1% · 20.10, 17:11 (2h)`).
+- `/opencode` gained `accounts`, `models`, `rules` and `test [model]`; `status` now includes per-account quotas and rules.
+- Request log compaction at 2 MB (newest 5000 lines) and a `npm run check` / `npm run release` workflow plus GitHub Actions CI (`typecheck`, tests, build, pack).
+- Live-verified two-account rotation in DSH Desktop: with an invalid default key, `/test` switched to `Go #2` and returned `OK`. A later run found `Go #2` at its monthly limit (98% before the tests) and showed `quota` with the provider's reset.
+- `GET /dsh-opencode/analytics` and the **Usage by model** table in the quota panel (7/30/90 days). It aggregates only numeric metadata from the local session projection cache; a session is attributed to its last-used model.
+- Verified live in DSH Desktop 0.2.1-rc.2; install there from the packed tarball (a directory path triggers the Desktop CLI's `dsh-desktop-runtime` alias bug).
+
+## 0.4.1
+
+- Accounts card can set each account's key from the page; unconfigured accounts are listed with a missing-key badge.
+- Live catalog refresh button (`POST /dsh-opencode/models/refresh`).
+- Quota warning banners at 80% and 95% in the settings page.
+- Expandable subscription-limits table: per model, Go and Go Plus monthly allowance plus 5h/week/month request estimates.
+
+## 0.4.0
+
+- Per-model OpenCode Go subscription limits: monthly dollar allowance and estimated requests for the 5-hour, weekly and monthly windows, for Go and Go Plus.
+- Limits appear in the model picker description and as a badge in the settings model list; hovering shows both plans.
+- Added `src/subscription-limits.ts` with the official table and formatting helpers.
+- Tests: limits table integrity, formatting, and route-gated model descriptions.
+
+## 0.3.1
+
+- Composer session-cost estimate (`≈`/`≥`/`Free`) from the generated price snapshot and the `tokenUsage`/`modelSelection` projections.
+- Model price badges in the settings page; model picker descriptions now include per-1M input/output rates.
+- OpenCode auth-entry autocomplete from the entries actually present in `auth.json`.
+- Broadened live tool-loop coverage (Grok, Muse, Qwen).
+
+## 0.3.0
+
+- Browser settings page (`Settings → OpenCode`): key management, quota bars, accounts, model allowlist, per-model transport overrides, connection settings.
+- Sidebar quota card (opt-in) and the center-column quota panel.
+- Host HTTP routes under `/dsh-opencode/*` with same-origin enforcement.
+- Key import from OpenCode's `auth.json` through the credentials seam.
+- Client bundle built as a `window.__ModuleLoader__` module with React externalized.
+
+## 0.2.0
+
+- Native Anthropic Messages transport (thinking blocks, signatures, tool use).
+- Native OpenAI Responses transport.
+- Native Google Generative AI transport with `thoughtSignature` replay.
+- Image input on every transport, through `ctx.attachments.readImageRequest`.
+- Multi-account pool with pre-stream 401/403/429 rotation and per-key cooldowns.
+- `/opencode` command with status and quota windows.
+- Reasoning-effort mapping and output caps.
+- Expanded unit tests and live smoke scripts.
+
+## 0.1.0
+
+- Initial P1 skeleton.
+- Registers `opencode` and `opencode-go` routes on the dsh `llm` service.
+- OpenAI Chat transport over the Go unified gateway.
+- Stable `x-opencode-session` derived from the durable session id.
+- Key resolution from config, the credential seam, OpenCode `auth.json`, and the launch environment.
+- Live model catalog with a generated `models.dev` fallback.
+- Text, reasoning, streamed tool calls, usage, and classified provider errors.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-opencode-provider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,15 @@
+dsh-opencode-provider
+=====================
+
+This project is an unofficial community integration. It is not affiliated
+with OpenCode, Anomaly, or DeepSeek Harness.
+
+Architectural ideas and wire-contract research were informed by these MIT
+projects:
+
+- dsh-commandcode-provider — https://github.com/Mars-Sea/dsh-commandcode-provider
+- dsh-clinebot — https://github.com/GooDAnDReaDY/dsh-clinebot
+- opencode2dsh — https://github.com/FishBottle7/opencode2dsh (reference for the
+  anonymous free-lane header requirements; that bypass is not implemented here)
+
+Model metadata is generated from https://models.dev.

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# @goodandready/dsh-opencode-provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenCode / OpenCode Go provider plugin for [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) (dsh).
+
+It registers two native LLM routes:
+
+| Route | Product | Base |
+|---|---|---|
+| `opencode` | OpenCode Console / Zen (pay-as-you-go) | `https://opencode.ai/inference` |
+| `opencode-go` | OpenCode Go / Go Plus subscription | `https://opencode.ai/inference/go` |
+
+Requests resolve the key per call, so a changed credential reaches the next request without a restart.
+
+## What works
+
+- **Four wire transports**, chosen per model:
+  - OpenAI Chat Completions (DeepSeek, GLM, Kimi, MiMo, LongCat, Hy3, Step, …).
+  - Anthropic Messages (Claude Haiku, MiniMax, Qwen).
+  - OpenAI Responses (GPT, Grok, Muse).
+  - Google Generative AI (Gemini).
+- **Text, reasoning, streamed tool calls, usage, finish reasons.**
+- **Images** through the durable attachment service, rendered natively per transport.
+- **Replay of provider metadata** where the endpoint requires it:
+  - Anthropic thinking signatures.
+  - Gemini `thoughtSignature` on historical function calls.
+- **Multi-account rotation** before a stream starts: 401/403/429 and quota/usage-limit bodies (400/402/403/429). An invalid key cools down for 24h, a quota rejection for 10 minutes or `Retry-After`, a rate limit for 60s or `Retry-After`. A request already streaming is never replayed on another account; the next request uses the next usable key.
+- **Per-account quotas**: each account row shows its own 5-hour / weekly / monthly usage, the active account drives the sidebar and quota panel, and the panel lists every account side by side.
+- **Model → account rules**: first matching glob pins a preferred account for that model; the other accounts remain fallbacks if it fails or is cooling.
+- **Request heatmap** in the quota panel: a Monday-first weekday × hour grid in local time, plus a 24-hour aggregate strip underneath. A selector switches between all requests and any single model. The adapter appends `{at, provider, model, purpose?}` to `~/.dsh/storages/dsh-opencode/requests.jsonl`; no prompt, response or key is stored. Auxiliary `session-title`/`compaction` calls are excluded from the heatmap and exact duplicate records collapse. The log compacts at 2 MB to the newest 5000 lines. Collection starts with this build — the projection cache only has `lastPromptAt`, not per-request timestamps.
+- **Stable `x-opencode-session`** derived from the durable session id, so retries and every turn of a conversation reuse the same routing key.
+- **Live catalog** from `/v1/models` with a generated `models.dev` fallback.
+- **Per-model subscription limits** from the OpenCode Go pricing table: monthly dollar allowance plus estimated requests for the 5-hour, weekly and monthly windows, for both Go and Go Plus. Shown in the model picker and the settings page; estimates only — the gateway remains the authority.
+- **`/opencode` command** for status, usage, accounts, models, rules, and `test [model]`.
+- **TUI settings section** for the terminal profile (`/settings → OpenCode`) with the key, endpoints, allowlist, active account and timeouts.
+- **Models-page key card** in Settings → Models.
+- **One-click plugin update** in Settings → OpenCode: current/latest version, an update badge, and an **Update now** button that installs the exact npm version through the DSH CLI and asks for a restart. The host endpoint is `GET/POST /dsh-opencode/update`.
+- **Plan-aware Go picker**: hides models outside the Go table unless turned off; descriptions carry `Go`, `Console` or `FREE`.
+- **Request-wide image budget** (newest images win, oldest become an omitted placeholder) and **object-root tool-schema normalization** for MCP/third-party tools.
+- **Usage analytics dashboard** in the quota panel: KPI cards (requests, tokens, success, input/output, reasoning, cache, TTFT, latency, errors), a 7/30/90 selector, and Models / Days / Sessions tables. Success and error cards show `—`: the local projection does not expose failed attempts or reasoning tokens.
+- **Usage by model** from the local session projection cache: sessions and tokens per OpenCode model. Only numeric metadata is read; titles and message content stay local.
+- **Browser UI**:
+  - **Settings → OpenCode**: key status, paste/import/clear, quota bars, accounts, model allowlist, per-model transport overrides, connection settings.
+  - **Sidebar quota card** (off by default): a ring with the active account and the highest window, then 5-hour / weekly / monthly rows with remaining quota, reset countdown and bars; clicking opens the full quota panel in the center column. The panel scrolls internally, so the heatmap and usage table below the fold stay reachable.
+  - **Cost** is shown only by DSH's native cost display; the plugin does not add a second composer pill.
+  - Model price badges in the settings page; the OpenCode auth-entry field autocompletes from `auth.json`.
+  - Host routes under `/dsh-opencode/*` serve state and accept writes only from a loopback Host with same-origin and JSON checks; `GET /dsh-opencode/health` reports provider registration, accounts and model count.
+  - The provider keeps core harness tools (`read`, `write`, `edit`, `bash`, `glob`, `grep`, …) when a large MCP set is trimmed to OpenCode's 128-tool limit.
+
+## Install
+
+Build and pack first:
+
+```bash
+npm install
+npm run build
+npm pack
+```
+
+Install the **packed tarball** into a profile:
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.0.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.0.tgz
+
+# Or install the published package:
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.0
+```
+
+Restart dsh (or DSH Desktop), then pick `OpenCode` or `OpenCode Go` in the model picker.
+
+> **Use the tarball, not the directory.** On dsh 0.2.1-rc.2 the Desktop CLI aliases a local
+> directory passed to `dsh plugin add` as `@deepseek-ai/dsh-desktop-runtime` and overwrites
+> the target's `package.json`. Installing the packed `.tgz` avoids that path and installs
+> the package under its real name.
+
+## Verified in DSH Desktop
+
+Tested against DSH Desktop **0.2.1-rc.2**:
+
+- the plugin loads and `/dsh-opencode/state` returns `200`;
+- the key is picked up from `~/.local/share/opencode/auth.json`;
+- the live catalog returned 37 models with prices and Go limits;
+- quota windows returned `rolling / weekly / monthly`;
+- `/dsh-opencode/analytics` scanned 7 local sessions (0 OpenCode sessions yet, as expected before the first OpenCode chat);
+- `/dsh-opencode/test` against `deepseek-v4.1-flash` returned `{"ok":true,"text":"OK"}`;
+- a second Go account was added, the default key was temporarily replaced with an invalid one, and `/test` rotated to the second account and still returned `OK`;
+- the second account was already at ~98% of its monthly allowance; the rotation test pushed it over, so a later run surfaced `QUOTA`, marked the default as `invalid-credential` and `Go #2` as `quota` until its reset (22 Oct 08:21), with no active account;
+- per-account usage returned `default` 1% / 5% / 2% and `Go #2` 9% / 4% / **100%** monthly (`rate-limited`, reset 22 Oct 08:21), so the exhausted account is visible without a failed request;
+- two `/test` requests produced `Tue 13:00 = 2` in the heatmap and two lines in `requests.jsonl`; the 24-hour strip shows the same value at 13:00;
+- a third request with `minimax-m3.1-flash-free` added a second per-model series (`deepseek-v4.1-flash` 2, `minimax-m3.1-flash-free` 1), so the model selector is populated;
+- after restarting Desktop, `Go #2` still showed its persisted `quota` cooldown (until 22 Oct 08:21) while the restored default key was active;
+- setting `*free* → Go #2` through `/config` returned the normalized rule from `/state`, and clearing it returned `[]`; the account list stayed unchanged;
+- the redesigned sidebar card was checked in Desktop: `OpenCode Go` with a 5% ring, `5-Hour Window 99% remaining · 3h`, `Weekly Window 95% remaining · 6d`, `Monthly Window 98% remaining · 29d`; it uses the DSH theme variables and matches the clinebot meter's row/ring layout;
+- a real chat produced two OpenCode sessions: `deepseek-v4.1-flash` (4105 in / 243 out, ≈$0.00079) and `beam-free` (10670 in / 171 out, Free); the heatmap counted 6 main requests (the two title calls and exact duplicates are filtered);
+- the renderer loaded the client bundle (`settings.opencode` is present in its code cache).
+
+Open **Settings → OpenCode** and enable *Show the quota card in the sidebar* if you want the
+sidebar meter.
+
+## Configure
+
+```yaml
+- id: llm-opencode
+  name: "@goodandready/dsh-opencode-provider"
+  config:
+    apiKeyEnv: OPENCODE_API_KEY   # default
+    # apiKey: oc_sk_...           # composition only, never commit
+    openCodeAuthEntry: opencode-go
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    modelTransports: {}
+    # contextWindowOverrides: { deepseek-v4-pro: 65536 }
+    # maxOutputTokens: 32768
+    accounts:
+      - label: Go #2
+        apiKeyEnv: OPENCODE_API_KEY_2
+    activeAccount: ''            # label or credential name to pin
+```
+
+Every field except `apiKey` is volatile and appears in dsh settings.
+
+### Keys
+
+1. `config.apiKey` (composition only, `role('secret')`).
+2. The dsh credential seam under `apiKeyEnv`.
+3. `~/.local/share/opencode/auth.json` → entry `openCodeAuthEntry` (default `opencode-go`), written by OpenCode's own `/connect`.
+4. The launch environment (process, project `.env`, `$DSH_HOME/.env`).
+
+Extra `accounts` resolve the same way (literal key or credential reference). If you already use OpenCode, the plugin picks up the stored Go key automatically.
+
+### Accounts and rotation
+
+Add a second account in **Settings → OpenCode → Accounts**: give it a name and a credential reference (for example `OPENCODE_API_KEY_2`), paste its key, then Save. The default account (the key card at the top) always serves first unless `activeAccount` pins another one.
+
+Rotation happens **before any content is streamed**. When the serving key is rejected with an invalid credential, a rate limit, or an exhausted quota, the adapter marks that key and retries the same request with the next usable account. An exhausted pinned account still falls back to the others; it returns to service once its cooldown passes. A request that has already started streaming is not replayed on another account.
+
+Each account row shows the current cooldown (`Invalid key`, `Quota cooldown · 23h`, `Rate limited · 30s`) and its own quota chips. The active marker moves to the first account that is not cooling down. The last account is marked too, so a failed turn explains which key ended it. Quota cooldowns honor the provider's reset (`Retry-After`) when present. The quota panel repeats the numbers in an accounts table, and the sidebar meter uses the active account.
+
+Cooldowns survive restarts: deadlines and reasons are stored in `~/.dsh/storages/dsh-opencode/cooldowns.json` keyed by a SHA-256 fingerprint — raw keys are never written. Expired entries are dropped on load, and the file keeps at most 50 entries.
+
+### Model → account rules
+
+Pin a model to a preferred account with a glob. The first matching rule wins; `*` and `?` are supported and matching is case-insensitive. The named account is tried first, and the other accounts remain fallbacks if it is cooling, missing, or rejected — a rule is a preference, not a hard filter. An unknown account label is ignored, and rules apply to both `opencode` and `opencode-go`.
+
+Configure them in **Settings → OpenCode → Model → account rules**, or in YAML:
+
+```yaml
+modelAccountRules:
+  - pattern: "*free*"
+    account: "free"
+  - pattern: "deepseek-*"
+    account: "go"
+```
+
+The account label is the same one shown in **Accounts** (`default` or the extra account's name).
+
+### Request heatmap
+
+The quota panel has a **Request heatmap**: rows are Monday–Sunday, columns are local-time hours, and each cell counts calls made through this adapter (including tool-loop steps and `Test connection`). Auxiliary `session-title` and `compaction` calls are excluded, and exact duplicate records collapse; tool-loop steps are separate adapter requests, so one chat message is not necessarily one cell. Hover a cell to see the exact count. A 24-hour strip below the grid aggregates the same window by hour across all days, so the daily shape stays readable even when the grid is sparse. When more than one model has traffic, a selector switches the grid and strip to a single model; each option shows its total. The data is append-only metadata in `~/.dsh/storages/dsh-opencode/requests.jsonl`; it never includes prompts, responses or keys. Because the local projection cache stores only the last prompt time per session, the heatmap starts collecting with this build and grows as you use the plugin.
+
+## Settings page
+
+Open **Settings → OpenCode**:
+
+- **Key** — status, paste a new key, import the key OpenCode already stored, clear it, or run a **Test connection** against a chosen model and see the latency and reply.
+- **Quota** — 5-hour, weekly and monthly bars with reset dates, plus warning banners at 80% and 95%.
+- **Accounts** — add extra accounts by credential reference, set each account's key from the page, see whether it is configured, pin one, or return to automatic rotation.
+- **Models** — search, refresh the live catalog, uncheck models to build an allowlist, override the wire transport per model, and see each model's input/output price plus its Go request estimate (`Go 34.7K/5h`). Hover the estimate for the full Go / Go Plus monthly allowance and 5h/week/month request counts; expand **Subscription limits** for a table of every model with both plans.
+- **Connection** — API bases, usage endpoint, timeouts, output cap, context override, sidebar-card switch. The OpenCode auth-entry field autocompletes from the keys present in `auth.json`.
+- **Plugin update** — current/latest version, update badge, and **Update now**. It installs the exact registry version through the normal `dsh plugin add` path, blocks a second click while installing, and reports when DSH must be restarted.
+
+The sidebar quota card is **off by default**. Enable *Show the quota card in the sidebar* in the settings page; clicking the card opens the full quota panel, which also carries the **Usage by model** table (7/30/90-day window).
+
+The Host serves `/dsh-opencode/state`, `/health`, `/analytics`, `/config`, `/key`, `/key/clear`, `/auth-import`, `/refresh`, `/models/refresh`, `/test` and `/update`. Writes require JSON, are refused for cross-origin requests, and are restricted to loopback (`127.0.0.1` / `::1`); reads stay same-origin. This keeps key and configuration writes off a LAN-exposed web server until the host's own auth token can be integrated.
+
+## Updates
+
+The **Plugin update** card in Settings → OpenCode calls `GET /dsh-opencode/update`, which compares the installed `package.json` with the npm registry. When a newer version exists, **Update now** sends the same-origin request with `x-dsh-plugin-update: 1`; the Host runs the normal DSH CLI:
+
+```text
+dsh plugin --profile <profile> add --config.minimumReleaseAge=0 @goodandready/dsh-opencode-provider@<exact-version>
+```
+
+The update is blocked while another update is running, never uses `--force`, and never installs from a worktree or a `file:` path. The card reports that DSH must be restarted after a successful install. If the runtime does not expose the CLI entry, the card says that automatic update is unavailable and points to the DSH plugin manager; the status check still works.
+
+## Visual verification
+
+![OpenCode quota and analytics panel](media/visual-verification.png)
+
+Captured from the exact 0.5.0 release candidate in DSH Desktop in the dark theme.
+
+## Command
+
+```
+/opencode status            # accounts, per-account quotas, rules
+/opencode usage             # quota windows only
+/opencode accounts          # labels, source, active/cooling, 5h/wk/mo
+/opencode models            # ids, FREE/Go limits
+/opencode rules             # model → account rules
+/opencode test [model]      # minimal real request (default deepseek-v4.1-flash)
+```
+
+Example:
+
+```
+OpenCode provider
+- opencode-go: 1 account(s) · auth.json:opencode-go
+- opencode: 1 account(s) · auth.json:opencode-go
+5h     : [░░░░░░░░░░] 1% · resets 2026-10-19 22:05Z
+weekly : [░░░░░░░░░░] 1% · resets 2026-10-26 00:00Z
+monthly: [░░░░░░░░░░] 0% · resets 2026-11-18 13:38Z
+Auth: opencode-go · OPENCODE_API_KEY
+```
+
+## Verified API facts
+
+- `GET /inference/go/v1/models` is public and returns the live Go roster.
+- `GET /zen/go/v1/usage` returns `rolling` (5h), `weekly`, `monthly` with `percent` and `resetsAt`. It is undocumented; the plugin treats it as fail-open.
+- The unified `POST /zen/go/v1/chat/completions` accepts OpenAI-compatible **and** Anthropic-backed models, but **not** Responses-only or Google models.
+- Responses-only models (GPT, Grok, Muse) and Gemini need their native endpoints, which the plugin uses.
+- Gemini 4 requires replaying `thoughtSignature` on historical function calls; the Google transport stores it in dsh's replay state.
+- `x-opencode-session` is mandatory. A stable opaque value is enough for a Go key; the canonical `ses_*` shape and CLI impersonation are only needed for the anonymous free lane, which this plugin deliberately does not implement.
+- Free-tier anonymous keys are rejected with `403 FreeTierError`; free models work normally with an active Go subscription.
+
+## Development
+
+```bash
+npm run typecheck
+npm run build
+npm test
+npm run check         # typecheck + tests + build
+npm run release       # check + packed tarball
+npm run sync:models   # regenerate src/models.generated.ts from models.dev
+```
+
+GitHub Actions runs `npm run check` and `npm pack` on push/PR (`.github/workflows/ci.yml`).
+
+Live smoke scripts (read your Go key from `auth.json`; no key is stored):
+
+```bash
+node scripts/smoke.mjs                 # OpenAI Chat text/reasoning/usage
+node scripts/smoke-tools.mjs           # OpenAI Chat tool call
+node scripts/smoke-transports.mjs      # all four transports, text
+node scripts/smoke-transport-tools.mjs # all four transports, tool call
+node scripts/smoke-tool-loop.mjs       # full tool loop, including Gemini replay
+node scripts/smoke-images.mjs          # vision on all four transports
+node scripts/smoke-rotation.mjs        # invalid key → valid key rotation
+node scripts/smoke-command.mjs         # /opencode output
+node scripts/smoke-client.mjs          # client bundle loader + slot registration
+```
+
+## Limitations
+
+- Verbatim file attachments are not forwarded yet; images are.
+- The usage endpoint is unofficial and may change; chat never depends on it.
+- Cost is displayed only by DSH's native cost display; this plugin has no second composer cost pill.
+- Automatic update requires the DSH CLI entry in the runtime. When it is not exposed, the update card shows the current/latest status and directs the user to the DSH plugin manager.
+- Subscription request counts are OpenCode's published estimates, not enforced quotas. They can change when OpenCode updates the Go pricing table; the gateway is the final authority.
+- Usage-by-model aggregates the local projection cache and attributes a whole session to its last-used model; a session that switched models is therefore approximate. It never reads prompt text or titles.
+- `opencode` (Console) billing shows no per-model allowance; the Go route is the primary target.
+- The anonymous free lane (`Bearer public` + CLI impersonation) is not implemented.
+- The UI requires a web profile (the Host needs `ctx.webServer`); the TUI keeps the `/opencode` command and the model routes.
+- Write routes are loopback-only; a web profile exposed to a LAN can read state but cannot save configuration or keys until the host auth token is integrated.
+
+## License
+
+MIT. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/README.ru.md

@@ -0,0 +1,87 @@
+# @goodandready/dsh-opencode-provider
+
+Плагин-провайдер OpenCode / OpenCode Go для [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) (dsh).
+
+Плагин регистрирует два нативных LLM-маршрута:
+
+| Маршрут | Продукт | База |
+|---|---|---|
+| `opencode` | OpenCode Console / Zen (pay-as-you-go) | `https://opencode.ai/inference` |
+| `opencode-go` | OpenCode Go / Go Plus | `https://opencode.ai/inference/go` |
+
+Ключ разрешается на каждый запрос, поэтому смена credential применяется без перезапуска.
+
+## Возможности
+
+- Четыре транспорта: OpenAI Chat, OpenAI Responses, Anthropic, Google; выбор по модели.
+- Живой каталог `/v1/models` с резервным generated-каталогом models.dev.
+- Оценки лимитов Go и Go Plus для 5 часов / недели / месяца.
+- Plan-aware picker (Go / Console / FREE).
+- Пул аккаунтов: ротация на 401/403/429 и исчерпанной квоте; cooldown хранится по fingerprint ключа.
+- Health аккаунтов, квоты по каждому аккаунту, правила «модель → аккаунт».
+- Аналитика использования, heatmap запросов, таблицы Models / Days / Sessions.
+- Core-инструменты сохраняются при лимите 128; изображения в tool-result заменяются placeholder.
+- One-click обновление плагина в Settings → OpenCode.
+
+## Установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.0
+# DSH Desktop:
+dsh plugin --profile desktop add @goodandready/dsh-opencode-provider@0.5.0
+```
+
+Либо из упакованного файла:
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.0.tgz
+```
+
+После установки перезапустите dsh / DSH Desktop и выберите **OpenCode** или **OpenCode Go** в picker.
+
+## Настройка
+
+Ключ берётся из DSH credentials, `OPENCODE_API_KEY` или `~/.local/share/opencode/auth.json`. В Settings → OpenCode можно вставить, импортировать или очистить ключ и выполнить **Test connection**.
+
+Аккаунт `default` используется первым; дополнительные аккаунты служат fallback. `modelAccountRules` использует регистронезависимые `*` / `?` glob: первое совпадение задаёт предпочтительный аккаунт, остальные остаются fallback.
+
+Go-маршрут показывает оценки лимитов на 5 часов, неделю и месяц, включая месячный долларовый allowance. Шлюз остаётся источником истины; значения в плагине — оценки.
+
+## Квоты и аналитика
+
+Карточка квоты в sidebar по умолчанию выключена; включите её в Settings → OpenCode. По клику открывается панель с аккаунтами, остатками 5h/неделя/месяц, временем сброса, аналитикой и heatmap запросов.
+
+Heatmap агрегирует реальные вызовы адаптера по локальному времени, исключает `session-title` и `compaction`, а точные дубликаты схлопывает. Данные пишутся только в `~/.dsh/storages/dsh-opencode/requests.jsonl`; промптов, ответов и ключей там нет. Стоимость показывает только встроенный DSH; второй composer-пилюли плагин не добавляет.
+
+## Обновление плагина
+
+Карточка **Plugin update** в Settings → OpenCode:
+
+1. `GET /dsh-opencode/update` сравнивает установленную версию с npm registry.
+2. При наличии новой версии показывает badge и **Update now**.
+3. Кнопка ставит точную версию через обычный `dsh plugin add`; параллельная установка блокируется, `--force` не используется, установка из worktree или `file:` запрещена.
+4. После успеха карточка просит перезапустить DSH.
+
+Если runtime не предоставляет DSH CLI, карточка сообщает, что автообновление недоступно, и направляет в plugin manager; проверка версии продолжает работать.
+
+## Безопасность
+
+- Write-маршруты требуют JSON, same-origin и literal loopback Host (`127.0.0.1` / `::1`) — это блокирует DNS rebinding.
+- POST обновления дополнительно требует loopback, same-origin и `x-dsh-plugin-update: 1`.
+- Ключ не возвращается из `/state` и не пишется в логи.
+- Тело записи ограничено 256 KiB; request log хранит только `{at, provider, model, purpose}`.
+
+## Совместимость
+
+Проверено на DSH **0.2.1-rc.2**. UI требует web profile (Host нужен `ctx.webServer`); в TUI остаются команда `/opencode` и модельные маршруты.
+
+## Ограничения
+
+- Файловые вложения пока не передаются; изображения поддерживаются.
+- Официальный usage endpoint неофициальный и может измениться; чат от него не зависит.
+- Автообновление требует DSH CLI в runtime; иначе используйте DSH plugin manager.
+- Анонимный free lane (`Bearer public` + CLI impersonation) не реализован.
+
+## License
+
+MIT. См. `LICENSE` и `NOTICE`.

package/README.zh.md

@@ -0,0 +1,87 @@
+# @goodandready/dsh-opencode-provider
+
+面向 [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/)（dsh）的 OpenCode / OpenCode Go 提供商插件。
+
+插件注册两个原生 LLM 路由：
+
+| 路由 | 产品 | 基础地址 |
+|---|---|---|
+| `opencode` | OpenCode Console / Zen（按量付费） | `https://opencode.ai/inference` |
+| `opencode-go` | OpenCode Go / Go Plus 订阅 | `https://opencode.ai/inference/go` |
+
+密钥在每次请求时解析，因此更换凭据后无需重启即可生效。
+
+## 功能
+
+- 支持 OpenAI Chat、OpenAI Responses、Anthropic 和 Google 四种传输，可按模型选择。
+- 从 `/v1/models` 读取实时目录，并有 models.dev 生成目录作为回退。
+- Go 与 Go Plus 的 5 小时 / 每周 / 每月订阅额度估算。
+- 计划感知的模型选择器（Go / Console / FREE）。
+- 多账户轮换：401/403/429 或配额耗尽时切换到下一个账户；冷却按密钥指纹持久化。
+- 账户健康、每账户配额、模型 → 账户规则。
+- 用量分析面板、请求热力图、Models / Days / Sessions 表。
+- 核心工具在 128 个工具上限内优先保留；工具结果图片转为占位符。
+- Settings → OpenCode 中的一键插件更新。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.0
+# DSH Desktop:
+dsh plugin --profile desktop add @goodandready/dsh-opencode-provider@0.5.0
+```
+
+也可以安装打包文件：
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.0.tgz
+```
+
+安装后重启 dsh / DSH Desktop，在模型选择器中选择 **OpenCode** 或 **OpenCode Go**。
+
+## 配置
+
+密钥来自 DSH 凭据服务、`OPENCODE_API_KEY` 或 `~/.local/share/opencode/auth.json`。Settings → OpenCode 可以粘贴、导入、清除密钥，并运行 **Test connection**。
+
+默认账户优先使用；额外账户按顺序作为回退。账户可按 credential reference 配置。`modelAccountRules` 使用大小写不敏感的 `*` / `?` glob，把匹配模型优先路由到指定账户，其余账户仍作为回退。
+
+Go 路由使用配额表：5 小时、每周、每月窗口，以及每月美元额度。网关仍是最终权威；插件中的请求数是估算值。
+
+## 配额和分析
+
+侧边栏配额卡默认关闭，可在 Settings → OpenCode 打开。点击卡片打开完整面板，显示账户、5h/周/月剩余额度、重置时间、用量分析和请求热力图。
+
+热力图按本地时间聚合真实适配器请求，排除 `session-title` 和 `compaction`，精确重复记录会折叠。数据只写到 `~/.dsh/storages/dsh-opencode/requests.jsonl`，不包含提示词、响应或密钥。成本由 DSH 原生成本显示提供，本插件不添加第二个 composer 成本胶囊。
+
+## 插件更新
+
+Settings → OpenCode 的 **Plugin update** 卡片：
+
+1. `GET /dsh-opencode/update` 比较已安装版本与 npm registry。
+2. 有更新时显示徽章和 **Update now**。
+3. 点击后通过正常的 `dsh plugin add` 安装精确版本；并发安装会被拒绝，不使用 `--force`，不会从 worktree 或 `file:` 安装。
+4. 成功后提示重启 DSH。
+
+如果运行时没有暴露 DSH CLI，卡片会说明自动更新不可用，并指向 DSH 插件管理器；状态检查仍然可用。
+
+## 安全
+
+- 写入路由要求 JSON、同源和 literal loopback Host（`127.0.0.1` / `::1`），阻止 DNS rebinding。
+- 更新 POST 额外要求 loopback、同源和 `x-dsh-plugin-update: 1`。
+- 密钥不会从 `/state` 返回，也不会写入日志。
+- 写入请求体上限 256 KiB；请求日志只保存 `{at, provider, model, purpose}`。
+
+## 兼容性
+
+已针对 DSH **0.2.1-rc.2** 验证。UI 需要 web profile（Host 需要 `ctx.webServer`）；TUI 保留 `/opencode` 命令和模型路由。
+
+## 限制
+
+- 文件附件暂不转发；图片支持。
+- 官方用量端点是非官方的，可能变化；聊天不依赖它。
+- 自动更新需要运行时提供 DSH CLI；否则使用 DSH 插件管理器。
+- 匿名免费通道（`Bearer public` + CLI 伪装）未实现。
+
+## License
+
+MIT。见 `LICENSE` 和 `NOTICE`。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-opencode-provider bundle layer.
+# Registers the `opencode` (Console/Zen) and `opencode-go` (Go subscription)
+# provider routes. All fields are optional — schema defaults apply.
+#
+# `name` must be the FULL package specifier as installed in the profile's
+# node_modules. Quote it: an unquoted YAML scalar starting with `@` fails.
+- insert:
+    - id: llm-opencode
+      name: "@goodandready/dsh-opencode-provider"
+      config:
+        apiKeyEnv: OPENCODE_API_KEY