@dan-ai-studio/dshopencodego 0.1.14 → 0.1.16

package/lib/index.js

@@ -48,15 +48,15 @@ var __callDispose = (stack, error, hasError) => {
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import * as llm2 from "@deepseek-ai/dsh-llm";
-import { LlmError as LlmError11 } from "@deepseek-ai/dsh-llm";
+import { LlmError as LlmError12 } from "@deepseek-ai/dsh-llm";
 
 // src/adapter.ts
 import { getSupportedThinkingLevels, normalizeContext } from "@earendil-works/pi-ai";
 import {
-  attributionHeaders as attributionHeaders4,
+  attributionHeaders as attributionHeaders5,
   contentHasImage as contentHasImage2,
   LlmAdapter,
-  LlmError as LlmError7,
+  LlmError as LlmError8,
   ReasoningEffortId,
   resolveRetryPolicy
 } from "@deepseek-ai/dsh-llm";
@@ -68,7 +68,7 @@ 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 { attributionHeaders as attributionHeaders2, LlmError as LlmError3 } from "@deepseek-ai/dsh-llm";
+import { attributionHeaders as attributionHeaders3, LlmError as LlmError4 } from "@deepseek-ai/dsh-llm";
 
 // src/catalog/constants.ts
 var PROVIDER_ID = "opencode-go";
@@ -172,6 +172,117 @@ async function fetchModelIds(baseURL, signal) {
   }
 }
 
+// src/catalog/go-doc.ts
+import { attributionHeaders as attributionHeaders2, LlmError as LlmError3 } from "@deepseek-ai/dsh-llm";
+var GO_DOC_URLS = [
+  "https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/content/docs/go.mdx",
+  "https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/packages/web/src/content/docs/go.mdx"
+];
+var GO_DOC_MAX_BYTES = 1024 * 1024;
+var ENDPOINT_PROTOCOLS = {
+  "/chat/completions": "openai-completions",
+  "/messages": "anthropic-messages",
+  "/responses": "openai-responses"
+};
+function cell(value) {
+  return (value ?? "").replace(/[*`]/g, "").trim();
+}
+function baseName(name2) {
+  return name2.replace(/\s*\(.*\)\s*$/, "").trim();
+}
+function parseAllowance(value) {
+  if (/^unlimited\b/i.test(value) || value.startsWith("\u65E0\u9650\u5236")) return "unlimited";
+  const match = value.match(/\$([\d,]+(?:\.\d+)?)/);
+  if (match?.[1] === void 0) return void 0;
+  const amount = Number(match[1].replace(/,/g, ""));
+  return Number.isFinite(amount) ? amount : void 0;
+}
+function parseCount(value) {
+  if (/^unlimited\b/i.test(value) || value.startsWith("\u65E0\u9650\u5236")) return "unlimited";
+  const amount = Number(value.replace(/,/g, ""));
+  return value.length > 0 && Number.isFinite(amount) ? amount : void 0;
+}
+function protocolOfEndpoint(endpoint) {
+  for (const [suffix, protocol] of Object.entries(ENDPOINT_PROTOCOLS)) {
+    if (endpoint.endsWith(suffix)) return protocol;
+  }
+  return void 0;
+}
+function tableRows(lines, required) {
+  const start = lines.findIndex((line) => line.startsWith("|") && line.includes(required));
+  if (start < 0) return [];
+  const rows = [];
+  for (let index = start + 2; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    if (!line.startsWith("|")) break;
+    rows.push(line.split("|").slice(1, -1).map((entry) => entry.trim()));
+  }
+  return rows;
+}
+function parseGoDocument(markdown) {
+  const lines = markdown.split("\n");
+  const ids = /* @__PURE__ */ new Map();
+  const protocols = /* @__PURE__ */ new Map();
+  for (const row of tableRows(lines, "Model ID")) {
+    const name2 = cell(row[0]);
+    const id = cell(row[1]);
+    if (name2.length === 0 || id.length === 0) continue;
+    ids.set(name2, id);
+    const protocol = protocolOfEndpoint(cell(row[2]));
+    if (protocol !== void 0) protocols.set(id, protocol);
+  }
+  const quotas = /* @__PURE__ */ new Map();
+  for (const row of tableRows(lines, "Monthly limit")) {
+    const id = ids.get(baseName(cell(row[0])));
+    if (id === void 0) continue;
+    const monthlyUsd = parseAllowance(cell(row[5]));
+    if (monthlyUsd === void 0) continue;
+    const previous = quotas.get(id);
+    if (previous === void 0) quotas.set(id, { monthlyUsd });
+    else if (previous.monthlyUsd !== monthlyUsd) quotas.delete(id);
+  }
+  for (const row of tableRows(lines, "requests per month")) {
+    const id = ids.get(baseName(cell(row[0])));
+    if (id === void 0) continue;
+    const monthlyRequests = parseCount(cell(row[3]));
+    const quota = quotas.get(id);
+    if (monthlyRequests === void 0 || quota === void 0) continue;
+    quotas.set(id, { ...quota, monthlyRequests });
+  }
+  return { quotas, protocols };
+}
+async function fetchGoDocument(signal) {
+  const failures = [];
+  for (const url of GO_DOC_URLS) {
+    try {
+      const timeout = AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS);
+      const response = await fetch(url, {
+        redirect: "error",
+        headers: { ...attributionHeaders2(), accept: "text/plain", "cache-control": "no-cache" },
+        signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout])
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {
+        });
+        failures.push(`${url} answered HTTP ${response.status}`);
+        continue;
+      }
+      const document = parseGoDocument(await readBoundedText(response, GO_DOC_MAX_BYTES));
+      if (document.quotas.size === 0) {
+        failures.push(`${url} carried no allowance table`);
+        continue;
+      }
+      return document;
+    } catch (error) {
+      failures.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new LlmError3(
+    `could not read the Go documentation (${failures.join("; ")})`,
+    "DOCUMENT_UNAVAILABLE"
+  );
+}
+
 // src/catalog/protocol.ts
 var WIRE_PROTOCOLS = [
   "anthropic-messages",
@@ -420,6 +531,8 @@ var OpencodeGoCatalog = class {
   metadataDocument;
   metadataETag;
   lastMetadata;
+  /** The last parsed documentation; retained across failed fetches. */
+  document;
   constructor(options) {
     this.options = options;
   }
@@ -452,19 +565,21 @@ var OpencodeGoCatalog = class {
     if (!snapshot.facts.has(id) && snapshot === cached) snapshot = await this.snapshot(true);
     const reason = snapshot.unavailable.get(id);
     if (reason !== void 0) {
-      throw new LlmError3(
+      throw new LlmError4(
         `opencode-go model "${id}" is advertised but cannot be configured: ${reason}; refresh the model list to retry`,
         "MODEL_METADATA_UNAVAILABLE"
       );
     }
     return snapshot;
   }
-  /** Revalidate both sources, reusing the metadata document when it is unchanged. */
+  /** Revalidate every source, reusing the metadata document when it is unchanged. */
   async build() {
     const builtin = builtinModels(this.options.baseURL);
-    const [listing, metadata] = await Promise.allSettled([
+    const readDocument = this.options.readDocument ?? fetchGoDocument;
+    const [listing, metadata, documentation] = await Promise.allSettled([
       fetchModelIds(this.options.baseURL),
-      this.refreshMetadata(builtin)
+      this.refreshMetadata(builtin),
+      readDocument()
     ]);
     if (metadata.status === "rejected") {
       this.options.observers?.onFallback?.({
@@ -473,6 +588,15 @@ var OpencodeGoCatalog = class {
         kept: this.lastMetadata?.models.size ?? 0
       });
     }
+    if (documentation.status === "fulfilled") {
+      this.document = documentation.value;
+    } else {
+      this.options.observers?.onFallback?.({
+        url: GO_DOC_URLS[0] ?? "the Go documentation",
+        error: documentation.reason,
+        kept: this.document?.quotas.size ?? 0
+      });
+    }
     if (listing.status === "rejected") {
       const previous = this.served;
       this.options.observers?.onFallback?.({
@@ -487,7 +611,8 @@ var OpencodeGoCatalog = class {
         provider: buildProvider(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
         live: false,
         listingFailure: listing.reason,
-        fetchedAtMs: Date.now()
+        fetchedAtMs: Date.now(),
+        ...this.documentQuotas()
       };
     }
     return this.assemble(
@@ -511,7 +636,7 @@ var OpencodeGoCatalog = class {
         unavailable.set(id, reason);
         continue;
       }
-      facts.set(id, this.inferredFacts(id, builtin));
+      facts.set(id, this.withDocumentedProtocol(this.inferredFacts(id, builtin)));
     }
     if (unavailable.size > 0) {
       this.options.observers?.onUnconfigured?.(
@@ -523,9 +648,28 @@ var OpencodeGoCatalog = class {
       unavailable,
       provider: buildProvider(this.options.baseURL, [...facts.values()].map((fact) => toPiModel(fact, this.options.baseURL))),
       live: true,
-      fetchedAtMs: Date.now()
+      fetchedAtMs: Date.now(),
+      ...this.documentQuotas()
     };
   }
+  /** The document allowances as a snapshot field, absent until one fetch lands. */
+  documentQuotas() {
+    return this.document === void 0 ? {} : { documentQuotas: this.document.quotas };
+  }
+  /**
+   * Prefer the documented protocol over anything below the installed catalog.
+   *
+   * The endpoint table is the provider's own statement, so it outranks both the
+   * family guess and models.dev's SDK hint — this turns an `inferred` badge into
+   * a known answer for ids the installed catalog misses. It never overrides a
+   * builtin entry or a configured override: those carry the wire quirks the
+   * adapter relies on.
+   */
+  withDocumentedProtocol(facts) {
+    if (facts.protocolSource !== "inferred" && facts.protocolSource !== "online") return facts;
+    const documented = this.document?.protocols.get(facts.id);
+    return documented === void 0 ? facts : { ...facts, api: documented, protocolSource: "document" };
+  }
   /** Facts for an id no source describes, from the ladder and the route defaults. */
   inferredFacts(id, builtin) {
     const exact = builtin.get(id);
@@ -556,7 +700,7 @@ var OpencodeGoCatalog = class {
     const response = await fetch(MODEL_METADATA_URL, {
       redirect: "error",
       headers: {
-        ...attributionHeaders2(),
+        ...attributionHeaders3(),
         accept: "application/json",
         "cache-control": "no-cache",
         ...this.metadataETag === void 0 ? {} : { "if-none-match": this.metadataETag }
@@ -598,8 +742,8 @@ function inferFamily(id) {
 async function discoverCatalogModels(catalog) {
   const snapshot = await catalog.snapshot(true);
   if (!snapshot.live) {
-    const detail = snapshot.listingFailure instanceof LlmError3 ? snapshot.listingFailure.message : "the live model listing is unreachable";
-    throw new LlmError3(`dshopencodego: ${detail}; refresh the model list to retry`, "DISCOVERY_FAILED", {
+    const detail = snapshot.listingFailure instanceof LlmError4 ? snapshot.listingFailure.message : "the live model listing is unreachable";
+    throw new LlmError4(`dshopencodego: ${detail}; refresh the model list to retry`, "DISCOVERY_FAILED", {
       cause: snapshot.listingFailure
     });
   }
@@ -670,11 +814,11 @@ function assertBaseURL(raw) {
 // src/conversion/context.ts
 import { brandString } from "@deepseek-ai/dsh-brand";
 import * as llm from "@deepseek-ai/dsh-llm";
-import { contentHasImage, LlmError as LlmError5, requestImageHandleText } from "@deepseek-ai/dsh-llm";
+import { contentHasImage, LlmError as LlmError6, requestImageHandleText } from "@deepseek-ai/dsh-llm";
 import { requestImageDimensions } from "@deepseek-ai/dsh-attachment";
 
 // src/conversion/replay.ts
-import { LlmError as LlmError4 } from "@deepseek-ai/dsh-llm";
+import { LlmError as LlmError5 } from "@deepseek-ai/dsh-llm";
 function parseArguments(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -733,7 +877,7 @@ function toPiReplayState(message, requestedModel = message.model) {
   };
 }
 function invalidReplay(message) {
-  throw new LlmError4(`invalid pi-ai replay state: ${message}`, "INVALID_REPLAY_STATE");
+  throw new LlmError5(`invalid pi-ai replay state: ${message}`, "INVALID_REPLAY_STATE");
 }
 function readReplayState(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return invalidReplay("expected a replay envelope");
@@ -793,7 +937,7 @@ function foreignAssistant(message) {
         });
         break;
       case "image":
-        throw new LlmError4("pi-ai chat history cannot represent structured assistant image output", "UNSUPPORTED_CONTENT");
+        throw new LlmError5("pi-ai chat history cannot represent structured assistant image output", "UNSUPPORTED_CONTENT");
       default:
         break;
     }
@@ -867,7 +1011,7 @@ function toPiAssistant(message, onDegrade) {
   try {
     return replayedAssistant(message, source, source.replayState);
   } catch (error) {
-    if (!(error instanceof LlmError4) || error.code !== "INVALID_REPLAY_STATE") throw error;
+    if (!(error instanceof LlmError5) || error.code !== "INVALID_REPLAY_STATE") throw error;
     onDegrade?.(error.message);
     return foreignAssistant(message);
   }
@@ -883,7 +1027,7 @@ function toolMessage(message) {
 function assertSupportedImageRoles(messages) {
   for (const message of messages) {
     if (message.role !== "user" && toolMessage(message) === void 0 && contentHasImage(message.content)) {
-      throw new LlmError5(`pi-ai cannot represent an image in an in-history ${message.role} message`, "UNSUPPORTED_CONTENT");
+      throw new LlmError6(`pi-ai cannot represent an image in an in-history ${message.role} message`, "UNSUPPORTED_CONTENT");
     }
   }
 }
@@ -931,7 +1075,7 @@ async function userContent(blocks, requestImages, resolveImageAccess) {
     if (block.type === "image") {
       const version = requestImages.get(block.attachment.attachmentId);
       if (version === void 0) {
-        throw new LlmError5(
+        throw new LlmError6(
           "dshopencodego: an image in this request has no prepared bytes; image input requires the attachment service",
           "UNSUPPORTED_CONTENT"
         );
@@ -955,7 +1099,7 @@ function projectImagesForRequest(messages, images, requestImages) {
       (block) => requestImages.get(block.attachment.attachmentId).bytes
     );
     if (over > 0) {
-      throw new LlmError5(
+      throw new LlmError6(
         `request images exceed the ${images.maxRequestImageBytes}-byte base64 bound; ${over} more oldest occurrence(s) must be offloaded`,
         llm.IMAGE_OFFLOAD_REQUIRED_CODE,
         { offloadImages: over }
@@ -1017,7 +1161,7 @@ import {
   EMPTY_RESPONSE_CODE,
   isContextWindowExceededError,
   isQuotaExceededError,
-  LlmError as LlmError6
+  LlmError as LlmError7
 } from "@deepseek-ai/dsh-llm";
 import { isContextOverflow } from "@earendil-works/pi-ai";
 function mapUsage(usage) {
@@ -1170,11 +1314,11 @@ async function* toStreamChunks(events, contextWindow, callerSignal, requestedMod
         return;
     }
   }
-  throw new LlmError6("pi-ai event stream ended without a terminal event", "STREAM_CLOSED");
+  throw new LlmError7("pi-ai event stream ended without a terminal event", "STREAM_CLOSED");
 }
 
 // src/go-limits.ts
-var GO_QUOTAS = {
+var SEED_QUOTAS = {
   "glm-5.3-flash": { monthlyUsd: 60, monthlyRequests: 31580 },
   "glm-5.3": { monthlyUsd: 15, monthlyRequests: 1080 },
   "glm-5.2": { monthlyUsd: 60, monthlyRequests: 4300 },
@@ -1210,7 +1354,7 @@ var GO_QUOTAS = {
   "gpt-5.6-luna": { monthlyUsd: 15, monthlyRequests: 10250 }
 };
 function goQuotaFor(id) {
-  return Object.hasOwn(GO_QUOTAS, id) ? GO_QUOTAS[id] : void 0;
+  return Object.hasOwn(SEED_QUOTAS, id) ? SEED_QUOTAS[id] : void 0;
 }
 function monthlyRequestsRank(quota) {
   if (quota === void 0) return -1;
@@ -1250,7 +1394,7 @@ function sortModels(models, now = Date.now()) {
 
 // src/session-header.ts
 import { randomUUID } from "node:crypto";
-import { attributionHeaders as attributionHeaders3 } from "@deepseek-ai/dsh-llm";
+import { attributionHeaders as attributionHeaders4 } from "@deepseek-ai/dsh-llm";
 var SESSION_HEADER = "x-opencode-session";
 function opencodeSessionValue(sessionId) {
   return sessionId !== void 0 && sessionId.length > 0 ? sessionId : randomUUID();
@@ -1258,7 +1402,7 @@ function opencodeSessionValue(sessionId) {
 function providerHeaders(sessionId) {
   return {
     [SESSION_HEADER]: opencodeSessionValue(sessionId),
-    ...attributionHeaders3()
+    ...attributionHeaders4()
   };
 }
 
@@ -1323,7 +1467,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
     const config = this.options.config();
     const snapshot = await this.catalogOf(config).forModel(model);
     const facts = snapshot.facts.get(model);
-    if (facts === void 0) throw new LlmError7(`opencode-go has no model "${model}"`, "UNKNOWN_MODEL");
+    if (facts === void 0) throw new LlmError8(`opencode-go has no model "${model}"`, "UNKNOWN_MODEL");
     return this.modelInfo(withModelLimit(toPiModel(facts, config.baseURL), config.modelLimits));
   }
   /** Describe one model: capacities plus the reasoning levels it really offers. */
@@ -1369,7 +1513,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
     if (effort === void 0 || effort === "off") return void 0;
     const supported = getSupportedThinkingLevels(model);
     if (supported.some((level) => level === effort)) return effort;
-    throw new LlmError7(
+    throw new LlmError8(
       `opencode-go model "${model.id}" does not support reasoning effort "${effort}"`,
       "UNSUPPORTED_REASONING_EFFORT"
     );
@@ -1378,18 +1522,18 @@ var OpencodeGoAdapter = class extends LlmAdapter {
     var _stack = [];
     try {
       if (options.stop !== void 0) {
-        throw new LlmError7("dshopencodego does not support GenerateOptions.stop", "UNSUPPORTED_OPTION");
+        throw new LlmError8("dshopencodego does not support GenerateOptions.stop", "UNSUPPORTED_OPTION");
       }
       const config = this.options.config();
       const snapshot = await this.catalogOf(config).forModel(options.model);
       const facts = snapshot.facts.get(options.model);
-      if (facts === void 0) throw new LlmError7(`opencode-go has no model "${options.model}"`, "UNKNOWN_MODEL");
+      if (facts === void 0) throw new LlmError8(`opencode-go has no model "${options.model}"`, "UNKNOWN_MODEL");
       const model = withModelLimit(toPiModel(facts, config.baseURL), config.modelLimits);
       const ceiling = config.modelLimits[model.id]?.maxTokens;
       const maxTokens = options.maxTokens === void 0 || ceiling === null || ceiling === void 0 ? options.maxTokens : Math.min(options.maxTokens, ceiling);
       const apiKey = await this.options.resolveApiKey();
       if (apiKey === void 0 || apiKey.length === 0) {
-        throw new LlmError7("dshopencodego: no credential resolved for the opencode-go route", "MISSING_CREDENTIAL");
+        throw new LlmError8("dshopencodego: no credential resolved for the opencode-go route", "MISSING_CREDENTIAL");
       }
       const reasoning = this.resolveReasoningLevel(model, options.reasoningEffort);
       const consumer = new AbortController();
@@ -1398,14 +1542,14 @@ var OpencodeGoAdapter = class extends LlmAdapter {
       try {
         const containsImage = options.messages.some((message) => contentHasImage2(message.content));
         if (containsImage && !model.input.includes("image")) {
-          throw new LlmError7(`opencode-go model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
+          throw new LlmError8(`opencode-go model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
         }
         let imageRequest;
         if (containsImage) {
           const access = this.options.imageAccess;
           const store = access?.resolveAttachments();
           if (access === void 0 || store === void 0) {
-            throw new LlmError7("dshopencodego image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
+            throw new LlmError8("dshopencodego image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
           }
           imageRequest = {
             attachments: store,
@@ -1435,7 +1579,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           while (true) {
             const result = await watchdog.next(iterator);
             if (timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT") !== void 0) {
-              throw new LlmError7("opencode-go stream idle timeout", "TIMEOUT");
+              throw new LlmError8("opencode-go stream idle timeout", "TIMEOUT");
             }
             if (result.done) {
               exhausted = true;
@@ -1457,10 +1601,10 @@ var OpencodeGoAdapter = class extends LlmAdapter {
         }
       } catch (error) {
         if (timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT") !== void 0) {
-          throw new LlmError7("opencode-go stream idle timeout", "TIMEOUT", { cause: error });
+          throw new LlmError8("opencode-go stream idle timeout", "TIMEOUT", { cause: error });
         }
         if (options.signal?.aborted) {
-          throw new LlmError7("opencode-go request aborted by caller", "ABORTED", { cause: error });
+          throw new LlmError8("opencode-go request aborted by caller", "ABORTED", { cause: error });
         }
         throw error;
       } finally {
@@ -1544,11 +1688,16 @@ function parseCatalogReading(value) {
     if (typeof entry !== "number" || !Number.isFinite(entry) || entry < 0) throw new Error(`invalid catalog count "${key}"`);
     return entry;
   };
+  const quotaSource = row["quotaSource"];
+  if (quotaSource !== void 0 && quotaSource !== "document" && quotaSource !== "seed") {
+    throw new Error("invalid catalog quota source");
+  }
   return {
     models: row["models"].map(parseModel),
     stale: row["stale"],
     ...typeof row["error"] === "string" ? { error: row["error"] } : {},
     fetchedAtMs: row["fetchedAtMs"],
+    quotaSource: quotaSource ?? "seed",
     counts: {
       total: count("total"),
       enabled: count("enabled"),
@@ -1691,13 +1840,14 @@ function registerRemotes(ctx) {
 
 // src/catalog/service.ts
 import { RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
-import { LlmError as LlmError8 } from "@deepseek-ai/dsh-llm";
+import { LlmError as LlmError9 } from "@deepseek-ai/dsh-llm";
 
 // src/catalog/reading.ts
 function catalogReading(snapshot, visibility, listingFailure) {
+  const documentQuotas = snapshot.documentQuotas;
   const rows = [
     ...[...snapshot.facts.values()].map((fact) => {
-      const quota = goQuotaFor(fact.id);
+      const quota = documentQuotas === void 0 ? goQuotaFor(fact.id) : documentQuotas.get(fact.id);
       const priced = fact.cost.input > 0 || fact.cost.output > 0;
       return {
         id: fact.id,
@@ -1731,6 +1881,7 @@ function catalogReading(snapshot, visibility, listingFailure) {
     stale: !snapshot.live,
     ...!snapshot.live && listingFailure !== void 0 ? { error: listingFailure } : {},
     fetchedAtMs: snapshot.fetchedAtMs,
+    quotaSource: documentQuotas === void 0 ? "seed" : "document",
     counts: {
       total: models.length,
       enabled,
@@ -1763,7 +1914,7 @@ var OpencodeGoCatalogService = class extends TypertRemoteService {
     return catalogReading(
       snapshot,
       this.options.visibility(),
-      failure === void 0 ? void 0 : failure instanceof LlmError8 || failure instanceof Error ? failure.message : String(failure)
+      failure === void 0 ? void 0 : failure instanceof LlmError9 || failure instanceof Error ? failure.message : String(failure)
     );
   }
 };
@@ -1819,7 +1970,7 @@ var UsageMeter = class {
 };
 
 // src/usage/windows.ts
-import { attributionHeaders as attributionHeaders5, LlmError as LlmError9 } from "@deepseek-ai/dsh-llm";
+import { attributionHeaders as attributionHeaders6, LlmError as LlmError10 } from "@deepseek-ai/dsh-llm";
 var USAGE_MAX_BYTES = 1024 * 1024;
 var USAGE_TIMEOUT_MS = 1e4;
 function parseGoUsage(value) {
@@ -1837,7 +1988,7 @@ function parseGoUsage(value) {
 }
 async function readUsageWindows(options) {
   if (options.apiKey === void 0 || options.apiKey.length === 0) {
-    throw new LlmError9("dshopencodego: no credential is configured for the opencode-go route", "USAGE_UNAVAILABLE");
+    throw new LlmError10("dshopencodego: no credential is configured for the opencode-go route", "USAGE_UNAVAILABLE");
   }
   const url = `${options.baseURL.replace(/\/+$/, "")}/usage`;
   const timeout = AbortSignal.timeout(USAGE_TIMEOUT_MS);
@@ -1846,19 +1997,19 @@ async function readUsageWindows(options) {
     response = await fetch(url, {
       redirect: "error",
       headers: {
-        ...attributionHeaders5(),
+        ...attributionHeaders6(),
         accept: "application/json",
         authorization: `Bearer ${options.apiKey}`
       },
       signal: options.signal === void 0 ? timeout : AbortSignal.any([options.signal, timeout])
     });
   } catch (error) {
-    throw new LlmError9(`could not reach ${url}`, "USAGE_UNAVAILABLE", { cause: error });
+    throw new LlmError10(`could not reach ${url}`, "USAGE_UNAVAILABLE", { cause: error });
   }
   if (!response.ok) {
     await response.body?.cancel().catch(() => {
     });
-    throw new LlmError9(`${url} answered HTTP ${response.status}`, "USAGE_UNAVAILABLE");
+    throw new LlmError10(`${url} answered HTTP ${response.status}`, "USAGE_UNAVAILABLE");
   }
   const body = await readBoundedJson(response, url, USAGE_MAX_BYTES);
   try {
@@ -1867,16 +2018,16 @@ async function readUsageWindows(options) {
       ...options.source === void 0 ? {} : { source: options.source }
     };
   } catch (error) {
-    throw new LlmError9(`${url} returned an invalid usage document`, "USAGE_UNAVAILABLE", { cause: error });
+    throw new LlmError10(`${url} returned an invalid usage document`, "USAGE_UNAVAILABLE", { cause: error });
   }
 }
 
 // src/usage/service.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { RemoteError as RemoteError2, TypertRemoteService as TypertRemoteService2 } from "@deepseek-ai/dsh-typert-protocol";
-import { LlmError as LlmError10 } from "@deepseek-ai/dsh-llm";
+import { LlmError as LlmError11 } from "@deepseek-ai/dsh-llm";
 function usageFailure(error, source) {
-  const missing = error instanceof LlmError10 && error.code === "MISSING_CREDENTIAL";
+  const missing = error instanceof LlmError11 && error.code === "MISSING_CREDENTIAL";
   return new RemoteError2(
     "dshopencodego/usage-unavailable",
     error instanceof Error ? error.message : "OpenCode Go usage is unavailable",
@@ -1903,7 +2054,7 @@ var OpencodeGoUsageService = class extends TypertRemoteService2 {
     }
     if (key === void 0 || key.length === 0) {
       this.identity = void 0;
-      throw usageFailure(new LlmError10("No OpenCode Go API key is configured", "MISSING_CREDENTIAL"), void 0);
+      throw usageFailure(new LlmError11("No OpenCode Go API key is configured", "MISSING_CREDENTIAL"), void 0);
     }
     if (this.identity?.baseURL !== baseURL || this.identity.key !== key) {
       this.identity = { baseURL, key, source: randomUUID2() };
@@ -1937,7 +2088,7 @@ function apply(ctx, raw) {
     const credentials = ctx.get("credentials");
     const hit = credentials !== void 0 ? (await credentials.resolve(credentialRef(ref)))?.value : launchEnvironmentOf(ctx).get(ref)?.value;
     if (hit !== void 0 && hit.length > 0) return llm2.assertUsableApiKey(hit, name, ref);
-    throw new LlmError11(
+    throw new LlmError12(
       `dshopencodego: no credential; the profile resolves ${ref}, which is not set \u2014 store ${ref} through the credentials service (the Web Models page writes it) or export it`,
       "MISSING_CREDENTIAL"
     );
@@ -2018,7 +2169,7 @@ function apply(ctx, raw) {
   syncRoute();
   const undiscover = ctx.llm.registerModelDiscovery(name, async (request) => {
     if (request.provider !== PROVIDER_ID && !(request.baseURL ?? "").includes("opencode.ai")) {
-      throw new LlmError11(
+      throw new LlmError12(
         "dshopencodego discovers only OpenCode zen/go endpoints; enter this provider's models by hand",
         "DISCOVERY_UNSUPPORTED"
       );

package/lib/types/catalog/contract.js

@@ -93,11 +93,18 @@ export function parseCatalogReading(value) {
             throw new Error(`invalid catalog count "${key}"`);
         return entry;
     };
+    const quotaSource = row['quotaSource'];
+    // Absent means the payload predates the field — a cached client bundle with a
+    // newer host — and the seed is what such a reading actually carries.
+    if (quotaSource !== undefined && quotaSource !== 'document' && quotaSource !== 'seed') {
+        throw new Error('invalid catalog quota source');
+    }
     return {
         models: row['models'].map(parseModel),
         stale: row['stale'],
         ...typeof row['error'] === 'string' ? { error: row['error'] } : {},
         fetchedAtMs: row['fetchedAtMs'],
+        quotaSource: quotaSource ?? 'seed',
         counts: {
             total: count('total'),
             enabled: count('enabled'),

package/lib/types/catalog/go-doc.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The provider's own Go documentation as a data source.
+ *
+ * No API exposes the per-model allowances: the gateway's `/models` answers ids,
+ * and `/usage` answers account-wide percentages. The numbers live on a docs page
+ * whose source is a markdown file in the provider's repository, so this module
+ * fetches that file and parses its tables — allowances (with the provider's own
+ * request estimates) and the endpoint table that names each model's protocol.
+ *
+ * The document is the primary source. The transcribed table in `go-limits.ts`
+ * stays behind it as a startup seed and a permanent fallback for the day the
+ * URL moves, and its age is surfaced wherever it is used.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/go-doc
+ */
+import type { GoQuota } from '../go-limits.ts';
+import type { WireProtocol } from './protocol.ts';
+/**
+ * Documentation sources, tried in order.
+ *
+ * The repository file is the source of truth; the jsDelivr entry caches the
+ * same path and is tried when GitHub itself is unreachable.
+ */
+export declare const GO_DOC_URLS: readonly string[];
+/** The document is about 30 KB; the cap leaves room without inviting a flood. */
+export declare const GO_DOC_MAX_BYTES: number;
+/** What one parse of the document yields. */
+export interface GoDoc {
+    /** Per-model allowances, keyed by the gateway's model id. */
+    readonly quotas: ReadonlyMap<string, GoQuota>;
+    /** Per-model protocol, straight from the provider's endpoint table. */
+    readonly protocols: ReadonlyMap<string, WireProtocol>;
+}
+/**
+ * Parse the Go documentation into the two data sets this plugin consumes.
+ *
+ * Titles are the join key: the allowance tables name models the way the page
+ * presents them while the endpoint table carries the ids, so ids come from the
+ * endpoint table and the other two attach by normalised display name. A row
+ * that names no known model, or states no usable number, is skipped rather than
+ * guessed; a tiered model whose rows disagree is dropped entirely.
+ * @param markdown - the raw document text.
+ * @returns the parsed allowances and protocols; both may be empty when the
+ *   document does not carry the expected tables.
+ */
+export declare function parseGoDocument(markdown: string): GoDoc;
+/**
+ * Fetch and parse the documentation, trying each source in turn.
+ *
+ * A source that answers without a usable allowance table counts as a failure,
+ * not as an empty document: that is what a moved or restructured page looks
+ * like, and the caller must keep its previous data rather than blank the page.
+ * @param signal - caller cancellation, if any.
+ * @returns the parsed document from the first source that carried one.
+ * @throws {LlmError} `DOCUMENT_UNAVAILABLE` when every source failed.
+ */
+export declare function fetchGoDocument(signal?: AbortSignal): Promise<GoDoc>;