@dan-ai-studio/dshopencodego 0.1.47 → 0.1.49

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

package/lib/client.js

@@ -128,6 +128,7 @@ function parseCatalogReading(value) {
     stale: row["stale"],
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
     degradations: parseDegradations(row["degradations"]),
+    ...typeof row["factsCachedAt"] === "number" ? { factsCachedAt: row["factsCachedAt"] } : {},
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -335,6 +336,7 @@ var en = {
   catalogDeprecated: "deprecated",
   catalogUnconfigured: "not configurable",
   quotaSeed: "Allowances are the built-in snapshot, transcribed",
+  factsCached: "Model metadata is from the last successful reading,",
   refreshLabel: "Catalog refresh (minutes)",
   refreshHint: "How long requests and the model picker reuse one listing.",
   writeRejected: "The settings write was rejected (the namespace was reloaded) \u2014 try again",
@@ -434,6 +436,7 @@ var zh = {
   catalogDeprecated: "\u5DF2\u5F03\u7528",
   catalogUnconfigured: "\u65E0\u6CD5\u914D\u7F6E",
   quotaSeed: "\u989D\u5EA6\u6765\u81EA\u5185\u7F6E\u5FEB\u7167\uFF0C\u8F6C\u5199\u4E8E",
+  factsCached: "\u6A21\u578B\u5143\u6570\u636E\u6765\u81EA\u4E0A\u6B21\u6210\u529F\u83B7\u53D6\uFF0C",
   refreshLabel: "\u76EE\u5F55\u5237\u65B0\uFF08\u5206\u949F\uFF09",
   refreshHint: "\u8BF7\u6C42\u4E0E\u6A21\u578B\u9009\u62E9\u5668\u590D\u7528\u540C\u4E00\u4EFD\u5217\u8868\u7684\u65F6\u957F\u3002",
   writeRejected: "\u8BBE\u7F6E\u5199\u5165\u88AB\u62D2\u7EDD\uFF08\u5DF2\u91CD\u65B0\u8F7D\u5165\uFF09\uFF0C\u8BF7\u91CD\u8BD5",
@@ -1244,6 +1247,11 @@ function Section({ controller, t, getLocale }) {
         " ",
         SEED_TRANSCRIBED
       ] }),
+      reading !== void 0 && reading.factsCachedAt !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { className: section_default.hint, children: [
+        t("factsCached"),
+        " ",
+        new Date(reading.factsCachedAt).toISOString().slice(0, 10)
+      ] }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: section_default.row, children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { className: section_default.hint, htmlFor: "dshopencodego-refresh", children: t("refreshLabel") }),
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)(

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: readFileSync3 } = __require("node:fs");
+      const data = readFileSync3("/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 join4 } 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";
@@ -42528,6 +42530,8 @@ var CONSOLE_BASE_URL = "https://opencode.ai/inference/v1";
 var MODEL_METADATA_URL = "https://models.dev/api.json";
 var MODEL_METADATA_PROVIDER = "opencode-go";
 var METADATA_FETCH_TIMEOUT_MS = 1e4;
+var MODEL_METADATA_TIMEOUT_MS = 3e4;
+var METADATA_RETRY_DELAY_MS = 1500;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
 var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
@@ -42549,7 +42553,8 @@ async function readBoundedJson(response, url, maxBytes) {
     text = await readBoundedText(response, maxBytes);
   } catch (error) {
     if (error instanceof LlmError) throw error;
-    throw new LlmError(`could not read ${url}`, "DISCOVERY_FAILED", { cause: error });
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new LlmError(`could not read ${url}: ${detail}`, "DISCOVERY_FAILED", { cause: error });
   }
   try {
     return JSON.parse(text);
@@ -42626,6 +42631,78 @@ 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/services/www/src/docs/content/console/go.mdx",
   "https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/services/www/src/docs/content/console/go.mdx"
@@ -42725,18 +42802,46 @@ async function readSource(url, signal) {
     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 = [
@@ -42951,6 +43056,43 @@ function toPiModel(facts, baseURL) {
   };
 }
 
+// src/catalog/metadata-cache.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+var CACHE_FILE2 = "models-dev-facts.json";
+var CACHE_VERSION2 = 1;
+function readFactsCache(cacheDir) {
+  if (cacheDir === void 0) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync2(join3(cacheDir, CACHE_FILE2), "utf8"));
+    if (parsed.version !== CACHE_VERSION2 || parsed.facts === null || typeof parsed.facts !== "object") return void 0;
+    const facts = /* @__PURE__ */ new Map();
+    for (const [id, fact] of Object.entries(parsed.facts)) {
+      if (fact === null || typeof fact !== "object") continue;
+      if (typeof fact.id !== "string" || typeof fact.api !== "string") continue;
+      facts.set(id, fact);
+    }
+    if (facts.size === 0) return void 0;
+    return { facts, updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0 };
+  } catch {
+    return void 0;
+  }
+}
+function writeFactsCache(cacheDir, facts) {
+  if (cacheDir === void 0 || facts.size === 0) return;
+  try {
+    mkdirSync2(cacheDir, { recursive: true });
+    const file = {
+      version: CACHE_VERSION2,
+      facts: Object.fromEntries(facts),
+      updatedAt: Date.now()
+    };
+    writeFileSync2(join3(cacheDir, CACHE_FILE2), `${JSON.stringify(file)}
+`, "utf8");
+  } catch {
+  }
+}
+
 // src/catalog/index.ts
 function reasonText(reason) {
   if (reason instanceof Error) return reason.message;
@@ -42999,12 +43141,27 @@ var OpencodeGoCatalog = class {
   metadataDocument;
   metadataETag;
   lastMetadata;
+  /**
+   * The facts a previous successful read produced, read from disk.
+   *
+   * This is what a cold process falls back on when the online metadata cannot
+   * be read. Without it a degraded catalog declares every model unable to
+   * think, and the host refuses the effort the session is already using.
+   */
+  cachedMetadata;
+  /** When the cached facts were written, for the page to show. */
+  cachedAt;
   /** 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;
+    const cached = readFactsCache(options.cacheDir);
+    if (cached !== void 0) {
+      this.cachedMetadata = { models: cached.facts, errors: /* @__PURE__ */ new Map() };
+      this.cachedAt = cached.updatedAt;
+    }
   }
   /**
    * The cached snapshot, refreshed when it is older than the configured TTL.
@@ -43074,7 +43231,7 @@ var OpencodeGoCatalog = class {
    */
   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),
@@ -43118,15 +43275,18 @@ var OpencodeGoCatalog = class {
         ...this.documentQuotas()
       };
     }
+    const fromCache = metadata.status !== "fulfilled" && this.lastMetadata === void 0;
+    const online = metadata.status === "fulfilled" ? metadata.value : this.lastMetadata ?? this.cachedMetadata;
     return this.assemble(
       listing.value,
-      metadata.status === "fulfilled" ? metadata.value : this.lastMetadata,
+      online,
       builtin,
-      degradations
+      degradations,
+      fromCache ? this.cachedAt : void 0
     );
   }
   /** Merge the listing with the metadata document and the installed entries. */
-  assemble(ids, online, builtin, degradations = []) {
+  assemble(ids, online, builtin, degradations = [], factsCachedAt) {
     const facts = /* @__PURE__ */ new Map();
     const unavailable = /* @__PURE__ */ new Map();
     for (const id of ids) {
@@ -43158,6 +43318,7 @@ var OpencodeGoCatalog = class {
       provider: buildProvider2(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
       live: true,
       ...degradations.length === 0 ? {} : { degradations },
+      ...factsCachedAt === void 0 ? {} : { factsCachedAt },
       fetchedAtMs: Date.now(),
       ...this.documentQuotas()
     };
@@ -43214,8 +43375,18 @@ var OpencodeGoCatalog = class {
       releaseDate: void 0
     };
   }
-  /** Conditional metadata GET: an unchanged document keeps its parsed form. */
-  async refreshMetadata(builtin) {
+  /**
+   * Read the model metadata document, once.
+   *
+   * The document is megabytes, so its budget is longer than the other two
+   * reads' — and the host that runs this is not always a plain Node process:
+   * the desktop build fetches over the browser's network stack, where the
+   * same document that a shell reads in half a second can take long enough
+   * to outrun a budget set for kilobyte-sized documents.
+   * @param builtin - the installed catalog, for the parse.
+   * @returns the parsed metadata.
+   */
+  async readMetadataDocument(builtin) {
     const response = await fetch(MODEL_METADATA_URL, {
       redirect: "error",
       headers: {
@@ -43224,7 +43395,7 @@ var OpencodeGoCatalog = class {
         "cache-control": "no-cache",
         ...this.metadataETag === void 0 ? {} : { "if-none-match": this.metadataETag }
       },
-      signal: AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS)
+      signal: AbortSignal.timeout(MODEL_METADATA_TIMEOUT_MS)
     });
     if (response.status === 304 && this.metadataDocument !== void 0) {
       await response.body?.cancel().catch(() => {
@@ -43251,8 +43422,36 @@ var OpencodeGoCatalog = class {
       overrides: this.options.overrides
     });
     this.lastMetadata = parsed;
+    writeFactsCache(this.options.cacheDir, parsed.models);
     return parsed;
   }
+  /**
+   * Read the model metadata document, retrying once.
+   *
+   * The failure this answers is not a broken network: the same document is
+   * reachable from a browser on the same machine while the host cannot read
+   * it. It is the host being busy — a plugin reload rewrites modules, unpacks
+   * packages, and rebuilds the runtime while the catalog asks for the
+   * document, and the request that loses that race is a timeout, not a
+   * refusal. A second attempt, a moment later, is the same request on a host
+   * that has finished what it was doing.
+   * @param builtin - the installed catalog, for the parse.
+   * @returns the parsed metadata.
+   */
+  async refreshMetadata(builtin) {
+    try {
+      return await this.readMetadataDocument(builtin);
+    } catch (first) {
+      await new Promise((resolve3) => {
+        setTimeout(resolve3, METADATA_RETRY_DELAY_MS);
+      });
+      try {
+        return await this.readMetadataDocument(builtin);
+      } catch (second) {
+        throw new Error(`${reasonText(first)}; retry: ${reasonText(second)}`);
+      }
+    }
+  }
 };
 function inferFamily(id) {
   const lower = id.toLowerCase();
@@ -45028,6 +45227,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 }
@@ -45355,6 +45555,7 @@ function parseCatalogReading(value) {
     stale: row["stale"],
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
     degradations: parseDegradations(row["degradations"]),
+    ...typeof row["factsCachedAt"] === "number" ? { factsCachedAt: row["factsCachedAt"] } : {},
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -45596,6 +45797,7 @@ function catalogReading(snapshot2, visibility, listingFailure, now) {
     stale: !snapshot2.live,
     ...!snapshot2.live && listingFailure !== void 0 ? { error: listingFailure } : {},
     degradations: snapshot2.degradations ?? [],
+    ...snapshot2.factsCachedAt === void 0 ? {} : { factsCachedAt: snapshot2.factsCachedAt },
     fetchedAtMs: snapshot2.fetchedAtMs,
     quotaSource: documentQuotas === void 0 ? "seed" : "document",
     counts: {
@@ -45764,7 +45966,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.47" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.49" : "0.0.0-dev";
 
 // src/update/service.ts
 import { TypertRemoteService as TypertRemoteService2 } from "@deepseek-ai/dsh-typert-protocol";
@@ -45901,6 +46103,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 : join4(homedir(), ".dsh");
+  return join4(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;
@@ -45921,6 +46135,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

@@ -11,8 +11,28 @@ export declare const CONSOLE_BASE_URL = "https://opencode.ai/inference/v1";
 export declare const MODEL_METADATA_URL = "https://models.dev/api.json";
 /** The models.dev provider key this plugin reads. */
 export declare const MODEL_METADATA_PROVIDER = "opencode-go";
-/** Timeout for the two metadata GETs. */
+/** Timeout for the two small metadata GETs. */
 export declare const METADATA_FETCH_TIMEOUT_MS = 10000;
+/**
+ * Timeout for the model metadata document.
+ *
+ * It is the one read measured in megabytes — 5.9 MB for the whole of
+ * models.dev, of which this plugin uses one provider — and the host that
+ * fetches it is not always a plain Node process. The desktop build fetches
+ * over the browser's network stack, where the same document a shell reads in
+ * half a second can outrun a budget set for kilobyte-sized documents. The
+ * longer budget costs nothing when the read succeeds; it is the difference
+ * between a catalog and a degraded one.
+ */
+export declare const MODEL_METADATA_TIMEOUT_MS = 30000;
+/**
+ * How long to wait before the one retry of the metadata read.
+ *
+ * Long enough for the host to finish whatever it was doing — a plugin
+ * reload, a package unpack — and short enough that a genuinely unreachable
+ * document still fails inside the catalog build.
+ */
+export declare const METADATA_RETRY_DELAY_MS = 1500;
 /** 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;

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

@@ -55,6 +55,23 @@ export interface GoDoc {
  *   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.
  *
@@ -64,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

@@ -73,6 +73,15 @@ export interface CatalogSnapshot {
      * a user cannot act on.
      */
     readonly degradations?: readonly CatalogDegradation[];
+    /**
+     * When the facts in this snapshot were written, when they came from disk
+     * rather than from a live read.
+     *
+     * The listing is always live; the metadata behind it may be older. The page
+     * says so, because a capacity that was true last week reads exactly like
+     * one that is true now.
+     */
+    readonly factsCachedAt?: number;
     readonly fetchedAtMs: number;
 }
 /** Observers the plugin logs through. */
@@ -106,6 +115,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
@@ -118,6 +135,16 @@ export declare class OpencodeGoCatalog {
     private metadataDocument;
     private metadataETag;
     private lastMetadata;
+    /**
+     * The facts a previous successful read produced, read from disk.
+     *
+     * This is what a cold process falls back on when the online metadata cannot
+     * be read. Without it a degraded catalog declares every model unable to
+     * think, and the host refuses the effort the session is already using.
+     */
+    private cachedMetadata;
+    /** When the cached facts were written, for the page to show. */
+    private readonly cachedAt;
     /** The last parsed documentation; retained across failed fetches. */
     private document;
     /** Ids that already forced a revalidation, with the time they did. */
@@ -185,7 +212,31 @@ export declare class OpencodeGoCatalog {
     private withDocumentedProtocol;
     /** Facts for an id no source describes, from the ladder and the route defaults. */
     private inferredFacts;
-    /** Conditional metadata GET: an unchanged document keeps its parsed form. */
+    /**
+     * Read the model metadata document, once.
+     *
+     * The document is megabytes, so its budget is longer than the other two
+     * reads' — and the host that runs this is not always a plain Node process:
+     * the desktop build fetches over the browser's network stack, where the
+     * same document that a shell reads in half a second can take long enough
+     * to outrun a budget set for kilobyte-sized documents.
+     * @param builtin - the installed catalog, for the parse.
+     * @returns the parsed metadata.
+     */
+    private readMetadataDocument;
+    /**
+     * Read the model metadata document, retrying once.
+     *
+     * The failure this answers is not a broken network: the same document is
+     * reachable from a browser on the same machine while the host cannot read
+     * it. It is the host being busy — a plugin reload rewrites modules, unpacks
+     * packages, and rebuilds the runtime while the catalog asks for the
+     * document, and the request that loses that race is a timeout, not a
+     * refusal. A second attempt, a moment later, is the same request on a host
+     * that has finished what it was doing.
+     * @param builtin - the installed catalog, for the parse.
+     * @returns the parsed metadata.
+     */
     private refreshMetadata;
 }
 /**

package/lib/types/catalog/metadata-cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Keeping what the last successful metadata read said.
+ *
+ * The online metadata is the only source that states which models can think
+ * and at which levels. When it cannot be read, the plugin still knows some of
+ * that — from the last time it could — and throwing that away turns a
+ * degraded catalog into a broken one: a model that does think is declared
+ * unable to think, the host's own check refuses the effort the session is
+ * already using, and the run fails before it starts.
+ *
+ * So the parsed facts are written down. What is written is deliberately
+ * small: the capabilities, the capacities, the prices — not the document.
+ * The listing stays the authority on which models exist, so a stale file can
+ * never introduce a model the gateway does not serve; it can only describe
+ * the ones it does, with what was true when the file was written.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/metadata-cache
+ */
+import type { ModelFacts } from './metadata.ts';
+/**
+ * The facts a previous successful read produced.
+ *
+ * A cache that cannot be read is no cache: the caller then has nothing to
+ * fall back on and says so, rather than pretending the models have no
+ * capabilities.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns the remembered facts and when they were written, or undefined.
+ */
+export declare function readFactsCache(cacheDir: string | undefined): {
+    readonly facts: ReadonlyMap<string, ModelFacts>;
+    readonly updatedAt: number;
+} | undefined;
+/**
+ * Remember the facts a successful read produced.
+ *
+ * A cache directory that cannot be written costs a degraded catalog after the
+ * next restart, and nothing else: the run continues with what it has.
+ * @param cacheDir - the plugin's cache directory.
+ * @param facts - the parsed facts to remember.
+ */
+export declare function writeFactsCache(cacheDir: string | undefined, facts: ReadonlyMap<string, ModelFacts>): void;

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

@@ -29,6 +29,15 @@ export interface CatalogReading {
      * difference between a user who can act and a user who cannot.
      */
     readonly degradations: readonly CatalogDegradation[];
+    /**
+     * When the model metadata behind this reading was written, when it came
+     * from disk rather than from a live read.
+     *
+     * The listing is live; the capacities, prices, and thinking levels behind
+     * it may not be. The page shows this, because a stale number reads exactly
+     * like a current one.
+     */
+    readonly factsCachedAt?: number;
     /** When the underlying snapshot was built. */
     readonly fetchedAtMs: number;
     /**

package/package.json

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