@darthph0enix/commandcode-go-opencode-provider 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darthph0enix/commandcode-go-opencode-provider",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "author": "Brent Weatherall",
   "repository": {
     "type": "git",

package/plugin.ts

@@ -21,7 +21,18 @@ export default async function commandcodePlugin() {
       if (!cc.env) cc.env = ["COMMANDCODE_API_KEY"]
 
       if (!cc.models) {
-        const { models } = await loadSyncedModels()
+        const options = (cc.options as Record<string, unknown> | undefined) ?? {}
+        const baseURL = typeof options.baseURL === "string" ? options.baseURL.replace(/\/+$/, "") : undefined
+        const catalogUrl =
+          typeof options.catalogUrl === "string"
+            ? options.catalogUrl
+            : baseURL
+              ? `${baseURL}/catalog.json`
+              : undefined
+        const { models, source } = await loadSyncedModels({ catalogUrl })
+        if (process.env.COMMANDCODE_DEBUG) {
+          console.warn(`[commandcode] injected ${models.length} models from ${source}`)
+        }
         const modelsObj: Record<string, unknown> = {}
         for (const entry of models) {
           const key = toConfigKey(entry.id)

package/src/convert.ts

@@ -1,4 +1,7 @@
 import type { LanguageModelV3CallOptions } from "@ai-sdk/provider"
+import { readFileSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
 import type {
   LanguageModelV3FunctionTool,
   LanguageModelV3Message,
@@ -109,7 +112,10 @@ function toDataUriOrUrl(data: string | Uint8Array | URL, defaultMime: string = "
   return String(data)
 }
 
-function convertUserContent(content: unknown): string | Array<{ type: string; [key: string]: unknown }> {
+function convertUserContent(
+  content: unknown,
+  forwarder?: ImageForwarder,
+): string | Array<{ type: string; [key: string]: unknown }> {
   if (typeof content === "string") return content
   if (!Array.isArray(content)) return ""
 
@@ -122,20 +128,20 @@ function convertUserContent(content: unknown): string | Array<{ type: string; [k
 
     if (item.type === "text" && typeof item.text === "string") {
       parts.push({ type: "text", text: item.text })
-    } else if (item.type === "image" && item.image) {
-      hasMultimodal = true
-      const mimeType = typeof item.mimeType === "string" ? item.mimeType : "image/png"
-      const imgUrl = toDataUriOrUrl(item.image as string | Uint8Array | URL, mimeType)
-      parts.push({ type: "image", image: imgUrl, mimeType })
-    } else if (item.type === "file" && item.data) {
-      const mimeType = typeof item.mimeType === "string" ? item.mimeType : "application/octet-stream"
-      if (mimeType.startsWith("image/")) {
+      continue
+    }
+    if (item.type === "file" || item.type === "image" || item.type === "media") {
+      // `{ type: "file", data: "<raw base64>", mediaType: "image/png" }` is how
+      // opencode hands tool-result attachments to providers. Emitting those as
+      // text is what pushed ~1.5M tokens of base64 into a single request.
+      if (convertBinaryPart(item, parts, forwarder ? forwarder.enabled : true)) {
         hasMultimodal = true
-        const imgUrl = toDataUriOrUrl(item.data as string | Uint8Array | URL, mimeType)
-        parts.push({ type: "image", image: imgUrl, mimeType })
-      } else if (typeof item.data === "string" && !item.data.startsWith("data:")) {
-        parts.push({ type: "text", text: item.data })
       }
+      continue
+    }
+    // Unknown part carrying an obvious binary payload: never serialize it as text
+    if (isBinaryLikePart(item)) {
+      parts.push({ type: "text", text: describeBinaryPart(item) })
     }
   }
 
@@ -145,29 +151,286 @@ function convertUserContent(content: unknown): string | Array<{ type: string; [k
   return parts
 }
 
-function convertToolResultOutput(output: LanguageModelV3ToolResultOutput): CCToolResultContent["output"] {
+/** Extract the mime type from a `data:<mime>;base64,<payload>` URI. */
+function dataUriMime(dataUri: string): string | null {
+  if (!dataUri.startsWith("data:")) return null
+  const semi = dataUri.indexOf(";")
+  const comma = dataUri.indexOf(",")
+  if (semi === -1 || comma === -1 || semi > comma) return null
+  const mime = dataUri.slice(5, semi)
+  return mime || null
+}
+
+/**
+ * Media type of a binary part. opencode's serialiser emits `mediaType`; older
+ * callers use `mimeType`; and when neither is declared, the payload's `data:`
+ * header still tells us what it is.
+ */
+function detectMediaType(item: Record<string, unknown>): string {
+  const declared = item.mediaType ?? item.mimeType ?? item.media_type
+  if (typeof declared === "string" && declared.trim()) return declared.trim()
+  const payload = item.data ?? item.url ?? item.image
+  if (typeof payload === "string") {
+    const mime = dataUriMime(payload)
+    if (mime) return mime
+  }
+  return "application/octet-stream"
+}
+
+function describeOmittedImage(item: Record<string, unknown>, mimeType: string, reason: string): string {
+  const bytes = byteLengthOf(item.data) || byteLengthOf(item.image) || byteLengthOf(item.url) || 0
+  const size = bytes > 0 ? `, ${Math.max(1, Math.round(bytes / 1024))} KB` : ""
+  return `[image omitted: ${mimeType}${size} — ${reason}]`
+}
+
+/**
+ * Convert one binary content part (user attachment or tool-result media) into a
+ * wire content part, appending to `parts`. Returns true when an actual image
+ * part was emitted (i.e. the message now carries multimodal content).
+ *
+ * Images are emitted as `{ type: "image", image: "data:<mime>;base64,<b64>",
+ * mimeType }` — byte-for-byte the shape the Command Code CLI itself sends.
+ * Anything that cannot be transported becomes a short note; payloads are never
+ * inlined into text.
+ */
+function convertBinaryPart(
+  item: Record<string, unknown>,
+  parts: Array<{ type: string; [key: string]: unknown }>,
+  visionEnabled: boolean,
+): boolean {
+  const mimeType = detectMediaType(item)
+  const payload = item.data ?? item.url ?? item.image
+
+  if (mimeType.startsWith("image/")) {
+    if (!visionEnabled) {
+      parts.push({ type: "text", text: describeOmittedImage(item, mimeType, "this model does not accept image input") })
+      return false
+    }
+    if (payload === undefined || payload === null) {
+      parts.push({ type: "text", text: describeOmittedImage(item, mimeType, "no payload present") })
+      return false
+    }
+    const imgUrl = toDataUriOrUrl(payload as string | Uint8Array | URL, mimeType)
+    if (typeof imgUrl === "string" && imgUrl.startsWith("data:")) {
+      parts.push({ type: "image", image: imgUrl, mimeType })
+      return true
+    }
+    parts.push({
+      type: "text",
+      text: describeOmittedImage(item, mimeType, "the API accepts inline data URIs only, not remote URLs"),
+    })
+    return false
+  }
+
+  if (mimeType.startsWith("text/") && typeof payload === "string" && !payload.startsWith("data:")) {
+    if (payload.length > MAX_INLINE_TOOL_TEXT_CHARS) {
+      parts.push({
+        type: "text",
+        text: `[attachment omitted: ${mimeType}, ${Math.round(payload.length / 1024)} KB exceeds the inline limit]`,
+      })
+    } else {
+      parts.push({ type: "text", text: payload })
+    }
+    return false
+  }
+
+  parts.push({ type: "text", text: describeBinaryPart(item) })
+  return false
+}
+
+/**
+ * Hard ceiling for any single inlined tool-result payload. Anything larger is
+ * replaced by a size note instead of being inlined. Binary payloads (base64
+ * images, PDFs, data URIs) are never inlined at all — see `describeBinaryPart`.
+ */
+const MAX_INLINE_TOOL_TEXT_CHARS = 200_000
+
+/**
+ * Image forwarding budget per request. Tool images cannot ride inside a
+ * tool-result (Command Code accepts images only in user content), so they are
+ * re-emitted as a synthetic user message right after the tool message. These
+ * caps keep a pathological read (huge screenshot, repeated reads) bounded.
+ */
+const MAX_FORWARD_IMAGE_BYTES = 8 * 1024 * 1024
+const MAX_FORWARD_IMAGES_TOTAL = 12
+const MAX_FORWARD_IMAGE_BYTES_TOTAL = 16 * 1024 * 1024
+
+interface ForwardedImage {
+  mediaType: string
+  dataUri: string
+}
+
+interface ImageForwarder {
+  /** Whether the target model accepts image input at all. */
+  enabled: boolean
+  images: ForwardedImage[]
+  seen: Set<string>
+  bytes: number
+}
+
+function createImageForwarder(enabled: boolean): ImageForwarder {
+  return { enabled, images: [], seen: new Set<string>(), bytes: 0 }
+}
+
+function imageFingerprint(dataUri: string): string {
+  return `${dataUri.length}:${dataUri.slice(0, 64)}:${dataUri.slice(-64)}`
+}
+
+function kilobytes(dataUri: string): number {
+  return Math.max(1, Math.round(dataUri.length / 1024))
+}
+
+/**
+ * Decide what happens to one binary tool-result part.
+ *
+ * Image parts are handed to the forwarder (which re-emits them as a user
+ * message for vision-capable models) and replaced in the tool result by a short
+ * note. Everything else — and every image when the model cannot see, when the
+ * payload is oversized, or when the budget is spent — becomes a size note so the
+ * payload never reaches the prompt as text.
+ */
+function handleBinaryPart(item: Record<string, unknown>, forwarder?: ImageForwarder): string {
+  const mediaType = detectMediaType(item)
+  const raw = item.data ?? item.image ?? item.url
+  if (!forwarder?.enabled || !mediaType.startsWith("image/")) {
+    return describeBinaryPart(item)
+  }
+  const dataUri = toDataUriOrUrl(raw as string | Uint8Array | URL, mediaType)
+  if (typeof dataUri !== "string" || !dataUri.startsWith("data:")) {
+    return describeBinaryPart(item)
+  }
+  if (dataUri.length > MAX_FORWARD_IMAGE_BYTES) {
+    return `[image omitted: ${mediaType}, ${kilobytes(dataUri)} KB exceeds the ${Math.round(MAX_FORWARD_IMAGE_BYTES / 1024 / 1024)} MB per-image forward limit]`
+  }
+  const fingerprint = imageFingerprint(dataUri)
+  if (forwarder.seen.has(fingerprint)) {
+    return `[identical ${mediaType} image already attached earlier in this conversation — not re-sent]`
+  }
+  if (
+    forwarder.images.length >= MAX_FORWARD_IMAGES_TOTAL ||
+    forwarder.bytes + dataUri.length > MAX_FORWARD_IMAGE_BYTES_TOTAL
+  ) {
+    return `[image omitted: per-request image forward budget reached — ${forwarder.images.length} image(s), ${Math.round(forwarder.bytes / 1024 / 1024)} MB already forwarded]`
+  }
+  forwarder.seen.add(fingerprint)
+  forwarder.bytes += dataUri.length
+  forwarder.images.push({ mediaType, dataUri })
+  return `[${mediaType} image, ${kilobytes(dataUri)} KB — attached as a user message below]`
+}
+
+function byteLengthOf(data: unknown): number {
+  if (typeof data === "string") return data.length
+  if (data instanceof Uint8Array) return data.byteLength
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) return data.length
+  return 0
+}
+
+/**
+ * Describe a non-text tool-result part without serializing its payload.
+ *
+ * Tool results can carry binary attachments (opencode's `read` on an image
+ * returns `{ type: "file", mediaType, data: "data:image/png;base64,..." }`).
+ * Inlining those as text pushes megabytes of base64 into the prompt and blows
+ * the model's context window, so they are summarised instead.
+ */
+function describeBinaryPart(item: Record<string, unknown>): string {
+  const mediaType =
+    typeof item.mediaType === "string"
+      ? item.mediaType
+      : typeof item.mimeType === "string"
+        ? item.mimeType
+        : "application/octet-stream"
+  const bytes =
+    byteLengthOf(item.data) || byteLengthOf(item.image) || byteLengthOf(item.url) || 0
+  const size = bytes > 0 ? `, ${Math.max(1, Math.round(bytes / 1024))} KB` : ""
+  return `[attachment omitted: ${mediaType}${size} — binary payloads are not inlined into text. Use a vision-capable model and send the image as a user attachment to inspect it.]`
+}
+
+function isBinaryLikePart(v: unknown): v is Record<string, unknown> {
+  if (!v || typeof v !== "object") return false
+  const item = v as Record<string, unknown>
+  if (item.type === "file" || item.type === "image" || item.type === "media") return true
+  if (typeof item.data === "string" && item.data.startsWith("data:")) return true
+  if (typeof item.url === "string" && item.url.startsWith("data:")) return true
+  return false
+}
+
+function inlineTextOrNote(v: unknown, forwarder?: ImageForwarder): string {
+  if (typeof v === "string") return v
+  if (!v || typeof v !== "object") return String(v ?? "")
+  const item = v as Record<string, unknown>
+  if (typeof item.text === "string") return item.text
+  if (isBinaryLikePart(item)) return handleBinaryPart(item, forwarder)
+  let serialized: string
+  try {
+    serialized = scrubEmbeddedPayloads(JSON.stringify(item) ?? "")
+  } catch {
+    return "[unserializable tool output omitted]"
+  }
+  if (serialized.length > MAX_INLINE_TOOL_TEXT_CHARS) {
+    return `[tool output omitted: ${serialized.length} chars exceed the ${MAX_INLINE_TOOL_TEXT_CHARS} char inline limit]`
+  }
+  return serialized
+}
+
+/**
+ * Safety net for serialised tool output: a `data:` URI buried inside an object
+ * must never turn into thousands of tokens of base64 text. Structural handling
+ * happens earlier (convertBinaryPart / handleBinaryPart); this catches the
+ * leftovers (e.g. a payload nested inside an otherwise-ordinary JSON result).
+ */
+const EMBEDDED_DATA_URI_RE = /data:[a-z0-9][a-z0-9.+-]*\/[a-z0-9][a-z0-9.+-]*;base64,[A-Za-z0-9+/=\s]{512,}/gi
+
+function scrubEmbeddedPayloads(text: string): string {
+  if (!text.includes(";base64,")) return text
+  return text.replace(
+    EMBEDDED_DATA_URI_RE,
+    (match) => `[embedded base64 payload omitted: ${Math.max(1, Math.round(match.length / 1024))} KB]`,
+  )
+}
+
+function capSerialized(value: unknown, fallback: string): string {
+  let serialized: string
+  try {
+    serialized = scrubEmbeddedPayloads(JSON.stringify(value) ?? "")
+  } catch {
+    return fallback
+  }
+  if (serialized.length > MAX_INLINE_TOOL_TEXT_CHARS) {
+    return `[tool output omitted: ${serialized.length} chars exceed the ${MAX_INLINE_TOOL_TEXT_CHARS} char inline limit]`
+  }
+  return serialized
+}
+
+function convertToolResultOutput(
+  output: LanguageModelV3ToolResultOutput,
+  forwarder?: ImageForwarder,
+): CCToolResultContent["output"] {
   switch (output.type) {
     case "text":
       return { type: "text", value: output.value }
     case "error-text":
       return { type: "error-text", value: output.value }
     case "json":
-      return { type: "text", value: JSON.stringify(output.value) }
+      return { type: "text", value: capSerialized(output.value, "[unserializable tool output omitted]") }
     case "execution-denied":
       return { type: "error-text", value: output.reason ?? "Execution denied" }
     case "error-json":
-      return { type: "error-text", value: JSON.stringify(output.value) }
+      return { type: "error-text", value: capSerialized(output.value, "[unserializable tool output omitted]") }
     case "content":
-      return { type: "text", value: output.value.map((v: Record<string, unknown>) => ("text" in v ? v.text : JSON.stringify(v))).join("\n") }
+      return {
+        type: "text",
+        value: output.value.map((v: unknown) => inlineTextOrNote(v, forwarder)).join("\n"),
+      }
     default:
-      return { type: "text", value: JSON.stringify(output) }
+      return { type: "text", value: capSerialized(output, "[unserializable tool output omitted]") }
   }
 }
 
-function convertMessage(msg: LanguageModelV3Message): CCMessage | null {
+function convertMessage(msg: LanguageModelV3Message, forwarder?: ImageForwarder): CCMessage | null {
   switch (msg.role) {
     case "user": {
-      const content = convertUserContent(msg.content)
+      const content = convertUserContent(msg.content, forwarder)
       return { role: "user", content: content as any }
     }
     case "assistant": {
@@ -196,7 +459,7 @@ function convertMessage(msg: LanguageModelV3Message): CCMessage | null {
             type: "tool-result",
             toolCallId: part.toolCallId,
             toolName: part.toolName,
-            output: convertToolResultOutput(part.output),
+            output: convertToolResultOutput(part.output, forwarder),
           })
         }
       }
@@ -253,24 +516,102 @@ function extractReasoningEffort(options: LanguageModelV3CallOptions): string | u
   return undefined
 }
 
+/**
+ * Lazily-loaded map of model id -> "accepts image input", built from the same
+ * catalog this provider registers with opencode (models.cache.json wins, then
+ * models.json). Unknown models are treated as image-capable: forwarding an image
+ * can at worst be rejected by the upstream, never silently explode the prompt.
+ */
+let imageInputSupport: Map<string, boolean> | null = null
+
+function loadImageInputSupport(): Map<string, boolean> {
+  if (imageInputSupport) return imageInputSupport
+  const support = new Map<string, boolean>()
+  const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..")
+  for (const file of ["models.cache.json", "models.json"]) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(packageRoot, file), "utf-8")) as unknown
+      const list = Array.isArray(parsed) ? parsed : Object.values((parsed ?? {}) as Record<string, unknown>)
+      for (const raw of list) {
+        if (!raw || typeof raw !== "object") continue
+        const entry = raw as Record<string, unknown>
+        const id = typeof entry.id === "string" ? entry.id : undefined
+        if (!id) continue
+        const modalities = (entry.modalities ?? {}) as Record<string, unknown>
+        const inputs = Array.isArray(modalities.input) ? (modalities.input as unknown[]) : undefined
+        const acceptsImages = inputs ? inputs.includes("image") : entry.attachment === true
+        const key = id.toLowerCase()
+        if (!support.has(key)) support.set(key, acceptsImages)
+        const short = key.split("/").pop()
+        if (short && !support.has(short)) support.set(short, acceptsImages)
+      }
+    } catch {
+      // catalog missing/unreadable: fall through to the permissive default
+    }
+  }
+  imageInputSupport = support
+  return support
+}
+
+function modelAcceptsImageInput(modelId: string): boolean {
+  const support = loadImageInputSupport()
+  const key = modelId.toLowerCase()
+  const hit = support.get(key) ?? support.get(key.split("/").pop() ?? key)
+  return hit ?? true
+}
+
 export function buildRequest(
   modelId: string,
   options: LanguageModelV3CallOptions,
 ): CCRequestEnvelope {
+  const rawDumpPath = process.env.COMMANDCODE_DEBUG_RAW
+  if (rawDumpPath) {
+    try {
+      writeFileSync(rawDumpPath, JSON.stringify(options.prompt, null, 1), "utf-8")
+    } catch {
+      // diagnostics only
+    }
+  }
   let systemPrompt = ""
   const messages: CCMessage[] = []
+  const forwarder = createImageForwarder(modelAcceptsImageInput(modelId))
 
   for (const msg of options.prompt) {
     if (msg.role === "system") {
       systemPrompt += (systemPrompt ? "\n\n" : "") + msg.content
       continue
     }
-    const converted = convertMessage(msg)
+    const converted = convertMessage(msg, forwarder)
     if (converted) messages.push(converted)
+    // Tool images cannot ride inside a tool-result, so they follow it as a
+    // user message (Command Code accepts images only in user content).
+    if (msg.role === "tool" && forwarder.images.length > 0) {
+      const pending = forwarder.images.splice(0, forwarder.images.length)
+      messages.push({
+        role: "user",
+        content: [
+          { type: "text", text: "Images returned by the tool call(s) above:" },
+          ...pending.map((image) => ({ type: "image", image: image.dataUri, mimeType: image.mediaType })),
+        ],
+      })
+    }
   }
 
   const effort = extractReasoningEffort(options)
 
+  // Opt-in wire inspection: COMMANDCODE_DEBUG_BODY=/path/to/body.json dumps the
+  // exact request this provider is about to send (used to prove whether image
+  // parts are forwarded as images or inlined as text).
+  const debugBodyPath = process.env.COMMANDCODE_DEBUG_BODY
+  if (debugBodyPath) {
+    const dump = JSON.stringify(messages, null, 1)
+    try {
+      writeFileSync(debugBodyPath, dump, "utf-8")
+    } catch {
+      // diagnostics only — never fail the request over it
+    }
+  }
+
   const params: CCRequestEnvelope["params"] = {
     model: modelId,
     messages,

package/src/model-sync.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from "fs"
+import { existsSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "fs"
 import { dirname, join } from "path"
 import { fileURLToPath } from "url"
 import { resolveApiKey } from "./auth.js"
@@ -55,6 +55,11 @@ function writeAtomic(file: string, data: string) {
 // Locate the model catalog bundled with the installed Command Code CLI.
 // The catalog is the vendor-maintained list for the same API endpoint this
 // provider talks to, so it is the most accurate metadata source available.
+function bundledMdIn(root: string): string | null {
+  const candidate = join(root, "command-code", "dist", "bundled", "command-code-knowledge", "reference", "models.md")
+  return existsSync(candidate) ? candidate : null
+}
+
 function findModelsMd(): string | null {
   const explicit = process.env.COMMANDCODE_MODELS_MD
   if (explicit && existsSync(explicit)) return explicit
@@ -80,6 +85,28 @@ function findModelsMd(): string | null {
       }
     }
   }
+
+  // Common global npm roots — PATH-independent so background services
+  // (OpenChamber, launchd/systemd) resolve the catalog even when the npm
+  // global bin dir is not exported into their environment.
+  const roots: string[] = []
+  const home = process.env.HOME
+  if (home) {
+    for (const base of [join(home, ".local", "share", "nvm"), join(home, ".nvm", "versions", "node"), join(home, ".npm-global", "lib")]) {
+      try {
+        for (const version of readdirSync(base)) {
+          roots.push(join(base, version, "lib", "node_modules"))
+        }
+      } catch {
+        // directory absent — skip
+      }
+    }
+  }
+  roots.push("/usr/local/lib/node_modules", "/usr/lib/node_modules", "/opt/homebrew/lib/node_modules")
+  for (const root of roots) {
+    const found = bundledMdIn(root)
+    if (found) return found
+  }
   return null
 }
 
@@ -247,6 +274,34 @@ export function parseModelsMd(text: string, hints: Map<string, ModelEntry>): Mod
   return entries
 }
 
+// Server-managed master catalog. The server (keypool) serves the same
+// enriched model list this provider builds locally, so clients fetch it at
+// startup and always see current models/capabilities — no plugin update and
+// no `op pull` needed when the catalog changes.
+export async function fetchRemoteCatalog(url: string, timeoutMs = 1500): Promise<ModelEntry[] | null> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: "application/json" } })
+    if (!response.ok) return null
+    const payload = (await response.json()) as unknown
+    const list = Array.isArray(payload)
+      ? payload
+      : payload && typeof payload === "object" && Array.isArray((payload as { models?: unknown }).models)
+        ? (payload as { models: unknown[] }).models
+        : null
+    if (!list) return null
+    const entries = list.filter(
+      (entry): entry is ModelEntry => typeof entry === "object" && entry !== null && typeof (entry as { id?: unknown }).id === "string",
+    )
+    return entries.length >= 5 ? entries : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 async function fetchApiModels(): Promise<ApiModel[] | null> {
   const apiKey = resolveApiKey({})
   const controller = new AbortController()
@@ -311,44 +366,68 @@ function mergeApiModels(entries: ModelEntry[], api: ApiModel[], hints?: Map<stri
 }
 
 // Build the model list fresh on every opencode instance start:
-//   1. CLI-bundled catalog (vendor-maintained, refreshed by `cmd update`)
-//   2. Command Code's public model endpoint (picks up brand-new models)
-//   3. last synced cache, then the bundled snapshot as an offline fallback.
-export async function loadSyncedModels(): Promise<SyncResult> {
+//   1. REMOTE master catalog (server-managed; always current — primary source
+//      so client devices never depend on a local CLI install for metadata)
+//   2. local CLI-bundled catalog + Command Code's public model endpoint
+//      (used to append models newer than the server catalog, and as the
+//      offline fallback when the server is unreachable)
+//   3. last synced cache, then the bundled snapshot as a final fallback.
+export async function loadSyncedModels(options?: { catalogUrl?: string }): Promise<SyncResult> {
   const bundled = loadCachedModels(BUNDLED_MODELS)
   const cached = loadCachedModels(CACHE_MODELS)
   const hints = new Map<string, ModelEntry>()
   for (const entry of [...(cached ?? []), ...(bundled ?? [])]) hints.set(entry.id.toLowerCase(), entry)
 
-  let docModels: ModelEntry[] | null = null
+  let localModels: ModelEntry[] | null = null
+  let localSource = ""
   try {
     const modelsMd = findModelsMd()
     if (modelsMd) {
       const parsed = parseModelsMd(readFileSync(modelsMd, "utf-8"), hints)
-      if (parsed.length >= 5) docModels = parsed
+      if (parsed.length >= 5) {
+        const apiModels = await fetchApiModels()
+        localModels = mergeApiModels(parsed, apiModels ?? [], hints)
+        localSource = apiModels?.length ? "cli-catalog+api" : "cli-catalog"
+      }
     }
   } catch {
-    // intentionally silent: fall through to the API or cache
+    // intentionally silent: fall through to the API or remote catalog
+  }
+  if (!localModels?.length) {
+    const apiModels = await fetchApiModels()
+    if (apiModels?.length) {
+      localModels = mergeApiModels([], apiModels, hints)
+      localSource = "api"
+    }
   }
-
-  const apiModels = await fetchApiModels()
 
   let models: ModelEntry[] | null = null
   let source = ""
-  if (docModels?.length) {
-    models = mergeApiModels(docModels, apiModels ?? [], hints)
-    source = apiModels?.length ? "cli-catalog+api" : "cli-catalog"
-  } else if (apiModels?.length) {
-    models = mergeApiModels([], apiModels, hints)
-    source = "api"
+  if (options?.catalogUrl) {
+    const remote = await fetchRemoteCatalog(options.catalogUrl)
+    if (remote) {
+      models = remote
+      source = "remote"
+      if (localModels?.length) {
+        const seen = new Set(remote.map((entry) => entry.id.toLowerCase()))
+        const extra = localModels.filter((entry) => !seen.has(entry.id.toLowerCase()))
+        if (extra.length) {
+          models = [...remote, ...extra]
+          source = "remote+local"
+        }
+      }
+    }
+  }
+  if (!models?.length && localModels?.length) {
+    models = localModels
+    source = localSource
   }
-
   if (!models?.length) {
     models = cached ?? bundled ?? []
     source = cached ? "cache" : "bundled"
   }
 
-  if (!models.length) throw new Error("Command Code model catalog unavailable (no CLI, API, cache, or bundled list)")
+  if (!models.length) throw new Error("Command Code model catalog unavailable (no remote, CLI, API, cache, or bundled list)")
 
   if (source !== "cache" && source !== "bundled") {
     try {
@@ -358,5 +437,9 @@ export async function loadSyncedModels(): Promise<SyncResult> {
     }
   }
 
+  if (process.env.COMMANDCODE_DEBUG) {
+    console.warn(`[commandcode] catalog source=${source} models=${models.length}`)
+  }
+
   return { models, source }
 }

package/src/stream.ts

@@ -1,4 +1,5 @@
 import type { LanguageModelV3StreamPart, LanguageModelV3Usage, LanguageModelV3FinishReason } from "@ai-sdk/provider"
+import { appendFileSync } from "fs"
 
 type RawEvent = Record<string, unknown> & { type: string }
 
@@ -84,10 +85,30 @@ function toStreamPart(event: RawEvent): LanguageModelV3StreamPart | null {
     case "finish-step": {
       const usage = event.usage ?? event.totalUsage ?? {}
       const rawReason = (event.finishReason ?? event.rawFinishReason ?? "stop") as string
+      const mapped = mapUsage(typeof usage === "object" && usage !== null ? (usage as Record<string, unknown>) : {})
+      // Opt-in usage accounting: COMMANDCODE_DEBUG_USAGE=/path/to/usage.jsonl
+      // appends one line per completed step (used to prove image token costs).
+      const usageLogPath = process.env.COMMANDCODE_DEBUG_USAGE
+      if (usageLogPath) {
+        try {
+          appendFileSync(
+            usageLogPath,
+            JSON.stringify({
+              ts: new Date().toISOString(),
+              inputTokens: mapped.inputTokens,
+              outputTokens: mapped.outputTokens,
+              finishReason: rawReason,
+            }) + "\n",
+            "utf-8",
+          )
+        } catch {
+          // diagnostics only
+        }
+      }
       return {
         type: "finish",
         finishReason: { unified: mapFinishReason(rawReason), raw: rawReason },
-        usage: mapUsage(typeof usage === "object" && usage !== null ? (usage as Record<string, unknown>) : {}),
+        usage: mapped,
       }
     }