@chatcode/cco-llm-chatcode-config 0.1.0

package/vendor/dsh-llm-pi-ai/src/context.ts

@@ -0,0 +1,349 @@
+/**
+ * ChatCode CLI request-history conversion into pi-ai's Context vocabulary.
+ *
+ * @module dsh-llm-pi-ai/context
+ */
+
+import { brandString } from '@deepseek-ai/dsh-brand'
+import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, requestImageHandleText, requiredImageOffload } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, ImageAttachmentAccessResolver, Message, ToolCallId } from '@deepseek-ai/dsh-llm'
+import type {
+  AttachmentId,
+  AttachmentStore,
+  ImageAttachmentRef,
+  ImageRequestTarget,
+  RequestImageAttachment,
+} from '@deepseek-ai/dsh-attachment'
+import type { Context as PiContext, ImageContent, Message as PiMessage, TextContent, Tool as PiTool } from '@earendil-works/pi-ai'
+import { toPiAssistant } from './replay.ts'
+import { requestImageDimensions } from '@deepseek-ai/dsh-attachment'
+import { DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET } from './config.ts'
+
+/** Join the text blocks of a harness message. */
+function flattenText(message: Message): string {
+  return message.content
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+
+/** Flatten text recursively inside one tool result. */
+function toolResultText(blocks: readonly ContentBlock[]): string {
+  return blocks.map(block => block.type === 'text'
+    ? block.text
+    : block.type === 'tool-result' ? toolResultText(block.content) : '').join('')
+}
+
+/** Reject image roles that pi-ai cannot replay before request-size offloading can replace them. */
+function assertSupportedImageRoles(messages: readonly Message[]): void {
+  for (const message of messages) {
+    if (message.role !== 'user' && contentHasImage(message.content)) {
+      throw new LlmError(
+        `pi-ai cannot represent an image in an in-history ${message.role} message`,
+        'UNSUPPORTED_CONTENT',
+      )
+    }
+  }
+}
+
+async function userContent(
+  blocks: readonly ContentBlock[],
+  requestImages: ReadonlyMap<AttachmentId, RequestImageAttachment>,
+  resolveImageAccess: ImageAttachmentAccessResolver,
+): Promise<string | (TextContent | ImageContent)[]> {
+  const content: (TextContent | ImageContent)[] = []
+  for (const block of blocks) {
+    switch (block.type) {
+      case 'text':
+        if (block.text.length > 0) content.push({ type: 'text', text: block.text })
+        break
+      case 'image': {
+        const version = requestImages.get(block.attachment.attachmentId) as RequestImageAttachment
+        content.push({
+          type: 'text',
+          text: requestImageHandleText(block.attachment, version, resolveImageAccess(block.attachment)),
+        })
+        content.push({
+          type: 'image',
+          data: Buffer.from(version.data).toString('base64'),
+          mimeType: version.mediaType,
+        })
+        break
+      }
+      case 'tool-result':
+        {
+          const nested = await userContent(block.content, requestImages, resolveImageAccess)
+          if (typeof nested === 'string') {
+            if (nested.length > 0) content.push({ type: 'text', text: nested })
+          } else {
+            content.push(...nested)
+          }
+        }
+        break
+      default:
+        // Other merge-extensible blocks are not user-input vocabulary for pi-ai.
+        break
+    }
+  }
+  if (content.every(block => block.type === 'text')) return content.map(block => block.text).join('')
+  return content
+}
+
+function collectImageRefs(
+  blocks: readonly ContentBlock[],
+  refs: Map<AttachmentId, ImageAttachmentRef>,
+): void {
+  for (const block of blocks) {
+    if (block.type === 'image') {
+      if (block.offloaded !== true) refs.set(block.attachment.attachmentId, block.attachment)
+    } else if (block.type === 'tool-result') {
+      collectImageRefs(block.content, refs)
+    }
+  }
+}
+
+async function prepareRequestImages(
+  messages: readonly Message[],
+  attachments: AttachmentStore,
+  budget: PiImageRequestBudget,
+  signal?: AbortSignal,
+): Promise<Map<AttachmentId, RequestImageAttachment>> {
+  const refs = new Map<AttachmentId, ImageAttachmentRef>()
+  for (const message of messages) collectImageRefs(message.content, refs)
+  const orderedRefs = [...refs.values()]
+  const prepared = await Promise.all(orderedRefs.map(
+    ref => attachments.readImageRequest(ref, requestImageTarget(ref, budget), signal),
+  ))
+  const versions = new Map<AttachmentId, RequestImageAttachment>()
+  for (const [index, ref] of orderedRefs.entries()) {
+    versions.set(ref.attachmentId, prepared[index] as RequestImageAttachment)
+  }
+  return versions
+}
+
+function toolsOf(options: GenerateOptions): PiTool[] | undefined {
+  return options.tools?.map(tool => ({
+    name: tool.name,
+    description: tool.description,
+    // ToolSchema.parameters is a JSON Schema object; pi-ai's TSchema
+    // (TypeBox) is structurally JSON Schema, so it assigns directly.
+    parameters: tool.parameters,
+  }))
+}
+
+/** The request split into pi-ai's single `systemPrompt` slot and the history that converts to `messages`. */
+interface SystemPromptSplit {
+  /** Text for pi-ai's `systemPrompt`; `undefined` sends no system prompt. */
+  systemPrompt: string | undefined
+  /** History messages that convert to pi-ai `messages`. */
+  messages: readonly Message[]
+}
+
+/** Select the pi-ai system prompt source shared by both conversion paths. */
+function splitSystemPrompt(options: GenerateOptions): SystemPromptSplit {
+  if (options.system !== undefined) return { systemPrompt: options.system, messages: options.messages }
+  const [first, ...rest] = options.messages
+  if (first?.role !== 'system') return { systemPrompt: undefined, messages: options.messages }
+  const text = flattenText(first)
+  return { systemPrompt: text.length > 0 ? text : undefined, messages: rest }
+}
+
+/** Assemble the request-level pi-ai context envelope shared by both conversion paths. */
+function piContext(systemPrompt: string | undefined, options: GenerateOptions, messages: PiMessage[]): PiContext {
+  const tools = toolsOf(options)
+  return {
+    ...systemPrompt !== undefined ? { systemPrompt } : {},
+    messages,
+    ...tools !== undefined && tools.length > 0 ? { tools } : {},
+  }
+}
+
+function appendAssistant(
+  message: Message,
+  messages: PiMessage[],
+  toolNames: Map<ToolCallId, string>,
+  onReplayDegrade?: (reason: string) => void,
+): void {
+  const assistant = toPiAssistant(message, onReplayDegrade)
+  for (const block of assistant.content) {
+    if (block.type === 'toolCall') toolNames.set(brandString<ToolCallId>(block.id), block.name)
+  }
+  messages.push(assistant)
+}
+
+function textOnlyContext(options: GenerateOptions, onReplayDegrade?: (reason: string) => void): PiContext {
+  assertSupportedImageRoles(options.messages)
+  const split = splitSystemPrompt(options)
+  const toolNames = new Map<ToolCallId, string>()
+  const messages: PiMessage[] = []
+  for (const message of split.messages) {
+    if (contentHasImage(message.content)) {
+      throw new LlmError('pi-ai image conversion requires the durable attachment service', 'UNSUPPORTED_CONTENT')
+    }
+    if (message.role === 'system') {
+      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
+      continue
+    }
+    if (message.role === 'assistant') {
+      appendAssistant(message, messages, toolNames, onReplayDegrade)
+      continue
+    }
+    const text = flattenText(message)
+    const results = message.content.filter(block => block.type === 'tool-result')
+    if (text.length > 0 || results.length === 0) messages.push({ role: 'user', content: text, timestamp: 0 })
+    for (const result of results) {
+      messages.push({
+        role: 'toolResult',
+        toolCallId: result.toolCallId,
+        toolName: toolNames.get(result.toolCallId) ?? 'unknown',
+        content: [{
+          type: 'text',
+          text: toolResultText(result.content) || '(no output)',
+        }],
+        isError: result.isError ?? false,
+        timestamp: 0,
+      })
+    }
+  }
+  return piContext(split.systemPrompt, options, messages)
+}
+
+/** Inputs that bind deterministic request images to one current tool execution world. */
+export interface PiImageRequestContext {
+  /** Durable provider that resolves request-image bytes and provider-owned host objects. */
+  attachments: AttachmentStore
+  /** Resolve current tool access separately from deterministic request-image versions. */
+  resolveImageAccess: ImageAttachmentAccessResolver
+  /** 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. */
+  requestImagePolicy?: PiImageRequestBudget
+}
+
+/** Per-route budgets from which each request image's target is derived. */
+export interface PiImageRequestBudget {
+  /** Total-pixel budget; larger sources are downscaled proportionally. */
+  maxPixels: number
+  /** Encoded-byte target for one request image. */
+  maxBytes: number
+}
+
+/** Deterministic request target for one source under the route budgets. */
+function requestImageTarget(ref: ImageAttachmentRef, budget: PiImageRequestBudget): ImageRequestTarget {
+  return { ...requestImageDimensions(ref.width, ref.height, budget.maxPixels), maxBytes: budget.maxBytes }
+}
+
+/**
+ * Convert text-only harness history to a synchronous pi-ai Context. Tool
+ * result names are recovered from preceding assistant tool calls.
+ * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.
+ * @param images - absent; selects the synchronous conversion.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the pi-ai context; `tools` is omitted when the request declares none.
+ * @throws {LlmError} `UNSUPPORTED_CONTENT` for images in any history role, including a leading system message.
+ */
+export function toPiContext(
+  options: GenerateOptions,
+  images?: undefined,
+  onReplayDegrade?: (reason: string) => void,
+): PiContext
+/**
+ * Convert harness history to a pi-ai Context while resolving durable images.
+ * Tool result names are recovered from preceding assistant tool calls. Image
+ * occurrences the surface marks offloaded become text placeholders; when the
+ * retained occurrences' exact base64 payload still 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.
+ * @param images - attachment provider, current path resolver, and request limits.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the asynchronously resolved pi-ai context.
+ */
+export function toPiContext(
+  options: GenerateOptions,
+  images: PiImageRequestContext,
+  onReplayDegrade?: (reason: string) => void,
+): Promise<PiContext>
+export function toPiContext(
+  options: GenerateOptions,
+  images?: PiImageRequestContext,
+  onReplayDegrade?: (reason: string) => void,
+): PiContext | Promise<PiContext> {
+  return images === undefined
+    ? textOnlyContext(options, onReplayDegrade)
+    : toPiContextWithImages(options, images, onReplayDegrade)
+}
+
+async function toPiContextWithImages(
+  options: GenerateOptions,
+  images: PiImageRequestContext,
+  onReplayDegrade?: (reason: string) => void,
+): Promise<PiContext> {
+  const { attachments, resolveImageAccess, maxRequestImageBytes } = images
+  const requestImagePolicy = images.requestImagePolicy ?? {
+    maxPixels: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+    maxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+  }
+  assertSupportedImageRoles(options.messages)
+  const split = splitSystemPrompt(options)
+  const requestImages = await prepareRequestImages(split.messages, attachments, requestImagePolicy, options.signal)
+  if (maxRequestImageBytes !== undefined) {
+    const offloadImages = requiredImageOffload(
+      split.messages,
+      { representation: 'base64', maxBytes: maxRequestImageBytes },
+      block => (requestImages.get(block.attachment.attachmentId) as RequestImageAttachment).bytes,
+    )
+    if (offloadImages > 0) {
+      throw new LlmError(
+        `pi-ai request images exceed the ${maxRequestImageBytes}-byte base64 bound; ${offloadImages} more oldest occurrence(s) must be offloaded.`,
+        IMAGE_OFFLOAD_REQUIRED_CODE,
+        { offloadImages },
+      )
+    }
+  }
+  const exactMessages = projectOffloadedImages(
+    split.messages,
+    ref => offloadedImageText(ref, resolveImageAccess(ref)),
+  )
+  const toolNames = new Map<ToolCallId, string>()
+  const messages: PiMessage[] = []
+
+  for (const message of exactMessages) {
+    if (message.role === 'system') {
+      // pi-ai has a single systemPrompt slot; in-history system messages are
+      // folded into user messages to preserve order (rare in practice — the
+      // harness sends the system prompt via options.system).
+      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
+      continue
+    }
+    if (message.role === 'assistant') {
+      appendAssistant(message, messages, toolNames, onReplayDegrade)
+      continue
+    }
+    // user role: text + tool results (each result becomes its own message).
+    const regular = message.content.filter(block => block.type !== 'tool-result')
+    const content = await userContent(regular, requestImages, resolveImageAccess)
+    const results = message.content.filter((block): block is Extract<ContentBlock, { type: 'tool-result' }> => (
+      block.type === 'tool-result'
+    ))
+    if (content.length > 0 || results.length === 0) {
+      messages.push({ role: 'user', content, timestamp: 0 })
+    }
+    for (const result of results) {
+      const resultContent = await userContent(result.content, requestImages, resolveImageAccess)
+      messages.push({
+        role: 'toolResult',
+        toolCallId: result.toolCallId,
+        toolName: toolNames.get(result.toolCallId) ?? 'unknown',
+        content: typeof resultContent === 'string'
+          ? [{ type: 'text', text: resultContent || '(no output)' }]
+          : resultContent,
+        isError: result.isError ?? false,
+        timestamp: 0,
+      })
+    }
+  }
+
+  return piContext(split.systemPrompt, options, messages)
+}

package/vendor/dsh-llm-pi-ai/src/discovery.ts

@@ -0,0 +1,284 @@
+/**
+ * Answering "which models can this provider serve?" for the configuration
+ * surface's "fetch available models" action.
+ *
+ * A route the installed pi-ai catalog ships is answered **from that catalog**,
+ * with no network call at all: pi-ai's registry is the authoritative list for
+ * its own providers, and it carries the capacities a listing endpoint would
+ * not disclose. Only a route the catalog does not describe — a gateway, a
+ * self-hosted server — is interrogated over the wire.
+ *
+ * Neither path is a catalog refresh. Nothing here is stored: the request
+ * carries a draft the user is still editing, and the reply is candidate
+ * metadata the surface offers for adoption. `settings.yaml` remains the only
+ * thing that decides what a route serves.
+ *
+ * Only OpenAI-compatible protocols are interrogated. Their listing is the one
+ * shape a gateway, a self-hosted server, and the official endpoints all agree
+ * on, which is the case this action exists for; every other protocol reports
+ * that it cannot be interrogated so the surface falls back to hand-entry
+ * rather than guessing a response shape.
+ *
+ * @module dsh-llm-pi-ai/discovery
+ */
+
+import { INVALID_CREDENTIAL_CODE, LlmError, normalizeApiKey } from '@deepseek-ai/dsh-llm'
+import type { LlmDiscoveredModel, LlmModelDiscoveryOperation } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders } from '@deepseek-ai/dsh-llm'
+import { catalogModels } from './catalog.ts'
+
+/**
+ * Protocols whose model listing this module can read: the two that speak
+ * OpenAI's `GET /models` shape with bearer auth. Azure is absent despite its
+ * OpenAI lineage — it authenticates with an `api-key` header and requires an
+ * `api-version` query — and Codex authenticates through OAuth; guessing at
+ * either would report an authentication failure as a provider with no models.
+ * pi-ai's remaining protocols are absent for the same reason.
+ */
+const LISTABLE_PROTOCOLS: ReadonlySet<string> = new Set([
+  'openai-completions',
+  'openai-responses',
+])
+
+/**
+ * Endpoint replies larger than this are refused. The endpoint is whatever URL
+ * the user typed, so the ceiling holds on the bytes actually read rather than
+ * on the length the server claims — the same two-stage shape `dsh-web-fetch`
+ * uses for its own caller-supplied URLs, except that a truncated model listing
+ * is not parseable, so overflow rejects instead of truncating.
+ */
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+/** One entry of an OpenAI-compatible `GET /models` reply. */
+interface ListingEntry {
+  id?: unknown
+  /** Common gateway extensions; absent from the official listings. */
+  name?: unknown
+  display_name?: unknown
+  context_window?: unknown
+  context_length?: unknown
+  max_tokens?: unknown
+  max_output_tokens?: unknown
+}
+
+/** A positive integer field of a listing entry, or `undefined` when absent or unusable. */
+function capacity(...candidates: readonly unknown[]): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isInteger(candidate) && candidate > 0) return candidate
+  }
+  return undefined
+}
+
+/** A non-empty string field of a listing entry, or `undefined`. */
+function label(...candidates: readonly unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Join the endpoint base with the listing path. The base is treated as a
+ * prefix rather than a URL to resolve against, so a deployment path such as
+ * `https://gateway.example/openai/v1` keeps its segments instead of losing
+ * them to `URL` resolution.
+ */
+function listingUrl(baseURL: string): string {
+  return `${baseURL.replace(/\/+$/, '')}/models`
+}
+
+/**
+ * Read a reply body, refusing one that outgrows the ceiling. A declared length
+ * is checked first so an honest server is turned away without transferring
+ * anything; the accumulated total is what actually enforces the bound, because
+ * a server that under-declares (or streams) tells us nothing up front.
+ */
+async function readBounded(response: Response, url: string): Promise<string> {
+  const oversized = (): LlmError =>
+    new LlmError(`${url} answered with more than ${MAX_RESPONSE_BYTES} bytes`, 'DISCOVERY_FAILED')
+  const declared = Number(response.headers.get('content-length') ?? Number.NaN)
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel()
+    throw oversized()
+  }
+  /* v8 ignore next -- fetch always exposes a body stream on a 2xx Response; the null guard is defensive. */
+  if (response.body === null) return ''
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > MAX_RESPONSE_BYTES) throw oversized()
+      chunks.push(value)
+    }
+  } finally {
+    /* v8 ignore next 4 -- cancel() after a completed or abandoned read settles without rejecting; unobserved best-effort cleanup. */
+    await reader.cancel().catch(() => {
+      // Cancel after a drained read, or after this function walked away from
+      // an oversized one, is cleanup; the reply is already decided either way.
+    })
+  }
+  const body = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(body)
+}
+
+/**
+ * Read one OpenAI-compatible listing reply. Entries without a usable id are
+ * skipped rather than failing the whole interrogation: a single malformed row
+ * should not deny the user the rest of a working endpoint's catalog.
+ */
+function readListing(body: unknown): LlmDiscoveredModel[] {
+  const data = (body as { data?: unknown } | null)?.data
+  if (!Array.isArray(data)) {
+    throw new LlmError(
+      'the endpoint\'s model listing has no "data" array; enter this provider\'s models by hand',
+      'DISCOVERY_FAILED',
+    )
+  }
+  const models: LlmDiscoveredModel[] = []
+  for (const raw of data) {
+    const entry = raw as ListingEntry | null
+    const id = label(entry?.id)
+    if (id === undefined) continue
+    const name = label(entry?.name, entry?.display_name)
+    const contextWindow = capacity(entry?.context_window, entry?.context_length)
+    const maxTokens = capacity(entry?.max_output_tokens, entry?.max_tokens)
+    models.push({
+      id,
+      ...name === undefined ? {} : { name },
+      ...contextWindow === undefined ? {} : { contextWindow },
+      ...maxTokens === undefined ? {} : { maxTokens },
+    })
+  }
+  return models
+}
+
+/**
+ * Accept one probe key, or refuse it before the header is built. Without this
+ * the `fetch` below would throw a ByteString `TypeError` that this function's
+ * catch reports as `could not reach <url>` — blaming the network for a local,
+ * deterministic fault.
+ * @param raw - the key typed into the form or read from storage.
+ * @returns the trimmed, usable key.
+ */
+function usableProbeKey(raw: string): string {
+  const checked = normalizeApiKey(raw)
+  if (checked.ok) return checked.value
+  throw new LlmError(
+    checked.reason === 'empty'
+      ? 'this provider\'s API key is blank; enter it on the Models page, or clear it to probe unauthenticated'
+      : 'this provider\'s API key contains characters no HTTP header can carry; paste the raw key only',
+    INVALID_CREDENTIAL_CODE,
+  )
+}
+
+/**
+ * Interrogate one draft provider endpoint for the models it advertises.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @param storedApiKey - the credential the named route already stored, asked
+ *   for only when the draft carries none and only on the path that reaches the
+ *   network. A configuration surface never holds a stored secret — it edits a
+ *   redacted descriptor — so without this an already-configured route would be
+ *   interrogated unauthenticated and answer 401.
+ * @returns the advertised models in endpoint order.
+ * @throws LlmError when the protocol has no readable listing, the endpoint
+ *   refuses or fails the request, or the reply is not a model listing.
+ */
+export async function discoverModels(
+  request: LlmModelDiscoveryOperation,
+  storedApiKey?: () => Promise<string | undefined>,
+): Promise<readonly LlmDiscoveredModel[]> {
+  // A catalog route already has its answer, and a better one: the installed
+  // entries carry context windows and output caps no listing endpoint reports.
+  if (request.provider !== undefined) {
+    const installed = catalogModels(request.provider)
+    if (installed.size > 0) {
+      return [...installed.values()].map(model => ({
+        id: model.id,
+        name: model.name,
+        contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens,
+      }))
+    }
+  }
+  if (request.baseURL === undefined || request.baseURL.length === 0) {
+    throw new LlmError(
+      `pi-ai ships no catalog for provider "${request.provider ?? ''}", so its models can only come from its`
+      + " endpoint; set a baseURL, or enter this provider's models by hand",
+      'DISCOVERY_FAILED',
+    )
+  }
+  // A draft that has not chosen a protocol yet is asked as OpenAI Chat
+  // Completions: it is the shape a gateway is overwhelmingly likely to speak,
+  // and the alternative — refusing until the field is filled — would withhold
+  // the action from the case it exists for. The cost is a misdirected message
+  // when the endpoint speaks something else (an Anthropic gateway answers 401,
+  // which reads as a credential problem), and hand-entry remains the way out.
+  const api = request.api ?? 'openai-completions'
+  if (!LISTABLE_PROTOCOLS.has(api)) {
+    throw new LlmError(
+      `pi-ai protocol "${api}" has no model listing this build can read; enter this provider's models by hand`,
+      'DISCOVERY_UNSUPPORTED',
+    )
+  }
+  const url = listingUrl(request.baseURL)
+  // A key typed into the form wins: it is the one the user is testing, and it
+  // may be the replacement for exactly the stored key that is failing. The
+  // stored one is only asked for here, past the catalog short-circuit and the
+  // protocol check, so a route answered from the registry costs no credential
+  // lookup — and no diagnostic about a credential it never needed.
+  // A probe carrying no key stays unauthenticated, which is how a route that
+  // relies on the provider's own ambient discovery is meant to be asked.
+  const supplied = request.apiKey ?? await storedApiKey?.()
+  const apiKey = supplied === undefined ? undefined : usableProbeKey(supplied)
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json',
+        ...apiKey === undefined ? {} : { authorization: `Bearer ${apiKey}` },
+        ...attributionHeaders(),
+      },
+      ...request.signal === undefined ? {} : { signal: request.signal },
+    })
+  } catch (error: unknown) {
+    if (request.signal?.aborted) {
+      throw new LlmError('model discovery aborted by caller', 'ABORTED', { cause: error })
+    }
+    throw new LlmError(`could not reach ${url}`, 'DISCOVERY_FAILED', { cause: error })
+  }
+  if (!response.ok) {
+    throw new LlmError(
+      `${url} answered ${response.status}${response.status === 401 || response.status === 403 ? '; check the API key' : ''}`,
+      'DISCOVERY_FAILED',
+    )
+  }
+  let text: string
+  try {
+    text = await readBounded(response, url)
+  } catch (error: unknown) {
+    // Cancellation during the body read rejects with the abort reason, which
+    // may be any value; the caller gets the same coded failure it would have
+    // for a cancellation before the request went out.
+    if (request.signal?.aborted) {
+      throw new LlmError('model discovery aborted by caller', 'ABORTED', { cause: error })
+    }
+    throw error
+  }
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch (error: unknown) {
+    throw new LlmError(`${url} did not answer with JSON`, 'DISCOVERY_FAILED', { cause: error })
+  }
+  return readListing(body)
+}