@justsilver/opencode-providers 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+本项目所有值得注意的变更都记录在此文件。
+
+格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.1.0-beta.0] - 2026-10-07
+
+> 首个**预发布**版本：先发到 npm 的 `next` dist-tag 试装，稳定后再发 `latest`。
+> 装上后不需要写 `opencode.json`，在 `/connect-providers` 里贴一次 API Key 即可用。
+
+### Added
+
+- `registry.json` + `registry.schema.json`：自维护供应商注册表（共享 `models` 表 + provider `base` 引用 + 覆盖），带 `schemaVersion`
+- server 入口 `plugin/opencode-providers/index.ts`：拉注册表（6h TTL + `ETag` + 失败沿用旧缓存）→ 注册 integration（`key`）与 provider（`activation: "auto"`）及其模型；**不 import 任何 `@opencode/*`**
+- TUI 入口 `plugin/opencode-providers/tui.ts` + `view/connect.ts`：`/connect-providers` 命令（选供应商 → 贴 API Key / 切换账号），与内置 `/connect` 共用同一张凭据表。**无 JSX、不依赖 Solid**，因此 npm / 配置安装不会踩「双 Solid 运行时」
+- `registry/` 纯逻辑：schema 校验 / `Model.Info` 映射 / 拉取缓存；`node --test` 覆盖（含「随仓注册表能通过校验」）
+- `package.json`：npm 包形态（`type: module`；`exports["./server"]` / `["./tui"]`；`files` 白名单；`publishConfig.tag = next`），可 `"plugins": ["@justsilver/opencode-providers"]` 配置安装
+- `install.sh` / `install.ps1` / `uninstall.sh` / `uninstall.ps1`：脚本安装（最新 Release 优先、回退 `main`、同文件系统原子替换）；`--local` / `-Local` 从工作树部署
+- `.github/workflows/ci.yml`（跑 `node --test` + 版本一致性）与 `release.yml`（tag 触发；预发布发 `next`，正式版必须手动勾选才发 `latest`；Release 内容取自本文件）
+
+### Changed
+
+- 插件源码从 `.opencode/plugins/opencode-providers/` 移到 `plugin/opencode-providers/`：仓库自身不再是插件发现根，避免在仓库里跑 opencode 时与全局安装的同 id 副本相撞（`Duplicate plugin ID` → 面板里一条 `failed`）
+- 安装后**通常无需重启**（插件目录被文件监视热重载），不再要求 `opencode service restart`
+
+[Unreleased]: https://github.com/Just-Silver/opencode-providers/compare/v0.1.0-beta.0...HEAD
+[0.1.0-beta.0]: https://github.com/Just-Silver/opencode-providers/releases/tag/v0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Just-Silver
+
+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/README.md

@@ -0,0 +1,208 @@
+# opencode-providers
+
+给 [OpenCode](https://opencode.ai) 补上**模型目录里没有的供应商**：一份自维护的注册表 + 一个插件。
+装完插件、在 `/connect-providers` 里贴一次 API Key 就能用 —— **不需要写 `opencode.json`**。
+
+```
+registry.json                    ← 唯一事实源：供应商 + 模型 + 参数（GitHub raw 托管）
+registry.schema.json             ← 给编辑器校验 registry.json
+plugin/opencode-providers/       ← 插件源码（安装时整目录复制到 ~/.config/opencode/plugins/）
+├── index.ts                     ← server 入口：拉注册表 → 注册 integration/provider/models
+├── tui.tsx                      ← TUI 入口：注册 /connect-providers 命令
+├── registry/                    ← 纯逻辑：schema 校验 / 元数据映射 / 拉取缓存
+└── view/                        ← /connect-providers 交互
+```
+
+> 源码**故意不放在 `.opencode/plugins/` 下**：那样在本仓库里跑 opencode 时，仓库副本会和全局安装副本撞同一个插件 id，
+> 被 supervisor 判为 `Duplicate plugin ID: opencode-providers`，在 `/plugins` 面板里显示成一条 `failed`（实际加载的是另一条，功能正常）。
+
+## 为什么需要它
+
+OpenCode 的供应商清单来自 models.dev 目录，**目录里没有的供应商不会出现在 `/connect`**。
+想用自建/网关/小众供应商，原本只能在 `opencode.json` 里手写 `providers.<id>` 加一长串模型参数。
+本项目把这份数据搬到一份共享注册表里，由插件在运行期注册 —— 配置零增长，改注册表也不用改插件版本。
+
+## 安装
+
+### 方式 A：npm 包（推荐）
+
+在 `opencode.json(c)` 里写一行（不需要手写 provider/模型）：
+
+```jsonc
+{
+  "plugins": ["@justsilver/opencode-providers"]
+}
+```
+
+想**试某个测试版**就把版本写全（试完再回到正式版）：
+
+```jsonc
+{
+  "plugins": ["@justsilver/opencode-providers@0.1.0-beta.0"]
+}
+```
+
+- 预发布版本发布在 npm 的 **`next`** dist-tag 上，正式版才发 `latest`。
+- 升级 / 卸载（`<目标>` 就是配置里那串原样）：`opencode plugin update @justsilver/opencode-providers` / `opencode plugin remove …`。
+- 本插件的 TUI 入口**不含 JSX**、不依赖 Solid，所以配置安装不会踩「双 Solid 运行时」的坑。
+
+### 方式 B：安装脚本（零依赖备用路径）
+
+```bash
+# Linux / macOS
+./install.sh
+```
+
+```powershell
+# Windows
+.\install.ps1
+```
+
+脚本把 `plugin/opencode-providers/` 整目录装到：
+
+```
+~/.config/opencode/plugins/opencode-providers/        # $XDG_CONFIG_HOME 优先
+```
+
+装完**通常无需重启**（插件目录被文件监视，覆盖后自动热重载）；必要时 `opencode service restart`。
+卸载：`./uninstall.sh` / `.\uninstall.ps1`。
+
+开发时把**工作树**（含未提交改动）直接部署到全局插件目录：
+
+```bash
+bash install.sh --local
+```
+```powershell
+pwsh -NoProfile -File .\install.ps1 -Local
+```
+
+## 使用
+
+```
+/connect-providers        # 选供应商 → 贴 API Key
+/models                   # 该供应商的模型随即出现在列表里
+```
+
+再运行一次可以添加第二个账号，或在已有账号之间切换。
+
+**为什么 `/models` 里一开始看不到新供应商**：provider 声明为 `activation: "auto"`，
+只有拿到凭据（你在 `/connect-providers` 里存过 key）后才会出现在 `/models`。
+这样就算注册表里有几十家供应商，也只会显示你真正配了 key 的那些。
+
+凭据存在 opencode 自己的 SQLite 里（`opencode debug paths db`），和内置 `/connect` 完全一致。
+API Key 只在你贴入时经过本插件的内存，不落任何本项目自己的文件。
+
+## 维护注册表
+
+改 `registry.json` 提交后，运行中的 opencode 最迟 6 小时（TTL）自动跟上；想立刻生效就重启服务。
+拉取使用 `ETag`，内容没变时不会重复下载；网络失败时继续沿用本地缓存，不会把供应商列表清空。
+
+### 结构
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "models": {
+    // 供应商无关的模型参数，写一份，被下面 provider 用 "base" 引用
+    "some-model": {
+      "name": "Some Model",
+      "limit": { "context": 131072, "output": 16384 },
+      "cost": { "input": 0.5, "output": 1.5, "cache_read": 0.05 },
+      "tools": true,
+      "input": ["text", "image"],
+      "output": ["text"]
+    }
+  },
+  "providers": {
+    "my-gateway": {
+      "name": "My Gateway",
+      "package": "@opencode/ai/providers/openai-compatible",
+      "baseURL": "https://llm.example.com/v1",
+      "keyLabel": "Paste API key",
+      "models": {
+        // key = 在 opencode 里使用的模型 ID；base 指向上面那份共享参数
+        "some-model": { "base": "some-model" },
+        // 覆盖任意字段；modelID 是发给上游的真实 ID
+        "some-model-fast": {
+          "base": "some-model",
+          "modelID": "some-model-2026-01",
+          "cost": { "input": 0.2, "output": 0.8 }
+        }
+      }
+    }
+  }
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `schemaVersion` | 当前为 `1`；插件只接受自己支持的版本，不匹配就整份拒绝（不会半注册） |
+| `providers.<id>.package` | 运行时包，如 `@opencode/ai/providers/openai-compatible`（**不要**用旧的 `aisdk:` / `@ai-sdk/*` 写法） |
+| `providers.<id>.baseURL` | API 端点；与 `settings` 合并后作为 provider `settings` |
+| `providers.<id>.keyLabel` | `/connect-providers` 里 API Key 输入框的提示，默认 `Paste API key` |
+| `providers.<id>.models` | key = 模型 ID（`provider/model` 里的 model 段）；每项字段见下表 |
+| 模型 `base` | 引用顶层 `models` 的 key，先铺共享参数再用本项覆盖 |
+| 模型 `modelID` | 发给上游的真实模型/部署 ID，默认等于上面的 key |
+| 模型 `limit` | `context` / `output` 必填（无 `base` 时），`input` 可选 |
+| 模型 `cost` | 每百万 token 美元；`cache_read`/`cache_write` 可选 |
+| 模型 `tools` / `input` / `output` | 能力：是否支持工具调用、输入/输出模态，默认 `true` / `["text"]` |
+| 模型 `reasoningField` / `maxTokensField` | 映射到 `Model.Compatibility` |
+| 模型 `variants` | `[{ "id": "high", "settings": {} }]` |
+| 模型 `status` / `disabled` | 生命周期标记；`disabled: true` 不出现在 `/models` |
+
+`registry.schema.json` 是同一份规则的 JSON Schema，编辑器可直接校验。
+
+## 范围之外
+
+- **不做参数推断**：注册表写什么就是什么，插件不会去猜 `limit`/`cost`。
+- **不调供应商 API**：不访问 `/v1/models`，也就没有运行期的额外网络与失败面。
+- **不声明 `env` 认证**：本插件只走 `/connect`-式交互；opencode 的 env 是静默旁路且不在 `/connect` 里展示。
+- 账号重命名/删除请用内置 `/connect`（同一个 integration，同一个凭据表）。
+
+## 开发
+
+```bash
+node --test                        # 纯逻辑单测（Node ≥ 22 原生 TS，无需依赖）
+node scripts/smoke-api.mjs --list  # 真机冒烟场景（HTTP，不需要 TUI）
+node scripts/smoke-api.mjs         # 全跑：插件已加载 / 供应商已注册 / 凭据→模型→清理
+```
+
+`smoke-api.mjs` 的鉴权自动读 `~/.local/state/opencode/service.json`；它的 `models` 场景会写入并删除一条
+临时凭据（label `smoke-throwaway`），且只对「当前没有任何凭据」的供应商生效。
+
+两个入口的打包/语法检查（两个入口都不 import 外部运行时依赖）：
+
+```bash
+npx --yes esbuild plugin/opencode-providers/index.ts --bundle --platform=node --format=esm \
+  --outfile=dist/providers-server.js
+
+npx --yes esbuild plugin/opencode-providers/tui.ts --bundle --platform=node --format=esm \
+  --outfile=dist/providers-tui.js
+```
+
+改完插件文件**通常无需重启**：插件目录被文件监视，覆盖后自动热重载。
+验证是否真的注册成功（用 opencode 自己的 API，不需要看 TUI）：
+
+```bash
+opencode api get /api/plugin        # 自己那条 state.status 必须是 active（多于 1 条 = 同 id 被发现两次）
+opencode api get /api/integration   # 注册的供应商（metadata.source = opencode-providers）
+opencode api get /api/model         # 只列可用供应商的模型；没配 key 时不会出现
+```
+
+**发布策略（预发布优先）**：`package.json` 的 `version` 是版本单一来源；
+预发布（如 `0.1.0-beta.0`）发到 npm 的 **`next`** dist-tag，正式版必须手动确认才发 `latest`。
+流水线：整理 `CHANGELOG.md` 的版本小节 → `npm version <x.y.z[-beta.n]> --no-git-tag-version` → commit →
+push tag `vX.Y.Z-beta.n`（或 Actions → Release → Run workflow 勾 `publish`；不勾只做 `npm pack --dry-run` 预检）。
+**首个版本必须人工发一次**（OIDC/trusted publisher 挂不到尚不存在的包上），命令与核对项见
+`docs/npm-distribution-and-testing.md` §5。
+
+## 疑难解答
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `/plugins` 面板里本插件有**一条 `failed`** | 同一插件 id 被发现两次（例：脚本装到 `~/.config/opencode/plugins/` + 又在 `opencode.json` 里配了 npm 包，或某个项目的 `.opencode/plugins/` 里也有一份）。supervisor 保留首个、把后来者标成 `failed`，错误信息是 `Duplicate plugin ID: opencode-providers`。删掉多余的那份即可 |
+| `/connect-providers` 说没有可用供应商 | 注册表没加载成功。看 server 日志里的 `[opencode-providers]`，并确认 `/api/plugin` 里自己那条 `state.status` 是 `active` |
+| `/models` 里看不到新供应商 | 正常：`activation: "auto"`，在 `/connect-providers` 里存过 key 之后才会出现 |
+| 改了插件代码没生效 | 覆盖的是**全局**那份（`~/.config/opencode/plugins/opencode-providers/`）。开发时用 `install.ps1 -Local` / `install.sh --local` 把工作树复制过去 |
+
+验证命令见上面的「开发」小节。

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@justsilver/opencode-providers",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "description": "Register providers missing from the models.dev catalog in OpenCode V2 from a self-hosted registry — no opencode.json needed",
+  "license": "MIT",
+  "author": "Just-Silver",
+  "homepage": "https://github.com/Just-Silver/opencode-providers#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Just-Silver/opencode-providers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Just-Silver/opencode-providers/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "provider",
+    "providers",
+    "models",
+    "gateway",
+    "llm"
+  ],
+  "main": "./plugin/opencode-providers/index.ts",
+  "exports": {
+    ".": "./plugin/opencode-providers/index.ts",
+    "./server": "./plugin/opencode-providers/index.ts",
+    "./tui": "./plugin/opencode-providers/tui.ts"
+  },
+  "files": [
+    "plugin/**/*.ts",
+    "!plugin/**/*.test.ts",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.24"
+  }
+}

package/plugin/opencode-providers/index.ts

@@ -0,0 +1,133 @@
+/**
+ * Server entry — registers providers from the registry.
+ *
+ * IMPORTANT: this file deliberately imports **nothing** from `@opencode/*`.
+ * A locally installed server plugin does not get the plugin module injected
+ * (opencode 2.0.24 fails with `Cannot find package '@opencode/plugin'`), unlike
+ * `@opencode/plugin/tui` for TUI entries. Everything the runtime needs here is a
+ * plain value:
+ *   - `Plugin.define` is the identity function, so a default export is enough
+ *   - `Provider.ID.make` / `Integration.ID.make` are identity at runtime
+ *   - `Provider.Info.empty(id)` is `{ id, name: id, activation: "auto", package: "" }`
+ *     and every field is overridden below anyway
+ *
+ * It registers an integration (single `key` method) and a provider
+ * (`activation: "auto"`) per registry entry. Credentials are never touched:
+ * opencode injects them by matching `provider.integrationID` to the integration
+ * the key was stored under. No `env` method is declared on purpose — env is a
+ * silent, non-interactive path and this plugin is `/connect`-only.
+ */
+
+import { buildProviderModels, buildProviderSettings } from "./registry/models.ts"
+import { DEFAULT_REGISTRY_URL, loadRegistry } from "./registry/source.ts"
+import type { RegistryCacheEntry } from "./registry/source.ts"
+
+const PLUGIN_ID = "opencode-providers"
+const CACHE_KEY = "registry-cache"
+
+/** Tags integrations so the TUI entry can recognise its own. */
+export const INTEGRATION_SOURCE = PLUGIN_ID
+
+interface IntegrationRefLike {
+  id: string
+  name: string
+}
+
+interface IntegrationEditorLike {
+  update(id: string, update: (integration: IntegrationRefLike) => void): void
+  method: { update(input: { integrationID: string; method: { type: "key"; label?: string } }): void }
+}
+
+interface ProviderEditorLike {
+  add(input: { info: Record<string, unknown>; models: readonly Record<string, unknown>[] }): void
+}
+
+/** Only the members this plugin uses; see the file comment for why it is structural. */
+interface SetupContextLike {
+  readonly options: Readonly<Record<string, unknown>>
+  readonly storage: {
+    get(key: string): Promise<unknown>
+    set(key: string, value: unknown): Promise<void>
+  }
+  readonly integration: { transform(callback: (editor: IntegrationEditorLike) => void): Promise<unknown> }
+  readonly provider: { transform(callback: (editor: ProviderEditorLike) => void): Promise<unknown> }
+}
+
+export default {
+  id: PLUGIN_ID,
+  async setup(ctx: SetupContextLike) {
+    // NOTE: discovered directory plugins are registered with `options: {}`, so this override is only
+    // reachable through a config `plugins` entry (which we deliberately do not use for TUI plugins).
+    // It exists for tests and forks; script installs always use DEFAULT_REGISTRY_URL.
+    const url = typeof ctx.options.registryUrl === "string" ? ctx.options.registryUrl : DEFAULT_REGISTRY_URL
+    const result = await loadRegistry({
+      url,
+      fetch: globalThis.fetch,
+      store: {
+        get: async () => asCacheEntry(await ctx.storage.get(CACHE_KEY)),
+        set: async (entry) => {
+          await ctx.storage.set(CACHE_KEY, entry)
+        },
+      },
+    })
+
+    if (!result.ok) {
+      console.error(`[${PLUGIN_ID}] registry unavailable (${url}): ${result.errors.join("; ")}`)
+      return
+    }
+    if (result.source === "stale-cache") {
+      console.warn(
+        `[${PLUGIN_ID}] registry refresh failed; serving cache from ${new Date(result.fetchedAt).toISOString()}`,
+      )
+    }
+
+    const { registry } = result
+    const entries = Object.entries(registry.providers)
+
+    await ctx.integration.transform((editor) => {
+      for (const [id, provider] of entries) {
+        editor.update(id, (integration) => {
+          integration.name = provider.name
+          // `metadata` is part of the integration ref and surfaces in `Integration.Info`,
+          // but the plugin-facing ref type only declares id/name.
+          ;(integration as IntegrationRefLike & { metadata?: Record<string, unknown> }).metadata = {
+            source: INTEGRATION_SOURCE,
+            ...(provider.keyLabel === undefined ? {} : { keyLabel: provider.keyLabel }),
+          }
+        })
+        editor.method.update({
+          integrationID: id,
+          method: { type: "key", label: provider.keyLabel ?? "Paste API key" },
+        })
+      }
+    })
+
+    await ctx.provider.transform((editor) => {
+      for (const [id, provider] of entries) {
+        const models = buildProviderModels(registry, id, provider)
+        if (models.length === 0) continue
+        const settings = buildProviderSettings(provider)
+        editor.add({
+          info: {
+            id,
+            name: provider.name,
+            activation: "auto",
+            integrationID: id,
+            package: provider.package,
+            ...(settings === undefined ? {} : { settings }),
+            ...(provider.headers === undefined ? {} : { headers: provider.headers }),
+          },
+          models,
+        })
+      }
+    })
+  },
+}
+
+function asCacheEntry(value: unknown): RegistryCacheEntry | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const entry = value as Partial<RegistryCacheEntry>
+  if (typeof entry.fetchedAt !== "number" || typeof entry.body !== "string") return undefined
+  if (entry.etag !== undefined && typeof entry.etag !== "string") return undefined
+  return entry as RegistryCacheEntry
+}

package/plugin/opencode-providers/registry/models.ts

@@ -0,0 +1,99 @@
+/**
+ * Maps validated registry entries onto plain `Model.Info`-shaped objects.
+ *
+ * Pure and dependency-free so `node --test` can cover it without the OpenCode
+ * runtime. The server entry feeds the result straight to `ctx.provider.transform`.
+ */
+
+import type { ProviderEntry, Registry } from "./schema.ts"
+import { resolveModelSpec } from "./schema.ts"
+
+export interface ModelInfoLike {
+  readonly id: string
+  readonly modelID: string
+  readonly providerID: string
+  readonly name: string
+  readonly family?: string
+  readonly compatibility?: Readonly<Record<string, unknown>>
+  readonly capabilities: {
+    readonly tools: boolean
+    readonly input: readonly string[]
+    readonly output: readonly string[]
+  }
+  readonly variants: ReadonlyArray<{ readonly id: string; readonly settings?: Readonly<Record<string, unknown>> }>
+  readonly time: { readonly released: number }
+  readonly cost: ReadonlyArray<{
+    readonly input: number
+    readonly output: number
+    readonly cache: { readonly read: number; readonly write: number }
+  }>
+  readonly status: "alpha" | "beta" | "deprecated" | "active"
+  readonly enabled: boolean
+  readonly limit: { readonly context: number; readonly input?: number; readonly output: number }
+}
+
+export function buildProviderModels(
+  registry: Registry,
+  providerID: string,
+  provider: ProviderEntry,
+): ModelInfoLike[] {
+  const models: ModelInfoLike[] = []
+
+  for (const [id, spec] of Object.entries(provider.models)) {
+    const resolved = resolveModelSpec(registry, spec)
+    if (resolved === undefined) continue
+
+    const compatibility: Record<string, unknown> = {}
+    if (resolved.reasoningField !== undefined) compatibility.reasoningField = resolved.reasoningField
+    if (resolved.maxTokensField !== undefined) compatibility.maxTokensField = resolved.maxTokensField
+
+    models.push({
+      id,
+      modelID: spec.modelID ?? id,
+      providerID,
+      name: resolved.name ?? id,
+      ...(resolved.family === undefined ? {} : { family: resolved.family }),
+      ...(Object.keys(compatibility).length === 0 ? {} : { compatibility }),
+      capabilities: {
+        tools: resolved.tools ?? true,
+        input: resolved.input ?? ["text"],
+        output: resolved.output ?? ["text"],
+      },
+      variants: (resolved.variants ?? []).map((variant) =>
+        variant.settings === undefined ? { id: variant.id } : { id: variant.id, settings: variant.settings },
+      ),
+      time: { released: resolveReleased(resolved.releaseDate) },
+      cost:
+        resolved.cost === undefined
+          ? []
+          : [
+              {
+                input: resolved.cost.input,
+                output: resolved.cost.output,
+                cache: { read: resolved.cost.cache_read ?? 0, write: resolved.cost.cache_write ?? 0 },
+              },
+            ],
+      status: resolved.status ?? "active",
+      enabled: resolved.disabled !== true,
+      limit: {
+        context: resolved.limit.context,
+        ...(resolved.limit.input === undefined ? {} : { input: resolved.limit.input }),
+        output: resolved.limit.output,
+      },
+    })
+  }
+
+  return models
+}
+
+/** Provider settings = registry `settings` layered over `{ baseURL }`. */
+export function buildProviderSettings(provider: ProviderEntry): Readonly<Record<string, unknown>> | undefined {
+  if (provider.baseURL === undefined && provider.settings === undefined) return undefined
+  return { ...(provider.baseURL === undefined ? {} : { baseURL: provider.baseURL }), ...provider.settings }
+}
+
+function resolveReleased(releaseDate: string | undefined): number {
+  if (releaseDate === undefined) return 0
+  const parsed = Date.parse(releaseDate)
+  return Number.isFinite(parsed) ? parsed : 0
+}

package/plugin/opencode-providers/registry/schema.ts

@@ -0,0 +1,278 @@
+/**
+ * Registry schema + validation.
+ *
+ * Dependency-free and runtime-agnostic on purpose: the server entry, the TUI
+ * entry and `node --test` all import this module, so it must not touch
+ * `@opencode/*`, JSX or Node built-ins.
+ */
+
+export const SUPPORTED_SCHEMA_VERSION = 1
+
+export type ModelStatus = "alpha" | "beta" | "deprecated" | "active"
+
+export interface Limit {
+  readonly context: number
+  readonly input?: number
+  readonly output: number
+}
+
+export interface Cost {
+  readonly input: number
+  readonly output: number
+  readonly cache_read?: number
+  readonly cache_write?: number
+}
+
+export interface Variant {
+  readonly id: string
+  readonly settings?: Readonly<Record<string, unknown>>
+}
+
+/** Provider-agnostic model facts. Shared by every provider through `base`. */
+export interface RegistryModel {
+  readonly name?: string
+  readonly family?: string
+  readonly releaseDate?: string
+  readonly status?: ModelStatus
+  readonly disabled?: boolean
+  readonly limit: Limit
+  readonly cost?: Cost
+  readonly tools?: boolean
+  readonly input?: readonly string[]
+  readonly output?: readonly string[]
+  /** `Model.Compatibility.reasoningField` */
+  readonly reasoningField?: string
+  /** `Model.Compatibility.maxTokensField` */
+  readonly maxTokensField?: "max_tokens" | "max_completion_tokens"
+  readonly variants?: readonly Variant[]
+}
+
+/**
+ * A model as exposed by one provider. `id` is the map key; everything else is
+ * optional and layered over the shared model named by `base`.
+ */
+export interface ModelSpec {
+  readonly base?: string
+  /** Model or deployment ID sent upstream. Defaults to the map key. */
+  readonly modelID?: string
+  readonly name?: string
+  readonly family?: string
+  readonly releaseDate?: string
+  readonly status?: ModelStatus
+  readonly disabled?: boolean
+  readonly limit?: Limit
+  readonly cost?: Cost
+  readonly tools?: boolean
+  readonly input?: readonly string[]
+  readonly output?: readonly string[]
+  readonly reasoningField?: string
+  readonly maxTokensField?: "max_tokens" | "max_completion_tokens"
+  readonly variants?: readonly Variant[]
+}
+
+export interface ProviderEntry {
+  readonly name: string
+  /** Runtime provider package, e.g. `@opencode/ai/providers/openai-compatible`. */
+  readonly package: string
+  readonly baseURL?: string
+  /** Extra provider settings merged over `{ baseURL }`. */
+  readonly settings?: Readonly<Record<string, unknown>>
+  readonly headers?: Readonly<Record<string, string>>
+  /** Label for the `/connect...` key prompt. Defaults to "Paste API key". */
+  readonly keyLabel?: string
+  readonly models: Readonly<Record<string, ModelSpec>>
+}
+
+export interface Registry {
+  readonly schemaVersion: number
+  readonly models: Readonly<Record<string, RegistryModel>>
+  readonly providers: Readonly<Record<string, ProviderEntry>>
+}
+
+export type ParseResult = { readonly ok: true; readonly registry: Registry } | { readonly ok: false; readonly errors: readonly string[] }
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isPositiveInt = (value: unknown): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value > 0
+
+const isNonNegativeNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string")
+
+const STATUSES: readonly ModelStatus[] = ["alpha", "beta", "deprecated", "active"]
+
+function checkLimit(value: unknown, path: string, errors: string[]): value is Limit {
+  if (!isRecord(value)) {
+    errors.push(`${path}: must be an object`)
+    return false
+  }
+  let valid = true
+  if (!isPositiveInt(value.context)) {
+    errors.push(`${path}.context: must be a positive integer`)
+    valid = false
+  }
+  if (!isPositiveInt(value.output)) {
+    errors.push(`${path}.output: must be a positive integer`)
+    valid = false
+  }
+  if (value.input !== undefined && !isPositiveInt(value.input)) {
+    errors.push(`${path}.input: must be a positive integer when present`)
+    valid = false
+  }
+  return valid
+}
+
+function checkCost(value: unknown, path: string, errors: string[]): boolean {
+  if (!isRecord(value)) {
+    errors.push(`${path}: must be an object`)
+    return false
+  }
+  let valid = true
+  for (const field of ["input", "output"] as const) {
+    if (!isNonNegativeNumber(value[field])) {
+      errors.push(`${path}.${field}: must be a number >= 0`)
+      valid = false
+    }
+  }
+  for (const field of ["cache_read", "cache_write"] as const) {
+    if (value[field] !== undefined && !isNonNegativeNumber(value[field])) {
+      errors.push(`${path}.${field}: must be a number >= 0 when present`)
+      valid = false
+    }
+  }
+  return valid
+}
+
+function checkVariants(value: unknown, path: string, errors: string[]): boolean {
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: must be an array`)
+    return false
+  }
+  let valid = true
+  value.forEach((variant, index) => {
+    if (!isRecord(variant) || typeof variant.id !== "string" || !variant.id) {
+      errors.push(`${path}[${index}].id: must be a non-empty string`)
+      valid = false
+    }
+  })
+  return valid
+}
+
+/** Validates the fields a model may declare; `requireLimit` is false for provider overrides. */
+function checkModelFields(
+  value: Record<string, unknown>,
+  path: string,
+  errors: string[],
+  options: { readonly requireLimit: boolean },
+) {
+  if (value.limit !== undefined) checkLimit(value.limit, `${path}.limit`, errors)
+  else if (options.requireLimit) errors.push(`${path}.limit: required`)
+
+  if (value.cost !== undefined) checkCost(value.cost, `${path}.cost`, errors)
+  if (value.variants !== undefined) checkVariants(value.variants, `${path}.variants`, errors)
+
+  if (value.tools !== undefined && typeof value.tools !== "boolean") errors.push(`${path}.tools: must be a boolean`)
+  if (value.disabled !== undefined && typeof value.disabled !== "boolean")
+    errors.push(`${path}.disabled: must be a boolean`)
+  if (value.input !== undefined && !isStringArray(value.input)) errors.push(`${path}.input: must be an array of strings`)
+  if (value.output !== undefined && !isStringArray(value.output))
+    errors.push(`${path}.output: must be an array of strings`)
+
+  for (const field of ["name", "family", "releaseDate", "reasoningField"] as const) {
+    if (value[field] !== undefined && typeof value[field] !== "string") errors.push(`${path}.${field}: must be a string`)
+  }
+  if (value.modelID !== undefined && (typeof value.modelID !== "string" || !value.modelID))
+    errors.push(`${path}.modelID: must be a non-empty string`)
+  if (value.status !== undefined && !STATUSES.includes(value.status as ModelStatus))
+    errors.push(`${path}.status: must be one of ${STATUSES.join(", ")}`)
+  if (value.maxTokensField !== undefined && value.maxTokensField !== "max_tokens" && value.maxTokensField !== "max_completion_tokens")
+    errors.push(`${path}.maxTokensField: must be "max_tokens" or "max_completion_tokens"`)
+}
+
+export function parseRegistry(input: unknown): ParseResult {
+  const errors: string[] = []
+
+  if (!isRecord(input)) return { ok: false, errors: ["registry: must be an object"] }
+
+  if (input.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+    errors.push(
+      `schemaVersion: unsupported value ${JSON.stringify(input.schemaVersion)} (this plugin supports ${SUPPORTED_SCHEMA_VERSION})`,
+    )
+  }
+
+  const shared: Record<string, RegistryModel> = {}
+  const rawModels = input.models ?? {}
+  if (!isRecord(rawModels)) {
+    errors.push("models: must be an object")
+  } else {
+    for (const [key, value] of Object.entries(rawModels)) {
+      const path = `models.${key}`
+      if (!isRecord(value)) {
+        errors.push(`${path}: must be an object`)
+        continue
+      }
+      checkModelFields(value, path, errors, { requireLimit: true })
+      shared[key] = value as unknown as RegistryModel
+    }
+  }
+
+  const providers: Record<string, ProviderEntry> = {}
+  const rawProviders = input.providers
+  if (!isRecord(rawProviders) || Object.keys(rawProviders).length === 0) {
+    errors.push("providers: must be a non-empty object")
+  } else {
+    for (const [id, value] of Object.entries(rawProviders)) {
+      const path = `providers.${id}`
+      if (!isRecord(value)) {
+        errors.push(`${path}: must be an object`)
+        continue
+      }
+      if (typeof value.name !== "string" || !value.name) errors.push(`${path}.name: must be a non-empty string`)
+      if (typeof value.package !== "string" || !value.package) errors.push(`${path}.package: must be a non-empty string`)
+      if (value.baseURL !== undefined && typeof value.baseURL !== "string") errors.push(`${path}.baseURL: must be a string`)
+      if (value.keyLabel !== undefined && typeof value.keyLabel !== "string") errors.push(`${path}.keyLabel: must be a string`)
+      if (value.settings !== undefined && !isRecord(value.settings)) errors.push(`${path}.settings: must be an object`)
+      if (value.headers !== undefined) {
+        if (!isRecord(value.headers) || !Object.values(value.headers).every((header) => typeof header === "string"))
+          errors.push(`${path}.headers: must be an object of strings`)
+      }
+
+      const models: Record<string, ModelSpec> = {}
+      if (!isRecord(value.models) || Object.keys(value.models).length === 0) {
+        errors.push(`${path}.models: must be a non-empty object`)
+      } else {
+        for (const [modelID, spec] of Object.entries(value.models)) {
+          const modelPath = `${path}.models.${modelID}`
+          if (!isRecord(spec)) {
+            errors.push(`${modelPath}: must be an object`)
+            continue
+          }
+          checkModelFields(spec, modelPath, errors, { requireLimit: spec.base === undefined })
+          if (spec.base !== undefined) {
+            if (typeof spec.base !== "string") errors.push(`${modelPath}.base: must be a string`)
+            else if (!(spec.base in shared)) errors.push(`${modelPath}.base: unknown shared model "${spec.base}"`)
+          }
+          models[modelID] = spec as unknown as ModelSpec
+        }
+      }
+
+      providers[id] = { ...(value as unknown as ProviderEntry), models }
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors }
+  return { ok: true, registry: { schemaVersion: SUPPORTED_SCHEMA_VERSION, models: shared, providers } }
+}
+
+/** Layers a provider model spec over its shared model, shared first. */
+export function resolveModelSpec(registry: Registry, spec: ModelSpec): RegistryModel | undefined {
+  const base = spec.base === undefined ? undefined : registry.models[spec.base]
+  if (spec.base !== undefined && base === undefined) return undefined
+  const { base: _base, modelID: _modelID, ...overrides } = spec
+  const model = { ...base, ...overrides } as RegistryModel
+  return model.limit === undefined ? undefined : model
+}

package/plugin/opencode-providers/registry/source.ts

@@ -0,0 +1,155 @@
+/**
+ * Registry loading: fetch + TTL + ETag + stale fallback.
+ *
+ * Pure logic with injected `fetch` / clock / cache so `node --test` can cover
+ * the failure paths. The server entry wires these to `ctx.storage` and the
+ * process `fetch`.
+ */
+
+import type { Registry } from "./schema.ts"
+import { parseRegistry } from "./schema.ts"
+
+export const DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/Just-Silver/opencode-providers/main/registry.json"
+
+/** Successful checks are trusted for 6h; a failed refresh keeps serving the cached copy. */
+export const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000
+export const DEFAULT_TIMEOUT_MS = 10_000
+
+export interface RegistryCacheEntry {
+  readonly etag?: string
+  readonly fetchedAt: number
+  readonly body: string
+}
+
+export interface RegistryStore {
+  get(): Promise<RegistryCacheEntry | undefined>
+  set(entry: RegistryCacheEntry): Promise<void>
+}
+
+export interface LoadRegistryOptions {
+  readonly store: RegistryStore
+  readonly fetch: typeof globalThis.fetch
+  /** Defaults to `DEFAULT_REGISTRY_URL`. */
+  readonly url?: string
+  readonly now?: () => number
+  readonly ttlMs?: number
+  readonly timeoutMs?: number
+}
+
+export type RegistrySource = "cache" | "network" | "stale-cache"
+
+export type LoadRegistryResult =
+  | { readonly ok: true; readonly registry: Registry; readonly source: RegistrySource; readonly fetchedAt: number }
+  | { readonly ok: false; readonly errors: readonly string[] }
+
+const isCacheEntry = (value: unknown): value is RegistryCacheEntry =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as RegistryCacheEntry).fetchedAt === "number" &&
+  typeof (value as RegistryCacheEntry).body === "string" &&
+  ((value as RegistryCacheEntry).etag === undefined || typeof (value as RegistryCacheEntry).etag === "string")
+
+export async function loadRegistry(options: LoadRegistryOptions): Promise<LoadRegistryResult> {
+  const url = options.url ?? DEFAULT_REGISTRY_URL
+  const now = options.now ?? Date.now
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  const cached = await readCache(options.store)
+
+  if (cached !== undefined && now() - cached.fetchedAt < ttlMs) {
+    const parsed = parseBody(cached.body)
+    if (parsed.ok) return { ok: true, registry: parsed.registry, source: "cache", fetchedAt: cached.fetchedAt }
+  }
+
+  let response: Response
+  try {
+    response = await options.fetch(url, {
+      headers: {
+        accept: "application/json",
+        "user-agent": "opencode-providers",
+        ...(cached?.etag === undefined ? {} : { "if-none-match": cached.etag }),
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+  } catch (error) {
+    return fallback(cached, errorMessage(error))
+  }
+
+  if (response.status === 304 && cached !== undefined) {
+    const entry = { ...cached, fetchedAt: now() }
+    await writeCache(options.store, entry)
+    const parsed = parseBody(cached.body)
+    if (parsed.ok) return { ok: true, registry: parsed.registry, source: "cache", fetchedAt: entry.fetchedAt }
+    return { ok: false, errors: parsed.errors }
+  }
+
+  if (!response.ok) return fallback(cached, `registry request failed: ${response.status} ${response.statusText}`)
+
+  let body: string
+  try {
+    body = await response.text()
+  } catch (error) {
+    return fallback(cached, errorMessage(error))
+  }
+
+  const parsed = parseBody(body)
+  if (!parsed.ok) {
+    const stale = await staleFallback(cached, parsed.errors)
+    if (stale !== undefined) return stale
+    return { ok: false, errors: parsed.errors }
+  }
+
+  const etag = response.headers.get("etag") ?? undefined
+  const fetchedAt = now()
+  await writeCache(options.store, { ...(etag === undefined ? {} : { etag }), fetchedAt, body })
+  return { ok: true, registry: parsed.registry, source: "network", fetchedAt }
+}
+
+/** A cache-write failure must never break loading; the payload is served regardless. */
+async function writeCache(store: RegistryStore, entry: RegistryCacheEntry): Promise<void> {
+  try {
+    await store.set(entry)
+  } catch {
+    // intentionally ignored
+  }
+}
+
+async function readCache(store: RegistryStore): Promise<RegistryCacheEntry | undefined> {
+  try {
+    const value = await store.get()
+    return isCacheEntry(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function parseBody(body: string): { ok: true; registry: Registry } | { ok: false; errors: string[] } {
+  let json: unknown
+  try {
+    json = JSON.parse(body)
+  } catch (error) {
+    return { ok: false, errors: [`registry is not valid JSON: ${errorMessage(error)}`] }
+  }
+  const parsed = parseRegistry(json)
+  return parsed.ok ? { ok: true, registry: parsed.registry } : { ok: false, errors: [...parsed.errors] }
+}
+
+async function fallback(cached: RegistryCacheEntry | undefined, reason: string): Promise<LoadRegistryResult> {
+  const stale = await staleFallback(cached, [reason])
+  return stale ?? { ok: false, errors: [reason] }
+}
+
+async function staleFallback(
+  cached: RegistryCacheEntry | undefined,
+  errors: readonly string[],
+): Promise<LoadRegistryResult | undefined> {
+  if (cached === undefined) return undefined
+  const parsed = parseBody(cached.body)
+  if (!parsed.ok) return undefined
+  return { ok: true, registry: parsed.registry, source: "stale-cache", fetchedAt: cached.fetchedAt }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/plugin/opencode-providers/tui.ts

@@ -0,0 +1,28 @@
+/**
+ * TUI entry — registers `/connect-providers`.
+ *
+ * The command only *reads* state (integrations the server entry registered) and
+ * talks to the server over the client API, so the key still lands in opencode's
+ * credential table through the normal `/connect` path.
+ */
+
+import { Plugin } from "@opencode/plugin/tui"
+import { connectProviders } from "./view/connect.ts"
+
+const PLUGIN_ID = "opencode-providers"
+
+export default Plugin.define({
+  id: PLUGIN_ID,
+  setup(context) {
+    context.keymap.layer(() => ({
+      commands: [
+        {
+          id: `${PLUGIN_ID}.connect`,
+          title: "Connect providers",
+          slash: { name: "connect-providers" },
+          run: () => connectProviders(context),
+        },
+      ],
+    }))
+  },
+})

package/plugin/opencode-providers/view/connect.ts

@@ -0,0 +1,140 @@
+/**
+ * `/connect-providers` flow.
+ *
+ * Mirrors the built-in `/connect` interaction for the providers this plugin
+ * registers: pick a provider, then either add an account (paste an API key) or
+ * activate one that already exists. Everything goes through the normal server
+ * API, so credentials land in opencode's own store.
+ *
+ * Out of scope on purpose (use the built-in `/connect` for these): renaming and
+ * deleting accounts. Renaming needs a bound footer action; deletion needs a
+ * confirm binding. Both are cosmetic actions on the same records.
+ */
+
+import type { IntegrationInfo } from "@opencode/client"
+import type { Plugin } from "@opencode/plugin/tui"
+
+type Context = Plugin.Context
+type Connection = IntegrationInfo["connections"][number]
+
+const INTEGRATION_SOURCE = "opencode-providers"
+const ADD_ACCOUNT = "\u0000add-account"
+
+export async function connectProviders(ctx: Context): Promise<void> {
+  const integrations = ownIntegrations(ctx).toSorted((a, b) => a.name.localeCompare(b.name))
+
+  if (integrations.length === 0) {
+    await ctx.ui.dialog.alert({
+      title: "Connect providers",
+      message:
+        "No providers from the registry are available. Check that the registry loaded (server log) and restart the service.",
+    })
+    return
+  }
+
+  const selected = await ctx.ui.dialog.select<string>({
+    title: "Connect providers",
+    options: integrations.map((integration) => ({
+      title: integration.name,
+      value: integration.id,
+      footer: footer(integration),
+    })),
+  })
+  if (selected === undefined) return
+
+  const integration = integrations.find((item) => item.id === selected)
+  if (integration === undefined) return
+
+  await openProvider(ctx, integration)
+}
+
+async function openProvider(ctx: Context, integration: IntegrationInfo): Promise<void> {
+  const credentials = credentialConnections(integration)
+  const active = credentials[0]
+
+  if (credentials.length === 0) {
+    await connectKey(ctx, integration)
+    return
+  }
+
+  const choice = await ctx.ui.dialog.select<string>({
+    title: integration.name,
+    current: active?.id,
+    options: [
+      {
+        title: "Add account",
+        value: ADD_ACCOUNT,
+        description: "Paste another API key; it becomes the active account",
+      },
+      ...credentials.toSorted((a, b) => a.label.localeCompare(b.label)).map((credential) => ({
+        title: credential.label,
+        value: credential.id,
+        category: "Accounts",
+        footer: credential.id === active?.id ? "active" : undefined,
+      })),
+    ],
+  })
+  if (choice === undefined) return
+
+  if (choice === ADD_ACCOUNT) {
+    await connectKey(ctx, integration)
+    return
+  }
+
+  const credential = credentials.find((item) => item.id === choice)
+  try {
+    await ctx.client.credential.activate({ credentialID: choice })
+    ctx.ui.toast.show({ variant: "success", message: `Activated ${credential?.label ?? choice}` })
+  } catch (error) {
+    ctx.ui.toast.show({ variant: "error", message: message(error) })
+  }
+}
+
+async function connectKey(ctx: Context, integration: IntegrationInfo): Promise<void> {
+  const description =
+    typeof integration.metadata?.keyLabel === "string" ? integration.metadata.keyLabel : "Enter your API key"
+
+  const key = await ctx.ui.dialog.prompt({
+    title: integration.name,
+    description,
+    placeholder: "sk-...",
+  })
+  if (key === undefined || key.trim() === "") return
+
+  try {
+    await ctx.client.integration.connect.key({ integrationID: integration.id, key: key.trim() })
+    ctx.data.location.integration.invalidate(ctx.location)
+    ctx.ui.toast.show({ variant: "success", message: `${integration.name} connected` })
+  } catch (error) {
+    ctx.ui.toast.show({ variant: "error", message: message(error) })
+  }
+}
+
+function ownIntegrations(ctx: Context): IntegrationInfo[] {
+  return (ctx.data.location.integration.list(ctx.location) ?? []).filter(
+    (integration) => integration.metadata?.source === INTEGRATION_SOURCE,
+  )
+}
+
+function credentialConnections(integration: IntegrationInfo): Array<Extract<Connection, { type: "credential" }>> {
+  return integration.connections.filter(
+    (connection): connection is Extract<Connection, { type: "credential" }> => connection.type === "credential",
+  )
+}
+
+function footer(integration: IntegrationInfo): string | undefined {
+  const pending = integration.connections.find((connection) => pendingUrl(connection) !== undefined)
+  if (pending) return "Sign in required →"
+  const credentials = credentialConnections(integration)
+  if (credentials.length === 0) return undefined
+  return credentials.map((credential) => credential.label).join(", ")
+}
+
+function pendingUrl(connection: Connection): string | undefined {
+  const status = (connection as { readonly status?: { readonly url?: string } }).status
+  return status?.url
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}