@dan-ai-studio/dshopencodego 0.1.45 → 0.1.47

package/README.en.md

@@ -6,12 +6,18 @@ Makes [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) work p
 
 ## Why it exists
 
-A stock DSH route to OpenCode Go has two gaps that no configuration can close:
+A stock DSH route to OpenCode Go already works (`llm-pi-ai` ships the provider). What this plugin adds is what that route does **not** do:
 
-1. **The model list is a build-time snapshot.** DSH's `llm-pi-ai` uses the catalog pi-ai shipped with; when the gateway adds a model, you either wait for a pi-ai release or declare it by hand.
-2. **No session header.** Since 2026-09-05 Go requires a stable `x-opencode-session` on every request and answers `400 MissingSessionID` without it; `llm-pi-ai` sends only static profile headers, which cannot vary per conversation.
+| Capability | Stock DSH | This plugin |
+| --- | --- | --- |
+| **Live model catalog** | A build-time snapshot: the fixed table pi-ai ships with, so a new gateway model waits for a pi-ai release | Reads the gateway catalog live, with multi-level fallback and TTL caching |
+| **Quota windows** (5-hour / weekly / monthly) | None | ✅ |
+| **Estimated spend** | None | ✅ |
+| **Per-model switches** `modelVisibility` | None | ✅ |
+
+This plugin serves the `opencode-go` route with its own adapter and adds the usage and settings surfaces.
 
-This plugin serves the `opencode-go` route with its own adapter and closes both gaps.
+> **On the session header**: Go requires a stable `x-opencode-session` on every request and answers `400 MissingSessionID` without it. That was one of this plugin's original reasons to exist, but pi-ai implemented the injection on 2026-09-09 (`561a2e06`) and `llm-pi-ai` carries it automatically, so a stock DSH route does not miss the header either. This plugin still keeps its own implementation — it falls back to a one-off UUID when a session id is missing — until that fallback lands upstream; the review is in [`docs/scope-review-2026-10.md`](docs/scope-review-2026-10.md).
 
 ## Install
 
@@ -241,7 +247,7 @@ npm test            # contract tests against a real local HTTP mock gateway
 
 **Order matters**: `npm run build` must come before `npm test` — `tests/pack-contents.spec.ts` walks every `exports` target, and whether `lib/` exists decides whether that check runs or is silently skipped (it does not fail, it just stops protecting you). `package.json` no longer carries `prepare`, so `npm ci` will not build for you; all three CI workflows run `npm run build` explicitly.
 
-The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest). That is **43 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
+The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest, and the READMEs' claims about the upstream match the upstream actually installed). That is **45 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
 
 ## Releasing (maintainers)
 

package/README.md

@@ -6,12 +6,18 @@
 
 ## 为什么需要它
 
-原生 DSH 接 OpenCode Go 有两个缺口，都不是配置能补的：
+原生 DSH 已经能连 OpenCode Go（`llm-pi-ai` 内置该 provider）。本插件补的是它**不提供**的那几件事：
 
-1. **模型列表是构建期快照**。DSH 的 `llm-pi-ai` 用 pi-ai 打包时生成的目录；网关新增模型后，要么等 pi-ai 发版，要么手工声明。
-2. **没有会话头**。Go 自 2026-09-05 起要求每个请求带稳定的 `x-opencode-session`，缺失即 `400 MissingSessionID`；`llm-pi-ai` 只发静态 profile headers，无法按会话取值。
+| 能力 | 原生 DSH | 本插件 |
+| --- | --- | --- |
+| **实时模型目录** | 构建期快照：pi-ai 打包时生成的固定表，网关新增模型要等 pi-ai 发版 | 实时读取网关目录，多级回退 + TTL 缓存 |
+| **额度窗口**（5 小时 / 本周 / 本月） | 无 | ✅ |
+| **花费估算** | 无 | ✅ |
+| **逐模型开关** `modelVisibility` | 无 | ✅ |
+
+本插件为 `opencode-go` 路由提供自己的适配器，并提供用量与设置界面。
 
-本插件为 `opencode-go` 路由提供自己的适配器，同时解决这两点。
+> **关于会话头**：Go 要求每个请求带稳定的 `x-opencode-session`，缺失即 `400 MissingSessionID`。这一项曾是本插件的原始存在理由，但 pi-ai 已于 2026-09-09（`561a2e06`）实现注入、`llm-pi-ai` 自动携带，因此**原生 DSH 现在也不会缺会话头**。本插件当前仍保留自己的实现（为缺失会话 id 的请求提供一次性 UUID 兜底），待该兜底进入上游后再收缩——评估过程见 [`docs/scope-review-2026-10.md`](docs/scope-review-2026-10.md)。
 
 ## 安装
 
@@ -241,7 +247,7 @@ npm test            # 契约测试：真实 HTTP mock 网关，断言请求头/
 
 **顺序有讲究**：`npm run build` 要排在 `npm test` 之前——`tests/pack-contents.spec.ts` 会遍历 `exports` 的每个目标，`lib/` 存在与否决定这条检查是执行还是被跳过（不报错，但会少一层保护）。`package.json` 已移除 `prepare`，因此 `npm ci` 不会再替你隐式构建；三个 CI workflow 都显式跑了 `npm run build`。
 
-测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致）。共 **43 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
+测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **45 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
 
 ## 发布（维护者）
 

package/lib/client.js

@@ -29,6 +29,7 @@ module.exports = __toCommonJS(index_exports);
 // src/catalog/constants.ts
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
+var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
 
 // src/catalog/metadata.ts
 var INPUT_MODALITIES = ["text", "image", "audio", "video", "pdf"];
@@ -84,12 +85,27 @@ function parseModel(value) {
     ...typeof row["releaseDate"] === "string" ? { releaseDate: row["releaseDate"] } : {},
     ...row["goQuota"] === void 0 ? {} : { goQuota: parseGoQuota(row["goQuota"]) },
     ...row["cost"] === void 0 ? {} : { cost: parseCost(row["cost"]) },
-    ...row["protocolSource"] === "builtin" || row["protocolSource"] === "online" || row["protocolSource"] === "inferred" || row["protocolSource"] === "override" ? { protocolSource: row["protocolSource"] } : {},
+    // `document` is the provider's own endpoint table — the most authoritative
+    // evidence there is — so it must survive the wire. Dropping it made a
+    // documented protocol indistinguishable from an unknown one on the page.
+    ...row["protocolSource"] === "builtin" || row["protocolSource"] === "document" || row["protocolSource"] === "online" || row["protocolSource"] === "inferred" || row["protocolSource"] === "override" ? { protocolSource: row["protocolSource"] } : {},
     ...typeof row["assumedLimits"] === "boolean" ? { assumedLimits: row["assumedLimits"] } : {},
     ...parseModalities(row["inputModalities"]),
     ...typeof row["configurationMissing"] === "string" ? { configurationMissing: row["configurationMissing"] } : {}
   };
 }
+function parseDegradations(value) {
+  if (!Array.isArray(value)) return [];
+  const kept = [];
+  for (const item of value) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+    const row = item;
+    if (row["source"] !== "metadata" && row["source"] !== "document") continue;
+    if (typeof row["reason"] !== "string") continue;
+    kept.push({ source: row["source"], reason: row["reason"] });
+  }
+  return kept;
+}
 function parseCatalogReading(value) {
   if (value === null || typeof value !== "object") throw new Error("invalid catalog reading");
   const row = value;
@@ -111,6 +127,7 @@ function parseCatalogReading(value) {
     models: row["models"].map(parseModel),
     stale: row["stale"],
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
+    degradations: parseDegradations(row["degradations"]),
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -309,6 +326,9 @@ var en = {
   catalogSelectAll: "Select all",
   catalogSelectNone: "Select none",
   catalogStale: "Showing the last successful listing",
+  catalogDegraded: "Catalog degraded",
+  catalogDegradedMetadata: "model metadata (models.dev) unavailable",
+  catalogDegradedDocument: "provider documentation unavailable",
   catalogCountUnit: "models",
   catalogInferred: "protocol inferred",
   catalogAssumed: "default capacities",
@@ -405,6 +425,9 @@ var zh = {
   catalogSelectAll: "\u5168\u9009",
   catalogSelectNone: "\u5168\u4E0D\u9009",
   catalogStale: "\u5F53\u524D\u663E\u793A\u7684\u662F\u4E0A\u6B21\u6210\u529F\u83B7\u53D6\u7684\u5217\u8868",
+  catalogDegraded: "\u76EE\u5F55\u5DF2\u964D\u7EA7",
+  catalogDegradedMetadata: "\u6A21\u578B\u5143\u6570\u636E\uFF08models.dev\uFF09\u4E0D\u53EF\u7528",
+  catalogDegradedDocument: "\u5382\u5546\u6587\u6863\u4E0D\u53EF\u7528",
   catalogCountUnit: "\u4E2A\u6A21\u578B",
   catalogInferred: "\u534F\u8BAE\u4E3A\u63A8\u65AD",
   catalogAssumed: "\u5BB9\u91CF\u4E3A\u9ED8\u8BA4\u503C",
@@ -1211,6 +1234,11 @@ function Section({ controller, t, getLocale }) {
         state.failure
       ] }),
       reading !== void 0 && reading.stale && state.failure === void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: section_default.warn, children: t("catalogStale") }),
+      reading !== void 0 && reading.degradations.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { className: section_default.warn, children: [
+        t("catalogDegraded"),
+        ": ",
+        reading.degradations.map((degradation) => `${t(degradation.source === "metadata" ? "catalogDegradedMetadata" : "catalogDegradedDocument")} \u2014 ${degradation.reason}`).join("; ")
+      ] }),
       reading !== void 0 && reading.quotaSource === "seed" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { className: section_default.hint, children: [
         t("quotaSeed"),
         " ",

package/lib/index.js

@@ -42530,6 +42530,7 @@ var MODEL_METADATA_PROVIDER = "opencode-go";
 var METADATA_FETCH_TIMEOUT_MS = 1e4;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
+var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
 
 // src/catalog/gateway.ts
 import { attributionHeaders, LlmError as LlmError2 } from "@deepseek-ai/dsh-llm";
@@ -42626,8 +42627,8 @@ async function fetchModelIds(baseURL, signal) {
 // src/catalog/go-doc.ts
 import { attributionHeaders as attributionHeaders2, LlmError as LlmError3 } from "@deepseek-ai/dsh-llm";
 var GO_DOC_URLS = [
-  "https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/content/docs/go.mdx",
-  "https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/packages/web/src/content/docs/go.mdx"
+  "https://raw.githubusercontent.com/anomalyco/opencode/dev/services/www/src/docs/content/console/go.mdx",
+  "https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/services/www/src/docs/content/console/go.mdx"
 ];
 var GO_DOC_MAX_BYTES = 1024 * 1024;
 var ENDPOINT_PROTOCOLS = {
@@ -42716,7 +42717,9 @@ async function readSource(url, signal) {
       return { failure: `${url} answered HTTP ${response.status}` };
     }
     const document = parseGoDocument(await readBoundedText(response, GO_DOC_MAX_BYTES));
-    if (document.quotas.size === 0) return { failure: `${url} carried no allowance table` };
+    if (document.quotas.size === 0 && document.protocols.size === 0) {
+      return { failure: `${url} carried neither an allowance table nor an endpoint table` };
+    }
     return { document };
   } catch (error) {
     return { failure: `${url}: ${error instanceof Error ? error.message : String(error)}` };
@@ -42949,6 +42952,10 @@ function toPiModel(facts, baseURL) {
 }
 
 // src/catalog/index.ts
+function reasonText(reason) {
+  if (reason instanceof Error) return reason.message;
+  return typeof reason === "string" ? reason : String(reason);
+}
 function builtinModels(baseURL) {
   return new Map(Object.values(OPENCODE_GO_MODELS).map((model) => [model.id, {
     ...model,
@@ -42994,6 +43001,8 @@ var OpencodeGoCatalog = class {
   lastMetadata;
   /** The last parsed documentation; retained across failed fetches. */
   document;
+  /** Ids that already forced a revalidation, with the time they did. */
+  probedAt = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = options;
   }
@@ -43030,7 +43039,8 @@ var OpencodeGoCatalog = class {
    */
   async forModel(id, signal) {
     let snapshot2 = await this.snapshot();
-    if (!snapshot2.facts.has(id) && !snapshot2.unavailable.has(id)) {
+    if (!snapshot2.facts.has(id) && !snapshot2.unavailable.has(id) && this.mayProbe(id)) {
+      this.probedAt.set(id, Date.now());
       snapshot2 = await this.snapshot(true, signal);
     }
     const reason = snapshot2.unavailable.get(id);
@@ -43042,6 +43052,22 @@ var OpencodeGoCatalog = class {
     }
     return snapshot2;
   }
+  /**
+   * Whether this id may revalidate the catalog again.
+   *
+   * The revalidation is what makes a newly published model usable without a
+   * restart, so it cannot simply be dropped. It is also the most expensive
+   * thing this route does — the metadata document is megabytes — and the host
+   * resolves a model on every list and on every new session. An id that never
+   * resolves would therefore pay that cost forever, which is how a plugin
+   * makes a host slow down over time rather than start slow.
+   * @param id - the model id that was not found.
+   * @returns true when the id may force a revalidation now.
+   */
+  mayProbe(id) {
+    const last = this.probedAt.get(id);
+    return last === void 0 || Date.now() - last >= UNKNOWN_MODEL_PROBE_COOLDOWN_MS;
+  }
   /**
    * Revalidate every source, reusing the metadata document when it is unchanged.
    * @param signal - caller cancellation, forwarded to the documentation read.
@@ -43054,7 +43080,9 @@ var OpencodeGoCatalog = class {
       this.refreshMetadata(builtin),
       readDocument(signal)
     ]);
+    const degradations = [];
     if (metadata.status === "rejected") {
+      degradations.push({ source: "metadata", reason: reasonText(metadata.reason) });
       this.options.observers?.onFallback?.({
         url: MODEL_METADATA_URL,
         error: metadata.reason,
@@ -43064,6 +43092,7 @@ var OpencodeGoCatalog = class {
     if (documentation.status === "fulfilled") {
       this.document = documentation.value;
     } else {
+      degradations.push({ source: "document", reason: reasonText(documentation.reason) });
       this.options.observers?.onFallback?.({
         url: GO_DOC_URLS[0] ?? "the Go documentation",
         error: documentation.reason,
@@ -43084,6 +43113,7 @@ var OpencodeGoCatalog = class {
         provider: buildProvider2(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
         live: false,
         listingFailure: listing.reason,
+        ...degradations.length === 0 ? {} : { degradations },
         fetchedAtMs: Date.now(),
         ...this.documentQuotas()
       };
@@ -43091,17 +43121,18 @@ var OpencodeGoCatalog = class {
     return this.assemble(
       listing.value,
       metadata.status === "fulfilled" ? metadata.value : this.lastMetadata,
-      builtin
+      builtin,
+      degradations
     );
   }
   /** Merge the listing with the metadata document and the installed entries. */
-  assemble(ids, online, builtin) {
+  assemble(ids, online, builtin, degradations = []) {
     const facts = /* @__PURE__ */ new Map();
     const unavailable = /* @__PURE__ */ new Map();
     for (const id of ids) {
       const parsed = online?.models.get(id);
       if (parsed !== void 0) {
-        facts.set(id, parsed);
+        facts.set(id, this.withDocumentedProtocol(parsed));
         continue;
       }
       const reason = online?.errors.get(id);
@@ -43126,13 +43157,22 @@ var OpencodeGoCatalog = class {
       unavailable,
       provider: buildProvider2(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
       live: true,
+      ...degradations.length === 0 ? {} : { degradations },
       fetchedAtMs: Date.now(),
       ...this.documentQuotas()
     };
   }
-  /** The document allowances as a snapshot field, absent until one fetch lands. */
+  /**
+   * The document allowances as a snapshot field, absent until one fetch lands.
+   *
+   * A document that carries no allowance table leaves the field absent rather
+   * than empty, so the frozen seed in `go-limits.ts` answers instead. An empty
+   * map would look like "the provider states no allowance for any model", and
+   * that is a different claim from "this build has no live allowances".
+   */
   documentQuotas() {
-    return this.document === void 0 ? {} : { documentQuotas: this.document.quotas };
+    if (this.document === void 0 || this.document.quotas.size === 0) return {};
+    return { documentQuotas: this.document.quotas };
   }
   /**
    * Prefer the documented protocol over anything below the installed catalog.
@@ -45272,12 +45312,27 @@ function parseModel(value) {
     ...typeof row["releaseDate"] === "string" ? { releaseDate: row["releaseDate"] } : {},
     ...row["goQuota"] === void 0 ? {} : { goQuota: parseGoQuota(row["goQuota"]) },
     ...row["cost"] === void 0 ? {} : { cost: parseCost(row["cost"]) },
-    ...row["protocolSource"] === "builtin" || row["protocolSource"] === "online" || row["protocolSource"] === "inferred" || row["protocolSource"] === "override" ? { protocolSource: row["protocolSource"] } : {},
+    // `document` is the provider's own endpoint table — the most authoritative
+    // evidence there is — so it must survive the wire. Dropping it made a
+    // documented protocol indistinguishable from an unknown one on the page.
+    ...row["protocolSource"] === "builtin" || row["protocolSource"] === "document" || row["protocolSource"] === "online" || row["protocolSource"] === "inferred" || row["protocolSource"] === "override" ? { protocolSource: row["protocolSource"] } : {},
     ...typeof row["assumedLimits"] === "boolean" ? { assumedLimits: row["assumedLimits"] } : {},
     ...parseModalities(row["inputModalities"]),
     ...typeof row["configurationMissing"] === "string" ? { configurationMissing: row["configurationMissing"] } : {}
   };
 }
+function parseDegradations(value) {
+  if (!Array.isArray(value)) return [];
+  const kept = [];
+  for (const item of value) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+    const row = item;
+    if (row["source"] !== "metadata" && row["source"] !== "document") continue;
+    if (typeof row["reason"] !== "string") continue;
+    kept.push({ source: row["source"], reason: row["reason"] });
+  }
+  return kept;
+}
 function parseCatalogReading(value) {
   if (value === null || typeof value !== "object") throw new Error("invalid catalog reading");
   const row = value;
@@ -45299,6 +45354,7 @@ function parseCatalogReading(value) {
     models: row["models"].map(parseModel),
     stale: row["stale"],
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
+    degradations: parseDegradations(row["degradations"]),
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -45539,6 +45595,7 @@ function catalogReading(snapshot2, visibility, listingFailure, now) {
     models: sortModels(models, now),
     stale: !snapshot2.live,
     ...!snapshot2.live && listingFailure !== void 0 ? { error: listingFailure } : {},
+    degradations: snapshot2.degradations ?? [],
     fetchedAtMs: snapshot2.fetchedAtMs,
     quotaSource: documentQuotas === void 0 ? "seed" : "document",
     counts: {
@@ -45707,7 +45764,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.45" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.47" : "0.0.0-dev";
 
 // src/update/service.ts
 import { TypertRemoteService as TypertRemoteService2 } from "@deepseek-ai/dsh-typert-protocol";

package/lib/types/catalog/constants.d.ts

@@ -16,3 +16,19 @@ export declare const METADATA_FETCH_TIMEOUT_MS = 10000;
 /** Response caps: the listing is tiny, the metadata document is not. */
 export declare const MODEL_LISTING_MAX_BYTES: number;
 export declare const MODEL_METADATA_MAX_BYTES: number;
+/**
+ * How long one unknown model id waits before it may revalidate the catalog
+ * again.
+ *
+ * An id the catalog has never seen forces one revalidation, because "this
+ * build has not seen it" and "it was just published" look the same from here.
+ * Without a cooldown, an id that will never resolve — a mistyped id, a model
+ * the gateway retired, a stale entry in a session — makes every single model
+ * resolution refetch the whole metadata document, which is megabytes. The
+ * host resolves a model on every list and on every new session, so that cost
+ * is paid over and over for an id whose answer will not change.
+ *
+ * Five minutes is short enough that a genuinely new model still shows up
+ * without a restart, and long enough that a bad id costs one fetch.
+ */
+export declare const UNKNOWN_MODEL_PROBE_COOLDOWN_MS: number;

package/lib/types/catalog/go-doc.d.ts

@@ -20,6 +20,13 @@ import type { WireProtocol } from './protocol.ts';
  *
  * The repository file is the source of truth; the jsDelivr entry caches the
  * same path and is tried when GitHub itself is unreachable.
+ *
+ * The path is the provider's own, and it moves: `go.mdx` used to live at
+ * `packages/web/src/content/docs/go.mdx` and the `packages/web` tree was
+ * restructured, after which every request answered 404. A document that cannot
+ * be read costs the endpoint table — the provider's own statement of each
+ * model's protocol — so the path is asserted against the live repository by
+ * `tests/go-doc-url.spec.ts` rather than left to rot unnoticed.
  */
 export declare const GO_DOC_URLS: readonly string[];
 /** What one parse of the document yields. */
@@ -37,6 +44,12 @@ export interface GoDoc {
  * endpoint table and the other two attach by normalised display name. A row
  * that names no known model, or states no usable number, is skipped rather than
  * guessed; a tiered model whose rows disagree is dropped entirely.
+ *
+ * The two tables are read independently because the provider's page has
+ * carried them at different times: the endpoint table names each model's
+ * protocol, and the allowance table states the monthly allowance. A document
+ * that keeps one and drops the other is still worth reading — the one it
+ * keeps is evidence the other source cannot supply.
  * @param markdown - the raw document text.
  * @returns the parsed allowances and protocols; both may be empty when the
  *   document does not carry the expected tables.

package/lib/types/catalog/index.d.ts

@@ -29,6 +29,22 @@ export { readOnlineMetadata, toPiModel, modelBaseURL } from './metadata.ts';
 export type { ModelFacts, OnlineMetadata, ModelDefaults } from './metadata.ts';
 export { decideProtocol, inferProtocol, protocolOfNpm } from './protocol.ts';
 export type { ProtocolDecision, ProtocolSource, WireProtocol } from './protocol.ts';
+/**
+ * One source the catalog could not read.
+ *
+ * A degradation is not a failure: the snapshot still answers, from the
+ * installed catalog and the frozen seed. But it is not the same answer, and
+ * the difference is invisible unless it is said out loud — a model whose
+ * protocol was inferred reads exactly like one whose protocol the provider
+ * documented, and a thinking level that the online metadata would have
+ * supplied is simply absent.
+ */
+export interface CatalogDegradation {
+    /** Which source could not be read. */
+    readonly source: 'metadata' | 'document';
+    /** Why it failed, in the source's own words. */
+    readonly reason: string;
+}
 /** One resolved view of the gateway's models. */
 export interface CatalogSnapshot {
     /** Models that can be called, by id, with the evidence behind each decision. */
@@ -47,6 +63,16 @@ export interface CatalogSnapshot {
     readonly documentQuotas?: ReadonlyMap<string, GoQuota>;
     /** Retained for explicit discovery when the listing failed. */
     readonly listingFailure?: unknown;
+    /**
+     * Sources this build could not read.
+     *
+     * Empty when every source answered. Otherwise the reading is degraded: the
+     * protocol of a model no installed entry describes falls back to a guess,
+     * and the thinking levels the online metadata carries are missing. The page
+     * shows this, because a degraded reading that looks whole is the one state
+     * a user cannot act on.
+     */
+    readonly degradations?: readonly CatalogDegradation[];
     readonly fetchedAtMs: number;
 }
 /** Observers the plugin logs through. */
@@ -94,6 +120,8 @@ export declare class OpencodeGoCatalog {
     private lastMetadata;
     /** The last parsed documentation; retained across failed fetches. */
     private document;
+    /** Ids that already forced a revalidation, with the time they did. */
+    private readonly probedAt;
     constructor(options: CatalogOptions);
     /**
      * The cached snapshot, refreshed when it is older than the configured TTL.
@@ -116,6 +144,19 @@ export declare class OpencodeGoCatalog {
      *   the id but this build cannot configure it, naming the reason.
      */
     forModel(id: string, signal?: AbortSignal): Promise<CatalogSnapshot>;
+    /**
+     * Whether this id may revalidate the catalog again.
+     *
+     * The revalidation is what makes a newly published model usable without a
+     * restart, so it cannot simply be dropped. It is also the most expensive
+     * thing this route does — the metadata document is megabytes — and the host
+     * resolves a model on every list and on every new session. An id that never
+     * resolves would therefore pay that cost forever, which is how a plugin
+     * makes a host slow down over time rather than start slow.
+     * @param id - the model id that was not found.
+     * @returns true when the id may force a revalidation now.
+     */
+    private mayProbe;
     /**
      * Revalidate every source, reusing the metadata document when it is unchanged.
      * @param signal - caller cancellation, forwarded to the documentation read.
@@ -123,7 +164,14 @@ export declare class OpencodeGoCatalog {
     private build;
     /** Merge the listing with the metadata document and the installed entries. */
     private assemble;
-    /** The document allowances as a snapshot field, absent until one fetch lands. */
+    /**
+     * The document allowances as a snapshot field, absent until one fetch lands.
+     *
+     * A document that carries no allowance table leaves the field absent rather
+     * than empty, so the frozen seed in `go-limits.ts` answers instead. An empty
+     * map would look like "the provider states no allowance for any model", and
+     * that is a different claim from "this build has no live allowances".
+     */
     private documentQuotas;
     /**
      * Prefer the documented protocol over anything below the installed catalog.

package/lib/types/catalog/reading.d.ts

@@ -11,6 +11,7 @@
  */
 import type { ModelSummary } from '../models.ts';
 import type { CatalogSnapshot } from './index.ts';
+import type { CatalogDegradation } from './index.ts';
 /** One settings-page reading of the catalog. */
 export interface CatalogReading {
     /** Every advertised model, new first, deprecated last. */
@@ -19,6 +20,15 @@ export interface CatalogReading {
     readonly stale: boolean;
     /** Why the reading is stale, when it is. */
     readonly error?: string;
+    /**
+     * Sources this reading could not read.
+     *
+     * Empty when every source answered. Otherwise the page is showing a
+     * degraded catalog: a protocol that no source describes is a guess, and the
+     * thinking levels the online metadata carries are missing. Saying so is the
+     * difference between a user who can act and a user who cannot.
+     */
+    readonly degradations: readonly CatalogDegradation[];
     /** When the underlying snapshot was built. */
     readonly fetchedAtMs: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dan-ai-studio/dshopencodego",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",