@vantran-se/openchamber-web 1.24.3 → 2.0.1

package/server/lib/small-model/DOCUMENTATION.md

@@ -1,229 +1,175 @@
 # Small Model
 
-Server-side direct LLM calls that reuse the user's existing OpenCode provider
-logins (`~/.local/share/opencode/auth.json`). OpenCode uses a "small model"
-internally (titles, summaries) but does not expose it through the SDK or
-plugins — this module replicates that mechanism as an OpenChamber runtime API.
+Background LLM calls for OpenChamber's own features — session titles, goal
+distillation, session assist, the changes walkthrough. Every call goes to the
+running OpenCode through `POST /api/experimental/generate`; OpenChamber never talks to a
+provider directly and never handles a provider credential.
 
 ## Security boundary
 
-Credentials never leave the server process. The client sends only a prompt;
-auth resolution, OAuth refresh, and provider dispatch all happen server-side.
-Routes live under `/api/*` and are gated by the ui-auth middleware like every
-other runtime API.
+The client sends a prompt. This server forwards it to OpenCode, which owns the
+credentials, the provider dispatch and the token refresh. Routes live under
+`/api/*` and are gated by the ui-auth middleware like every other runtime API.
 
 ## Files
 
-- `index.js` — orchestration: `generateSmallModelText()` / `describeSmallModel()`.
-- `runtime-providers.js` — provider state that exists only inside the running
-  OpenCode process. A plugin registers its provider from the `config` hook and
-  supplies the credential from its `auth` loader, so neither reaches
-  `opencode.json` nor `auth.json`; `GET /provider` is the only place they
-  become visible. The module caches one snapshot (30s TTL, shared in-flight
-  request) and answers `null` — never an empty provider list — when OpenCode is
-  unreachable, so a momentary outage cannot retract providers. It is wired once
-  from `server/index.js` and reset on OpenCode restart, which reloads plugins
-  and can move their ports and keys.
-- `resolve.js` — model selection, mirroring OpenCode's `getSmallModel` chain:
-  0. OpenChamber's own settings override (Settings → Sessions → Small Model):
-     when `smallModelUseDefault` is `false`, `smallModelOverride`
-     (`provider/model`) outranks everything below. Sanitized in
-     `settings-helpers.js` (server), `persistence.ts` (client), and
-     `bridge-settings-runtime.ts` (VS Code).
-  1. `small_model` from the merged OpenCode config layers (`provider/model`).
-  2. Family-priority scan (`gemini-flash` → `gpt-nano` → `claude-haiku`)
-     **within the session's provider first** (`preferredProviderID`, like
-     OpenCode resolves within the current provider), then over the other
-     providers with a usable auth entry, newest `release_date` first.
-  3. GitHub Copilot hidden utility models (`gpt-*-nano/mini`) — these never
-     appear in the catalog, so they participate as the `gpt-nano` family entry
-     and as a final utility fallback.
-  4. Last resort: the session's own model (`preferredModelID`) when no small
-     model resolves anywhere — costlier, but always valid.
-- Input clamp: the prompt is measured against the resolved model's catalog
-  `limit.context` (minus an output reserve, ~4 chars/token estimate;
-  conservative default when the model is not in the catalog). `onOverflow`
-  decides what an oversized prompt means:
-  - `truncate` (default) clips the tail and reports `inputTruncated: true`.
-    Correct for callers that degrade gracefully (summaries, commit messages).
-  - `error` throws a `413` with `code: 'context-too-small'` plus
-    `requiredChars`/`availableChars`. Correct for callers whose output would be
-    quietly wrong on a clipped input, so they can ask the user for a roomier
-    model instead of returning confident nonsense.
-- Structured output: pass `responseSchema` (a JSON Schema) to get
-  schema-shaped JSON back as `text`. Wire support differs per format —
-  `response_format: {type: 'json_schema'}` for OpenAI-compatible chat,
-  `text.format` for the Responses API, a forced single tool call for the
-  Anthropic messages API, and `generationConfig.responseSchema` for Google
-  (whose OpenAPI-flavored dialect drops unknown JSON Schema keywords). The
-  ChatGPT-plan codex backend has no equivalent and rejects a schema request
-  with `code: 'structured-output-unsupported'` rather than silently returning
-  prose.
-- Output budget: `maxOutputTokens` is capped at the catalog's `limit.output` for
-  the model, and the **same number** is reserved from the input allowance. The
-  two must not drift — a caller that asks for a large answer while the reserve
-  stays at the default overruns the context, and the failure looks like a
-  truncation bug rather than a budgeting one. `describeSmallModel` takes
-  `outputReserveTokens` so readiness checks agree with what generation will do.
-  It may be a **function** of `{ contextTokens, outputTokenLimit }` for callers
-  that want as much answer room as the resolved model allows — they cannot name
-  a number before knowing which model they got. The resolved value comes back as
-  `outputTokens`, which is what the caller should then request, so the reserve
-  and the request are the same number by construction.
-- Reasoning models can spend the entire output budget thinking and return
-  nothing. That case (empty content with `finish_reason: 'length'`, or content
-  empty while `reasoning_content` is populated) throws with
-  `code: 'output-exhausted'` so callers can offer a different model instead of
-  showing a transport error.
-- `timeoutMs` overrides the 60s default per call; `signal` lets a caller abort
-  a request that is no longer wanted. Both apply to every wire format.
-- `describeSmallModel()` additionally reports `inputCharBudget`,
-  `contextTokens`, `contextKnown`, `structuredOutput`, and `hasLogin`. The last
-  is whether the resolved provider has a usable credential (`auth.json` or
-  config `provider.<id>.options.apiKey`) — settings/config overrides can name a
-  provider with none, and callers such as the walkthrough refuse before the
-  request. `structuredOutput` is tri-state: `true`/`false` from the catalog,
-  `null` when the catalog omits the field — which it does for roughly half of
-  all models, aggregators and proxies especially. Callers must treat `null` as
-  "try it", not "unsupported".
-- Missing credentials throw with `statusCode: 401` and
-  `code: 'no-provider-login'` rather than a bare `Error`, so UI callers can show
-  a blocker instead of a raw 500 message.
-- `call.js` — wire formats and per-provider auth, replicating OpenCode's
-  plugin auth loaders:
-  - OpenCode-hosted providers receive `x-opencode-session`. Session-backed
-    features reuse the real OpenCode session id, walkthrough retries reuse the
-    walkthrough cache key, and standalone one-shot actions receive a fresh
-    opaque id for that generation.
-  - **GitHub Copilot**: fetches the requested model's authenticated `/models`
-    metadata from `https://api.githubcopilot.com` (or
-    `copilot-api.<enterprise>`) and honors its advertised endpoint, preferring
-    Anthropic-compatible `/v1/messages`, then OpenAI `/responses`, then
-    `/chat/completions`. Models without `supported_endpoints` retain the legacy
-    Chat Completions default; metadata, missing-model, and unsupported-endpoint
-    failures are surfaced instead of guessing. The stored device-OAuth token is
-    used as the bearer with no token exchange or expiry.
-  - **OpenAI OAuth (ChatGPT plan)**: streaming Responses API on
-    `https://chatgpt.com/backend-api/codex/responses` with
-    `ChatGPT-Account-Id`; expired tokens are refreshed against
-    `auth.openai.com` (single-flight) and written back to `auth.json`.
-  - **Anthropic** (`type: api`): `/messages` with `x-api-key`, against
-    `provider.anthropic.options.baseURL` when configured (used as-is, matching
-    `@ai-sdk/anthropic` — no `/v1` is inserted) or `https://api.anthropic.com/v1`
-    otherwise.
-  - **Google** (`type: api`): `generateContent` with `x-goog-api-key`; Gemini 3
-    uses `thinkingLevel`, Gemini 2.x uses `thinkingBudget: 0`, and all other
-    models omit `thinkingConfig` entirely.
-  - Everything else: OpenAI-compatible `/chat/completions` against the
-    provider's base URL, resolved from (1) `provider.<id>.options.baseURL`
-    in the OpenCode config, (2) the hardcoded `https://api.openai.com/v1`
-     endpoint, (3) the selected model's endpoint OpenCode resolved at runtime,
-     (4) the provider-level runtime endpoint, (5) the provider's `api` field
-     from the models.dev catalog, or (6) `SDK_DEFAULT_BASE_URLS` — providers
-     such as Groq, xAI, and Mistral keep their endpoint inside a dedicated AI
-     SDK package, so neither the catalog nor OpenCode reports one. The
-     credential follows
-    the same shape: config `options.apiKey`, then the runtime credential, then
-    the auth.json entry. `provider.<id>.options.headers` is sent with the
-    request and overrides the bearer default, so gateways that authenticate on
-    their own header work here exactly as they do in a chat turn. Configured API
-    keys and header values honor OpenCode's `{env:NAME}` and `{file:path}`
-    substitutions; file contents and resolved credentials remain server-side.
-  - `thinking: { type: 'disabled' }` is sent in two cases, mirroring OpenCode's
-    `transform.ts`. The GLM switch belongs to the endpoint, not the model
-    family: it goes to a provider whose id contains `zai`/`zhipu` or whose
-    base URL is on `api.z.ai`/`bigmodel.cn`, because the same GLM model served
-    by another provider (OpenCode Go) rejects the unknown field with a 400.
-    The MiniMax M3 switch goes only behind the `@ai-sdk/openai-compatible` and
-    `@ai-sdk/anthropic` adapters (runtime model, then catalog model, then
-    catalog provider `npm`); a provider that reports no adapter counts as
-    OpenAI-compatible.
-  - The runtime credential is refused for providers listed in
-    `OWN_CREDENTIAL_HANDLING`. Their branches need the stored entry rather than
-    a bearer token: the clearest case is the ChatGPT-plan `openai` login, whose
-    runtime `options.apiKey` is an OAuth access token that `api.openai.com`
-    answers with 401.
-  - `[small-model:diagnostic]` logs record provider/model, input character
-    counts, output budget, thinking toggle, HTTP/finish status, and
-    content/reasoning lengths without logging prompts, response text, or
-    credentials. Goal audit parsing similarly emits
-    `[session-goal:diagnostic]` structural verdict metadata.
-- `catalog.js` — models.dev catalog via the shared in-process cache
-  (`../opencode/models-metadata.js`, also serving
-   `/api/openchamber/models-metadata`).
+- `client.js` — the connection to the running OpenCode. `server/index.js` wires
+  it once with `buildOpenCodeUrl` and `getOpenCodeAuthHeaders`; the client is
+  built per call because the port and the server password both change across an
+  OpenCode restart. Scoping is the `x-opencode-directory` header, URI-encoded.
+  Also caches the model list for 30 seconds — a generation needs the model's
+  context and output limits, and a round trip per session title is the wrong
+  trade. An unreachable OpenCode keeps the previous answer rather than
+  retracting it.
+- `index.js` — `generateSmallModelText()`, `describeSmallModel()`,
+  `listAuthenticatedProviders()`.
 - `routes.js` — `GET /api/small-model` (resolution preview) and
   `POST /api/small-model/generate` (`{ prompt, system?, maxOutputTokens?,
   model?, directory? }` → `{ text, providerID, modelID, source }`).
+- `runtime-providers.js` — compatibility re-export so `server/index.js` keeps
+  resolving its import. Delete it once that import points at `client.js`.
+
+## Free tier and the session fallback
+
+OpenCode's free zen models are listed as enabled without a login, but
+`/api/experimental/generate` refuses them ("free tier can only be used in OpenCode") and
+`/api/model/default` answers nothing, so on a fresh install with no provider
+login `generateSmallModelText` throws `404`. What happens next is per feature:
+
+- Commit message and PR description (`packages/ui/src/lib/gitApi.ts`) fall back
+  to `POST /api/session/:id/generate`, which runs on the open session's own
+  model with the session as context and does not touch its history. Verified
+  on OpenCode 2.0.2: the reply comes back and the message count stays at zero.
+- Session renaming, the session goal and the walkthrough do NOT fall back —
+  feeding a whole session into a model to write a title or audit a goal is the
+  wrong cost. Their entry points read `available` from `GET /api/small-model`
+  (`packages/ui/src/stores/useSmallModelStore.ts`) and show a disabled control
+  with the reason; the walkthrough uses its own readiness (`no-model`).
+- Session assist is server-side and simply does nothing when
+  `describeSmallModel` answers null.
+- Notes summarization and spoken summaries keep the original text and silence
+  the 404.
+
+## Model resolution
+
+Four things are decided here, in order:
+
+1. An explicit `model` on the request (`provider/model`) — `source: 'request'`.
+2. OpenChamber's settings override (Settings → Sessions → Small Model): when
+   `smallModelUseDefault` is `false`, `smallModelOverride` wins —
+   `source: 'settings'`.
+3. The small model of the session's provider (`preferredProviderID`) —
+   `source: 'session-provider-small'` — found by `pickSmallModelInProvider`:
+   the newest enabled, active, text-in text-out model of the first family in
+   `SMALL_MODEL_FAMILY_PRIORITY` (`gpt-luna`, `gemini-flash-lite`,
+   `gemini-flash`, `claude-haiku`, then `gpt-nano`, `gpt-mini`) that the
+   provider has. The first four are OpenCode's own list for its session
+   titles (`Catalog.model.small`), repeated here because OpenCode does not
+   expose it over HTTP; the last two are v1's additions so a provider with
+   only utility models (Copilot) still gets a cheap one. Families are
+   models.dev `family` values, not model ids (`gpt-luna` is the family of
+   `gpt-5.6-luna`); a model without one — a custom provider, a subscription
+   outside the catalog — gets its family read from its id (`familyOf`:
+   luna / flash-lite / flash / haiku / nano / mini). A caller that passes `restrictToPreferredProvider`
+   (session titles, the session goal, session assist, notes from a selection)
+   and finds none then takes the session's own model — `source:
+   'session-model'`: costlier than a small model elsewhere, but never another
+   provider's subscription.
+4. The small model of any provider OpenCode can call, same family order,
+   newest first — `source: 'small'`. Where callers without a session (commit
+   messages, spoken summaries) usually land.
+5. Otherwise `GET /api/model/default` — `source: 'default'`. This is
+   OpenCode's default chat model, not a small one; it is the last resort.
+
+Claude Code is refused unconditionally (`422`,
+`code: 'small-model-provider-unsupported'`). A plugin can publish an
+OpenAI-compatible endpoint for it, but that endpoint is a façade over the
+Claude Agent SDK, which spawns the Claude Code CLI per request and spends the
+user's Claude subscription rate limit. An available endpoint does not lift the
+refusal — the cost is the reason, not the transport.
+
+## Prompt shape
+
+`/api/experimental/generate` takes one prompt and no system message, so `system` leads the
+prompt, separated by a blank line.
+
+Input clamp: the prompt is measured against the resolved model's `limit.context`
+as OpenCode reports it, minus an output reserve, at ~4 chars/token. A model
+OpenCode does not list gets a conservative 64k default. `onOverflow` decides
+what an oversized prompt means:
+
+- `truncate` (default) clips the tail and reports `inputTruncated: true`.
+  Correct for callers that degrade gracefully (summaries, commit messages).
+- `error` throws a `413` with `code: 'context-too-small'` plus
+  `requiredChars`/`availableChars`. Correct for callers whose output would be
+  quietly wrong on a clipped input, so they can ask the user for a roomier
+  model instead of returning confident nonsense.
+
+Output budget: `maxOutputTokens` is capped at the model's `limit.output`, and
+the **same number** is reserved from the input allowance. `/api/experimental/generate` takes
+no output budget of its own, so this number only shapes the reserve — but the
+two sides must stay equal or a caller that asks for a large answer overruns the
+context and the failure looks like a truncation bug.
+`describeSmallModel` takes `outputReserveTokens` so readiness checks agree with
+what generation will do. It may be a **function** of
+`{ contextTokens, outputTokenLimit }` for callers that want as much answer room
+as the resolved model allows — they cannot name a number before knowing which
+model they got. The resolved value comes back as `outputTokens`.
+
+`timeoutMs` overrides the 60s default; `signal` aborts a request that is no
+longer wanted. The timeout covers generation, retry waits and structured-output
+retries together.
+
+OpenCode 2 can reject an explicit model before its cold catalog finishes loading.
+An `InvalidRequestError` whose message exactly names the selected model as
+`Model unavailable: provider/model` gets one retry after 500 ms, with the same
+model and prompt. Cancellation also stops the wait. Other errors are not retried.
+If the model remains unavailable, the route returns 503 with
+`code: 'small-model-unavailable'` and the model-specific reason. Commit and PR
+generation own their error toast and suppress the shared request toast.
+
+## Structured output
+
+`/api/experimental/generate` has no structured-output mode. `responseSchema` is therefore
+emulated: the schema is appended to the prompt as "Reply with JSON matching this
+schema and nothing else: …", and the reply is parsed here. A ```json fence is
+stripped. An unparseable reply is retried **once** — a model that ignored the
+shape often honours it on a second pass, and the alternative is failing a
+walkthrough over a stray sentence of preamble. A second failure throws with
+`code: 'structured-output-unsupported'` (`422`).
+
+`describeSmallModel` reports `structuredOutput: null`, never `false`. The
+capability is not knowable before the call, and callers must read `null` as
+"try it".
 
 ## Which providers the pickers may offer
 
 `listAuthenticatedProviders()` answers one question for the Small Model and
-Changes Walkthrough pickers alike: which providers can this module actually
-call. One rule decides it, applied the same way to every provider — **a
-credential we are allowed to use, and an endpoint to send it to.** The
-auth.json scan as before, plus the credential and endpoint OpenCode resolved
-for a plugin provider.
-
-**opencode zen is excluded without a real login.** When the user has no zen
-credential, OpenCode substitutes the sentinel `options.apiKey = "public"` and
-trims its catalog to the free models. Those run on OpenCode's own subsidised
-infrastructure and are meant to be reached through OpenCode, so the sentinel is
-never accepted as a credential — see `ZEN_ANONYMOUS_API_KEY`.
-
-### Why there is no capability probe
-
-A plugin may implement its whole integration inside `options.fetch` —
-rewriting the path, signing the request, translating the payload — and OpenCode
-cannot serialise a function. Such a provider advertises an ordinary base URL
-that answers nothing we know how to ask, and no reported field distinguishes it
-from a plain one.
-
-Asking the endpoint (`GET /models`) does identify that case correctly. It was
-measured against all 166 providers carrying an `api` URL in the models.dev
-catalog, and it also denies six of them — `cloudflare-workers-ai`,
-`infomaniak`, `iflowcn`, `inference`, `kuae-cloud-coding-plan`,
-`thinkingmachines` — which work fine and simply have no `/models` route. At a
-3.6% false-negative rate on providers known to work, the probe removes more
-working models from the picker than broken ones, and a provider that silently
-vanishes explains nothing while one that fails on use says why.
-
-So availability stops at credential and endpoint, and the protocol verdict is
-left to the call. A provider whose protocol lives in a plugin's `fetch` stays
-selectable and fails when used — which is what it did before this resolution
-existed.
-
-Claude Code is refused unconditionally. A plugin can publish an
-OpenAI-compatible endpoint for it, but that endpoint is a façade over the
-Claude Agent SDK, which spawns the Claude Code CLI per request and spends the
-user's Claude subscription rate limit. Paying that for a session title or a
-summary is the wrong trade, so an available endpoint does not lift the
-refusal — the cost is the reason, not the transport.
+Changes Walkthrough pickers: which providers OpenCode can call right now. A
+provider counts when it has at least one enabled model in `GET /api/model` —
+the same test OpenCode applies before letting a chat turn use it.
 
-The result is served as `authenticatedProviders` on `GET /api/small-model`.
-The field name predates the runtime resolution; it now means "callable", which
-is a superset of "has an auth.json entry".
+`GET /api/provider` only contributes names. It comes back empty on setups where
+models are perfectly usable, so an empty provider list is never read as "no
+providers". Claude Code is removed from the result for the reason above.
+
+The field is served as `authenticatedProviders` on `GET /api/small-model`. The
+name predates this resolution; it now means "callable".
+
+## describeSmallModel
+
+Reports which model would be used without calling it: `providerID`, `modelID`,
+`source`, plus `inputCharBudget`, `contextTokens`, `contextKnown`,
+`outputTokens`, `outputTokenLimit`, `structuredOutput` and `hasLogin`.
+
+`hasLogin` is `false` when OpenCode lists the model as disabled — a settings
+override can name a model there is no credential for, and the walkthrough
+refuses before the user pays for a failed request. A model OpenCode does not
+list at all is not evidence either way, so it counts as usable.
+
+Returns `null` when OpenCode is not reachable.
 
 ## Registration
 
 Mounted lazily from `feature-routes-runtime.js` (same pattern as quota): the
 module is imported on first request, not at server startup.
-
-## Known limitations
-
-- OpenCode's free models (`opencode/big-pickle`, `*-free`) work without a
-  token only through OpenCode's own server — direct calls are rejected, and
-  piggybacking on their subsidized infra is out of bounds by design. Every
-  resolution step therefore requires a credential we are allowed to use:
-  a session on an unauthenticated `opencode` provider falls through to the
-  global scan (or a clean 404 on a vanilla setup with no logins). The runtime
-  snapshot does not weaken this — OpenCode reports the sentinel
-  `apiKey: "public"` for that state, and this module refuses to read it as a
-  credential.
-
-- Anthropic OAuth (Claude Pro/Max) entries are not supported — OpenCode itself
-  keeps those outside `auth.json` in this generation; only `type: api` keys
-  work for Anthropic.
-- Amazon Bedrock, GitLab, Azure and other credential-chain providers are out
-  of scope; they need more than a key/token (regions, resource names).
-- Responses from the codex backend are collected from the SSE stream; the
-  endpoint itself is non-streaming by design (small utility calls).

package/server/lib/small-model/client.js

@@ -0,0 +1,113 @@
+import { OpenCode } from '@opencode/client';
+
+// The running OpenCode instance is the only transport this module has. It is
+// wired once from `server/index.js`, and re-read on every call because the
+// port and the server password both move across an OpenCode restart.
+let connection = null;
+
+/**
+ * Wires this module to the running OpenCode instance. Pass `null` to detach.
+ * Until it is wired, every lookup answers "no client", which the callers
+ * report as "no small model available" rather than guessing.
+ */
+export function configureOpenCodeRuntimeProviders(next) {
+  connection = next ?? null;
+}
+
+/**
+ * Drops anything cached about the running instance. An OpenCode restart can
+ * change the port, the password and the model list.
+ */
+export function resetOpenCodeRuntimeProviders() {
+  modelCache = null;
+  modelCacheKey = '';
+  modelCacheAt = 0;
+}
+
+const stripTrailingSlash = (value) => value.replace(/\/+$/, '');
+
+/**
+ * A `@opencode/client` bound to the running instance and scoped to
+ * `directory`, or `null` when OpenCode is not reachable yet.
+ *
+ * Built per call on purpose: `OpenCode.make` only closes over a base URL and
+ * headers, and both change when OpenCode restarts.
+ */
+export function getSmallModelClient(directory) {
+  if (!connection) return null;
+  let baseUrl;
+  try {
+    baseUrl = stripTrailingSlash(connection.buildOpenCodeUrl('', ''));
+  } catch {
+    // The port is not known yet — OpenCode has not finished starting.
+    return null;
+  }
+  const headers = { ...connection.getOpenCodeAuthHeaders() };
+  if (typeof directory === 'string' && directory.trim()) {
+    headers['x-opencode-directory'] = encodeURIComponent(directory.trim());
+  }
+  return OpenCode.make({ baseUrl, headers });
+}
+
+const MODEL_CACHE_TTL_MS = 30_000;
+let modelCache = null;
+let modelCacheKey = '';
+let modelCacheAt = 0;
+
+const unwrap = (payload) => (Array.isArray(payload?.data) ? payload.data : []);
+
+/**
+ * Every model the running OpenCode knows about for `directory`.
+ *
+ * Cached briefly: a generation needs the model's context and output limits,
+ * and paying a round trip for them on every title or summary would be the
+ * wrong trade. An empty array means "asked and got nothing", so callers fall
+ * back to conservative defaults rather than refusing.
+ */
+export async function listModelInfos(client, directory) {
+  const key = typeof directory === 'string' ? directory : '';
+  if (modelCache && modelCacheKey === key && Date.now() - modelCacheAt < MODEL_CACHE_TTL_MS) {
+    return modelCache;
+  }
+  try {
+    const models = unwrap(await client.model.list());
+    modelCache = models;
+    modelCacheKey = key;
+    modelCacheAt = Date.now();
+    return models;
+  } catch {
+    // Keep the previous answer for this directory when there is one: a
+    // momentarily unreachable OpenCode must not retract model limits.
+    return modelCacheKey === key && modelCache ? modelCache : [];
+  }
+}
+
+export async function listProviderInfos(client) {
+  try {
+    return unwrap(await client.provider.list());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The model OpenCode would pick on its own, or `null` when it cannot say.
+ */
+export async function getDefaultModelInfo(client) {
+  try {
+    const payload = await client.model.default();
+    const info = payload?.data ?? payload;
+    return info && typeof info === 'object' && typeof info.id === 'string' ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The model entry for a `provider/model` reference. `modelID` and `id` are
+ * both accepted because OpenCode reports the same model under both.
+ */
+export function findModelInfo(models, providerID, modelID) {
+  return models.find((model) => model?.providerID === providerID
+    && (model.id === modelID || model.modelID === modelID)) ?? null;
+}