dsh-opencode-go 0.1.14 → 0.1.16

package/lib/index.js

@@ -50,7 +50,7 @@ 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 { randomUUID as randomUUID2 } from "node:crypto";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import {
   LlmAdapter,
@@ -273,15 +273,15 @@ var api = llm;
 function projectRequestImages(messages, policy) {
   if (api.requiredImageOffload !== void 0 && api.projectOffloadedImages !== void 0) {
     if (!policy.exact) return messages;
-    if (policy.maxBytes !== void 0) {
+    if (policy.maxBytes !== void 0 || policy.maxImages !== void 0) {
       const offloadImages = api.requiredImageOffload(
         messages,
-        { representation: "base64", maxBytes: policy.maxBytes },
+        { representation: "base64", maxBytes: policy.maxBytes, maxImages: policy.maxImages, countQuantum: 1 },
         (block) => policy.byteLength(block.attachment)
       );
       if (offloadImages > 0) {
         throw new llm.LlmError(
-          `pi-ai request images exceed the ${policy.maxBytes}-byte base64 bound; ${offloadImages} more oldest occurrence(s) must be offloaded.`,
+          `pi-ai request images exceed the configured image count or base64 payload bound; ${offloadImages} more oldest occurrence(s) must be offloaded.`,
           api.IMAGE_OFFLOAD_REQUIRED_CODE ?? "IMAGE_OFFLOAD_REQUIRED",
           { offloadImages }
         );
@@ -295,6 +295,8 @@ function projectRequestImages(messages, policy) {
   return api.offloadRequestImagesWithPolicy(messages, {
     representation: "base64",
     byteQuantum: 1,
+    countQuantum: 1,
+    maxImages: policy.maxImages,
     maxBytes: policy.maxBytes,
     byteLength: policy.byteLength,
     placeholder: policy.placeholder
@@ -478,7 +480,7 @@ function toPiContext(options, images, onReplayDegrade) {
   return images === void 0 ? textOnlyContext(options, onReplayDegrade) : toPiContextWithImages(options, images, onReplayDegrade);
 }
 async function toPiContextWithImages(options, images, onReplayDegrade) {
-  const { attachments, resolveImageAccess, maxRequestImageBytes } = images;
+  const { attachments, resolveImageAccess, maxImages, maxRequestImageBytes } = images;
   const requestImagePolicy = images.requestImagePolicy ?? {
     maxPixels: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
     maxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES
@@ -486,6 +488,7 @@ async function toPiContextWithImages(options, images, onReplayDegrade) {
   assertSupportedHistory(options.messages);
   const split = splitSystemPrompt(options);
   const projection = {
+    maxImages,
     maxBytes: maxRequestImageBytes,
     placeholder: (ref) => offloadedImageText(ref, resolveImageAccess(ref))
   };
@@ -713,6 +716,13 @@ import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.l
 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;
@@ -744,6 +754,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;
   });
 }
@@ -849,9 +861,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);
@@ -993,6 +1007,55 @@ 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/catalog.ts
 var PROVIDER_ID = "opencode-go";
 var DISPLAY_NAME = "OpenCode Go";
@@ -1001,19 +1064,22 @@ 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);
@@ -1084,15 +1150,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;
@@ -1101,19 +1174,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 {
+    }
+  }
+  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;
+      });
     }
-    this.pending ??= this.build().then((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,6 +1245,8 @@ var OpencodeGoCatalog = class {
     }, MODEL_METADATA_MAX_BYTES);
     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");
@@ -1138,26 +1257,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();
@@ -1185,7 +1302,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,
@@ -1207,7 +1326,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(
@@ -1286,6 +1407,7 @@ var fields = {
   baseURL: z.string().default(DEFAULT_BASE_URL),
   refreshMinutes: z.number().step(1).min(1).max(7 * 24 * 60).default(DEFAULT_REFRESH_MINUTES),
   streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  maxImages: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
   // The image defaults are the generic pi-ai adapter's: one normalized
   // request image fits the budget, and fifteen of them fit the payload cap.
   maxRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_IMAGE_BYTES),
@@ -1332,7 +1454,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) {
@@ -1356,19 +1478,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;
   }
@@ -1476,6 +1599,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           imageRequest = {
             attachments: store,
             resolveImageAccess: (ref) => access.resolveImageAccess(store, ref),
+            maxImages: config.maxImages ?? void 0,
             maxRequestImageBytes: config.maxRequestImageBytes,
             requestImagePolicy: {
               maxPixels: config.requestImagePixelBudget,
@@ -1543,7 +1667,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";
 
@@ -1615,7 +1739,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`);
@@ -1721,6 +1845,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,
@@ -1734,11 +1859,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: () => {
@@ -1791,6 +1918,7 @@ function apply(ctx, raw) {
   });
   ctx.effect(() => () => {
     registration?.();
+    registration = void 0;
     undiscover();
   });
   ctx.inject(["settings"], (settingsCtx) => {

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

@@ -30,9 +30,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 +49,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/Section.d.ts

@@ -1,9 +1,10 @@
 /**
- * The OpenCode Go settings section. It leads with the one value a user has to
- * supply — the API key, stored write-only through the credentials domain — and
- * the models the gateway currently serves, then keeps the credential
- * reference, the endpoint, and the adapter tuning fields in the
- * `llm-opencode-go` namespace behind a collapsed disclosure.
+ * The OpenCode Go settings page. Three cards carry the page's whole order — the
+ * connection (the switch that routes the provider plus the API key it
+ * authenticates with), the models the gateway currently serves and their
+ * capacities, and the adapter tuning fields behind a collapsed disclosure at the
+ * foot. The credential reference, the endpoint, and the tuning knobs all live in
+ * the `llm-opencode-go` namespace, so every card writes the same document.
  */
 import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
 import type { OpencodeGoSectionFace } from './section-controller.ts';

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

@@ -19,6 +19,7 @@ export declare const en: {
     usageRefreshing: string;
     nav: string;
     title: string;
+    titleLabel: string;
     intro: string;
     starProject: string;
     starProjectTitle: string;
@@ -56,6 +57,15 @@ export declare const en: {
     limitsOutput: string;
     capacityDefault: string;
     capacityMissing: string;
+    modalityLabel: string;
+    modalityText: string;
+    modalityImage: string;
+    modalityAudio: string;
+    modalityVideo: string;
+    modalityPdf: string;
+    modalityUnknown: string;
+    modalitiesSource: string;
+    modalitiesForwarding: string;
     visibilityHint: string;
     modelVisibleLabel: string;
     configurationMissing: string;
@@ -67,7 +77,6 @@ export declare const en: {
     deprecatedHint: string;
     newHint: string;
     newBadge: string;
-    releasedOn: string;
     releaseSource: string;
     modelDetails: string;
     filterLabel: string;
@@ -81,6 +90,7 @@ export declare const en: {
     limitsEmpty: string;
     limitsContextLabel: string;
     limitsOutputLabel: string;
+    advancedSummary: string;
     advancedLabel: string;
     advancedHint: string;
     apiKeyEnvLabel: string;
@@ -91,6 +101,8 @@ export declare const en: {
     refreshMinutesHint: string;
     streamIdleTimeoutMsLabel: string;
     streamIdleTimeoutMsHint: string;
+    maxImagesLabel: string;
+    maxImagesHint: string;
     maxRequestImageBytesLabel: string;
     maxRequestImageBytesHint: string;
     requestImagePixelBudgetLabel: string;

package/lib/types/client/section-controller.d.ts

@@ -30,6 +30,8 @@ export interface OpencodeGoSettings {
     refreshMinutes?: number;
     /** Largest idle gap between stream events, in milliseconds. */
     streamIdleTimeoutMs?: number;
+    /** Optional retained image occurrence cap per request. */
+    maxImages?: number | null;
     /** Accumulated base64 image payload bound for one request. */
     maxRequestImageBytes?: number;
     /** Total-pixel budget for one request image. */
@@ -94,6 +96,8 @@ export interface OpencodeGoSectionState extends FormShell {
     refreshMinutes: FieldState;
     /** Largest idle gap between stream events, in milliseconds. */
     streamIdleTimeoutMs: FieldState;
+    /** Optional retained image occurrence cap; blank inherits the base configuration. */
+    maxImages: FieldState;
     /** Accumulated base64 image payload bound for one request. */
     maxRequestImageBytes: FieldState;
     /** Total-pixel budget for one request image. */

package/lib/types/client/staged-form.d.ts

@@ -88,12 +88,13 @@ export interface FormActions {
     discard: () => void;
 }
 /**
- * A whole-number field. An empty draft clears the field; any other draft that
- * is not a finite number blocks the save.
+ * A numeric field. An empty draft clears the field; other drafts must be
+ * finite numbers and satisfy the optional constraint before saving.
  * @param field - field name inside the namespace section.
+ * @param validate - additional numeric constraint, if needed.
  * @returns the field's conversion spec.
  */
-export declare function numberField(field: string): FieldSpec;
+export declare function numberField(field: string, validate?: (value: number) => boolean): FieldSpec;
 /**
  * A two-state field. Unlike the text fields, the draft is the boolean itself
  * rather than text: the control that renders it reports the state the user

package/lib/types/config.d.ts

@@ -48,6 +48,8 @@ export interface OpencodeGoConfig {
     refreshMinutes: number;
     /** Largest idle gap between stream events before the request fails. */
     streamIdleTimeoutMs: number;
+    /** Optional retained image occurrence cap per request; omission or null leaves the count unlimited. */
+    maxImages?: number | null;
     /** Request-level bound on base64-encoded image payload, in bytes. */
     maxRequestImageBytes: number;
     /** Total-pixel budget for one request image. */

package/lib/types/conversion/context.d.ts

@@ -12,6 +12,8 @@ export interface PiImageRequestContext {
     attachments: AttachmentStore;
     /** Resolve current tool access separately from deterministic request-image versions. */
     resolveImageAccess: ImageAttachmentAccessResolver;
+    /** Maximum retained image occurrences across request history; omission leaves the count unlimited. */
+    maxImages?: number;
     /** Request-level bound on the base64-encoded payload of retained images; omission leaves the bound unchecked. */
     maxRequestImageBytes?: number;
     /** Route pixel and raw encoded-byte budgets. */
@@ -39,7 +41,7 @@ export declare function toPiContext(options: GenerateOptions, images?: undefined
  * Tool result names are recovered from preceding assistant tool calls. On DSH
  * 0.1.5, oldest images over the request budget become transient placeholders.
  * On newer hosts, occurrences the surface marks offloaded become placeholders; when the
- * retained occurrences' exact base64 payload still exceeds
+ * retained occurrences exceed `maxImages` or their exact base64 payload exceeds
  * `maxRequestImageBytes`, the call fails with `IMAGE_OFFLOAD_REQUIRED` naming
  * how many more oldest occurrences must be offloaded.
  * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.

package/lib/types/conversion/image-offload.d.ts

@@ -1,6 +1,7 @@
 import type { Message } from '@deepseek-ai/dsh-llm';
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
 interface ImageProjectionPolicy {
+    maxImages?: number;
     maxBytes?: number;
     byteLength: (ref: ImageAttachmentRef) => number;
     placeholder: (ref: ImageAttachmentRef) => string;

package/lib/types/metadata-cache.d.ts

@@ -0,0 +1,12 @@
+export declare const MODEL_METADATA_MAX_BYTES: number;
+export interface CachedMetadata {
+    readonly body: unknown;
+    readonly etag?: string;
+    /** Last successful download or HTTP 304 verification. */
+    readonly savedAtMs: number;
+}
+export declare function metadataCachePath(): string;
+/** Only persist validators that can safely become an HTTP request header. */
+export declare function metadataETag(value: unknown): string | undefined;
+export declare function readMetadataCache(path: string): Promise<CachedMetadata | undefined>;
+export declare function writeMetadataCache(path: string, value: CachedMetadata): Promise<void>;

package/lib/types/model-metadata.d.ts

@@ -2,9 +2,11 @@
 import type { Api, Model } from '@earendil-works/pi-ai';
 import { type GoModel } from './models-contract.ts';
 export declare const MODEL_METADATA_URL = "https://models.dev/api.json";
+/** Lifecycle and capability data the online catalog adds to a gateway listing. */
+export type ModelDetails = Pick<GoModel, 'deprecated' | 'releaseDate' | 'inputModalities'>;
 export interface ModelMetadata {
     readonly models: ReadonlyMap<string, Model<Api>>;
-    readonly details: ReadonlyMap<string, Pick<GoModel, 'deprecated' | 'releaseDate'>>;
+    readonly details: ReadonlyMap<string, ModelDetails>;
     readonly errors: ReadonlyMap<string, string>;
 }
 /** Anthropic's SDK appends /v1/messages; the OpenAI SDKs append paths below /v1. */