dsh-opencode-go 0.1.15 → 0.1.17

package/lib/index.js

@@ -50,8 +50,8 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { LlmError as LlmError7, assertUsableApiKey, resolveImageAttachmentAccess } from "@deepseek-ai/dsh-llm";
 
 // src/adapter.ts
-import { randomUUID } from "node:crypto";
-import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { getSupportedThinkingLevels, normalizeContext } from "opencode-go-pi-ai";
 import {
   LlmAdapter,
   LlmError as LlmError6,
@@ -86,13 +86,14 @@ function emptyPiUsage() {
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
   };
 }
-function toPiReplayState(message, requestedModel = message.model) {
+function toPiReplayState(message, requestedModel = message.model, requestedProvider = message.provider) {
   const responseModel = message.api === "anthropic-messages" && message.model !== requestedModel ? message.model : message.responseModel;
   const response = {
     kind: "pi-ai",
     version: 2,
     api: message.api,
-    provider: message.provider,
+    provider: requestedProvider,
+    ...requestedProvider === message.provider ? {} : { sdkProvider: message.provider },
     model: requestedModel,
     ...responseModel === void 0 ? {} : { responseModel },
     ...message.responseId === void 0 ? {} : { responseId: message.responseId },
@@ -137,6 +138,9 @@ function readReplayState(value) {
   for (const key of ["api", "provider", "model"]) {
     if (typeof response[key] !== "string" || response[key].length === 0) return invalidReplay(`${key} must be a non-empty string`);
   }
+  if (response["sdkProvider"] !== void 0 && (typeof response["sdkProvider"] !== "string" || response["sdkProvider"].length === 0)) {
+    return invalidReplay("sdkProvider must be a non-empty string");
+  }
   if (!["stop", "length", "toolUse", "error", "aborted"].includes(String(response["stopReason"]))) {
     return invalidReplay("unknown stopReason");
   }
@@ -236,7 +240,7 @@ function replayedAssistant(message, source, rawState) {
     role: "assistant",
     content,
     api: state.response.api,
-    provider: state.response.provider,
+    provider: state.response.sdkProvider ?? state.response.provider,
     // Anthropic reports aliases and fallbacks as model, unlike Completions' informational responseModel.
     model: state.response.api === "anthropic-messages" ? state.response.responseModel ?? state.response.model : state.response.model,
     ...state.response.responseModel === void 0 ? {} : { responseModel: state.response.responseModel },
@@ -551,7 +555,7 @@ async function toPiContextWithImages(options, images, onReplayDegrade) {
 // src/conversion/stream.ts
 import { brandString as brandString2 } from "@deepseek-ai/dsh-brand";
 import { CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError as LlmError4, QUOTA_EXCEEDED_CODE } from "@deepseek-ai/dsh-llm";
-import { isContextOverflow } from "@earendil-works/pi-ai";
+import { isContextOverflow } from "opencode-go-pi-ai";
 function mapUsage(usage) {
   return {
     inputTokens: usage.input,
@@ -624,7 +628,7 @@ function mapStopReason(message, contextWindow) {
     }
   }
 }
-async function* toStreamChunks(events, contextWindow, callerSignal, requestedModel) {
+async function* toStreamChunks(events, contextWindow, callerSignal, requestedModel, requestedProvider) {
   const toolIds = /* @__PURE__ */ new Map();
   for await (const event of events) {
     switch (event.type) {
@@ -686,7 +690,7 @@ async function* toStreamChunks(events, contextWindow, callerSignal, requestedMod
         yield {
           type: "finish",
           reason: mapStopReason(event.message, contextWindow),
-          replayState: toPiReplayState(event.message, requestedModel)
+          replayState: toPiReplayState(event.message, requestedModel, requestedProvider)
         };
         return;
       case "error":
@@ -708,14 +712,21 @@ async function* toStreamChunks(events, contextWindow, callerSignal, requestedMod
 import { idleWatchdog, timeoutOf } from "@deepseek-ai/dsh-timeout";
 
 // src/catalog.ts
-import { createProvider } from "@earendil-works/pi-ai";
-import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
-import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
-import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
-import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { createProvider } from "opencode-go-pi-ai";
+import { getBuiltinModels } from "opencode-go-pi-ai/providers/all";
+import { anthropicMessagesApi } from "opencode-go-pi-ai/api/anthropic-messages.lazy";
+import { openAICompletionsApi } from "opencode-go-pi-ai/api/openai-completions.lazy";
+import { openAIResponsesApi } from "opencode-go-pi-ai/api/openai-responses.lazy";
 import { attributionHeaders, LlmError as LlmError5 } from "@deepseek-ai/dsh-llm";
 
 // src/models-contract.ts
+var INPUT_MODALITIES = ["text", "image", "audio", "video", "pdf"];
+function normalizeInputModalities(value) {
+  if (!Array.isArray(value)) return void 0;
+  const declared = new Set(value.filter((item) => typeof item === "string").map((item) => item.toLowerCase()));
+  const ordered = INPUT_MODALITIES.filter((modality) => declared.has(modality));
+  return ordered.length === 0 ? void 0 : ordered;
+}
 function isModelEnabled(model, modelVisibility) {
   if (model.configurationMissing) return false;
   const enabled = modelVisibility && Object.hasOwn(modelVisibility, model.id) ? modelVisibility[model.id] : void 0;
@@ -747,6 +758,8 @@ function parseGoModels(value) {
     if (typeof row.deprecated === "boolean") model.deprecated = row.deprecated;
     if (typeof row.configurationMissing === "boolean") model.configurationMissing = row.configurationMissing;
     if (validReleaseDate(row.releaseDate)) model.releaseDate = row.releaseDate;
+    const modalities = normalizeInputModalities(row.inputModalities);
+    if (modalities !== void 0) model.inputModalities = modalities;
     return model;
   });
 }
@@ -852,9 +865,11 @@ function readModelMetadata(body, baseURL, builtin) {
   const details = /* @__PURE__ */ new Map();
   for (const [id, value] of Object.entries(entries)) {
     const data = record(value);
+    const inputModalities = normalizeInputModalities(record(data.modalities).input);
     details.set(id, {
       deprecated: data.status === "deprecated",
-      ...validReleaseDate(data.release_date) ? { releaseDate: data.release_date } : {}
+      ...validReleaseDate(data.release_date) ? { releaseDate: data.release_date } : {},
+      ...inputModalities === void 0 ? {} : { inputModalities }
     });
     try {
       const metadata = record(value);
@@ -906,6 +921,9 @@ function readModelMetadata(body, baseURL, builtin) {
 
 // src/json-response.ts
 import { setTimeout as delay } from "node:timers/promises";
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
 var RETRYABLE_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "EPIPE", "UND_ERR_SOCKET", "EAI_AGAIN"]);
 function errorCauses(error) {
   const causes = [];
@@ -943,10 +961,10 @@ function diagnosticURL(raw) {
   url.hash = "";
   return url.href;
 }
-async function fetchJsonResponse(url, init, maxBytes) {
+async function fetchJsonResponse(url, init, maxBytes, encoding = "identity") {
   if ((init.method ?? "GET").toUpperCase() !== "GET") throw new TypeError("JSON requests must use GET");
   const headers = new Headers(init.headers);
-  headers.set("accept-encoding", "identity");
+  headers.set("accept-encoding", encoding);
   const options = { ...init, method: "GET", headers };
   for (let attempt = 0; ; attempt += 1) {
     init.signal?.throwIfAborted();
@@ -957,7 +975,7 @@ async function fetchJsonResponse(url, init, maxBytes) {
         });
         return { response, body: void 0 };
       }
-      return { response, body: await readJsonResponse(response, maxBytes) };
+      return { response, body: await readJsonResponse(response, maxBytes, { gzip: encoding === "gzip", signal: init.signal }) };
     } catch (error) {
       init.signal?.throwIfAborted();
       if (attempt > 0 || !retryableTransportFailure(error)) throw error;
@@ -987,8 +1005,33 @@ async function readBoundedBody(response, maxBytes) {
     reader.releaseLock();
   }
 }
-async function readJsonResponse(response, maxBytes) {
-  const bytes = await readBoundedBody(response, maxBytes);
+async function readGzipBody(bytes, maxBytes, signal) {
+  const chunks = [];
+  let size = 0;
+  await pipeline(Readable.from([bytes]), createGunzip(), new Writable({
+    write(chunk, _encoding, done) {
+      if (chunk.length > maxBytes - size) {
+        done(new RangeError(`Response body exceeds ${maxBytes} byte limit`));
+        return;
+      }
+      size += chunk.length;
+      chunks.push(chunk);
+      done();
+    }
+  }), { signal: signal ?? void 0 });
+  return Buffer.concat(chunks, size);
+}
+async function readJsonResponse(response, maxBytes, options = {}) {
+  let bytes = await readBoundedBody(response, maxBytes);
+  if (options.gzip && bytes[0] === 31 && bytes[1] === 139) {
+    try {
+      bytes = await readGzipBody(bytes, maxBytes, options.signal);
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      if (error instanceof RangeError) throw error;
+      throw new SyntaxError("Response is not valid gzip", { cause: error });
+    }
+  }
   try {
     return JSON.parse(new TextDecoder().decode(bytes));
   } catch (error) {
@@ -996,27 +1039,82 @@ async function readJsonResponse(response, maxBytes) {
   }
 }
 
+// src/metadata-cache.ts
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
+var CACHE_MAX_BYTES = MODEL_METADATA_MAX_BYTES + 4096;
+function metadataCachePath() {
+  const home = process.env.DSH_HOME?.trim() || join(homedir(), ".dsh");
+  return resolve(home, "cache", "dsh-opencode-go", "models.dev.api.json");
+}
+function metadataETag(value) {
+  return typeof value === "string" && value.length <= 1024 && /^(W\/)?"[\x21\x23-\x7e\x80-\xff]*"$/.test(value) ? value : void 0;
+}
+async function readMetadataCache(path) {
+  try {
+    const info = await stat(path);
+    if (!info.isFile() || info.size > CACHE_MAX_BYTES) return void 0;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of createReadStream(path)) {
+      const bytes = chunk;
+      size += bytes.length;
+      if (size > CACHE_MAX_BYTES) return void 0;
+      chunks.push(bytes);
+    }
+    const value = JSON.parse(Buffer.concat(chunks, size).toString("utf8"));
+    if (!value || value.version !== 1 || value.sourceURL !== MODEL_METADATA_URL || typeof value.savedAtMs !== "number" || !Number.isSafeInteger(value.savedAtMs) || value.savedAtMs < 0 || value.savedAtMs > Date.now() || value.etag !== void 0 && metadataETag(value.etag) === void 0) return void 0;
+    return { body: value.body, savedAtMs: value.savedAtMs, etag: metadataETag(value.etag) };
+  } catch {
+    return void 0;
+  }
+}
+async function writeMetadataCache(path, value) {
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  try {
+    const content = JSON.stringify({ version: 1, sourceURL: MODEL_METADATA_URL, ...value });
+    if (Buffer.byteLength(content) > CACHE_MAX_BYTES) return;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(temporary, content, { flag: "wx", mode: 384 });
+    await rename(temporary, path);
+  } catch {
+  } finally {
+    await rm(temporary, { force: true }).catch(() => {
+    });
+  }
+}
+
+// src/provider-identity.ts
+var PROVIDER_ID = "dsh-opencode-go";
+var DISPLAY_NAME = "DSH OpenCode Go";
+var SDK_PROVIDER_ID = "opencode-go";
+
 // src/catalog.ts
-var PROVIDER_ID = "opencode-go";
-var DISPLAY_NAME = "OpenCode Go";
 var DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1";
 var MODELS_FETCH_TIMEOUT_MS = 1e4;
 var METADATA_FETCH_TIMEOUT_MS = 3e4;
 var STALE_WHILE_REVALIDATE_MS = 5 * 6e4;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
-var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
 var RETRY_MIN_MS = 5e3;
 var RETRY_MAX_MS = 6e4;
+async function settled(promise) {
+  const [result] = await Promise.allSettled([promise]);
+  return result;
+}
 function waitForSnapshot(pending, signal) {
   if (signal === void 0) return pending;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const abort = () => {
       signal.removeEventListener("abort", abort);
       reject(new LlmError5("opencode-go catalog request aborted by caller", "ABORTED", { cause: signal.reason }));
     };
     pending.then((value) => {
       signal.removeEventListener("abort", abort);
-      resolve(value);
+      resolve2(value);
     }, (error) => {
       signal.removeEventListener("abort", abort);
       reject(error);
@@ -1026,9 +1124,9 @@ function waitForSnapshot(pending, signal) {
   });
 }
 function builtinModels(baseURL) {
-  return new Map(getBuiltinModels("opencode-go").map((model) => [model.id, {
+  return new Map(getBuiltinModels(SDK_PROVIDER_ID).map((model) => [model.id, {
     ...model,
-    provider: PROVIDER_ID,
+    provider: SDK_PROVIDER_ID,
     baseUrl: modelBaseURL(model.api, baseURL)
   }]));
 }
@@ -1074,7 +1172,7 @@ function harnessApiKeyAuth() {
 }
 function buildProvider(baseURL, models) {
   return createProvider({
-    id: PROVIDER_ID,
+    id: SDK_PROVIDER_ID,
     name: DISPLAY_NAME,
     baseUrl: baseURL,
     auth: harnessApiKeyAuth(),
@@ -1087,15 +1185,22 @@ function buildProvider(baseURL, models) {
   });
 }
 var OpencodeGoCatalog = class {
-  constructor(baseURL, refreshMs, onFallback, onOmitted) {
+  constructor(baseURL, refreshMs, onFallback, onOmitted, onRefresh = () => {
+  }) {
     this.baseURL = baseURL;
     this.refreshMs = refreshMs;
     this.onFallback = onFallback;
     this.onOmitted = onOmitted;
+    this.onRefresh = onRefresh;
   }
   served;
   pending;
+  /** A cold runtime read can use disk metadata while the shared online refresh runs. */
+  cachedPending;
+  initialized;
+  cachePath = metadataCachePath();
   metadata;
+  metadataBody;
   metadataETag;
   metadataUpdatedAtMs;
   failures = 0;
@@ -1104,19 +1209,63 @@ var OpencodeGoCatalog = class {
     if (signal?.aborted) {
       return Promise.reject(new LlmError5("opencode-go catalog request aborted by caller", "ABORTED", { cause: signal.reason }));
     }
-    if (!force && this.served !== void 0 && Date.now() < this.refreshAtMs) {
-      return Promise.resolve(this.served);
+    return waitForSnapshot(this.served === void 0 ? this.readSnapshot(force) : this.currentSnapshot(force), signal);
+  }
+  async restoreMetadata() {
+    const saved = await readMetadataCache(this.cachePath);
+    if (saved === void 0) return;
+    try {
+      this.metadata = readModelMetadata(saved.body, this.baseURL, builtinModels(this.baseURL));
+      this.metadataBody = saved.body;
+      this.metadataETag = saved.etag;
+      this.metadataUpdatedAtMs = saved.savedAtMs;
+    } catch {
     }
-    this.pending ??= this.build().then((snapshot) => {
+  }
+  async readSnapshot(force) {
+    await (this.initialized ??= this.restoreMetadata());
+    return this.currentSnapshot(force);
+  }
+  currentSnapshot(force) {
+    if (!force && this.served !== void 0 && Date.now() < this.refreshAtMs) return Promise.resolve(this.served);
+    if (this.pending === void 0) this.startRefresh(force);
+    return !force && this.cachedPending !== void 0 ? this.cachedPending : this.pending;
+  }
+  startRefresh(force) {
+    const builtin = builtinModels(this.baseURL);
+    const listing = settled(fetchLiveModelIds(this.baseURL).then((ids) => ({ ids, updatedAtMs: Date.now() })));
+    const restored = this.metadata;
+    if (!force && this.served === void 0 && restored !== void 0) {
+      const status = { metadataLive: false, metadataUpdatedAtMs: this.metadataUpdatedAtMs };
+      this.cachedPending = listing.then((result) => {
+        const snapshot = this.build(builtin, result, restored, status);
+        this.served = snapshot;
+        return snapshot;
+      });
+    }
+    const notify = this.cachedPending !== void 0 || !force && this.served !== void 0;
+    this.pending = Promise.all([listing, settled(this.refreshMetadata(builtin)), this.cachedPending]).then(([listing2, result]) => this.build(
+      builtin,
+      listing2,
+      result.status === "fulfilled" ? result.value : this.metadata,
+      {
+        metadataLive: result.status === "fulfilled",
+        ...this.metadataUpdatedAtMs === void 0 ? {} : { metadataUpdatedAtMs: this.metadataUpdatedAtMs },
+        ...result.status === "rejected" ? { metadataFailure: result.reason } : {}
+      }
+    )).then((snapshot) => {
       this.served = snapshot;
       this.failures = snapshot.live && snapshot.metadataLive ? 0 : Math.min(this.failures + 1, 5);
       const lifetime = this.failures === 0 ? this.refreshMs : Math.min(this.refreshMs, RETRY_MIN_MS * 2 ** (this.failures - 1), RETRY_MAX_MS);
       this.refreshAtMs = snapshot.fetchedAtMs + lifetime;
+      if (notify) this.onRefresh();
       return snapshot;
     }).finally(() => {
       this.pending = void 0;
+      this.cachedPending = void 0;
+    });
+    void this.pending.catch(() => {
     });
-    return waitForSnapshot(this.pending, signal);
   }
   /** Conditional HTTP requests save bandwidth while still checking for updated metadata. */
   async refreshMetadata(builtin) {
@@ -1128,9 +1277,11 @@ var OpencodeGoCatalog = class {
       },
       cache: "no-cache",
       signal: AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS)
-    }, MODEL_METADATA_MAX_BYTES);
+    }, MODEL_METADATA_MAX_BYTES, "gzip");
     if (response.status === 304 && this.metadata !== void 0) {
       this.metadataUpdatedAtMs = Date.now();
+      this.metadataETag = metadataETag(response.headers.get("etag")) ?? this.metadataETag;
+      await this.persistMetadata();
       return this.metadata;
     }
     if (!response.ok) throw new LlmError5(`${MODEL_METADATA_URL} answered HTTP ${response.status}`, "DISCOVERY_FAILED");
@@ -1141,26 +1292,24 @@ var OpencodeGoCatalog = class {
       throw new LlmError5(`${MODEL_METADATA_URL} returned invalid model configuration`, "DISCOVERY_FAILED", { cause: error });
     }
     this.metadata = metadata;
-    this.metadataETag = response.headers.get("etag") ?? void 0;
+    this.metadataBody = body;
+    this.metadataETag = metadataETag(response.headers.get("etag"));
     this.metadataUpdatedAtMs = Date.now();
+    await this.persistMetadata();
     return metadata;
   }
+  async persistMetadata() {
+    await writeMetadataCache(this.cachePath, {
+      body: this.metadataBody,
+      etag: this.metadataETag,
+      savedAtMs: this.metadataUpdatedAtMs
+    });
+  }
   /** Gateway ids decide membership; online metadata decides how to call each model. */
-  async build() {
-    const builtin = builtinModels(this.baseURL);
-    const [listing, metadataResult] = await Promise.allSettled([
-      fetchLiveModelIds(this.baseURL).then((ids) => ({ ids, updatedAtMs: Date.now() })),
-      this.refreshMetadata(builtin)
-    ]);
-    const metadata = metadataResult.status === "fulfilled" ? metadataResult.value : this.metadata;
-    const metadataStatus = {
-      metadataLive: metadataResult.status === "fulfilled",
-      ...this.metadataUpdatedAtMs === void 0 ? {} : { metadataUpdatedAtMs: this.metadataUpdatedAtMs },
-      ...metadataResult.status === "rejected" ? { metadataFailure: metadataResult.reason } : {}
-    };
+  build(builtin, listing, metadata, metadataStatus) {
     const known = new Map([...builtin, ...this.served?.models ?? [], ...metadata?.models ?? []]);
-    if (metadataResult.status === "rejected") {
-      this.onFallback({ url: MODEL_METADATA_URL, error: metadataResult.reason, kept: known.size });
+    if (metadataStatus.metadataFailure !== void 0) {
+      this.onFallback({ url: MODEL_METADATA_URL, error: metadataStatus.metadataFailure, kept: known.size });
     }
     if (listing.status === "rejected") {
       const models2 = this.served?.models ?? /* @__PURE__ */ new Map();
@@ -1188,7 +1337,9 @@ var OpencodeGoCatalog = class {
         models.set(id, model);
       }
     }
-    if (unavailable.size > 0) this.onOmitted([...unavailable.keys()]);
+    if (unavailable.size > 0 && (metadataStatus.metadataLive || metadataStatus.metadataFailure !== void 0)) {
+      this.onOmitted([...unavailable.keys()]);
+    }
     return {
       details: new Map(listing.value.ids.map((id) => [id, metadata?.details.get(id) ?? {}])),
       models,
@@ -1210,7 +1361,9 @@ var OpencodeGoCatalog = class {
       return cached;
     }
     let snapshot = await this.snapshot(false, signal);
-    if (!snapshot.models.has(id) && snapshot === cached) snapshot = await this.snapshot(true, signal);
+    if (!snapshot.models.has(id) && (snapshot === cached || this.cachedPending !== void 0)) {
+      snapshot = await this.snapshot(true, signal);
+    }
     if (signal?.aborted) throw new LlmError5("opencode-go catalog request aborted by caller", "ABORTED", { cause: signal.reason });
     if (snapshot.unavailable.has(id)) {
       throw new LlmError5(
@@ -1336,7 +1489,7 @@ function withModelLimit(model, limits) {
   };
 }
 function opencodeSessionValue(sessionId) {
-  return sessionId !== void 0 && sessionId.length > 0 ? sessionId : randomUUID();
+  return sessionId !== void 0 && sessionId.length > 0 ? sessionId : randomUUID2();
 }
 var OpencodeGoAdapter = class extends LlmAdapter {
   constructor(options) {
@@ -1360,19 +1513,20 @@ var OpencodeGoAdapter = class extends LlmAdapter {
   catalogOf(config) {
     const key = `${config.baseURL}|${String(config.refreshMinutes)}`;
     if (this.catalogCache?.key !== key) {
-      this.catalogCache = {
-        key,
-        catalog: new OpencodeGoCatalog(
-          assertBaseURL(config.baseURL),
-          config.refreshMinutes * 6e4,
-          /* v8 ignore next -- the plugin always passes both observers; the defaults exist for direct construction */
-          this.options.onFallback ?? (() => {
-          }),
-          /* v8 ignore next -- the plugin always passes both observers; the defaults exist for direct construction */
-          this.options.onOmitted ?? (() => {
-          })
-        )
-      };
+      const catalog = new OpencodeGoCatalog(
+        assertBaseURL(config.baseURL),
+        config.refreshMinutes * 6e4,
+        /* v8 ignore next -- the plugin always passes both observers; the defaults exist for direct construction */
+        this.options.onFallback ?? (() => {
+        }),
+        /* v8 ignore next -- the plugin always passes both observers; the defaults exist for direct construction */
+        this.options.onOmitted ?? (() => {
+        }),
+        () => {
+          if (this.catalogCache?.catalog === catalog) this.options.onCatalogRefresh?.();
+        }
+      );
+      this.catalogCache = { key, catalog };
     }
     return this.catalogCache.catalog;
   }
@@ -1489,7 +1643,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           };
         }
         const context = imageRequest === void 0 ? toPiContext(options, void 0, this.options.onReplayDegrade) : await toPiContext({ ...options, signal: watchdog.signal }, imageRequest, this.options.onReplayDegrade);
-        const events = snapshot.provider.streamSimple(model, context, {
+        const events = snapshot.provider.streamSimple(model, normalizeContext(context), {
           apiKey,
           ...reasoning === void 0 || reasoning === "off" ? {} : { reasoning },
           ...options.temperature === void 0 ? {} : { temperature: options.temperature },
@@ -1507,7 +1661,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           // one SDK attempt.
           maxRetries: 0
         });
-        const iterator = toStreamChunks(events, model.contextWindow, options.signal, model.id)[Symbol.asyncIterator]();
+        const iterator = toStreamChunks(events, model.contextWindow, options.signal, model.id, options.provider)[Symbol.asyncIterator]();
         let exhausted = false;
         try {
           while (true) {
@@ -1548,7 +1702,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
 };
 
 // src/usage.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { attributionHeaders as attributionHeaders3 } from "@deepseek-ai/dsh-llm";
 
@@ -1620,7 +1774,7 @@ var GoUsageService = class extends TypertRemoteService {
       });
     }
     if (this.identity?.baseURL !== baseURL || this.identity.key !== key) {
-      this.identity = { baseURL, key, source: randomUUID2() };
+      this.identity = { baseURL, key, source: randomUUID3() };
     }
     const { source } = this.identity;
     const endpoint = diagnosticURL(`${baseURL}/usage`);
@@ -1726,6 +1880,7 @@ function apply(ctx, raw) {
       ctx.logger.warn(`llm-opencode-go: gateway models awaiting usable online metadata: ${ids.join(", ")}`);
     }
   };
+  let registration;
   const adapter = new OpencodeGoAdapter({
     config: () => current(),
     resolveApiKey,
@@ -1739,11 +1894,13 @@ function apply(ctx, raw) {
     },
     onFallback: logger.fallback,
     onOmitted: logger.omitted,
+    onCatalogRefresh: () => {
+      registration?.replace([PROVIDER_ID]);
+    },
     onReplayDegrade: (reason) => {
       ctx.logger.warn(`llm-opencode-go: unusable replay state on assistant history; sending provider-neutral content (${reason})`);
     }
   });
-  let registration;
   ctx.plugin(GoModelsService, {
     catalog: () => adapter.catalogOf(current()),
     onRefresh: () => {
@@ -1756,6 +1913,7 @@ function apply(ctx, raw) {
     if (configured && current().enabled && registration === void 0) {
       try {
         registration = ctx.llm.registerAdapter([PROVIDER_ID], adapter);
+        ctx.logger.info(`llm-opencode-go: route "${PROVIDER_ID}" registered as ${DISPLAY_NAME}`);
       } catch (error) {
         ctx.logger.error(`llm-opencode-go: not registering the "${PROVIDER_ID}" route (${String(error)})`);
       }
@@ -1796,6 +1954,7 @@ function apply(ctx, raw) {
   });
   ctx.effect(() => () => {
     registration?.();
+    registration = void 0;
     undiscover();
   });
   ctx.inject(["settings"], (settingsCtx) => {
@@ -1828,7 +1987,6 @@ function apply(ctx, raw) {
     });
     syncRoute();
   });
-  ctx.logger.info(`llm-opencode-go: route "${PROVIDER_ID}" registered as ${DISPLAY_NAME}`);
 }
 export {
   Config,

package/lib/types/adapter.d.ts

@@ -62,6 +62,8 @@ export interface OpencodeGoAdapterOptions {
     onOmitted?: (ids: readonly string[]) => void;
     /** Observe assistant history degrading to provider-neutral conversion. */
     onReplayDegrade?: (reason: string) => void;
+    /** Re-read picker models after a background catalog refresh commits. */
+    onCatalogRefresh?: () => void;
 }
 /**
  * The single route's adapter. The catalog snapshot freezes at each operation,

package/lib/types/catalog.d.ts

@@ -1,9 +1,8 @@
-import type { Api, Model, Provider } from '@earendil-works/pi-ai';
+import type { Api, Model, Provider } from 'opencode-go-pi-ai';
 import type { LlmDiscoveredModel } from '@deepseek-ai/dsh-llm';
 import { type GoModelCatalog } from './models-contract.ts';
 import type { ModelMetadata } from './model-metadata.ts';
-export declare const PROVIDER_ID = "opencode-go";
-export declare const DISPLAY_NAME = "OpenCode Go";
+export { PROVIDER_ID, DISPLAY_NAME } from './provider-identity.ts';
 export declare const DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1";
 export interface CatalogSnapshot {
     readonly details: ModelMetadata['details'];
@@ -30,9 +29,15 @@ export declare class OpencodeGoCatalog {
     private readonly onFallback;
     /** Kept for API compatibility; now reports unconfigured ids rather than hiding them. */
     private readonly onOmitted;
+    private readonly onRefresh;
     private served;
     private pending;
+    /** A cold runtime read can use disk metadata while the shared online refresh runs. */
+    private cachedPending;
+    private initialized;
+    private readonly cachePath;
     private metadata;
+    private metadataBody;
     private metadataETag;
     private metadataUpdatedAtMs;
     private failures;
@@ -43,10 +48,15 @@ export declare class OpencodeGoCatalog {
         kept: number;
     }) => void, 
     /** Kept for API compatibility; now reports unconfigured ids rather than hiding them. */
-    onOmitted: (ids: readonly string[]) => void);
+    onOmitted: (ids: readonly string[]) => void, onRefresh?: () => void);
     snapshot(force?: boolean, signal?: AbortSignal): Promise<CatalogSnapshot>;
+    private restoreMetadata;
+    private readSnapshot;
+    private currentSnapshot;
+    private startRefresh;
     /** Conditional HTTP requests save bandwidth while still checking for updated metadata. */
     private refreshMetadata;
+    private persistMetadata;
     /** Gateway ids decide membership; online metadata decides how to call each model. */
     private build;
     /** New or previously unconfigured ids get a fresh lookup even during the runtime TTL. */

package/lib/types/client/ModelEditor.d.ts

@@ -1,9 +1,10 @@
+import { type ReactNode } from 'react';
 import type { OpencodeGoModelLimit, OpencodeGoModelLimits, OpencodeGoModels } from './section-controller.ts';
 import type { en } from './locales.ts';
 type Translate = (key: keyof typeof en, params?: Record<string, unknown>) => string;
 export declare function hasCapacityOverride(limit: OpencodeGoModelLimit | null | undefined): boolean;
 /** Per-model switches apply immediately; capacity edits stay in the staged form. */
-export declare function ModelEditor({ models, draft, modelVisibility, t, locale, disabled, visibilitySaving, onEdit, onModelEnabled }: {
+export declare function ModelEditor({ models, draft, modelVisibility, t, locale, disabled, visibilitySaving, filterAction, onEdit, onModelEnabled }: {
     models: OpencodeGoModels;
     draft: OpencodeGoModelLimits;
     modelVisibility: Readonly<Record<string, boolean>>;
@@ -11,6 +12,8 @@ export declare function ModelEditor({ models, draft, modelVisibility, t, locale,
     locale?: string;
     disabled: boolean;
     visibilitySaving: boolean;
+    /** Optional control pinned to the right of the filter row, such as a refresh. */
+    filterAction?: ReactNode;
     onEdit: (next: OpencodeGoModelLimits) => void;
     onModelEnabled: (id: string, enabled: boolean) => void;
 }): import("react").JSX.Element;