@justsilver/opencode-providers 0.1.0-beta.2 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,62 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-07
+
+### Added
+
+- `/connect-providers` 弹窗新增**强制刷新**：footer 动作 + 快捷键 `ctrl+r`（与内置弹窗一致的键位提示），
+  经 server RPC（纯 JSON Schema）绕过 6h TTL 重拉注册表并 `provider`/`integration` `reload()`；上游不可达时保留原有列表并报错
+- `tests/setup.test.ts` 新用例：钉住 `ctx.options.registryUrl` —— 配置里把 `plugins` 写成对象条目传 `options` 即可换注册表地址，
+  不用改源码（`schema/src/config/plugin.ts` 证明 config 条目支持 `options`）
+
+### Changed
+
+- 评审修复：`revision` 对 CRLF/LF 归一（Windows 检出与 Linux CI 算出同一个哈希）；路径段校验收紧（单段字段禁 `/`、`base` 必须恰为 `<lab>/<model>`）；`add-provider` 缺 `--model-name` 时不再拿供应商名顶替模型名；`ctx.rpc` 缺失或刷新失败不再拖垮 provider 注册；强制刷新失败不再谎报「已重载」；stale 回落保留 `warnings`
+- 模型**能力**改为技能**多选问出后显式写入**（CLI `--input text,image`）；`tools` 不再写入注册表、默认继承上游
+- **破坏性变更：注册表改为按供应商分文件 + 插件运行期聚合。** 源 = `registry/index.json`（manifest：`schemaVersion`/`revision`/`providers`）
+  + `registry/providers/<id>/{provider,models}.json` + 顶层共享模型 `registry/models/<lab>/<model>.json`；插件拉 manifest、按 `revision`
+  决定是否重拉子文件，聚合成旧的 `{schemaVersion, models, providers}` 后写 kv（TTL / `ETag` / 失败沿用缓存语义不变）。
+  插件默认地址改为 `.../registry/index.json`；旧的单文件 `registry/registry.json` 与 `registry/registry.schema.json` 已删除。
+  - **旧版本（≤ 0.1.0）拉旧地址会 404** → 沿用本地缓存（列表不清空，但不再更新），需升级到本版才能继续拿到更新。
+- 维护脚本（`.opencode/skills/.../scripts/registry.mjs`）改写为操作分文件：新增 `sync`（重算 `revision` + 重写 `index.json`）、
+  `--root <注册表目录>`（原 `--registry`），`add-shared-model` 改 `--lab` + `--key`；`base`/`lab`/`key`/`id` 逐段校验（拒 Windows 非法字符）
+- 清理死代码：去掉 `INTEGRATION_SOURCE` / `DEFAULT_TIMEOUT_MS` 的多余 `export`；删除 `/connect-providers` 里
+  不可达的 OAuth「Sign in required」分支（注册表只声明 `key`，pending 连接不可能出现）
+- 文档按源码复核：注册表缓存的**位置/TTL/重拉条件**（全局 `kv` 表、键含 URL、无后台定时器）、
+  **模型列表进 `/model` 的四层链路**、opencode 内核 TTL 对照；README 修正 `tui.ts` 文件名与「最迟 6 小时自动跟上」的错误说法
+
+## [0.1.0] - 2026-10-07
+
+> 首个**正式版**（由 `0.1.0-beta.0` → `0.1.0-beta.2` 三个预发布版本稳定而来）；npm 的 `latest` 指向它。
+
+### Added
+
+- 自维护注册表 `registry/registry.json` + `registry/registry.schema.json`：共享 `models` 表 + provider `base` 引用/覆盖，
+  带 `schemaVersion` —— 改数据**不需要**发插件版本
+- 注册表收入两家真实供应商：**Command Code**（`https://api.commandcode.ai/provider/v1`）与
+  **R4 Coder**（`https://api.r4.codes/v1`）。二者共享 `deepseek-v4.1-flash`
+  （context 1048576 / output 393216，`reasoningEffort` 变体 low/high/max）；Command Code 用 `modelID` 覆盖成 `deepseek/deepseek-v4.1-flash`
+- server 入口：按注册表注册 integration（只声明 `key` 方法）与 provider（`activation: "auto"`）及其模型；
+  拉取 6h TTL + `ETag` + 失败沿用旧缓存（`ctx.storage`）
+- TUI 入口 `/connect-providers`：选供应商 → 贴 API Key / 切换账号，与内置 `/connect` 共用同一张凭据表
+- 两种安装方式：npm 包（`"plugins": ["@justsilver/opencode-providers"]`）与安装脚本（整目录复制到
+  `~/.config/opencode/plugins/`，支持 `--local` / `-Local` 从工作树部署）
+- 预发布优先的发版流水线：CD 走 OIDC（自动签名 provenance），预发布发 npm 的 `next`；
+  正式版必须**手动** Run workflow 勾 `publish` + `stable`（该次运行发布到 `latest` 并补 tag + GitHub Release）
+- `.opencode/skills/opencode-providers-registry`：维护注册表的技能（两条路由 + 最小字段铁律 + 协议 → package）
+
+### Fixed
+
+- **`/connect-providers` 在输入框里"看不见"**：命令图层补 `mode: "global"`（图层默认 `base`，而提示框 push 的是
+  `composer`／补全时 `autocomplete` → 不可达，命令不进补全列表）
+- 仓库自身不再是插件发现根（源码移到 `plugin/opencode-providers/`），避免在仓库里跑 opencode 时与全局安装**同 id 相撞**
+  （supervisor 会把后者标成 `failed` + `Duplicate plugin ID`）
+
+### Changed
+
+- 注册表移出仓库根：`registry.json` → `registry/registry.json`（`$id` 同步）；插件默认拉取地址与**缓存键**同步改为含 URL，换地址立即重拉
+
 ## [0.1.0-beta.2] - 2026-10-07
 
 ### Added
@@ -58,7 +114,8 @@
 - 插件源码从 `.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.2...HEAD
+[Unreleased]: https://github.com/Just-Silver/opencode-providers/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Just-Silver/opencode-providers/releases/tag/v0.1.0
 [0.1.0-beta.2]: https://github.com/Just-Silver/opencode-providers/releases/tag/v0.1.0-beta.2
 [0.1.0-beta.1]: https://github.com/Just-Silver/opencode-providers/releases/tag/v0.1.0-beta.1
 [0.1.0-beta.0]: https://github.com/Just-Silver/opencode-providers/releases/tag/v0.1.0-beta.0

package/README.md

@@ -4,11 +4,12 @@
 装完插件、在 `/connect-providers` 里贴一次 API Key 就能用 —— **不需要写 `opencode.json`**。
 
 ```
-registry/registry.json           ← 唯一事实源：供应商 + 模型 + 参数（GitHub raw 托管）
-registry/registry.schema.json    ← 给编辑器校验 registry.json
+registry/index.json              ← manifest：schemaVersion / revision / providers[]（CLI 自动维护）
+registry/providers/<id>/          ← 每家：provider.json（供应商参数）+ models.json（该家模型）
+registry/models/<lab>/<model>.json ← 顶层共享模型（多家用 base 引用）
 plugin/opencode-providers/       ← 插件源码（安装时整目录复制到 ~/.config/opencode/plugins/）
 ├── index.ts                     ← server 入口：拉注册表 → 注册 integration/provider/models
-├── tui.tsx                      ← TUI 入口：注册 /connect-providers 命令
+├── tui.ts                       ← TUI 入口：注册 /connect-providers 命令（不写 JSX，见下）
 ├── registry/                    ← 纯逻辑：schema 校验 / 元数据映射 / 拉取缓存
 └── view/                        ← /connect-providers 交互
 ```
@@ -34,17 +35,28 @@ OpenCode 的供应商清单来自 models.dev 目录，**目录里没有的供应
 }
 ```
 
+等价的一条命令（帮你写进全局配置）：`opencode plugin add @justsilver/opencode-providers`。
+
 想**试某个测试版**就把版本写全（试完再回到正式版）：
 
 ```jsonc
 {
-  "plugins": ["@justsilver/opencode-providers@0.1.0-beta.0"]
+  "plugins": ["@justsilver/opencode-providers@0.1.0-beta.2"]
 }
 ```
 
 - 预发布版本发布在 npm 的 **`next`** dist-tag 上，正式版才发 `latest`。
 - 升级 / 卸载（`<目标>` 就是配置里那串原样）：`opencode plugin update @justsilver/opencode-providers` / `opencode plugin remove …`。
 - 本插件的 TUI 入口**不含 JSX**、不依赖 Solid，所以配置安装不会踩「双 Solid 运行时」的坑。
+- 想指向**别的注册表**（自建/私有）：配置改成对象条目传 options，不用改源码——
+
+  ```jsonc
+  {
+    "plugins": [
+      { "package": "@justsilver/opencode-providers", "options": { "registryUrl": "https://example.com/registry/index.json" } }
+    ]
+  }
+  ```
 
 ### 方式 B：安装脚本（零依赖备用路径）
 
@@ -89,6 +101,9 @@ pwsh -NoProfile -File .\install.ps1 -Local
 
 再运行一次可以添加第二个账号，或在已有账号之间切换。
 
+在 `/connect-providers` 弹窗里按 `Ctrl+R`，或点弹窗底部那行 **Force refresh**，
+即可绕过 6h TTL 立刻重拉注册表并重注册（上游拉不到时保留原有列表并报错，不会清空）。
+
 **为什么 `/models` 里一开始看不到新供应商**：provider 声明为 `activation: "auto"`，
 只有拿到凭据（你在 `/connect-providers` 里存过 key）后才会出现在 `/models`。
 这样就算注册表里有几十家供应商，也只会显示你真正配了 key 的那些。
@@ -98,63 +113,74 @@ API Key 只在你贴入时经过本插件的内存，不落任何本项目自己
 
 ## 维护注册表
 
-改 `registry/registry.json` 提交后，运行中的 opencode 最迟 6 小时（TTL）自动跟上；想立刻生效就重启服务。
-拉取使用 `ETag`，内容没变时不会重复下载；网络失败时继续沿用本地缓存，不会把供应商列表清空。
+改注册表源（`registry/index.json` / `registry/providers/**` / `registry/models/**`）提交后，**下一次这个插件被加载时**才会跟上：加载时若缓存已超过 6 小时（TTL）就重新拉取。
+插件**没有后台定时器**，所以一个连着跑很久的服务不会自己刷新——想立刻生效就在 `/connect-providers` 弹窗里按 `Ctrl+R`（强制刷新），或 `opencode service restart`。
+拉取先抓 manifest（`ETag`）；`revision` 与缓存一致就不重拉子文件，变了才并发拉各分文件并重新聚合；网络失败时继续沿用本地缓存，不会把供应商列表清空。
 
 ### 结构
 
+源按供应商拆分（`registry/index.json` 是 manifest，其 `revision` 与 `providers` 由维护脚本自动维护）：
+
+```
+registry/
+  index.json                       # manifest：{ schemaVersion, revision, providers: ["my-gateway", …] }
+  providers/my-gateway/
+    provider.json                  # 供应商参数
+    models.json                    # 该家模型（key = 模型 ID）
+  models/some-lab/some-model.json    # 顶层共享模型（可选；多家用 base 引用）
+```
+
+`providers/<id>/provider.json`：
+
 ```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 }
-        }
-      }
-    }
-  }
+  "name": "My Gateway",
+  "package": "@opencode/ai/providers/openai-compatible",
+  "baseURL": "https://llm.example.com/v1"
+}
+```
+
+`providers/<id>/models.json`（key = 在 opencode 里使用的模型 ID；`base` 指向共享模型；`modelID` 是发给上游的真实 ID）：
+
+```jsonc
+{
+  "some-model": { "base": "some-lab/some-model", "name": "Some Model", "limit": { "context": 131072, "output": 16384 } },
+  "some-model-fast": { "base": "some-lab/some-model", "modelID": "some-model-2026-01" }
+}
+```
+
+`registry/models/<lab>/<model>.json`（顶层共享模型，供应商无关）：
+
+```jsonc
+{
+  "name": "Some Model",
+  "family": "some-lab",
+  "limit": { "context": 131072, "output": 16384 },
+  "cost": { "input": 0.5, "output": 1.5, "cache_read": 0.05 },
+  "tools": true,
+  "input": ["text", "image"],
+  "output": ["text"]
 }
 ```
 
 | 字段 | 说明 |
 |---|---|
-| `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，先铺共享参数再用本项覆盖 |
+| manifest `schemaVersion` | 当前为 `1`；插件只接受自己支持的版本，不匹配就整份拒绝（不会半注册） |
+| manifest `revision` | `providers/**` + `models/**` 全部文件内容的确定性哈希；子文件改动会连带它一起变，插件据此决定是否重拉 |
+| `provider.json` `package` | 运行时包，如 `@opencode/ai/providers/openai-compatible`（**不要**用旧的 `aisdk:` / `@ai-sdk/*` 写法） |
+| `provider.json` `baseURL` | API 端点；与 `settings` 合并后作为 provider `settings` |
+| `provider.json` `keyLabel` | `/connect-providers` 里 API Key 输入框的提示，默认 `Paste API key`（技能 CLI 保持最小字段，不写它） |
+| `models.json` 的 key | 模型 ID（`provider/model` 里的 model 段）；每项字段见下表 |
+| 模型 `base` | 引用顶层共享模型（值形如 `<lab>/<model>`，对应 `registry/models/<lab>/<model>.json`），先铺共享参数再用本项覆盖 |
 | 模型 `modelID` | 发给上游的真实模型/部署 ID，默认等于上面的 key |
 | 模型 `limit` | `context` / `output` 必填（无 `base` 时），`input` 可选 |
 | 模型 `cost` | 每百万 token 美元；`cache_read`/`cache_write` 可选 |
-| 模型 `tools` / `input` / `output` | 能力：是否支持工具调用、输入/输出模态，默认 `true` / `["text"]` |
+| 模型 `tools` / `input` / `output` | 能力：是否支持工具调用、输入/输出模态，默认 `true` / `["text"]`；**`input` 要多模态必须显式写**（技能会用多选问你） |
 | 模型 `reasoningField` / `maxTokensField` | 映射到 `Model.Compatibility` |
 | 模型 `variants` | `[{ "id": "high", "settings": {} }]` |
 | 模型 `status` / `disabled` | 生命周期标记；`disabled: true` 不出现在 `/models` |
 
-`registry/registry.schema.json` 是同一份规则的 JSON Schema，编辑器可直接校验。
+字段的权威校验是插件里的 `parseRegistry`；维护时用技能 CLI 的 `validate`（组装 → schema → `index.json`/目录/`revision` 一致性）即可，不再随仓放 JSON Schema 文件。
 
 ## 范围之外
 
@@ -167,6 +193,7 @@ API Key 只在你贴入时经过本插件的内存，不落任何本项目自己
 
 ```bash
 node --test                        # 纯逻辑单测（Node ≥ 22 原生 TS，无需依赖）
+node .opencode/skills/opencode-providers-registry/scripts/registry.mjs validate   # 分文件注册表：组装 + schema + index/revision 一致
 node scripts/smoke-api.mjs --list  # 真机冒烟场景（HTTP，不需要 TUI）
 node scripts/smoke-api.mjs         # 全跑：插件已加载 / 供应商已注册 / 凭据→模型→清理
 ```
@@ -174,14 +201,14 @@ node scripts/smoke-api.mjs         # 全跑：插件已加载 / 供应商已注
 `smoke-api.mjs` 的鉴权自动读 `~/.local/state/opencode/service.json`；它的 `models` 场景会写入并删除一条
 临时凭据（label `smoke-throwaway`），且只对「当前没有任何凭据」的供应商生效。
 
-两个入口的打包/语法检查（两个入口都不 import 外部运行时依赖）：
+两个入口的打包/语法检查（TUI 入口的 `@opencode/plugin/tui` 是运行时注入的，必须标 `--external`）：
 
 ```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
+  --external:@opencode/plugin/tui --outfile=dist/providers-tui.js
 ```
 
 改完插件文件**通常无需重启**：插件目录被文件监视，覆盖后自动热重载。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justsilver/opencode-providers",
-  "version": "0.1.0-beta.2",
+  "version": "0.2.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",

package/plugin/opencode-providers/index.ts

@@ -10,22 +10,30 @@
  *   - `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
+ *   - `Rpc.define` is the identity function and plain JSON Schema is accepted,
+ *     so `rpc.ts` needs no `@opencode/*` either
  *
  * 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.
+ *
+ * The registry lives in a closure-local `state`, and both transforms read it at
+ * call time, so the force-refresh RPC can populate a registry that was
+ * unavailable at startup.
  */
 
 import { buildProviderModels, buildProviderSettings } from "./registry/models.ts"
 import { DEFAULT_REGISTRY_URL, loadRegistry } from "./registry/source.ts"
-import type { RegistryCacheEntry } from "./registry/source.ts"
+import type { RegistryCacheEntry, RegistryStore } from "./registry/source.ts"
+import type { Registry } from "./registry/schema.ts"
+import { registryRpc, type RefreshSummary } from "./rpc.ts"
 
 const PLUGIN_ID = "opencode-providers"
 
-/** Tags integrations so the TUI entry can recognise its own. */
-export const INTEGRATION_SOURCE = PLUGIN_ID
+/** Tags integrations so the TUI entry can recognise its own (TUI side keeps its own copy of this string). */
+const INTEGRATION_SOURCE = PLUGIN_ID
 
 interface IntegrationRefLike {
   id: string
@@ -48,8 +56,21 @@ interface SetupContextLike {
     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> }
+  readonly integration: {
+    transform(callback: (editor: IntegrationEditorLike) => void): Promise<unknown>
+    reload(): Promise<unknown>
+  }
+  readonly provider: {
+    transform(callback: (editor: ProviderEditorLike) => void): Promise<unknown>
+    reload(): Promise<unknown>
+  }
+  /** Absent on hosts/versions without the RPC domain; force refresh then degrades to unavailable. */
+  readonly rpc?: {
+    register(
+      definition: unknown,
+      handlers: Record<string, (input: unknown, context: unknown) => Promise<unknown>>,
+    ): Promise<unknown>
+  }
 }
 
 export default {
@@ -61,32 +82,67 @@ export default {
     const url = typeof ctx.options.registryUrl === "string" ? ctx.options.registryUrl : DEFAULT_REGISTRY_URL
     // Cache per URL: switching the registry URL must not keep serving the old body for a TTL.
     const cacheKey = `registry-cache:${url}`
-    const result = await loadRegistry({
-      url,
-      fetch: globalThis.fetch,
-      store: {
-        get: async () => asCacheEntry(await ctx.storage.get(cacheKey)),
-        set: async (entry) => {
-          await ctx.storage.set(cacheKey, entry)
-        },
+    const store: RegistryStore = {
+      get: async () => asCacheEntry(await ctx.storage.get(cacheKey)),
+      set: async (entry) => {
+        await ctx.storage.set(cacheKey, entry)
       },
-    })
+    }
 
-    if (!result.ok) {
-      console.error(`[${PLUGIN_ID}] registry unavailable (${url}): ${result.errors.join("; ")}`)
-      return
+    // Closure-local: repeated `setup` calls (config hot reload) must not share state.
+    const state: { registry?: Registry } = {}
+
+    // Force refresh: bypass the TTL, re-register, and tell the TUI what it got.
+    // A `stale-cache` result means upstream was unreachable, so it counts as a
+    // failure and leaves `state` (and the registered providers) untouched.
+    const refresh = async (): Promise<RefreshSummary> => {
+      const result = await loadRegistry({ url, fetch: globalThis.fetch, store, force: true })
+      if (!result.ok) return { ok: false, errors: [...result.errors] }
+      if (result.source === "stale-cache") {
+        return { ok: false, errors: ["registry refresh failed; serving the cached copy"] }
+      }
+      state.registry = result.registry
+      await ctx.integration.reload()
+      await ctx.provider.reload()
+      return {
+        ok: true,
+        providers: Object.keys(result.registry.providers).length,
+        models: countModels(result.registry),
+        source: result.source,
+        fetchedAt: result.fetchedAt,
+      }
     }
-    if (result.source === "stale-cache") {
+
+    try {
+      await ctx.rpc?.register(registryRpc, { refresh })
+    } catch (error) {
+      // Refresh being unavailable must never block provider registration.
       console.warn(
-        `[${PLUGIN_ID}] registry refresh failed; serving cache from ${new Date(result.fetchedAt).toISOString()}`,
+        `[${PLUGIN_ID}] rpc refresh unavailable: ${error instanceof Error ? error.message : String(error)}`,
       )
     }
 
-    const { registry } = result
-    const entries = Object.entries(registry.providers)
+    const result = await loadRegistry({ url, fetch: globalThis.fetch, store })
+    if (!result.ok) {
+      console.error(`[${PLUGIN_ID}] registry unavailable (${url}): ${result.errors.join("; ")}`)
+    } else {
+      if (result.source === "stale-cache") {
+        console.warn(
+          `[${PLUGIN_ID}] registry refresh failed; serving cache from ${new Date(result.fetchedAt).toISOString()}`,
+        )
+      }
+      if (result.warnings.length > 0) {
+        console.warn(`[${PLUGIN_ID}] skipped registry entries: ${result.warnings.join("; ")}`)
+      }
+      state.registry = result.registry
+    }
 
+    // Always register both transforms (no-op while `state.registry` is empty), so a
+    // later force refresh can recover from a registry that was unavailable at boot.
     await ctx.integration.transform((editor) => {
-      for (const [id, provider] of entries) {
+      const registry = state.registry
+      if (registry === undefined) return
+      for (const [id, provider] of Object.entries(registry.providers)) {
         editor.update(id, (integration) => {
           integration.name = provider.name
           // `metadata` is part of the integration ref and surfaces in `Integration.Info`,
@@ -104,7 +160,9 @@ export default {
     })
 
     await ctx.provider.transform((editor) => {
-      for (const [id, provider] of entries) {
+      const registry = state.registry
+      if (registry === undefined) return
+      for (const [id, provider] of Object.entries(registry.providers)) {
         const models = buildProviderModels(registry, id, provider)
         if (models.length === 0) continue
         const settings = buildProviderSettings(provider)
@@ -125,10 +183,17 @@ export default {
   },
 }
 
+function countModels(registry: Registry): number {
+  let total = 0
+  for (const provider of Object.values(registry.providers)) total += Object.keys(provider.models).length
+  return total
+}
+
 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
+  if (entry.revision !== undefined && typeof entry.revision !== "string") return undefined
   return entry as RegistryCacheEntry
-}
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Split-registry aggregation.
+ *
+ * The registry source is spread across `providers/<id>/{provider,models}.json`
+ * and `models/<lab>/<model>.json`; the plugin pulls the manifest, then every
+ * child file, and reassembles one `Registry`-shaped object for `parseRegistry`.
+ *
+ * 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. Reads are injected so tests can fake
+ * the network.
+ */
+
+import { SUPPORTED_SCHEMA_VERSION, parseRegistry } from "./schema.ts"
+
+export interface Manifest {
+  readonly schemaVersion: number
+  readonly revision: string
+  readonly providers: readonly string[]
+}
+
+export type ParseManifestResult =
+  | { readonly ok: true; readonly manifest: Manifest }
+  | { readonly ok: false; readonly errors: readonly string[] }
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+export function parseManifest(input: unknown): ParseManifestResult {
+  const errors: string[] = []
+  if (!isRecord(input)) return { ok: false, errors: ["manifest: 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})`,
+    )
+  }
+  if (typeof input.revision !== "string" || !input.revision) errors.push("revision: must be a non-empty string")
+
+  let providers: string[] = []
+  if (!Array.isArray(input.providers) || !input.providers.every((id) => typeof id === "string" && id.length > 0)) {
+    errors.push("providers: must be an array of non-empty strings")
+  } else {
+    providers = input.providers as string[]
+  }
+
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    manifest: { schemaVersion: SUPPORTED_SCHEMA_VERSION, revision: input.revision as string, providers },
+  }
+}
+
+export interface AggregatedRegistry {
+  readonly schemaVersion: number
+  readonly models: Record<string, unknown>
+  readonly providers: Record<string, Record<string, unknown>>
+}
+
+export type BuildRegistryResult =
+  | { readonly ok: true; readonly registry: AggregatedRegistry; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly errors: readonly string[]; readonly warnings: readonly string[] }
+
+/** Extracts the `base` references a provider's models declare. */
+function basesOf(models: Record<string, unknown>): string[] {
+  const bases: string[] = []
+  for (const spec of Object.values(models)) {
+    if (isRecord(spec) && typeof spec.base === "string" && spec.base) bases.push(spec.base)
+  }
+  return bases
+}
+
+/**
+ * Fetches every provider + referenced shared model, validates each provider in
+ * isolation, and skips the ones that fail (a single bad provider must not
+ * poison the rest). Returns `ok:false` only when no provider survives.
+ */
+export async function buildRegistry(
+  manifest: Manifest,
+  readJson: (relativePath: string) => Promise<unknown>,
+): Promise<BuildRegistryResult> {
+  const warnings: string[] = []
+
+  const loaded = new Map<string, { provider: Record<string, unknown>; models: Record<string, unknown> }>()
+  await Promise.all(
+    manifest.providers.map(async (id) => {
+      try {
+        const provider = await readJson(`providers/${id}/provider.json`)
+        if (!isRecord(provider)) {
+          warnings.push(`${id}: provider.json must be an object`)
+          return
+        }
+        const models = await readJson(`providers/${id}/models.json`)
+        if (!isRecord(models)) {
+          warnings.push(`${id}: models.json must be an object`)
+          return
+        }
+        loaded.set(id, { provider, models })
+      } catch (error) {
+        warnings.push(`${id}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }),
+  )
+
+  const bases = new Set<string>()
+  for (const entry of loaded.values()) for (const base of basesOf(entry.models)) bases.add(base)
+
+  const fetched: Record<string, unknown> = {}
+  await Promise.all(
+    [...bases].map(async (base) => {
+      try {
+        const model = await readJson(`models/${base}.json`)
+        if (!isRecord(model)) {
+          warnings.push(`shared model ${base}: must be an object`)
+          return
+        }
+        fetched[base] = model
+      } catch (error) {
+        warnings.push(`shared model ${base}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }),
+  )
+
+  // Keep only shared models that pass the schema on their own, so the final
+  // aggregate cannot be rejected by one malformed shared file.
+  const shared: Record<string, unknown> = {}
+  for (const [base, model] of Object.entries(fetched)) {
+    const probe = parseRegistry({
+      schemaVersion: SUPPORTED_SCHEMA_VERSION,
+      models: { [base]: model },
+      providers: { __probe__: { name: "probe", package: "probe", models: { probe: { base } } } },
+    })
+    if (probe.ok) shared[base] = model
+    else warnings.push(`shared model ${base}: ${probe.errors.join("; ")}`)
+  }
+
+  const providers: Record<string, Record<string, unknown>> = {}
+  for (const id of manifest.providers) {
+    const entry = loaded.get(id)
+    if (!entry) continue
+
+    const candidateModels: Record<string, unknown> = {}
+    for (const base of basesOf(entry.models)) if (base in shared) candidateModels[base] = shared[base]
+
+    const candidate = {
+      schemaVersion: SUPPORTED_SCHEMA_VERSION,
+      models: candidateModels,
+      providers: { [id]: { ...entry.provider, models: entry.models } },
+    }
+    const parsed = parseRegistry(candidate)
+    if (!parsed.ok) {
+      warnings.push(`${id}: ${parsed.errors.join("; ")}`)
+      continue
+    }
+    providers[id] = { ...entry.provider, models: entry.models }
+  }
+
+  if (Object.keys(providers).length === 0) {
+    return { ok: false, errors: ["no providers could be loaded"], warnings }
+  }
+  return { ok: true, registry: { schemaVersion: SUPPORTED_SCHEMA_VERSION, models: shared, providers }, warnings }
+}

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

@@ -1,23 +1,33 @@
 /**
- * Registry loading: fetch + TTL + ETag + stale fallback.
+ * Registry loading: manifest fetch + TTL + ETag + revision short-circuit +
+ * force refresh + stale fallback.
+ *
+ * The remote source is split across many files (`index.json` manifest +
+ * `providers/**` + `models/**`); this module fetches the manifest, and only
+ * when its `revision` moved does it pull the child files through
+ * `buildRegistry`. The cache holds the *aggregated* body, so downstream
+ * (`parseRegistry`, `models.ts`) is unchanged.
  *
  * 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 { buildRegistry, parseManifest } from "./aggregate.ts"
 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/registry.json"
+  "https://raw.githubusercontent.com/Just-Silver/opencode-providers/main/registry/index.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
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000
+const DEFAULT_TIMEOUT_MS = 10_000
 
 export interface RegistryCacheEntry {
   readonly etag?: string
+  /** Manifest revision the cached body was built from. */
+  readonly revision?: string
   readonly fetchedAt: number
   readonly body: string
 }
@@ -35,12 +45,20 @@ export interface LoadRegistryOptions {
   readonly now?: () => number
   readonly ttlMs?: number
   readonly timeoutMs?: number
+  /** Bypass the TTL and revalidate now (used by force refresh). */
+  readonly force?: boolean
 }
 
 export type RegistrySource = "cache" | "network" | "stale-cache"
 
 export type LoadRegistryResult =
-  | { readonly ok: true; readonly registry: Registry; readonly source: RegistrySource; readonly fetchedAt: number }
+  | {
+      readonly ok: true
+      readonly registry: Registry
+      readonly source: RegistrySource
+      readonly fetchedAt: number
+      readonly warnings: readonly string[]
+    }
   | { readonly ok: false; readonly errors: readonly string[] }
 
 const isCacheEntry = (value: unknown): value is RegistryCacheEntry =>
@@ -48,7 +66,8 @@ const isCacheEntry = (value: unknown): value is RegistryCacheEntry =>
   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")
+  ((value as RegistryCacheEntry).etag === undefined || typeof (value as RegistryCacheEntry).etag === "string") &&
+  ((value as RegistryCacheEntry).revision === undefined || typeof (value as RegistryCacheEntry).revision === "string")
 
 export async function loadRegistry(options: LoadRegistryOptions): Promise<LoadRegistryResult> {
   const url = options.url ?? DEFAULT_REGISTRY_URL
@@ -58,53 +77,108 @@ export async function loadRegistry(options: LoadRegistryOptions): Promise<LoadRe
 
   const cached = await readCache(options.store)
 
-  if (cached !== undefined && now() - cached.fetchedAt < ttlMs) {
+  if (!options.force && 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 }
+    if (parsed.ok) return success(parsed.registry, "cache", cached.fetchedAt)
   }
 
-  let response: Response
+  let manifestBody: string
+  let manifestEtag: string | undefined
   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),
-    })
+    const headers: Record<string, string> = { accept: "application/json", "user-agent": "opencode-providers" }
+    if (cached?.etag !== undefined) headers["if-none-match"] = cached.etag
+
+    const response = await options.fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) })
+
+    if (response.status === 304 && cached !== undefined) {
+      const parsed = parseBody(cached.body)
+      if (parsed.ok) {
+        const entry = { ...cached, fetchedAt: now() }
+        await writeCache(options.store, entry)
+        return success(parsed.registry, "cache", entry.fetchedAt)
+      }
+      // The cached body is unusable: we cannot rebuild from an empty 304, so
+      // refetch the manifest unconditionally (RF2).
+      const unconditional = await options.fetch(url, {
+        headers: { accept: "application/json", "user-agent": "opencode-providers" },
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      if (!unconditional.ok)
+        return fallback(cached, `registry request failed: ${unconditional.status} ${unconditional.statusText}`)
+      manifestBody = await unconditional.text()
+      manifestEtag = unconditional.headers.get("etag") ?? undefined
+    } else if (response.ok) {
+      manifestBody = await response.text()
+      manifestEtag = response.headers.get("etag") ?? undefined
+    } else {
+      return fallback(cached, `registry request failed: ${response.status} ${response.statusText}`)
+    }
   } 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 }
+  let manifestInput: unknown
+  try {
+    manifestInput = JSON.parse(manifestBody)
+  } catch (error) {
+    const errors = [`registry manifest is not valid JSON: ${errorMessage(error)}`]
+    const stale = await staleFallback(cached, errors)
+    return stale ?? { ok: false, errors }
   }
 
-  if (!response.ok) return fallback(cached, `registry request failed: ${response.status} ${response.statusText}`)
+  const manifest = parseManifest(manifestInput)
+  if (!manifest.ok) {
+    const stale = await staleFallback(cached, manifest.errors)
+    return stale ?? { ok: false, errors: [...manifest.errors] }
+  }
 
-  let body: string
-  try {
-    body = await response.text()
-  } catch (error) {
-    return fallback(cached, errorMessage(error))
+  // Short-circuit: same revision and a healthy cached aggregate → no child
+  // fetches. A corrupt cached body falls through and is rebuilt.
+  if (cached !== undefined && cached.revision !== undefined && cached.revision === manifest.manifest.revision) {
+    const parsed = parseBody(cached.body)
+    if (parsed.ok) {
+      const entry = {
+        ...cached,
+        ...(manifestEtag === undefined ? {} : { etag: manifestEtag }),
+        fetchedAt: now(),
+      }
+      await writeCache(options.store, entry)
+      return success(parsed.registry, "cache", entry.fetchedAt)
+    }
   }
 
-  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 built = await buildRegistry(manifest.manifest, async (relativePath) => {
+    const childUrl = new URL(relativePath, url).toString()
+    const response = await options.fetch(childUrl, {
+      headers: { accept: "application/json", "user-agent": "opencode-providers" },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!response.ok) throw new Error(`registry request failed: ${response.status} ${response.statusText}`)
+    return JSON.parse(await response.text())
+  })
+
+  if (!built.ok) {
+    const stale = await staleFallback(cached, built.errors)
+    return stale ?? { ok: false, errors: [...built.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 }
+  await writeCache(options.store, {
+    ...(manifestEtag === undefined ? {} : { etag: manifestEtag }),
+    revision: manifest.manifest.revision,
+    fetchedAt,
+    body: JSON.stringify(built.registry),
+  })
+  return success(built.registry, "network", fetchedAt, built.warnings)
+}
+
+function success(
+  registry: Registry,
+  source: RegistrySource,
+  fetchedAt: number,
+  warnings: readonly string[] = [],
+): LoadRegistryResult {
+  return { ok: true, registry, source, fetchedAt, warnings }
 }
 
 /** A cache-write failure must never break loading; the payload is served regardless. */
@@ -148,9 +222,9 @@ async function staleFallback(
   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 }
+  return { ok: true, registry: parsed.registry, source: "stale-cache", fetchedAt: cached.fetchedAt, warnings: [...errors] }
 }
 
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
-}
+}

package/plugin/opencode-providers/rpc.ts

@@ -0,0 +1,41 @@
+/**
+ * RPC definition for the server entry's force refresh.
+ *
+ * Plain JSON Schema — no `effect`, no `@opencode/*` — so `index.ts` stays free
+ * of `@opencode/*` imports (a locally installed server plugin does not get the
+ * module injected). `Rpc.define` is the identity function and the core parser
+ * accepts plain JSON Schema, so `ctx.rpc.register(registryRpc, …)` can take this
+ * object as-is.
+ */
+
+export const registryRpc = {
+  id: "opencode-providers",
+  methods: {
+    refresh: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: {
+        type: "object",
+        properties: {
+          ok: { type: "boolean" },
+          providers: { type: "number" },
+          models: { type: "number" },
+          source: { type: "string" },
+          fetchedAt: { type: "number" },
+          errors: { type: "array", items: { type: "string" } },
+        },
+        required: ["ok"],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {},
+} as const
+
+export interface RefreshSummary {
+  readonly ok: boolean
+  readonly providers?: number
+  readonly models?: number
+  readonly source?: string
+  readonly fetchedAt?: number
+  readonly errors?: readonly string[]
+}

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

@@ -14,6 +14,8 @@
 import type { IntegrationInfo } from "@opencode/client"
 import type { Plugin } from "@opencode/plugin/tui"
 
+import { registryRpc } from "../rpc.ts"
+
 type Context = Plugin.Context
 type Connection = IntegrationInfo["connections"][number]
 
@@ -24,11 +26,19 @@ 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({
+    // Nothing to connect yet — offer the refresh here rather than making the user
+    // restart the service and wait out the 6h TTL.
+    const confirmed = await ctx.ui.dialog.confirm({
       title: "Connect providers",
       message:
-        "No providers from the registry are available. Check that the registry loaded (server log) and restart the service.",
+        "No providers from the registry are available. Force a refresh to re-fetch the registry, then run /connect-providers again.",
+      label: { confirm: "Force refresh" },
     })
+    if (confirmed) {
+      if (await forceRefresh(ctx)) {
+        ctx.ui.toast.show({ variant: "info", message: "Reloaded. Run /connect-providers again to connect a provider." })
+      }
+    }
     return
   }
 
@@ -39,6 +49,14 @@ export async function connectProviders(ctx: Context): Promise<void> {
       value: integration.id,
       footer: footer(integration),
     })),
+    actions: [
+      {
+        title: "Force refresh",
+        bind: "ctrl+r",
+        selection: "none",
+        onTrigger: () => void forceRefresh(ctx),
+      },
+    ],
   })
   if (selected === undefined) return
 
@@ -48,6 +66,32 @@ export async function connectProviders(ctx: Context): Promise<void> {
   await openProvider(ctx, integration)
 }
 
+/**
+ * Re-fetch the registry through the server RPC (bypasses the TTL) and refresh the
+ * provider list. Returns whether it succeeded. A failure only surfaces as an
+ * error toast: the previously registered providers stay usable, so nothing is
+ * invalidated.
+ */
+export async function forceRefresh(ctx: Context): Promise<boolean> {
+  try {
+    const result = await ctx.client.rpc(registryRpc).refresh({})
+    if (!result.ok) {
+      const detail = (result.errors ?? ["unknown error"]).join("; ")
+      ctx.ui.toast.show({ variant: "error", message: `Registry refresh failed: ${detail}` })
+      return false
+    }
+    ctx.data.location.integration.invalidate(ctx.location)
+    ctx.ui.toast.show({
+      variant: "success",
+      message: `Registry refreshed: ${result.providers ?? 0} providers, ${result.models ?? 0} models`,
+    })
+    return true
+  } catch (error) {
+    ctx.ui.toast.show({ variant: "error", message: message(error) })
+    return false
+  }
+}
+
 async function openProvider(ctx: Context, integration: IntegrationInfo): Promise<void> {
   const credentials = credentialConnections(integration)
   const active = credentials[0]
@@ -123,18 +167,13 @@ function credentialConnections(integration: IntegrationInfo): Array<Extract<Conn
 }
 
 function footer(integration: IntegrationInfo): string | undefined {
-  const pending = integration.connections.find((connection) => pendingUrl(connection) !== undefined)
-  if (pending) return "Sign in required →"
+  // Key-only by design (the registry only ever declares a `key` method), so there is
+  // no OAuth "pending" connection to advertise here — only existing account labels.
   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)
 }