@dan-ai-studio/dshopencodego 0.1.51 → 0.1.54

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

package/lib/client.js

@@ -27,6 +27,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/catalog/constants.ts
+var BACKGROUND_RETRY_BACKOFF_MS = 5 * 6e4;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
 var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
@@ -129,6 +130,7 @@ function parseCatalogReading(value) {
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
     degradations: parseDegradations(row["degradations"]),
     ...typeof row["factsCachedAt"] === "number" ? { factsCachedAt: row["factsCachedAt"] } : {},
+    ...row["cached"] === true ? { cached: true } : {},
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -337,6 +339,7 @@ var en = {
   catalogUnconfigured: "not configurable",
   quotaSeed: "Allowances are the built-in snapshot, transcribed",
   factsCached: "Model metadata is from the last successful reading,",
+  catalogRefreshing: "Showing the last known catalog; a refresh is running in the background.",
   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",
@@ -437,6 +440,7 @@ var zh = {
   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",
+  catalogRefreshing: "\u663E\u793A\u4E0A\u6B21\u5DF2\u77E5\u7684\u76EE\u5F55\uFF0C\u540E\u53F0\u6B63\u5728\u5237\u65B0\u3002",
   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",
@@ -1252,6 +1256,7 @@ function Section({ controller, t, getLocale }) {
         " ",
         new Date(reading.factsCachedAt).toISOString().slice(0, 10)
       ] }),
+      reading !== void 0 && reading.cached === true && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: section_default.hint, children: t("catalogRefreshing") }),
       /* @__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: readFileSync3 } = __require("node:fs");
-      const data = readFileSync3("/proc/self/environ", "utf-8");
+      const { readFileSync: readFileSync5 } = __require("node:fs");
+      const data = readFileSync5("/proc/self/environ", "utf-8");
       for (const entry of data.split("\0")) {
         const idx = entry.indexOf("=");
         if (idx > 0) {
@@ -42530,6 +42530,7 @@ 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 BACKGROUND_RETRY_BACKOFF_MS = 5 * 6e4;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
 var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
@@ -42700,6 +42701,45 @@ function rememberPaths(cacheDir, discovered) {
   return merged;
 }
 
+// src/catalog/go-doc-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 = "go-doc-cache.json";
+var CACHE_VERSION2 = 1;
+function readDocCache(cacheDir) {
+  if (cacheDir === void 0) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync2(join3(cacheDir, CACHE_FILE2), "utf8"));
+    if (parsed.version !== CACHE_VERSION2) return void 0;
+    if (typeof parsed.url !== "string" || typeof parsed.body !== "string") return void 0;
+    if (parsed.body.length === 0) return void 0;
+    return {
+      url: parsed.url,
+      etag: typeof parsed.etag === "string" ? parsed.etag : void 0,
+      body: parsed.body,
+      savedAt: typeof parsed.savedAt === "number" ? parsed.savedAt : 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function writeDocCache(cacheDir, entry) {
+  if (cacheDir === void 0 || entry.body.length === 0) return;
+  try {
+    mkdirSync2(cacheDir, { recursive: true });
+    const file = {
+      version: CACHE_VERSION2,
+      url: entry.url,
+      ...entry.etag === void 0 ? {} : { etag: entry.etag },
+      body: entry.body,
+      savedAt: Date.now()
+    };
+    writeFileSync2(join3(cacheDir, CACHE_FILE2), `${JSON.stringify(file)}
+`, "utf8");
+  } catch {
+  }
+}
+
 // src/catalog/go-doc.ts
 var GO_DOC_URLS = [
   "https://raw.githubusercontent.com/anomalyco/opencode/dev/services/www/src/docs/content/console/go.mdx",
@@ -42778,36 +42818,47 @@ function parseGoDocument(markdown) {
   }
   return { quotas, protocols };
 }
-async function readSource(url, signal) {
+async function readSource(url, signal, etag) {
   const timeout = AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS);
   try {
     const response = await fetch(url, {
       redirect: "error",
-      headers: { ...attributionHeaders2(), accept: "text/plain", "cache-control": "no-cache" },
+      headers: {
+        ...attributionHeaders2(),
+        accept: "text/plain",
+        "cache-control": "no-cache",
+        ...etag === void 0 ? {} : { "if-none-match": etag }
+      },
       signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout])
     });
+    if (response.status === 304) {
+      await response.body?.cancel().catch(() => {
+      });
+      return { url, notModified: true };
+    }
     if (!response.ok) {
       await response.body?.cancel().catch(() => {
       });
-      return { failure: `${url} answered HTTP ${response.status}` };
+      return { url, failure: `${url} answered HTTP ${response.status}` };
     }
-    const document = parseGoDocument(await readBoundedText(response, GO_DOC_MAX_BYTES));
+    const body = await readBoundedText(response, GO_DOC_MAX_BYTES);
+    const document = parseGoDocument(body);
     if (document.quotas.size === 0 && document.protocols.size === 0) {
-      return { failure: `${url} carried neither an allowance table nor an endpoint table` };
+      return { url, failure: `${url} carried neither an allowance table nor an endpoint table` };
     }
-    return { document };
+    return { url, document, body, etag: response.headers.get("etag") ?? void 0 };
   } catch (error) {
-    return { failure: `${url}: ${error instanceof Error ? error.message : String(error)}` };
+    return { url, failure: `${url}: ${error instanceof Error ? error.message : String(error)}` };
   }
 }
 async function fetchGoDocument(signal, options = {}) {
   const failures = [];
-  const known = await readSources(GO_DOC_URLS, signal);
+  const known = await readSources(GO_DOC_URLS, signal, options.cacheDir);
   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);
+    const cached = await readSources(remembered.flatMap(mirrorsOf), signal, options.cacheDir);
     if (cached.document !== void 0) return cached.document;
     failures.push(...cached.failures);
   }
@@ -42821,7 +42872,7 @@ async function fetchGoDocument(signal, options = {}) {
     if (fresh.length === 0) {
       failures.push("the provider repository named the path that was already tried");
     } else {
-      const result = await readSources(fresh, signal);
+      const result = await readSources(fresh, signal, options.cacheDir);
       if (result.document !== void 0) return result.document;
       failures.push(...result.failures);
     }
@@ -42831,12 +42882,32 @@ async function fetchGoDocument(signal, options = {}) {
     "DOCUMENT_UNAVAILABLE"
   );
 }
-async function readSources(urls, signal) {
-  const attempts = await Promise.all(urls.map((url) => readSource(url, signal)));
+async function readSources(urls, signal, cacheDir) {
   const failures = [];
+  const cached = readDocCache(cacheDir);
+  if (cached !== void 0 && urls.includes(cached.url)) {
+    const attempt = await readSource(cached.url, signal, cached.etag);
+    if ("notModified" in attempt) {
+      const document = parseGoDocument(cached.body);
+      if (document.quotas.size > 0 || document.protocols.size > 0) {
+        return { document, failures };
+      }
+      failures.push(`${attempt.url} answered 304, and the remembered copy carries no table this build can read`);
+    } else if ("document" in attempt) {
+      writeDocCache(cacheDir, { url: attempt.url, etag: attempt.etag, body: attempt.body });
+      return { document: attempt.document, failures };
+    } else {
+      failures.push(attempt.failure);
+    }
+  }
+  const rest = cached === void 0 ? urls : urls.filter((url) => url !== cached.url);
+  const attempts = await Promise.all(rest.map((url) => readSource(url, signal)));
   for (const attempt of attempts) {
-    if ("document" in attempt) return { document: attempt.document, failures };
-    failures.push(attempt.failure);
+    if ("document" in attempt) {
+      writeDocCache(cacheDir, { url: attempt.url, etag: attempt.etag, body: attempt.body });
+      return { document: attempt.document, failures };
+    }
+    if ("failure" in attempt) failures.push(attempt.failure);
   }
   return { failures };
 }
@@ -43055,15 +43126,15 @@ 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;
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+var CACHE_FILE3 = "models-dev-facts.json";
+var CACHE_VERSION3 = 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 parsed = JSON.parse(readFileSync3(join4(cacheDir, CACHE_FILE3), "utf8"));
+    if (parsed.version !== CACHE_VERSION3 || 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;
@@ -43083,14 +43154,69 @@ function readFactsCache(cacheDir) {
 function writeFactsCache(cacheDir, facts, etag) {
   if (cacheDir === void 0 || facts.size === 0) return;
   try {
-    mkdirSync2(cacheDir, { recursive: true });
+    mkdirSync3(cacheDir, { recursive: true });
     const file = {
-      version: CACHE_VERSION2,
+      version: CACHE_VERSION3,
       facts: Object.fromEntries(facts),
       updatedAt: Date.now(),
       ...etag === void 0 ? {} : { etag }
     };
-    writeFileSync2(join3(cacheDir, CACHE_FILE2), `${JSON.stringify(file)}
+    writeFileSync3(join4(cacheDir, CACHE_FILE3), `${JSON.stringify(file)}
+`, "utf8");
+  } catch {
+  }
+}
+
+// src/catalog/snapshot-cache.ts
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+var CACHE_FILE4 = "catalog-snapshot.json";
+var CACHE_VERSION4 = 1;
+function readSnapshotCache(cacheDir) {
+  if (cacheDir === void 0) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync4(join5(cacheDir, CACHE_FILE4), "utf8"));
+    if (parsed.version !== CACHE_VERSION4) return void 0;
+    if (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;
+    const quotas = /* @__PURE__ */ new Map();
+    for (const [id, quota] of Object.entries(parsed.quotas ?? {})) {
+      if (quota === null || typeof quota !== "object") continue;
+      quotas.set(id, quota);
+    }
+    const protocols = /* @__PURE__ */ new Map();
+    for (const [id, protocol] of Object.entries(parsed.protocols ?? {})) {
+      if (typeof protocol !== "string") continue;
+      protocols.set(id, protocol);
+    }
+    return {
+      facts,
+      quotas,
+      protocols,
+      updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function writeSnapshotCache(cacheDir, facts, quotas, protocols) {
+  if (cacheDir === void 0 || facts.size === 0) return;
+  try {
+    mkdirSync4(cacheDir, { recursive: true });
+    const file = {
+      version: CACHE_VERSION4,
+      facts: Object.fromEntries(facts),
+      ...quotas.size === 0 ? {} : { quotas: Object.fromEntries(quotas) },
+      ...protocols.size === 0 ? {} : { protocols: Object.fromEntries(protocols) },
+      updatedAt: Date.now()
+    };
+    writeFileSync4(join5(cacheDir, CACHE_FILE4), `${JSON.stringify(file)}
 `, "utf8");
   } catch {
   }
@@ -43158,6 +43284,10 @@ var OpencodeGoCatalog = class {
   document;
   /** Ids that already forced a revalidation, with the time they did. */
   probedAt = /* @__PURE__ */ new Map();
+  /** The background refresh, kept so a caller can wait for it to be over. */
+  backgroundRefresh;
+  /** When the last background refresh was started, for the back-off. */
+  lastRefreshAttemptAt = 0;
   constructor(options) {
     this.options = options;
     const cached = readFactsCache(options.cacheDir);
@@ -43169,7 +43299,19 @@ var OpencodeGoCatalog = class {
   }
   /**
    * The cached snapshot, refreshed when it is older than the configured TTL.
-   * @param force - revalidate every source, ignoring the cache.
+   *
+   * A snapshot that is past its TTL is still served — and refreshed behind
+   * it. A caller that asks for a model must not wait for the network to
+   * learn what it already knew, so the answer is the one in hand and the
+   * refresh goes on without anyone watching it. A caller that forces a
+   * refresh — the settings page's button — waits for it, because asking to
+   * refresh and not waiting for the result is asking for nothing.
+   *
+   * A process that has never built a catalog reads the one it wrote down
+   * last time and refreshes that in the background. The first message of a
+   * session therefore names its model at once, instead of after a wait that
+   * belongs to the network rather than to the session.
+   * @param force - revalidate every source, ignoring the cache, and wait.
    * @param signal - caller cancellation, forwarded to the documentation read,
    *   the slowest source and the only one a caller can cancel; a build already
    *   in flight keeps the signal of the caller that started it, because one
@@ -43179,6 +43321,19 @@ var OpencodeGoCatalog = class {
     if (!force && this.served !== void 0 && Date.now() - this.served.fetchedAtMs < this.options.refreshMs) {
       return Promise.resolve(this.served);
     }
+    if (!force) {
+      if (this.served === void 0) {
+        const remembered = this.readRememberedSnapshot();
+        if (remembered !== void 0) {
+          this.served = remembered;
+          this.refreshInBackground();
+          return Promise.resolve(remembered);
+        }
+      } else {
+        this.refreshInBackground();
+        return Promise.resolve(this.served);
+      }
+    }
     this.pending ??= this.build(signal).then((snapshot2) => {
       this.served = snapshot2;
       return snapshot2;
@@ -43187,6 +43342,64 @@ var OpencodeGoCatalog = class {
     });
     return this.pending;
   }
+  /**
+   * Refresh the catalog behind the snapshot in hand.
+   *
+   * The build is not awaited and its failure is not reported here: the
+   * snapshot in hand stays, and whoever asked for the refresh will see the
+   * next one.
+   */
+  refreshInBackground() {
+    if (this.pending !== void 0) return;
+    if (Date.now() - this.lastRefreshAttemptAt < BACKGROUND_RETRY_BACKOFF_MS) return;
+    this.lastRefreshAttemptAt = Date.now();
+    const refresh = this.build(void 0, false).then((snapshot2) => {
+      this.served = snapshot2;
+      return snapshot2;
+    }).finally(() => {
+      this.pending = void 0;
+    });
+    this.pending = refresh;
+    this.backgroundRefresh = refresh;
+    void refresh.catch(() => void 0);
+  }
+  /**
+   * Wait for the background refresh, if one is running.
+   *
+   * The refresh belongs to no caller, so nothing else can wait for it. A
+   * host that is shutting down — or a test that must not have a request
+   * outlive it — needs to know when the quiet is over.
+   * @returns a promise that settles when the background refresh has.
+   */
+  settled() {
+    const refresh = this.backgroundRefresh;
+    return refresh === void 0 ? Promise.resolve() : refresh.then(() => void 0, () => void 0);
+  }
+  /**
+   * The catalog a previous build produced, read from disk.
+   *
+   * It is presented as what it is: a listing from the past, being brought up
+   * to date in the background. The facts it carries are the ones the last
+   * build produced, so the protocols and the thinking levels are the ones
+   * that were true then.
+   * @returns the remembered catalog, or undefined when there is none.
+   */
+  readRememberedSnapshot() {
+    const remembered = readSnapshotCache(this.options.cacheDir);
+    if (remembered === void 0) return void 0;
+    const facts = new Map(remembered.facts);
+    return {
+      facts,
+      unavailable: /* @__PURE__ */ new Map(),
+      provider: buildProvider2(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
+      // The listing is from the past, and the page says so.
+      live: false,
+      // And a refresh of it is already under way.
+      cached: true,
+      fetchedAtMs: remembered.updatedAt,
+      ...remembered.quotas.size === 0 ? {} : { documentQuotas: remembered.quotas }
+    };
+  }
   /**
    * The snapshot that can serve one exact model.
    *
@@ -43232,13 +43445,17 @@ var OpencodeGoCatalog = class {
   /**
    * Revalidate every source, reusing the metadata document when it is unchanged.
    * @param signal - caller cancellation, forwarded to the documentation read.
+   * @param retry - whether a failed metadata read is tried again. A caller
+   *   that is waiting for the answer wants it tried again; a refresh nobody
+   *   is waiting for does not, because the answer it wants is the one it
+   *   already has.
    */
-  async build(signal) {
+  async build(signal, retry = true) {
     const builtin = builtinModels(this.options.baseURL);
     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),
+      this.refreshMetadata(builtin, retry),
       readDocument(signal)
     ]);
     const degradations = [];
@@ -43281,13 +43498,20 @@ var OpencodeGoCatalog = class {
     }
     const fromCache = metadata.status !== "fulfilled" && this.lastMetadata === void 0;
     const online = metadata.status === "fulfilled" ? metadata.value : this.lastMetadata ?? this.cachedMetadata;
-    return this.assemble(
+    const snapshot2 = this.assemble(
       listing.value,
       online,
       builtin,
       degradations,
       fromCache ? this.cachedAt : void 0
     );
+    writeSnapshotCache(
+      this.options.cacheDir,
+      snapshot2.facts,
+      this.document?.quotas ?? /* @__PURE__ */ new Map(),
+      this.document?.protocols ?? /* @__PURE__ */ new Map()
+    );
+    return snapshot2;
   }
   /** Merge the listing with the metadata document and the installed entries. */
   assemble(ids, online, builtin, degradations = [], factsCachedAt) {
@@ -43453,10 +43677,11 @@ var OpencodeGoCatalog = class {
    * @param builtin - the installed catalog, for the parse.
    * @returns the parsed metadata.
    */
-  async refreshMetadata(builtin) {
+  async refreshMetadata(builtin, retry) {
     try {
       return await this.readMetadataDocument(builtin);
     } catch (first) {
+      if (!retry) throw first;
       await new Promise((resolve3) => {
         setTimeout(resolve3, METADATA_RETRY_DELAY_MS);
       });
@@ -45571,6 +45796,7 @@ function parseCatalogReading(value) {
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
     degradations: parseDegradations(row["degradations"]),
     ...typeof row["factsCachedAt"] === "number" ? { factsCachedAt: row["factsCachedAt"] } : {},
+    ...row["cached"] === true ? { cached: true } : {},
     fetchedAtMs: row["fetchedAtMs"],
     quotaSource: quotaSource ?? "seed",
     counts: {
@@ -45813,6 +46039,7 @@ function catalogReading(snapshot2, visibility, listingFailure, now) {
     ...!snapshot2.live && listingFailure !== void 0 ? { error: listingFailure } : {},
     degradations: snapshot2.degradations ?? [],
     ...snapshot2.factsCachedAt === void 0 ? {} : { factsCachedAt: snapshot2.factsCachedAt },
+    ...snapshot2.cached === void 0 ? {} : { cached: snapshot2.cached },
     fetchedAtMs: snapshot2.fetchedAtMs,
     quotaSource: documentQuotas === void 0 ? "seed" : "document",
     counts: {
@@ -45981,7 +46208,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.51" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.54" : "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

@@ -33,6 +33,18 @@ export declare const MODEL_METADATA_TIMEOUT_MS = 30000;
  * document still fails inside the catalog build.
  */
 export declare const METADATA_RETRY_DELAY_MS = 1500;
+/**
+ * How long a failed background refresh waits before it is tried again.
+ *
+ * A refresh that fails leaves the catalog's age where it was, so every call
+ * sees it as past its TTL and starts another. Without a back-off, a service
+ * that is down turns every model request into a full download attempt.
+ *
+ * Five minutes is short enough that a service that comes back is picked up
+ * soon, and long enough that a service that stays down is asked once, not
+ * once per request.
+ */
+export declare const BACKGROUND_RETRY_BACKOFF_MS: number;
 /** 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-cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Remembering the provider's document.
+ *
+ * The document is small — tens of kilobytes — but it is fetched by every
+ * process that builds a catalog, and a desktop build fetches over the
+ * browser's network stack, where that fetch is measured in hundreds of
+ * milliseconds. The registry serves an ETag for it, and a conditional
+ * request that comes back `304 Not Modified` carries no body at all, so a
+ * process that remembers the ETag can have the document for the price of a
+ * round trip.
+ *
+ * What is remembered is the raw text, not the parsed tables. The parsed
+ * form is a reading of a document, and a reading can be taken again; the
+ * text is the document.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/go-doc-cache
+ */
+/**
+ * The document a previous read produced.
+ *
+ * A cache that cannot be read is no cache: the caller then reads the
+ * document the ordinary way, which is slower and no worse.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns the remembered document, or undefined.
+ */
+export declare function readDocCache(cacheDir: string | undefined): {
+    readonly url: string;
+    readonly etag: string | undefined;
+    readonly body: string;
+    readonly savedAt: number;
+} | undefined;
+/**
+ * Remember the document a read produced.
+ *
+ * A cache directory that cannot be written costs a fetch, and nothing else.
+ * @param cacheDir - the plugin's cache directory.
+ * @param entry - the document, where it came from, and its ETag.
+ */
+export declare function writeDocCache(cacheDir: string | undefined, entry: {
+    readonly url: string;
+    readonly etag: string | undefined;
+    readonly body: string;
+}): void;

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

@@ -73,6 +73,15 @@ export interface CatalogSnapshot {
      * a user cannot act on.
      */
     readonly degradations?: readonly CatalogDegradation[];
+    /**
+     * True when this snapshot was read from disk and is being brought up to
+     * date in the background.
+     *
+     * It is the difference between "here is the last known catalog" and "here
+     * is the catalog, and it is current". A page that shows the first must
+     * also say that a refresh is under way.
+     */
+    readonly cached?: boolean;
     /**
      * When the facts in this snapshot were written, when they came from disk
      * rather than from a live read.
@@ -149,16 +158,59 @@ export declare class OpencodeGoCatalog {
     private document;
     /** Ids that already forced a revalidation, with the time they did. */
     private readonly probedAt;
+    /** The background refresh, kept so a caller can wait for it to be over. */
+    private backgroundRefresh;
+    /** When the last background refresh was started, for the back-off. */
+    private lastRefreshAttemptAt;
     constructor(options: CatalogOptions);
     /**
      * The cached snapshot, refreshed when it is older than the configured TTL.
-     * @param force - revalidate every source, ignoring the cache.
+     *
+     * A snapshot that is past its TTL is still served — and refreshed behind
+     * it. A caller that asks for a model must not wait for the network to
+     * learn what it already knew, so the answer is the one in hand and the
+     * refresh goes on without anyone watching it. A caller that forces a
+     * refresh — the settings page's button — waits for it, because asking to
+     * refresh and not waiting for the result is asking for nothing.
+     *
+     * A process that has never built a catalog reads the one it wrote down
+     * last time and refreshes that in the background. The first message of a
+     * session therefore names its model at once, instead of after a wait that
+     * belongs to the network rather than to the session.
+     * @param force - revalidate every source, ignoring the cache, and wait.
      * @param signal - caller cancellation, forwarded to the documentation read,
      *   the slowest source and the only one a caller can cancel; a build already
      *   in flight keeps the signal of the caller that started it, because one
      *   shared snapshot cannot carry two different cancellations.
      */
     snapshot(force?: boolean, signal?: AbortSignal): Promise<CatalogSnapshot>;
+    /**
+     * Refresh the catalog behind the snapshot in hand.
+     *
+     * The build is not awaited and its failure is not reported here: the
+     * snapshot in hand stays, and whoever asked for the refresh will see the
+     * next one.
+     */
+    private refreshInBackground;
+    /**
+     * Wait for the background refresh, if one is running.
+     *
+     * The refresh belongs to no caller, so nothing else can wait for it. A
+     * host that is shutting down — or a test that must not have a request
+     * outlive it — needs to know when the quiet is over.
+     * @returns a promise that settles when the background refresh has.
+     */
+    settled(): Promise<void>;
+    /**
+     * The catalog a previous build produced, read from disk.
+     *
+     * It is presented as what it is: a listing from the past, being brought up
+     * to date in the background. The facts it carries are the ones the last
+     * build produced, so the protocols and the thinking levels are the ones
+     * that were true then.
+     * @returns the remembered catalog, or undefined when there is none.
+     */
+    private readRememberedSnapshot;
     /**
      * The snapshot that can serve one exact model.
      *
@@ -187,6 +239,10 @@ export declare class OpencodeGoCatalog {
     /**
      * Revalidate every source, reusing the metadata document when it is unchanged.
      * @param signal - caller cancellation, forwarded to the documentation read.
+     * @param retry - whether a failed metadata read is tried again. A caller
+     *   that is waiting for the answer wants it tried again; a refresh nobody
+     *   is waiting for does not, because the answer it wants is the one it
+     *   already has.
      */
     private build;
     /** Merge the listing with the metadata document and the installed entries. */

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

@@ -38,6 +38,16 @@ export interface CatalogReading {
      * like a current one.
      */
     readonly factsCachedAt?: number;
+    /**
+     * True when the catalog behind this reading was read from disk and is
+     * being brought up to date in the background.
+     *
+     * The reading is usable — the models, the protocols, the levels are all
+     * there — but it was true when it was written, and a refresh is under
+     * way. The page says so, because a page that looks current and is not is
+     * worse than one that admits it.
+     */
+    readonly cached?: boolean;
     /** When the underlying snapshot was built. */
     readonly fetchedAtMs: number;
     /**

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

@@ -0,0 +1,50 @@
+/**
+ * Remembering the whole catalog.
+ *
+ * The parsed metadata facts and the provider's document are remembered
+ * already, but they are remembered as *evidence* — what to ask about, and
+ * what to fall back to when an answer cannot be had. This file remembers
+ * the *answer*: the catalog as it stood, so that a process can serve it
+ * without waiting for the network at all.
+ *
+ * That is the difference between a wait and a stale page. A process that
+ * starts with nothing must ask the gateway, the metadata document, and the
+ * provider's page before it can name a model — and a new session's first
+ * message waits for that. A process that starts with a remembered catalog
+ * can name a model immediately, and refresh what it remembered afterwards.
+ *
+ * The listing is the authority on which models exist, so a remembered
+ * catalog can only describe the models the gateway advertised when it was
+ * written. A model the gateway has since added is missing from it — and a
+ * model the gateway has since retired is still in it, which is why the
+ * remembered catalog is always presented as being *from* the past.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/snapshot-cache
+ */
+import type { GoQuota } from '../go-limits.ts';
+import type { ModelFacts } from './metadata.ts';
+import type { WireProtocol } from './protocol.ts';
+/**
+ * The catalog a previous build produced.
+ *
+ * A cache that cannot be read is no cache: the caller then builds the
+ * catalog the ordinary way, which waits, and no worse.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns the remembered catalog, or undefined.
+ */
+export declare function readSnapshotCache(cacheDir: string | undefined): {
+    readonly facts: ReadonlyMap<string, ModelFacts>;
+    readonly quotas: ReadonlyMap<string, GoQuota>;
+    readonly protocols: ReadonlyMap<string, WireProtocol>;
+    readonly updatedAt: number;
+} | undefined;
+/**
+ * Remember the catalog a build produced.
+ *
+ * A cache directory that cannot be written costs a wait, and nothing else.
+ * @param cacheDir - the plugin's cache directory.
+ * @param facts - the facts the build produced.
+ * @param quotas - the provider's allowances.
+ * @param protocols - the provider's protocols.
+ */
+export declare function writeSnapshotCache(cacheDir: string | undefined, facts: ReadonlyMap<string, ModelFacts>, quotas: ReadonlyMap<string, GoQuota>, protocols: ReadonlyMap<string, WireProtocol>): void;

package/package.json

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