@dan-ai-studio/dshopencodego 0.1.56 → 0.1.58

package/README.en.md

@@ -173,6 +173,8 @@ The gateway's `/v1/models` answers only *which* models exist, never *how* to cal
 - a model the provider **retires** disappears on the next refresh;
 - the bundled catalog is **frozen at the plugin's version** and affects only the quality of the "how to call it" decision, never *which* models exist.
 
+When the gateway is **temporarily unavailable**, the plugin keeps the last listing that succeeded, marks it stale on the page, and retries in the background. The retry rate is governed by a **five-minute back-off** rather than by the TTL, so a gateway that comes back is picked up within five minutes; while it stays down it is asked once, not once per model request. The settings page's Recheck button revalidates at any time and is not bound by that back-off.
+
 The only thing that waits on a plugin release is a missing wire quirk in the pi-ai catalog (DeepSeek's `thinkingFormat`, say) — the model itself is already usable.
 
 ## The model list in the settings page
@@ -260,7 +262,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 **56 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 **57 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
 
 ## Releasing (maintainers)
 

package/README.md

@@ -173,6 +173,8 @@ API Key 通过 Harness 凭证库提供（引用名 `OPENCODE_GO_API_KEY`），
 - 官方**下线**模型 → 下次刷新即消失；
 - 内置目录**冻结**在插件版本里，仅影响"怎么调"的推断质量，不影响"有哪些"。
 
+网关**临时不可用**时，插件保留上次成功获取的列表并在页面上标注陈旧，同时在后台重试：重试由**5 分钟的退避**控制，而不是等满一个 TTL，所以网关恢复后 5 分钟内列表就会更新；网关持续不可用时，它只被问一次，不会每次模型请求都去问一遍。设置页的「重新检查」随时可以强制重验，不受这个退避限制。
+
 只有当 pi-ai 内置目录**缺了某个模型的线怪癖**（如 DeepSeek 的 `thinkingFormat`）时，才需要等插件同步 pi-ai 的新版本——而模型本身早已可用。
 
 ## 设置页里的模型列表
@@ -260,7 +262,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 对上游的断言与实装的上游一致）。共 **56 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
+测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **57 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
 
 ## 发布（维护者）
 

package/lib/index.js

@@ -74390,12 +74390,15 @@ var OpencodeGoCatalog = class {
         return Promise.resolve(this.served);
       }
     }
-    this.pending ??= this.build(signal).then((snapshot2) => {
-      this.served = snapshot2;
-      return snapshot2;
-    }).finally(() => {
-      this.pending = void 0;
-    });
+    if (this.pending === void 0) {
+      this.lastRefreshAttemptAt = Date.now();
+      this.pending = this.build(signal).then((snapshot2) => {
+        this.served = snapshot2;
+        return snapshot2;
+      }).finally(() => {
+        this.pending = void 0;
+      });
+    }
     return this.pending;
   }
   /**
@@ -74548,7 +74551,20 @@ var OpencodeGoCatalog = class {
         live: false,
         listingFailure: listing.reason,
         ...degradations.length === 0 ? {} : { degradations },
-        fetchedAtMs: Date.now(),
+        // The age of this snapshot is the age of what it holds, not the age of
+        // the failure.
+        //
+        // Stamping it "now" resets the TTL on every failure, and the refresh
+        // behind it then waits a whole TTL before asking again — which is
+        // exactly when a gateway that came back would be noticed. The age
+        // stays where the last successful listing left it, so the TTL keeps
+        // expiring and the back-off decides how often the gateway is asked
+        // while it is down.
+        //
+        // Zero means "no listing has ever answered": there is nothing to be
+        // old about, so the snapshot is treated as already stale and the
+        // back-off is the only thing between it and the next attempt.
+        fetchedAtMs: previous?.fetchedAtMs ?? 0,
         ...this.documentQuotas()
       };
     }
@@ -77318,6 +77334,13 @@ function hostOf(input) {
     return void 0;
   }
 }
+async function edgeRefused(response) {
+  try {
+    return (await response.clone().text()).includes("developers.cloudflare.com");
+  } catch {
+    return false;
+  }
+}
 function gatewayFetch(pin) {
   const address = pin.address;
   if (address === void 0) return globalThis.fetch;
@@ -77327,10 +77350,17 @@ function gatewayFetch(pin) {
     if (isPinSpent(pin)) return globalThis.fetch(input, init);
     try {
       const dispatcher = dispatcherFor(pin.host, address);
-      return await dispatchingFetch(input, {
+      const response = await dispatchingFetch(input, {
         ...init,
         dispatcher
       });
+      if (response.status === 403 && await edgeRefused(response)) {
+        await response.body?.cancel().catch(() => {
+        });
+        spent.add(spentKey(pin));
+        return globalThis.fetch(input, init);
+      }
+      return response;
     } catch (error) {
       if (!addressIsGone(error)) throw error;
       if (init?.signal?.aborted === true) throw error;
@@ -77452,7 +77482,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.56" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.58" : "0.0.0-dev";
 
 // src/update/service.ts
 import { TypertRemoteService as TypertRemoteService3 } from "@deepseek-ai/dsh-typert-protocol";

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

@@ -43,6 +43,11 @@ export declare const METADATA_RETRY_DELAY_MS = 1500;
  * 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.
+ *
+ * This is also the ceiling on how long an outage costs. A failed refresh
+ * keeps the age of the last reading that succeeded, so the TTL stays expired
+ * and the next call after this window tries again — a gateway that comes back
+ * is noticed within five minutes, not within a whole TTL.
  */
 export declare const BACKGROUND_RETRY_BACKOFF_MS: number;
 /** Response caps: the listing is tiny, the metadata document is not. */

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

@@ -91,6 +91,16 @@ export interface CatalogSnapshot {
      * one that is true now.
      */
     readonly factsCachedAt?: number;
+    /**
+     * When the content of this snapshot was obtained.
+     *
+     * It is the age of the *knowledge*, not of the attempt: a snapshot that
+     * could not be rebuilt keeps the age of the last reading that succeeded,
+     * because that is when the content became true. Stamping it with the time
+     * of the failure instead would make a failed refresh look like a fresh one,
+     * and the TTL that governs the next attempt would then be measured from
+     * the failure rather than from the last thing that was actually known.
+     */
     readonly fetchedAtMs: number;
 }
 /** Observers the plugin logs through. */

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

@@ -48,7 +48,7 @@ export interface CatalogReading {
      * worse than one that admits it.
      */
     readonly cached?: boolean;
-    /** When the underlying snapshot was built. */
+    /** When the content behind this reading was obtained. */
     readonly fetchedAtMs: number;
     /**
      * Where the per-model allowances came from: the provider's live document, or

package/lib/types/network/pinning.d.ts

@@ -80,6 +80,14 @@ export declare function closeDispatcher(): Promise<void>;
  * @returns true when the address was found to be gone.
  */
 export declare function isPinSpent(pin: GatewayPin): boolean;
+/**
+ * Forget the addresses that were found to be gone.
+ *
+ * The memory belongs to the process, so it outlives every request. A test
+ * that needs a spent address to be unspent again has no other way to say
+ * so, and a spent address is exactly what such a test sets up.
+ */
+export declare function resetSpentAddresses(): void;
 /**
  * A fetch that sends the gateway's name to the pinned address.
  *

package/package.json

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