pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.10

package/src/pantheon/v2-vision.ts

@@ -0,0 +1,622 @@
+/** Native OpenCode V2 image analysis using the live model catalog and Zen auth. */
+
+import type { LookupAddress } from 'node:dns'
+import { lookup as dnsLookup } from 'node:dns/promises'
+import { readFile } from 'node:fs/promises'
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { isIP, type LookupFunction } from 'node:net'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveActivePreset } from './presets.mjs'
+import {
+  describeImagesNative,
+  NATIVE_MAX_TOKENS,
+  type NativeVisionFailure,
+  type NativeVisionTarget,
+  nativeVisionFailureMessage,
+  resolveNativeVisionTarget,
+  saveDataUrlImageSync,
+  truncateUserText,
+} from './vision.ts'
+
+// Default native vision model. Must be a PAID OpenCode Go (zen/go) model: the
+// free-tier MiMo (`opencode/mimo-v2.6-flash-free`) is rejected by the direct
+// gateway with HTTP 403 ("free tier can only be used from within OpenCode"),
+// and zen/v1 paid models require account access this plugin cannot assume. The
+// go endpoint accepts the request once the Zen session header is present.
+// NOTE: intentionally diverges from V1's DEFAULT_VISION_MODEL
+// (`opencode-go/mimo-v2.5`) — V2 tracks the newer Zen Go MiMo 2.6 Flash family.
+const DEFAULT_MODEL = 'opencode-go/mimo-v2.6-flash'
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024
+const MAX_REDIRECTS = 3
+const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
+/**
+ * Generic describe instruction — byte-identical to the pre-contextual fixed
+ * IMAGE_PROMPT, so a turn without a user question behaves exactly as before.
+ */
+const IMAGE_PROMPT_GENERIC =
+  'Descreva fielmente a imagem anexada. Inclua conteúdo, texto visível, layout e objetos; ' +
+  'declare incerteza em vez de adivinhar e responda em português claro.'
+
+/**
+ * Describe-prompt template with the `{userText}` slot. Substitution is
+ * single-pass (`buildV2ImagePrompt`): the question is inserted via a function
+ * replacement and never re-scanned, so `{imageList}`-style literals inside the
+ * user's text stay inert data. The question is capped by
+ * `truncateUserText` (payload bound); empty/whitespace falls back to the
+ * generic prompt above.
+ */
+const IMAGE_PROMPT_TEMPLATE = `${IMAGE_PROMPT_GENERIC}
+Pergunta do usuário: {userText}`
+
+/** Fill `{userText}` into the describe template (single pass, injection-safe). */
+export function buildV2ImagePrompt(userText?: string): string {
+  const question = truncateUserText(userText ?? '')
+  if (!question) return IMAGE_PROMPT_GENERIC
+  return IMAGE_PROMPT_TEMPLATE.replace('{userText}', () => question)
+}
+
+const IMAGE_URI_PATTERN = /\.(?:png|jpe?g|webp|gif)(?:[?#].*)?$/i
+
+/**
+ * Reference line for one attached image. A `data:` (inline/clipboard)
+ * attachment has no path on disk — the bytes live only in the URI — so a path
+ * based tool (`vision_describe`, the MCP) could never read it and the model
+ * would fall back to guessing a path from the display name (observed as
+ * `ENOENT: .../clipboard`). Materialize the bytes once to the shared
+ * temp/LRU location and reference THAT path, so the native tool AND the MCP
+ * receive a real file. The payload is never copied into the prompt text. Only
+ * if materialization fails (no usable bytes) do we fall back to the previous
+ * "URI omitted" form.
+ */
+function imageReference(uri: string, mime: string, name: string): string {
+  if (!/^data:image\//i.test(uri)) {
+    return `${JSON.stringify(name)} em ${JSON.stringify(uri)}`
+  }
+  const path = saveDataUrlImageSync(uri, mime)
+  if (path) {
+    return `${JSON.stringify(name)} em ${JSON.stringify(path)} (anexo inline materializado em arquivo temporário local; use este caminho — o payload não é repetido no texto)`
+  }
+  return `${JSON.stringify(name)} (conteúdo anexado; URI codificada omitida)`
+}
+
+/**
+ * Add model-visible instructions for image files on a V2 prompt admission.
+ * Inline image bytes are deliberately never copied into persisted prompt text;
+ * a `data:` attachment is materialized to a temp file and referenced by path
+ * instead (see `imageReference`).
+ * `userText` (the admission's prompt text, when available) is trimmed, capped
+ * by `truncateUserText` and appended as the user's question for this turn so
+ * the main model calibrates the inspection AND forwards it as the vision
+ * tool's `prompt`. NOTE: the description cache keys on the full prompt, so the
+ * same image asked with a new question gets a fresh describe — same image +
+ * same question within the TTL reuses the stored description.
+ * `sessionID` (the V2 `prompt` hook event's live session id, when present) is
+ * relayed as an MCP `session_id` instruction: the MCP runs in a separate
+ * process the host hands no session id to, and the Zen gateway rejects a
+ * sessionless call with HTTP 400 `MissingSessionID` (mirrors
+ * `generateInjectionPrompt` on the V1 path).
+ * The question and the session id are never logged.
+ */
+export function buildV2VisionPromptContext(
+  files: unknown,
+  userText?: string,
+  sessionID?: string,
+): string | undefined {
+  if (!Array.isArray(files)) return undefined
+  const images = files.flatMap((value, index) => {
+    const file = asRecord(value)
+    if (!file) return []
+    const uri = typeof file?.uri === 'string' ? file.uri.trim() : ''
+    if (!uri) return []
+    const mime = typeof file?.mime === 'string' ? file.mime.toLowerCase() : ''
+    const image =
+      ['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(mime) ||
+      /^data:image\/(?:png|jpeg|webp|gif);base64,/i.test(uri) ||
+      IMAGE_URI_PATTERN.test(uri)
+    if (!image) return []
+    const name =
+      typeof file.filename === 'string'
+        ? file.filename
+        : typeof file.name === 'string'
+          ? file.name
+          : `imagem ${index + 1}`
+    const reference = imageReference(uri, mime, name)
+    return [reference]
+  })
+  if (images.length === 0) return undefined
+  const lines = [
+    '<!-- pantheon-v2-visual-context -->',
+    '[Contexto visual do Pantheon]',
+    `O usuário anexou imagem(ns):\n${images.map((image) => `- ${image}`).join('\n')}`,
+    'Se a imagem orientar uma implementação, inspecione-a com vision_describe ou visão nativa antes de delegar. Inclua a referência e observações visuais relevantes no handoff para @aphrodite. Preserve alterações existentes fora do escopo: a imagem não autoriza apagar nem reverter trabalho; se a substituição for necessária e não estiver explícita, pergunte antes.',
+  ]
+  const question = truncateUserText(userText ?? '')
+  if (question) {
+    // JSON.stringify quotes/escapes the question so it cannot spoof the
+    // surrounding instruction layout; the value is never re-expanded and
+    // never logged.
+    lines.push(
+      `Pergunta do usuário neste turno: ${JSON.stringify(question)} — ao inspecionar com vision_describe, repasse essa pergunta no parâmetro \`prompt\` da ferramenta para uma análise direcionada.`,
+    )
+  }
+  // MCP session relay (see the doc comment above): JSON.stringify quotes the
+  // id so it cannot spoof the surrounding instruction layout; never logged.
+  const session = sessionID?.trim()
+  if (session) {
+    lines.push(
+      `Prefira a ferramenta nativa \`vision_describe\` (ela já repassa a sessão automaticamente). Se usar o MCP pantheon-vision (\`vision_describe\`/\`vision_ocr\`/\`vision_analyze\`), repasse session_id=${JSON.stringify(session)} no parâmetro \`session_id\` — sem ele o gateway Zen rejeita a chamada com MissingSessionID.`,
+    )
+  }
+  return lines.join('\n')
+}
+
+export interface V2VisionModel {
+  id: string
+  providerID: string
+  enabled?: boolean
+  status?: string
+  input?: string[] | Record<string, boolean>
+  capabilities?: {
+    input?: string[] | Record<string, boolean>
+  }
+  /** Catalog cost (optional); `input: 0` marks a free-tier model. */
+  cost?: { input?: unknown }
+}
+
+export interface V2VisionRuntime {
+  model: { list: (input?: unknown) => Promise<unknown> }
+}
+
+export interface V2VisionToolContext {
+  sessionID?: string
+  directory?: string
+  signal?: AbortSignal
+}
+
+export interface V2VisionToolDefinition {
+  name: string
+  description: string
+  input: Record<string, unknown>
+  output: Record<string, unknown>
+  execute: (
+    input: Record<string, unknown>,
+    context: unknown,
+  ) => Promise<{ output: string; title?: string; metadata?: Record<string, unknown> }>
+}
+
+type ImageAttachment = { uri: string; name: string }
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function modelList(value: unknown): V2VisionModel[] {
+  const root = asRecord(value)
+  const candidates = Array.isArray(value) ? value : (root?.data ?? root?.models)
+  if (!Array.isArray(candidates)) return []
+  return candidates.filter((item): item is V2VisionModel => {
+    const model = asRecord(item)
+    return typeof model?.id === 'string' && typeof model.providerID === 'string'
+  })
+}
+
+function acceptsImages(model: V2VisionModel): boolean {
+  const input = model.capabilities?.input ?? model.input
+  if (Array.isArray(input)) return input.some((modality) => modality.toLowerCase() === 'image')
+  return input?.image === true
+}
+
+function supportsZenVision(model: V2VisionModel): boolean {
+  return model.providerID === 'opencode' || model.providerID.startsWith('opencode-go')
+}
+
+/**
+ * Whether a catalog model is FREE-TIER. Free-tier Zen models are rejected by
+ * the direct gateway with HTTP 403 ("free tier can only be used from within
+ * OpenCode"), so they must never be picked on the native describe path. Two
+ * conservative signals: the `-free` id suffix (the reliable marker) OR an
+ * explicit `cost.input` of 0.
+ */
+function isFreeVisionModel(model: V2VisionModel): boolean {
+  if (/-free$/i.test(model.id)) return true
+  const input = model.cost?.input
+  return typeof input === 'number' && input <= 0
+}
+
+function modelKey(model: Pick<V2VisionModel, 'providerID' | 'id'>): string {
+  return `${model.providerID}/${model.id}`
+}
+
+function exactModelMatch(models: V2VisionModel[], requested: string): V2VisionModel | undefined {
+  const slash = requested.indexOf('/')
+  if (slash < 1) return models.find((model) => model.id === requested)
+  const providerID = requested.slice(0, slash)
+  const id = requested.slice(slash + 1)
+  return models.find((model) => model.providerID === providerID && model.id === id)
+}
+
+/**
+ * Select a native transport model. An EXPLICIT pin (`preferred` — the env
+ * `PANTHEON_VISION_MODEL`, the config file, or the active preset) ALWAYS wins,
+ * even when it names a free-tier model: the pin is the user's decision, so the
+ * call surfaces the gateway's HTTP 403 with its actionable message instead of
+ * silently substituting a different model. The free-tier exclusion
+ * (`-free` suffix / cost ≤ 0) applies ONLY to AUTOMATIC selection — discovery
+ * then the Go default — because the direct gateway rejects free-tier models
+ * with HTTP 403, so they cannot serve the native describe path unasked.
+ */
+export function selectV2VisionModel(
+  available: unknown,
+  preferred?: string,
+): V2VisionModel | undefined {
+  const capable = modelList(available).filter(
+    (model) =>
+      model.enabled !== false &&
+      model.status !== 'deprecated' &&
+      supportsZenVision(model) &&
+      acceptsImages(model),
+  )
+  const pinned = preferred?.trim()
+  if (pinned) {
+    const configured = exactModelMatch(capable, pinned)
+    if (configured) return configured
+  }
+  const candidates = capable.filter((model) => !isFreeVisionModel(model))
+  const defaultModel = exactModelMatch(candidates, DEFAULT_MODEL)
+  if (defaultModel) return defaultModel
+  return candidates.sort((left, right) => {
+    const priority = (model: V2VisionModel): number => {
+      const key = modelKey(model).toLowerCase()
+      if (key === DEFAULT_MODEL) return 0
+      // Prefer the Go endpoint (paid, session-header gated) over zen/v1.
+      return model.providerID.startsWith('opencode-go')
+        ? 1
+        : model.providerID === 'opencode'
+          ? 2
+          : 3
+    }
+    return priority(left) - priority(right) || modelKey(left).localeCompare(modelKey(right))
+  })[0]
+}
+
+function activePresetCandidates(directory: string): string[] {
+  const home = process.env.HOME || homedir()
+  const xdg = process.env.XDG_CONFIG_HOME || join(home, '.config')
+  return [
+    join(directory, '.pantheon', 'active-preset.json'),
+    join(xdg, 'opencode', '.pantheon', 'active-preset.json'),
+    join(home, '.opencode', '.pantheon', 'active-preset.json'),
+  ]
+}
+
+async function configuredVisionModel(directory: string): Promise<string | undefined> {
+  const home = process.env.HOME || homedir()
+  const xdg = process.env.XDG_CONFIG_HOME || join(home, '.config')
+  const paths = [
+    join(directory, '.opencode', 'opencode-vision.json'),
+    join(xdg, 'opencode', 'opencode-vision.json'),
+  ]
+  for (const path of paths) {
+    try {
+      const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+      if (typeof parsed.visionModel === 'string' && parsed.visionModel.trim()) {
+        return parsed.visionModel.trim()
+      }
+    } catch {
+      // A missing or malformed optional preference must not disable Vision.
+    }
+  }
+  return undefined
+}
+
+async function preferredVisionModel(directory: string): Promise<string> {
+  const envModel = process.env.PANTHEON_VISION_MODEL?.trim()
+  if (envModel) return envModel
+  const configModel = await configuredVisionModel(directory)
+  if (configModel) return configModel
+  try {
+    return (
+      resolveActivePreset({
+        env: process.env,
+        candidates: activePresetCandidates(directory),
+        logger: { warn: () => undefined },
+      })?.vision?.model ?? DEFAULT_MODEL
+    )
+  } catch {
+    return DEFAULT_MODEL
+  }
+}
+
+function imageMime(bytes: Buffer): string | undefined {
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+    return 'image/png'
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (
+    bytes
+      .subarray(0, 6)
+      .toString('ascii')
+      .match(/^GIF8[79]a$/)
+  )
+    return 'image/gif'
+  if (
+    bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'image/webp'
+  }
+  return undefined
+}
+
+function toImageAttachment(bytes: Buffer, name: string): ImageAttachment {
+  if (bytes.length === 0) throw new Error('image is empty')
+  if (bytes.length > MAX_IMAGE_BYTES)
+    throw new Error('image exceeds OpenCode’s 20 MiB attachment limit')
+  const mime = imageMime(bytes)
+  if (!mime || !IMAGE_TYPES.has(mime)) {
+    throw new Error('unsupported image; use PNG, JPEG, WebP, or GIF')
+  }
+  return { uri: `data:${mime};base64,${bytes.toString('base64')}`, name }
+}
+
+function parseDataUri(value: string): ImageAttachment {
+  const match = /^data:(image\/(?:png|jpeg|webp|gif));base64,([A-Za-z0-9+/]*={0,2})$/i.exec(value)
+  if (!match?.[1] || match[2] === undefined) throw new Error('invalid base64 image data URI')
+  if (match[2].length > Math.ceil((MAX_IMAGE_BYTES * 4) / 3)) {
+    throw new Error('image exceeds OpenCode’s 20 MiB attachment limit')
+  }
+  const bytes = Buffer.from(match[2], 'base64')
+  if (bytes.toString('base64') !== match[2]) throw new Error('invalid base64 image data URI')
+  return toImageAttachment(bytes, `image.${match[1].slice('image/'.length).replace('jpeg', 'jpg')}`)
+}
+
+function isPublicAddress(address: string): boolean {
+  if (isIP(address) === 4) {
+    const [a = 0, b = 0, c = 0] = address.split('.').map(Number)
+    return !(
+      a === 0 ||
+      a === 10 ||
+      a === 127 ||
+      a >= 224 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && (b === 168 || b === 0)) ||
+      (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+      (a === 203 && b === 0 && c === 113)
+    )
+  }
+  if (isIP(address) !== 6) return false
+  const normalized = address.toLowerCase()
+  if (normalized.includes('.')) return false // IPv4-mapped and transition addresses are rejected.
+  const first = Number.parseInt(normalized.split(':')[0] || '0', 16)
+  return first >= 0x2000 && first <= 0x3fff && !normalized.startsWith('2001:db8:')
+}
+
+export function createPinnedLookup(record: LookupAddress): LookupFunction {
+  return (_hostname, options, callback) => {
+    if (options.all) callback(null, [record])
+    else callback(null, record.address, record.family)
+  }
+}
+
+async function pinnedPublicAddress(hostname: string): Promise<{ address: string; family: number }> {
+  const bareHost =
+    hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname
+  const records = await dnsLookup(bareHost, { all: true, verbatim: true })
+  if (records.length === 0 || records.some((record) => !isPublicAddress(record.address))) {
+    throw new Error('remote image host must resolve only to public IP addresses')
+  }
+  const record = records[0]
+  if (!record) throw new Error('remote image host did not resolve')
+  return record
+}
+
+async function readRemoteImage(
+  url: URL,
+  signal: AbortSignal | undefined,
+  redirects = 0,
+  secureOrigin = url.protocol === 'https:',
+): Promise<{ bytes: Buffer; name: string }> {
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+    throw new Error('only public HTTP(S) image URLs without credentials are supported')
+  }
+  if (secureOrigin && url.protocol !== 'https:')
+    throw new Error('HTTPS image redirects cannot downgrade to HTTP')
+  const pinned = await pinnedPublicAddress(url.hostname)
+  const requestFn = url.protocol === 'https:' ? httpsRequest : httpRequest
+  const response = await new Promise<{ status: number; location?: string; bytes: Buffer }>(
+    (resolveResponse, reject) => {
+      const request = requestFn(
+        url,
+        {
+          method: 'GET',
+          headers: { accept: 'image/png,image/jpeg,image/webp,image/gif' },
+          lookup: createPinnedLookup(pinned),
+          ...(signal ? { signal } : {}),
+        },
+        (incoming) => {
+          const status = incoming.statusCode ?? 0
+          const location = incoming.headers.location
+          if (status >= 300 && status < 400 && location) {
+            incoming.resume()
+            resolveResponse({ status, location, bytes: Buffer.alloc(0) })
+            return
+          }
+          const contentLength = Number(incoming.headers['content-length'] ?? 0)
+          if (contentLength > MAX_IMAGE_BYTES) {
+            incoming.destroy(new Error('image exceeds OpenCode’s 20 MiB attachment limit'))
+            reject(new Error('image exceeds OpenCode’s 20 MiB attachment limit'))
+            return
+          }
+          const chunks: Buffer[] = []
+          let total = 0
+          incoming.on('data', (chunk: Buffer | string) => {
+            const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+            total += data.length
+            if (total > MAX_IMAGE_BYTES) {
+              incoming.destroy(new Error('image exceeds OpenCode’s 20 MiB attachment limit'))
+              reject(new Error('image exceeds OpenCode’s 20 MiB attachment limit'))
+              return
+            }
+            chunks.push(data)
+          })
+          incoming.on('error', reject)
+          incoming.on('end', () => resolveResponse({ status, bytes: Buffer.concat(chunks) }))
+        },
+      )
+      request.setTimeout(15_000, () => request.destroy(new Error('image download timed out')))
+      request.on('error', reject)
+      request.end()
+    },
+  )
+  if (response.location) {
+    if (redirects >= MAX_REDIRECTS) throw new Error('remote image redirected too many times')
+    return readRemoteImage(new URL(response.location, url), signal, redirects + 1, secureOrigin)
+  }
+  if (response.status !== 200) throw new Error(`image download returned HTTP ${response.status}`)
+  const name = decodeURIComponent(url.pathname.split('/').at(-1) || 'image')
+  return { bytes: response.bytes, name: name || 'image' }
+}
+
+async function imageAttachment(
+  value: string,
+  directory: string,
+  signal?: AbortSignal,
+): Promise<ImageAttachment> {
+  const source = value.trim()
+  if (!source) throw new Error('path must identify an image file, HTTP(S) URL, or base64 image URI')
+  if (source.startsWith('data:')) return parseDataUri(source)
+  let url: URL | undefined
+  try {
+    url = new URL(source)
+  } catch {
+    // A non-URL string is a local path.
+  }
+  if (url?.protocol === 'http:' || url?.protocol === 'https:') {
+    const remote = await readRemoteImage(url, signal)
+    return toImageAttachment(remote.bytes, remote.name)
+  }
+  let localPath: string
+  if (url?.protocol === 'file:') {
+    localPath = fileURLToPath(url)
+  } else if (url) {
+    throw new Error('only file, HTTP, HTTPS, and base64 image sources are supported')
+  } else {
+    const expanded = source.startsWith('~/') ? join(homedir(), source.slice(2)) : source
+    localPath = resolve(directory, expanded)
+  }
+  let bytes: Buffer
+  try {
+    bytes = await readFile(localPath, signal ? { signal } : undefined)
+  } catch (error) {
+    // A clipboard/inline attachment has no path on disk: the model may pass the
+    // display name as if it were a file (observed: `ENOENT .../clipboard`).
+    // Surface an actionable message instead of the raw ENOENT.
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+      throw new Error(
+        `image file not found: ${localPath}; pass an existing file path, file URL, public HTTP(S) URL, or base64 image data URI`,
+      )
+    }
+    throw error
+  }
+  return toImageAttachment(bytes, localPath.split(/[\\/]/).at(-1) || 'image')
+}
+
+export function createV2VisionTool(runtime: V2VisionRuntime): V2VisionToolDefinition {
+  return {
+    name: 'vision_describe',
+    description:
+      'Analyze an image with an OpenCode Zen multimodal model confirmed by the current V2 model catalog. ' +
+      'Prefers the OpenCode Go MiMo 2.6 Flash model and falls back to another live image-capable Zen model. ' +
+      'Free-tier models are excluded (the direct gateway rejects them). ' +
+      'Accepts a local path, file URL, public HTTP(S) URL, or base64 image data URI.',
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          minLength: 1,
+          description:
+            'Local image path, file URL, public HTTP(S) image URL, or base64 image data URI.',
+        },
+        prompt: { type: 'string', description: 'Optional image-analysis instruction.' },
+      },
+    },
+    output: {},
+    execute: async (input, rawContext) => {
+      let stage = 'load image'
+      try {
+        const pathValue = typeof input.path === 'string' ? input.path : ''
+        const call = (asRecord(rawContext) ?? {}) as V2VisionToolContext
+        const directory = call.directory || process.cwd()
+        const image = await imageAttachment(pathValue, directory, call.signal)
+        stage = 'read model catalog'
+        const preferred = await preferredVisionModel(directory)
+        const catalog = await runtime.model.list()
+        const model = selectV2VisionModel(catalog, preferred)
+        if (!model) {
+          throw new Error(
+            'no available OpenCode Zen multimodal model accepts image input; connect OpenCode Zen and enable an image-capable model',
+          )
+        }
+        stage = 'resolve OpenCode Zen authentication'
+        const modelID = modelKey(model)
+        const dataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
+        const target = await resolveNativeVisionTarget({
+          preset: { vision: { model: modelID } },
+          env: { ...process.env, PANTHEON_VISION_MODEL: modelID },
+          authStatePath: join(dataHome, 'opencode'),
+        })
+        if (!target) {
+          throw new Error(
+            'OpenCode Zen authentication is missing; run `opencode auth login` ' +
+              '(checked the auth store and the V2 credential database)',
+          )
+        }
+        stage = 'send image to the selected multimodal model'
+        // Attach the live session id: the Zen gateway rejects a sessionless
+        // request (HTTP 400 MissingSessionID). describeImagesNative sends the
+        // header ONLY for Zen targets, never to a non-Zen provider.
+        const requestTarget: NativeVisionTarget = {
+          ...target,
+          ...(call.sessionID ? { sessionID: call.sessionID } : {}),
+        }
+        let failure: NativeVisionFailure | undefined
+        const output = await describeImagesNative(
+          [{ url: image.uri }],
+          requestTarget,
+          typeof input.prompt === 'string' && input.prompt.trim()
+            ? input.prompt.trim()
+            : buildV2ImagePrompt(),
+          NATIVE_MAX_TOKENS,
+          call.signal,
+          (details) => {
+            failure = details
+          },
+        )
+        if (!output?.trim()) {
+          // Surface the gateway status / finish_reason (never the key or
+          // payload) so a 400/401/403 or a max_tokens truncation is actionable.
+          throw new Error(nativeVisionFailureMessage(failure, modelKey(model)))
+        }
+        return {
+          output: output.trim(),
+          title: `Vision · ${modelKey(model)}`,
+          metadata: { model: modelKey(model), attachment: 'image' },
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'request failed'
+        return {
+          output: `Error: Pantheon Vision could not analyze the image during ${stage}: ${message}`,
+        }
+      }
+    },
+  }
+}