@dan-ai-studio/dshopencodego 0.1.48 → 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 **46 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 对上游的断言与实装的上游一致）。共 **46 个测试文件**——这个数字由 `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: readFileSync2 } = __require("node:fs");
-      const data = readFileSync2("/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) {
@@ -42463,7 +42463,7 @@ Check your ChatGPT usage: ${CHATGPT_USAGE_URL}` : errorMessage;
 
 // src/index.ts
 import { homedir } from "node:os";
-import { join as join3 } from "node:path";
+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";
@@ -42530,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;
@@ -42551,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);
@@ -43053,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;
@@ -43101,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.
@@ -43220,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) {
@@ -43260,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()
     };
@@ -43316,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: {
@@ -43326,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(() => {
@@ -43353,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();
@@ -45458,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: {
@@ -45699,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: {
@@ -45867,7 +45966,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.48" : "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";
@@ -46013,8 +46112,8 @@ function resolveCacheDir(ctx) {
     }
   }
   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");
+  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;

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/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. */
@@ -126,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. */
@@ -193,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.48",
+  "version": "0.1.49",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",