@dan-ai-studio/dshopencodego 0.1.46 → 0.1.48

package/README.en.md

@@ -247,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, and the READMEs' claims about the upstream match the upstream actually installed). That is **44 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 **46 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
 
 ## Releasing (maintainers)
 

package/README.md

@@ -247,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 一致、README 对上游的断言与实装的上游一致）。共 **44 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
+测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **46 个测试文件**——这个数字由 `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

@@ -17788,8 +17788,8 @@ function getBunSandboxEnvValue(name2) {
   if (procEnvCache === null) {
     procEnvCache = /* @__PURE__ */ new Map();
     try {
-      const { readFileSync } = __require("node:fs");
-      const data = readFileSync("/proc/self/environ", "utf-8");
+      const { readFileSync: readFileSync2 } = __require("node:fs");
+      const data = readFileSync2("/proc/self/environ", "utf-8");
       for (const entry of data.split("\0")) {
         const idx = entry.indexOf("=");
         if (idx > 0) {
@@ -42462,6 +42462,8 @@ Check your ChatGPT usage: ${CHATGPT_USAGE_URL}` : errorMessage;
 });
 
 // src/index.ts
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import * as llm2 from "@deepseek-ai/dsh-llm";
@@ -42530,6 +42532,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";
@@ -42625,9 +42628,81 @@ async function fetchModelIds(baseURL, signal) {
 
 // src/catalog/go-doc.ts
 import { attributionHeaders as attributionHeaders2, LlmError as LlmError3 } from "@deepseek-ai/dsh-llm";
+
+// src/catalog/go-doc-discovery.ts
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+var DISCOVERY_URL = "https://api.github.com/repos/anomalyco/opencode/git/trees/dev?recursive=1";
+var DOCUMENT_NAME = /^go[^/]*\.mdx$/i;
+var DISCOVERY_MAX_BYTES = 8 * 1024 * 1024;
+var DISCOVERY_TIMEOUT_MS = 1e4;
+var CACHE_FILE = "go-doc-paths.json";
+var CACHE_VERSION = 1;
+function selectDocumentPaths(paths) {
+  const selected = [];
+  for (const path5 of paths) {
+    const name2 = path5.slice(path5.lastIndexOf("/") + 1);
+    if (!DOCUMENT_NAME.test(name2)) continue;
+    if (!/(^|\/)(docs?|content|console)\//i.test(path5) && !/^packages\/web\/src\/content\/docs\//i.test(path5)) continue;
+    selected.push(path5);
+  }
+  return selected.sort((left, right) => right.length - left.length);
+}
+function mirrorsOf(path5) {
+  const encoded = path5.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  return [
+    `https://raw.githubusercontent.com/anomalyco/opencode/dev/${encoded}`,
+    `https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/${encoded}`
+  ];
+}
+async function discoverDocumentPaths(signal, fetchImpl = fetch) {
+  const timeout = AbortSignal.timeout(DISCOVERY_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(DISCOVERY_URL, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "dshopencodego" },
+      signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout])
+    });
+    if (!response.ok) return [];
+    const body = await response.text();
+    if (body.length > DISCOVERY_MAX_BYTES) return [];
+    const listing = JSON.parse(body);
+    const paths = (listing.tree ?? []).map((entry) => entry.path).filter((path5) => typeof path5 === "string");
+    return selectDocumentPaths(paths);
+  } catch {
+    return [];
+  }
+}
+function readCachedPaths(cacheDir) {
+  if (cacheDir === void 0) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(join2(cacheDir, CACHE_FILE), "utf8"));
+    if (parsed.version !== CACHE_VERSION || !Array.isArray(parsed.paths)) return [];
+    return parsed.paths.filter((path5) => typeof path5 === "string");
+  } catch {
+    return [];
+  }
+}
+function rememberPaths(cacheDir, discovered) {
+  const known = readCachedPaths(cacheDir);
+  const merged = [];
+  for (const path5 of [...discovered, ...known]) {
+    if (!merged.includes(path5)) merged.push(path5);
+  }
+  if (cacheDir === void 0 || discovered.length === 0) return merged;
+  try {
+    mkdirSync(cacheDir, { recursive: true });
+    const file = { version: CACHE_VERSION, paths: merged, updatedAt: Date.now() };
+    writeFileSync(join2(cacheDir, CACHE_FILE), `${JSON.stringify(file, null, 2)}
+`, "utf8");
+  } catch {
+  }
+  return merged;
+}
+
+// src/catalog/go-doc.ts
 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,24 +42791,54 @@ 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)}` };
   }
 }
-async function fetchGoDocument(signal) {
-  const attempts = await Promise.all(GO_DOC_URLS.map((url) => readSource(url, signal)));
+async function fetchGoDocument(signal, options = {}) {
   const failures = [];
-  for (const attempt of attempts) {
-    if ("document" in attempt) return attempt.document;
-    failures.push(attempt.failure);
+  const known = await readSources(GO_DOC_URLS, signal);
+  if (known.document !== void 0) return known.document;
+  failures.push(...known.failures);
+  const remembered = readCachedPaths(options.cacheDir).filter((path5) => !GO_DOC_URLS.some((url) => url.endsWith(path5)));
+  if (remembered.length > 0) {
+    const cached = await readSources(remembered.flatMap(mirrorsOf), signal);
+    if (cached.document !== void 0) return cached.document;
+    failures.push(...cached.failures);
+  }
+  const discover = options.discover ?? discoverDocumentPaths;
+  const discovered = await discover(signal);
+  if (discovered.length === 0) {
+    failures.push("the provider repository named no document");
+  } else {
+    const merged = rememberPaths(options.cacheDir, discovered);
+    const fresh = merged.filter((path5) => !GO_DOC_URLS.some((url) => url.endsWith(path5))).flatMap(mirrorsOf);
+    if (fresh.length === 0) {
+      failures.push("the provider repository named the path that was already tried");
+    } else {
+      const result = await readSources(fresh, signal);
+      if (result.document !== void 0) return result.document;
+      failures.push(...result.failures);
+    }
   }
   throw new LlmError3(
     `could not read the Go documentation (${failures.join("; ")})`,
     "DOCUMENT_UNAVAILABLE"
   );
 }
+async function readSources(urls, signal) {
+  const attempts = await Promise.all(urls.map((url) => readSource(url, signal)));
+  const failures = [];
+  for (const attempt of attempts) {
+    if ("document" in attempt) return { document: attempt.document, failures };
+    failures.push(attempt.failure);
+  }
+  return { failures };
+}
 
 // src/catalog/protocol.ts
 var WIRE_PROTOCOLS = [
@@ -42949,6 +43054,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 +43103,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 +43141,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,19 +43154,37 @@ 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.
    */
   async build(signal) {
     const builtin = builtinModels(this.options.baseURL);
-    const readDocument = this.options.readDocument ?? fetchGoDocument;
+    const readDocument = this.options.readDocument ?? ((signal2) => fetchGoDocument(signal2, { cacheDir: this.options.cacheDir }));
     const [listing, metadata, documentation] = await Promise.allSettled([
       fetchModelIds(this.options.baseURL),
       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 +43194,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 +43215,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 +43223,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 +43259,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.
@@ -44988,6 +45130,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           },
           overrides: config.modelProtocols,
           ...this.options.readDocument === void 0 ? {} : { readDocument: this.options.readDocument },
+          ...this.options.cacheDir === void 0 ? {} : { cacheDir: this.options.cacheDir },
           observers: {
             ...this.options.onFallback === void 0 ? {} : { onFallback: this.options.onFallback },
             ...this.options.onUnconfigured === void 0 ? {} : { onUnconfigured: this.options.onUnconfigured }
@@ -45272,12 +45415,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 +45457,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 +45698,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 +45867,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.46" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.48" : "0.0.0-dev";
 
 // src/update/service.ts
 import { TypertRemoteService as TypertRemoteService2 } from "@deepseek-ai/dsh-typert-protocol";
@@ -45844,6 +46004,18 @@ var inject = ["llm"];
 function isLiveConfig(raw) {
   return typeof raw === "object" && raw !== null && typeof raw.enabled === "object" && typeof raw.enabled?.get === "function";
 }
+function resolveCacheDir(ctx) {
+  const home = ctx.dshHomePath;
+  if (typeof home === "function") {
+    try {
+      return home("cache", "@dan-ai-studio/dshopencodego");
+    } catch {
+    }
+  }
+  const configured = process.env.DSH_HOME?.trim();
+  const root = configured !== void 0 && configured.length > 0 ? configured : join3(homedir(), ".dsh");
+  return join3(root, "cache", "@dan-ai-studio/dshopencodego");
+}
 function apply(ctx, raw) {
   const live = isLiveConfig(raw) ? raw : void 0;
   const constant = live === void 0 ? PlainConfig(raw ?? {}) : void 0;
@@ -45864,6 +46036,7 @@ function apply(ctx, raw) {
   const adapter = new OpencodeGoAdapter({
     config: current,
     resolveApiKey,
+    cacheDir: resolveCacheDir(ctx),
     imageAccess: {
       resolveAttachments: () => ctx.get("attachments"),
       resolveImageAccess: (attachments, ref) => llm2.resolveImageAttachmentAccess(

package/lib/types/adapter.d.ts

@@ -52,6 +52,13 @@ export interface OpencodeGoAdapterOptions {
      * a fixed document so the suite stays offline. Production omits this.
      */
     readonly readDocument?: () => Promise<GoDoc>;
+    /**
+     * Where the discovered provider-document paths are remembered.
+     *
+     * Absent means the plugin keeps them in memory only, which costs one
+     * discovery per start and nothing else.
+     */
+    readonly cacheDir?: string;
     /**
      * Observe the provider's own usage for one completed call. This is the only
      * honest source of token counts: the gateway's `/usage` endpoint reports

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-discovery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Finding the provider's document without being told where it is.
+ *
+ * The document is the provider's own statement of each model's protocol, and
+ * the provider moves it: `go.mdx` lived at
+ * `packages/web/src/content/docs/go.mdx` until the `packages/web` tree was
+ * restructured, and the plugin then read 404 from both mirrors for as long as
+ * the old path was hardcoded. A hardcoded path is a promise the provider did
+ * not make.
+ *
+ * So the path is discovered instead of declared. The discovery is a read-only
+ * listing of the provider's own repository, and it runs only when every known
+ * path has already failed — the common case costs one request to a file that
+ * is there, and the rare case costs one listing.
+ *
+ * The paths that discovery finds are remembered on disk, as a *set of paths
+ * known to have existed*, not as one current path. That distinction matters:
+ * a cache holding a single path would hand back a stale path the moment the
+ * provider moved the file again, which is exactly the moment the cache is
+ * consulted. A set is only ever a list of candidates to try, so a stale entry
+ * costs one failed request and nothing else.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/go-doc-discovery
+ */
+/** A repository listing is large; the cap keeps a hostile response bounded. */
+export declare const DISCOVERY_MAX_BYTES: number;
+/**
+ * The repository paths a discovery run found.
+ *
+ * A path is only useful if it names the document this plugin parses, and the
+ * listing also contains unrelated `go.mdx` files in other packages' fixtures.
+ * The path must therefore sit under a documentation tree.
+ * @param paths - every repository path the listing mentioned.
+ * @returns the paths that name the provider's Go document.
+ */
+export declare function selectDocumentPaths(paths: readonly string[]): readonly string[];
+/**
+ * The mirrors a repository path can be read from.
+ *
+ * Two hosts, one file: the repository itself and a CDN that caches it. They
+ * fail independently, which is why both are tried.
+ * @param path - a repository-relative path.
+ * @returns the URLs to read that path from.
+ */
+export declare function mirrorsOf(path: string): readonly string[];
+/**
+ * Ask the provider's repository where its document is.
+ *
+ * The listing is unauthenticated, so it is rate-limited. That is why this runs
+ * only after every known path has failed, and why the paths it finds are
+ * remembered: the next process starts with the answer and never asks.
+ * @param signal - caller cancellation.
+ * @param fetchImpl - the fetch to use; injected for tests.
+ * @returns the repository paths that name the document; empty when the
+ *   listing could not be read or named nothing.
+ */
+export declare function discoverDocumentPaths(signal?: AbortSignal, fetchImpl?: typeof fetch): Promise<readonly string[]>;
+/**
+ * The paths the cache remembers, most recently discovered first.
+ *
+ * A cache that cannot be read is an empty cache: the caller then tries the
+ * paths it knows and discovers again.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns the remembered repository paths.
+ */
+export declare function readCachedPaths(cacheDir: string | undefined): readonly string[];
+/**
+ * Remember the paths a discovery run found.
+ *
+ * The known paths are merged rather than replaced, newest first, so a cache
+ * that a concurrent process also wrote does not lose the other process's
+ * entry. A cache that cannot be written is not an error: the paths stay in
+ * memory for this process and are rediscovered next time.
+ * @param cacheDir - the plugin's cache directory.
+ * @param discovered - the paths a discovery run found.
+ * @returns the merged set, in the order it should be tried.
+ */
+export declare function rememberPaths(cacheDir: string | undefined, discovered: readonly string[]): readonly string[];

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,11 +44,34 @@ 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.
  */
 export declare function parseGoDocument(markdown: string): GoDoc;
+/**
+ * How the document is found and where the answer is kept.
+ *
+ * The discovery is injectable so a test can decide what the provider's
+ * repository says without reaching the network — which is the only way this
+ * module can be exercised offline at all.
+ */
+export interface GoDocOptions {
+    /** Where the discovered document paths are remembered. */
+    readonly cacheDir?: string | undefined;
+    /**
+     * Ask the provider's repository where its document is.
+     *
+     * Defaults to the real listing. A test injects a fixed answer.
+     */
+    readonly discover?: (signal?: AbortSignal) => Promise<readonly string[]>;
+}
 /**
  * Fetch and parse the documentation, asking every source concurrently.
  *
@@ -51,9 +81,16 @@ export declare function parseGoDocument(markdown: string): GoDoc;
  * quota badge and the protocol fallback. `GO_DOC_URLS` order still decides:
  * the repository file is examined before its cache mirror, and a source that
  * fails is reported with its own reason.
+ *
+ * The known paths are tried first, then the paths a previous discovery
+ * remembered, and only then is the provider's repository asked where its
+ * document is. That order is what keeps the cost at one request in the common
+ * case while still surviving the provider moving the file: a path that is
+ * there is used, and a path that is not is replaced by a discovered one.
  * @param signal - caller cancellation; it reaches every source's fetch and
  *   aborts all of them, so a cancelled discovery stops waiting on the network.
+ * @param options - where the discovered paths are remembered.
  * @returns the parsed document from the first source that carried one.
  * @throws {LlmError} `DOCUMENT_UNAVAILABLE` when every source failed.
  */
-export declare function fetchGoDocument(signal?: AbortSignal): Promise<GoDoc>;
+export declare function fetchGoDocument(signal?: AbortSignal, options?: GoDocOptions): Promise<GoDoc>;

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. */
@@ -80,6 +106,14 @@ export interface CatalogOptions {
      * cancellation, forwarded to every documentation request.
      */
     readonly readDocument?: (signal?: AbortSignal) => Promise<GoDoc>;
+    /**
+     * Where the discovered document paths are remembered.
+     *
+     * Absent means the plugin cannot write a cache, and the paths are then only
+     * known to the running process. That costs one discovery per start, and
+     * nothing else.
+     */
+    readonly cacheDir?: string;
 }
 /**
  * One gateway's catalog. Requests reuse a cached snapshot; explicit discovery
@@ -94,6 +128,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 +152,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 +172,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.46",
+  "version": "0.1.48",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",