Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(images): enforce model capabilities and preserve rejected input (#669)

ALFREDO J LOPEZ H (alfredolopez80.eth)05aebc2594d3
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000..96026ad75
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+# Generated data. `linguist-generated` collapses the file in GitHub diffs and
+# keeps it out of the repository's language statistics: it is produced by
+# control-api/scripts/regenerate-models-dev-snapshot.mjs and never hand-edited.
+control-api/src/data/modelsDevSnapshot.ts linguist-generated=true
diff --git a/.github/workflows/ci-public.yml b/.github/workflows/ci-public.yml
index bc1e52655..35f19dd1d 100644
--- a/.github/workflows/ci-public.yml
+++ b/.github/workflows/ci-public.yml
@@ -150,6 +150,20 @@ jobs:
scripts/e2e/approved-tools-resource-cleanup.test.mjs \
tests/e2e/fixtures/codex-subscription/approved-tools-workflow/index.test.mjs
+ # Image-capabilities (issue #654) node:test fixtures. The pixel-fixture
+ # unit proves the fixture contract and the SDK test drives the compiled
+ # OpenAICompatibleProvider against the production serializer. Both
+ # depend on Host's built dist/, so the step runs after `Build` and after
+ # `Test Codex approved-tools fixtures and runner` (same registration
+ # pattern as the approved-tools lane).
+ - name: Test image-capabilities fixtures and runner
+ if: matrix.service == 'mcp-host'
+ run: |
+ node scripts/tests/run-node-test-files.mjs \
+ scripts/e2e/image-capabilities-fixture.test.mjs \
+ tests/e2e/fixtures/image-capabilities/provider.test.mjs \
+ tests/e2e/fixtures/image-capabilities/sdk.test.mjs
+
# Typecheck against the base tsconfig (covers src + test dirs).
# This catches errors in test files that tsconfig.build.json may exclude.
#
@@ -166,6 +180,9 @@ jobs:
# llm-providers, and codex-catalog-projection are the same shape:
# hand-authored .cjs + .d.ts, no tsconfig; node --test keeps the
# types aligned with the runtime.
+ # llm-providers is that shape too (index.cjs + imageInput.cjs + index.d.ts,
+ # no tsconfig and no typescript dependency), so `npx tsc` there would fetch
+ # the unrelated `tsc` package from the registry instead of typechecking.
- name: Typecheck (tsc --noEmit)
if: matrix.service != 'mcp-servers' && matrix.service != 'packages/desktop-app-links' && matrix.service != 'packages/gfs-interaction-policy' && matrix.service != 'packages/network-policy-core' && matrix.service != 'packages/llm-provider-attempt-contract' && matrix.service != 'packages/grok-provider-attempt-contract' && matrix.service != 'packages/llm-providers' && matrix.service != 'packages/codex-catalog-projection'
working-directory: ${{ matrix.service }}
@@ -267,7 +284,8 @@ jobs:
services.grokProviderAttemptRedemption.realPostgres.integration \
services.grokProviderAttemptRedemption.refresh.realPostgres.integration \
services.codexSubscriptionLifecycle.realPostgres.integration \
- db.llmProviderAttemptConnectionIntegrity.realPostgres.integration
+ db.llmProviderAttemptConnectionIntegrity.realPostgres.integration \
+ services.llmCatalogSync.realPostgres.integration
do
grep -Fq "$suite" "$normalized_log" || {
echo "real-Postgres control-api lane omitted Codex suite ${suite}" >&2
diff --git a/Makefile b/Makefile
index aa427eeda..d1a48e173 100644
--- a/Makefile
+++ b/Makefile
@@ -82,6 +82,7 @@ TEST_SERVICES := \
packages/llm-providers \
packages/grok-provider-attempt-contract
+
# ── Optional private infra (gcp-*, promotion) ──────────────────────────────
-include Makefile.infra
# ── Optional OSS-launch tooling (public snapshot / infra carve) — monorepo-only
@@ -281,6 +282,31 @@ minikube-build-627-worktracker: ## Build the reviewed Worktracker sources locall
T2_SKIP_LOCK="$(T2_SKIP_LOCK)" T2_LOCK_TOKEN="$(T2_LOCK_TOKEN)" \
bash scripts/minikube/with-t2-mutation-lock.sh -- bash scripts/e2e/build-627-worktracker.sh
+.PHONY: minikube-build-image-capabilities-fixture minikube-build-image-capabilities-fixture-body
+minikube-build-image-capabilities-fixture: ## Build the unpublished image-input provider fixture under the owned profile lease
+ @T2_PROJECT_DIR="$(CURDIR)" T2_PROFILE="$(MINIKUBE_PROFILE)" T2_CONTEXT="$(MINIKUBE_PROFILE)" \
+ T2_SKIP_LOCK="$(T2_SKIP_LOCK)" T2_LOCK_TOKEN="$(T2_LOCK_TOKEN)" \
+ bash scripts/minikube/with-t2-mutation-lock.sh -- \
+ $(MAKE) --no-print-directory minikube-build-image-capabilities-fixture-body
+
+minikube-build-image-capabilities-fixture-body:
+ @bash scripts/minikube/require-t2-mutation-lock.sh
+ @MINIKUBE_PROFILE="$(MINIKUBE_PROFILE)" scripts/minikube/build-images.sh --only=mcp-host
+ @MINIKUBE_PROFILE="$(MINIKUBE_PROFILE)" scripts/minikube/build-images.sh --only=image-capabilities-mcp-host
+
+.PHONY: minikube-run-image-capabilities minikube-restore-image-capabilities
+minikube-run-image-capabilities: ## Run the visible image journey with an isolated external-provider fixture and restore the Host
+ @T2_PROJECT_DIR="$(CURDIR)" T2_PROFILE="$(MINIKUBE_PROFILE)" T2_CONTEXT="$(MINIKUBE_PROFILE)" \
+ T2_SKIP_LOCK="$(T2_SKIP_LOCK)" T2_LOCK_TOKEN="$(T2_LOCK_TOKEN)" \
+ bash scripts/minikube/with-t2-mutation-lock.sh -- node scripts/e2e/image-capabilities-fixture.mjs run
+
+minikube-restore-image-capabilities: ## Resume restoration of a recorded image fixture run (IMAGE_CAPABILITIES_RUN_DIR=<dir printed by minikube-run-image-capabilities>)
+ @test -n "$(IMAGE_CAPABILITIES_RUN_DIR)" || { echo "IMAGE_CAPABILITIES_RUN_DIR is required: the run directory printed by 'make minikube-run-image-capabilities'"; exit 1; }
+ @T2_PROJECT_DIR="$(CURDIR)" T2_PROFILE="$(MINIKUBE_PROFILE)" T2_CONTEXT="$(MINIKUBE_PROFILE)" \
+ T2_SKIP_LOCK="$(T2_SKIP_LOCK)" T2_LOCK_TOKEN="$(T2_LOCK_TOKEN)" \
+ IMAGE_CAPABILITIES_RUN_DIR="$(IMAGE_CAPABILITIES_RUN_DIR)" \
+ bash scripts/minikube/with-t2-mutation-lock.sh -- node scripts/e2e/image-capabilities-fixture.mjs restore
+
.PHONY: minikube-build-codex-approved-tools-fixtures minikube-build-codex-approved-tools-fixtures-body
minikube-build-codex-approved-tools-fixtures: ## Acquire optional Codex tools fixture images before T2 reconcile
@T2_PROJECT_DIR="$(CURDIR)" T2_PROFILE="$(MINIKUBE_PROFILE)" T2_CONTEXT="$(MINIKUBE_PROFILE)" \
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index e07f53919..b88ea1a7d 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.581",
+ "version": "0.1.584",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.581",
+ "version": "0.1.584",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 55b75e8bf..7904ea41c 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.581",
+ "version": "0.1.584",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/scripts/regenerate-models-dev-snapshot.mjs b/control-api/scripts/regenerate-models-dev-snapshot.mjs
new file mode 100644
index 000000000..00e129bab
--- /dev/null
+++ b/control-api/scripts/regenerate-models-dev-snapshot.mjs
@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Regenerates `control-api/src/data/modelsDevSnapshot.ts` from the public
+ * models.dev catalog.
+ *
+ * PREREQUISITE: `npm run build` in `control-api` first. This script imports
+ * `PROVIDER_KEY_MAP` from the BUILT module (`dist/services/modelsDevClient.js`)
+ * rather than duplicating the provider-key list, so the snapshot can never be
+ * trimmed to a set of keys the code no longer maps.
+ *
+ * cd control-api && npm run build && node scripts/regenerate-models-dev-snapshot.mjs
+ *
+ * Offline / reproducible runs read a saved payload instead of fetching. The
+ * capture time of a saved file is something only the person who saved it knows,
+ * so it must be supplied — it is never guessed from the file's mtime:
+ *
+ * node scripts/regenerate-models-dev-snapshot.mjs \
+ * --input ./api.json --captured-at 2026-09-18T16:16:10.000Z
+ *
+ * Every failure throws and exits non-zero: a snapshot regenerated from partial
+ * data is worse than no regeneration at all.
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { PROVIDER_KEY_MAP } from '../dist/services/modelsDevClient.js'
+
+const CATALOG_URL = 'https://models.dev/api.json'
+const HERE = dirname(fileURLToPath(import.meta.url))
+const OUTPUT_PATH = join(HERE, '..', 'src', 'data', 'modelsDevSnapshot.ts')
+
+/** Minimal flag parser — `--input <path>` and `--captured-at <iso>` only. */
+function parseArgs(argv) {
+ const out = {}
+ for (let i = 0; i < argv.length; i += 1) {
+ const flag = argv[i]
+ if (flag !== '--input' && flag !== '--captured-at') {
+ throw new Error(`Unknown argument: ${flag}`)
+ }
+ const value = argv[i + 1]
+ if (value === undefined || value.startsWith('--')) {
+ throw new Error(`${flag} requires a value`)
+ }
+ out[flag === '--input' ? 'input' : 'capturedAt'] = value
+ i += 1
+ }
+ if (out.capturedAt !== undefined && out.input === undefined) {
+ throw new Error('--captured-at is only meaningful with --input')
+ }
+ if (out.input !== undefined && out.capturedAt === undefined) {
+ throw new Error(
+ '--input requires --captured-at <iso>: a saved payload carries no capture time, and ' +
+ 'stamping it with the current clock would rejuvenate stale evidence'
+ )
+ }
+ if (out.capturedAt !== undefined) {
+ const parsed = new Date(out.capturedAt)
+ if (Number.isNaN(parsed.getTime())) {
+ throw new Error(`--captured-at is not a valid date: ${out.capturedAt}`)
+ }
+ out.capturedAt = parsed.toISOString()
+ }
+ return out
+}
+
+/**
+ * Reads the catalog and the instant it was captured. For a live run the stamp is
+ * taken immediately BEFORE the request, so it can never overstate the data's
+ * freshness.
+ */
+async function loadCatalog(args) {
+ if (args.input !== undefined) {
+ const payload = JSON.parse(readFileSync(args.input, 'utf8'))
+ return { payload, capturedAt: args.capturedAt }
+ }
+ const capturedAt = new Date().toISOString()
+ const response = await fetch(CATALOG_URL)
+ if (!response.ok) {
+ throw new Error(`GET ${CATALOG_URL} failed: ${response.status} ${response.statusText}`)
+ }
+ return { payload: await response.json(), capturedAt }
+}
+
+const isStringArray = value => Array.isArray(value) && value.every(v => typeof v === 'string')
+
+/**
+ * Trims one models.dev entry to the fields discovery consumes. `modalities.input`
+ * is copied VERBATIM when it is an array of strings and omitted otherwise: the
+ * tri-state classifier treats absence as `unknown` at load time, so the snapshot
+ * stays a faithful trim rather than a normalized rewrite that would bake one
+ * interpretation of malformed upstream data into the vendored file.
+ */
+function trimModel(raw) {
+ const trimmed = { id: raw.id }
+ if (typeof raw.name === 'string') trimmed.name = raw.name
+ if (typeof raw.limit?.context === 'number') trimmed.limit = { context: raw.limit.context }
+ if (isStringArray(raw.modalities?.input)) trimmed.modalities = { input: raw.modalities.input }
+ return trimmed
+}
+
+function buildSnapshot(payload) {
+ if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+ throw new Error('models.dev payload is not an object')
+ }
+ const catalog = {}
+ let models = 0
+ let withImage = 0
+ let droppedIds = 0
+ for (const key of Object.values(PROVIDER_KEY_MAP)) {
+ const provider = payload[key]
+ if (provider === null || typeof provider !== 'object' || Array.isArray(provider)) {
+ throw new Error(
+ `models.dev has no provider "${key}". PROVIDER_KEY_MAP must be corrected, not skipped: ` +
+ 'silently dropping the key would make that provider look like it has no models.'
+ )
+ }
+ const entry = {}
+ if (typeof provider.name === 'string') entry.name = provider.name
+ entry.models = {}
+ for (const raw of Object.values(provider.models ?? {})) {
+ if (raw === null || typeof raw !== 'object' || typeof raw.id !== 'string') {
+ droppedIds += 1
+ continue
+ }
+ const trimmed = trimModel(raw)
+ entry.models[raw.id] = trimmed
+ models += 1
+ if (trimmed.modalities?.input.includes('image')) withImage += 1
+ }
+ catalog[key] = entry
+ }
+ return {
+ catalog,
+ stats: { providers: Object.keys(catalog).length, models, withImage, droppedIds },
+ }
+}
+
+function render(catalog, capturedAt) {
+ return `/**
+ * VENDORED offline snapshot of the public models.dev catalog
+ * (https://models.dev/api.json, MIT-licensed). GENERATED DATA — do not edit by hand.
+ *
+ * Trimmed to only the ~22 models.dev provider keys that control-api maps to its
+ * providers, and to only the fields discovery consumes
+ * ({ id, name?, limit.context?, modalities.input? }).
+ * Used by services/modelsDevClient.ts as the offline fallback when the LIVE fetch
+ * of api.json fails, so catalog sync always has data. Regenerate with:
+ *
+ * cd control-api && npm run build && node scripts/regenerate-models-dev-snapshot.mjs
+ *
+ * Shape mirrors the normalized catalog: providerKey -> { name?, models: id -> entry }.
+ */
+import type { RawModelsDevCatalog } from '../services/modelsDevClient.js'
+
+/**
+ * When this snapshot's data was captured from the public catalog — the instant
+ * the regeneration script read api.json, NOT the time it is loaded. The script
+ * writes it; never edit it by hand.
+ *
+ * Catalog evidence must never be rejuvenated by re-reading an old file (a
+ * vendored fallback is a static offline copy, not a fresh observation).
+ */
+export const VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT = '${capturedAt}'
+
+export const VENDORED_MODELS_DEV_SNAPSHOT: RawModelsDevCatalog = ${JSON.stringify(catalog, null, 2)}
+`
+}
+
+const args = parseArgs(process.argv.slice(2))
+const { payload, capturedAt } = await loadCatalog(args)
+const { catalog, stats } = buildSnapshot(payload)
+writeFileSync(OUTPUT_PATH, render(catalog, capturedAt), 'utf8')
+execFileSync('npx', ['prettier', '--write', OUTPUT_PATH], {
+ cwd: join(HERE, '..'),
+ stdio: 'inherit',
+})
+
+console.log(
+ [
+ `providers: ${stats.providers}`,
+ `models: ${stats.models}`,
+ `accept image: ${stats.withImage}`,
+ `dropped (no string id): ${stats.droppedIds}`,
+ `bytes: ${statSync(OUTPUT_PATH).size}`,
+ `capturedAt: ${capturedAt}`,
+ ].join('\n')
+)
diff --git a/control-api/src/config.ts b/control-api/src/config.ts
index aa666df10..a953e2c73 100644
--- a/control-api/src/config.ts
+++ b/control-api/src/config.ts
@@ -112,10 +112,10 @@ type Config = {
usageRetentionIntervalMs: number
budgetReservationSweepIntervalMs: number
// LLM catalog discovery sync cron (Fase 4). Runs syncDiscoveredModels()
- // periodically. DEFAULT OFF — the operator opts in consciously so a fresh
- // plane never hammers models.dev on boot. When on, one tick every
- // llmCatalogSyncIntervalMs (default 24h), cross-replica-deduped by a session
- // advisory lock inside the cron.
+ // periodically. Code default off; the base deploy enables it
+ // (deploy/base/control-plane/configmaps.yaml). When on, one tick a few
+ // seconds after start and then one every llmCatalogSyncIntervalMs (default
+ // 24h), cross-replica-deduped by a session advisory lock inside the cron.
llmCatalogSyncCronEnabled: boolean
// Default OFF. Codex subscription management/admission stays dark until
// CONTROL_API_CODEX_SUBSCRIPTION_ENABLED=true.
@@ -130,6 +130,12 @@ type Config = {
// the grant. Override only to pin a documented registration.
grokOAuthClientId: string
llmCatalogSyncIntervalMs: number
+ // How long image-input evidence derived from models.dev stays valid, counted
+ // from the catalog CAPTURE time (not the wall clock). Past it the shared
+ // contract resolves the row to `unknown` with reason `evidence_expired` and
+ // images are refused loudly until the next sync. Default 30 days; refused at
+ // boot when it is below twice llmCatalogSyncIntervalMs and the cron is on.
+ llmCatalogImageEvidenceTtlMs: number
// §4.5 sanity guard, layer 3: absolute plausibility floor. If a LIVE run's
// TOTAL mapped model count is below this, the whole run SKIPS stale-marking
// (a flappy/truncated external catalog must not mass-stale the allowlist);
@@ -435,6 +441,10 @@ const DEFAULT_MCP_HOST_JWT_MAX_HOST_REF_LENGTH = 63 + 1 + 253
const REGISTRY_PULL_SECRET_RECONCILE_MIN_INTERVAL_MS = 10_000
// A 24h-default cron should never be dialed below a minute — refuse a hot loop.
const LLM_CATALOG_SYNC_MIN_INTERVAL_MS = 60_000
+// Image-input evidence written by a sync expires this long after the capture it
+// came from. The floor is two sync intervals: anything shorter would expire the
+// evidence before the cron could possibly renew it.
+const LLM_CATALOG_IMAGE_EVIDENCE_MIN_TTL_MS = 2 * LLM_CATALOG_SYNC_MIN_INTERVAL_MS
const WORKFLOW_MAX_WORKLOADS_PER_RECIPE_CEILING = 25
const WORKFLOW_UI_EGRESS_INTERNAL_MAX_ITEMS_CEILING = 25
const WORKFLOW_MAX_STEPS_CEILING = 100
@@ -647,6 +657,31 @@ if (memberRegistrationMode === 'hosted') {
// REGISTRY_CONNECTION_MODE a second time).
const registryConnectionMode: 'managed' | 'self-hosted' = parseRegistryConnectionMode()
+// Computed as locals because the two values are coupled: image-input evidence
+// written by a sync expires TTL after the capture it came from, so a TTL shorter
+// than the refresh cadence would expire every claim before the next tick could
+// renew it. The cross-field check below is only meaningful while the cron is the
+// thing doing the refreshing; with the cron off the operator owns the cadence
+// (documented in docs/llm-providers/README.md).
+const llmCatalogSyncIntervalMs = intervalMsFromEnv(
+ 'LLM_CATALOG_SYNC_INTERVAL_MS',
+ 24 * 60 * 60 * 1000,
+ LLM_CATALOG_SYNC_MIN_INTERVAL_MS
+)
+const llmCatalogImageEvidenceTtlMs = intervalMsFromEnv(
+ 'LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS',
+ 30 * 24 * 60 * 60 * 1000,
+ LLM_CATALOG_IMAGE_EVIDENCE_MIN_TTL_MS
+)
+if (
+ process.env.LLM_CATALOG_SYNC_CRON_ENABLED === 'true' &&
+ llmCatalogImageEvidenceTtlMs < 2 * llmCatalogSyncIntervalMs
+) {
+ throw new Error(
+ 'LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS must be at least twice LLM_CATALOG_SYNC_INTERVAL_MS when LLM_CATALOG_SYNC_CRON_ENABLED=true'
+ )
+}
+
export const config: Config = {
port: Number(process.env.CONTROL_API_PORT || 8090),
jsonBodyLimit: process.env.CONTROL_API_JSON_BODY_LIMIT || '150mb',
@@ -823,14 +858,11 @@ export const config: Config = {
// This is not a confidential client secret. Same shape as Codex above.
grokOAuthClientId:
process.env.CONTROL_API_GROK_OAUTH_CLIENT_ID || 'b1a00492-073a-47ea-816f-4c329264a828',
- // Default 24h. Validated (not merely parsed): the value goes straight into
- // setInterval and each tick opens a Postgres transaction + advisory lock. A
- // 60s floor is orders of magnitude below the default and far above a hot loop.
- llmCatalogSyncIntervalMs: intervalMsFromEnv(
- 'LLM_CATALOG_SYNC_INTERVAL_MS',
- 24 * 60 * 60 * 1000,
- LLM_CATALOG_SYNC_MIN_INTERVAL_MS
- ),
+ // Both computed above the literal (same env var, default and 60s floor as the
+ // inline form they replace): the TTL is validated against the interval, which
+ // needs both values in scope before the object is built.
+ llmCatalogSyncIntervalMs,
+ llmCatalogImageEvidenceTtlMs,
modelsDevMinPlausibleLiveTotal: positiveIntegerFromEnv(
'MODELS_DEV_MIN_PLAUSIBLE_LIVE_TOTAL',
100
diff --git a/control-api/src/data/modelsDevSnapshot.ts b/control-api/src/data/modelsDevSnapshot.ts
index c988c1751..78973e570 100644
--- a/control-api/src/data/modelsDevSnapshot.ts
+++ b/control-api/src/data/modelsDevSnapshot.ts
@@ -3,4554 +3,11996 @@
* (https://models.dev/api.json, MIT-licensed). GENERATED DATA — do not edit by hand.
*
* Trimmed to only the ~22 models.dev provider keys that control-api maps to its
- * providers, and to only the fields discovery consumes ({ id, name?, limit.context? }).
+ * providers, and to only the fields discovery consumes
+ * ({ id, name?, limit.context?, modalities.input? }).
* Used by services/modelsDevClient.ts as the offline fallback when the LIVE fetch
- * of api.json fails, so catalog sync always has data. Regenerate by re-fetching
- * api.json and re-trimming to these provider keys (see modelsDevClient.ts).
+ * of api.json fails, so catalog sync always has data. Regenerate with:
+ *
+ * cd control-api && npm run build && node scripts/regenerate-models-dev-snapshot.mjs
*
* Shape mirrors the normalized catalog: providerKey -> { name?, models: id -> entry }.
*/
import type { RawModelsDevCatalog } from '../services/modelsDevClient.js'
+/**
+ * When this snapshot's data was captured from the public catalog — the instant
+ * the regeneration script read api.json, NOT the time it is loaded. The script
+ * writes it; never edit it by hand.
+ *
+ * Catalog evidence must never be rejuvenated by re-reading an old file (a
+ * vendored fallback is a static offline copy, not a fresh observation).
+ */
+export const VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT = '2026-09-18T09:45:53.791Z'
+
export const VENDORED_MODELS_DEV_SNAPSHOT: RawModelsDevCatalog = {
openai: {
name: 'OpenAI',
models: {
- o3: { id: 'o3', name: 'o3', limit: { context: 200000 } },
- 'text-embedding-3-large': {
- id: 'text-embedding-3-large',
- name: 'text-embedding-3-large',
- limit: { context: 8191 },
- },
- 'gpt-5.2-pro': { id: 'gpt-5.2-pro', name: 'GPT-5.2 Pro', limit: { context: 400000 } },
- 'gpt-5.6': { id: 'gpt-5.6', name: 'GPT-5.6', limit: { context: 1050000 } },
- 'gpt-5': { id: 'gpt-5', name: 'GPT-5', limit: { context: 400000 } },
- 'gpt-3.5-turbo': { id: 'gpt-3.5-turbo', name: 'GPT-3.5-turbo', limit: { context: 16385 } },
- 'gpt-5-pro': { id: 'gpt-5-pro', name: 'GPT-5 Pro', limit: { context: 400000 } },
- 'gpt-4o': { id: 'gpt-4o', name: 'GPT-4o', limit: { context: 128000 } },
- 'gpt-4': { id: 'gpt-4', name: 'GPT-4', limit: { context: 8192 } },
- 'o4-mini': { id: 'o4-mini', name: 'o4-mini', limit: { context: 200000 } },
- 'o3-pro': { id: 'o3-pro', name: 'o3-pro', limit: { context: 200000 } },
- 'chatgpt-image-latest': { id: 'chatgpt-image-latest', name: 'chatgpt-image-latest' },
+ 'gpt-5-nano': {
+ id: 'gpt-5-nano',
+ name: 'GPT-5 Nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-4.1-nano': {
+ id: 'gpt-4.1-nano',
+ name: 'GPT-4.1 nano',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
'gpt-4o-2024-05-13': {
id: 'gpt-4o-2024-05-13',
name: 'GPT-4o (2024-05-13)',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5-pro': {
+ id: 'gpt-5-pro',
+ name: 'GPT-5 Pro',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'chatgpt-image-latest': {
+ id: 'chatgpt-image-latest',
+ name: 'chatgpt-image-latest',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.6-sol': {
+ id: 'gpt-5.6-sol',
+ name: 'GPT-5.6 Sol',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gpt-5.4-nano': { id: 'gpt-5.4-nano', name: 'GPT-5.4 nano', limit: { context: 400000 } },
- 'gpt-5-chat-latest': {
- id: 'gpt-5-chat-latest',
- name: 'GPT-5 Chat (latest)',
- limit: { context: 400000 },
+ 'gpt-4o-2024-08-06': {
+ id: 'gpt-4o-2024-08-06',
+ name: 'GPT-4o (2024-08-06)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-6-astra': {
+ id: 'gpt-6-astra',
+ name: 'GPT-6 Astra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5.2-pro': {
+ id: 'gpt-5.2-pro',
+ name: 'GPT-5.2 Pro',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-5.1-codex': { id: 'gpt-5.1-codex', name: 'GPT-5.1 Codex', limit: { context: 400000 } },
'gpt-5.3-codex-spark': {
id: 'gpt-5.3-codex-spark',
name: 'GPT-5.3 Codex Spark',
- limit: { context: 128000 },
- },
- 'gpt-5.1-codex-max': {
- id: 'gpt-5.1-codex-max',
- name: 'GPT-5.1 Codex Max',
- limit: { context: 400000 },
- },
- 'gpt-5.3-chat-latest': {
- id: 'gpt-5.3-chat-latest',
- name: 'GPT-5.3 Chat (latest)',
- limit: { context: 128000 },
- },
- 'gpt-4o-2024-08-06': {
- id: 'gpt-4o-2024-08-06',
- name: 'GPT-4o (2024-08-06)',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4.1-mini': {
+ id: 'gpt-4.1-mini',
+ name: 'GPT-4.1 mini',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5.4': {
+ id: 'gpt-5.4',
+ name: 'GPT-5.4',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4-turbo': {
+ id: 'gpt-4-turbo',
+ name: 'GPT-4 Turbo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.1': {
+ id: 'gpt-5.1',
+ name: 'GPT-5.1',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ o1: {
+ id: 'o1',
+ name: 'o1',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4o': {
+ id: 'gpt-4o',
+ name: 'GPT-4o',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5.6-luna': {
+ id: 'gpt-5.6-luna',
+ name: 'GPT-5.6 Luna',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5.3-codex': {
+ id: 'gpt-5.3-codex',
+ name: 'GPT-5.3 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4o-mini': {
+ id: 'gpt-4o-mini',
+ name: 'GPT-4o mini',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-image-1.5': {
+ id: 'gpt-image-1.5',
+ name: 'gpt-image-1.5',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'o1-pro': {
+ id: 'o1-pro',
+ name: 'o1-pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-4.1': {
+ id: 'gpt-4.1',
+ name: 'GPT-4.1',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'text-embedding-ada-002': {
id: 'text-embedding-ada-002',
name: 'text-embedding-ada-002',
- limit: { context: 8192 },
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-image-1': {
+ id: 'gpt-image-1',
+ name: 'gpt-image-1',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.4-nano': {
+ id: 'gpt-5.4-nano',
+ name: 'GPT-5.4 nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.5-pro': {
+ id: 'gpt-5.5-pro',
+ name: 'GPT-5.5 Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-image-1-mini': {
+ id: 'gpt-image-1-mini',
+ name: 'gpt-image-1-mini',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.4-mini': {
+ id: 'gpt-5.4-mini',
+ name: 'GPT-5.4 mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-image-2': {
+ id: 'gpt-image-2',
+ name: 'gpt-image-2',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-3.5-turbo': {
+ id: 'gpt-3.5-turbo',
+ name: 'GPT-3.5-turbo',
+ limit: {
+ context: 16385,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.6': {
+ id: 'gpt-5.6',
+ name: 'GPT-5.6',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'o3-mini': { id: 'o3-mini', name: 'o3-mini', limit: { context: 200000 } },
- 'gpt-5.2': { id: 'gpt-5.2', name: 'GPT-5.2', limit: { context: 400000 } },
- 'gpt-5.3-codex': { id: 'gpt-5.3-codex', name: 'GPT-5.3 Codex', limit: { context: 400000 } },
'text-embedding-3-small': {
id: 'text-embedding-3-small',
name: 'text-embedding-3-small',
- limit: { context: 8191 },
- },
- 'gpt-5.6-luna': { id: 'gpt-5.6-luna', name: 'GPT-5.6 Luna', limit: { context: 1050000 } },
- 'gpt-5.1-codex-mini': {
- id: 'gpt-5.1-codex-mini',
- name: 'GPT-5.1 Codex mini',
- limit: { context: 400000 },
- },
- 'gpt-realtime-2.1': {
- id: 'gpt-realtime-2.1',
- name: 'GPT-Realtime-2.1',
- limit: { context: 128000 },
+ limit: {
+ context: 8191,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5-mini': {
+ id: 'gpt-5-mini',
+ name: 'GPT-5 Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.4-pro': {
+ id: 'gpt-5.4-pro',
+ name: 'GPT-5.4 Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-5.6-terra': { id: 'gpt-5.6-terra', name: 'GPT-5.6 Terra', limit: { context: 1050000 } },
- 'gpt-5.1-chat-latest': {
- id: 'gpt-5.1-chat-latest',
- name: 'GPT-5.1 Chat',
- limit: { context: 128000 },
+ 'text-embedding-3-large': {
+ id: 'text-embedding-3-large',
+ name: 'text-embedding-3-large',
+ limit: {
+ context: 8191,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.6-terra': {
+ id: 'gpt-5.6-terra',
+ name: 'GPT-5.6 Terra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4': {
+ id: 'gpt-4',
+ name: 'GPT-4',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.2': {
+ id: 'gpt-5.2',
+ name: 'GPT-5.2',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5': {
+ id: 'gpt-5',
+ name: 'GPT-5',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'gpt-5.2-chat-latest': {
id: 'gpt-5.2-chat-latest',
name: 'GPT-5.2 Chat',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'o4-mini': {
+ id: 'o4-mini',
+ name: 'o4-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-realtime-2.1': {
+ id: 'gpt-realtime-2.1',
+ name: 'GPT-Realtime-2.1',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'audio', 'image'],
+ },
+ },
+ 'o3-mini': {
+ id: 'o3-mini',
+ name: 'o3-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ o3: {
+ id: 'o3',
+ name: 'o3',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'o3-pro': {
+ id: 'o3-pro',
+ name: 'o3-pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'o4-mini-deep-research': {
- id: 'o4-mini-deep-research',
- name: 'o4-mini-deep-research',
- limit: { context: 200000 },
+ 'gpt-5.3-chat-latest': {
+ id: 'gpt-5.3-chat-latest',
+ name: 'GPT-5.3 Chat (latest)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.5': {
+ id: 'gpt-5.5',
+ name: 'GPT-5.5',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gpt-image-1.5': { id: 'gpt-image-1.5', name: 'gpt-image-1.5' },
- 'gpt-4.1-nano': { id: 'gpt-4.1-nano', name: 'GPT-4.1 nano', limit: { context: 1047576 } },
'gpt-4o-2024-11-20': {
id: 'gpt-4o-2024-11-20',
name: 'GPT-4o (2024-11-20)',
- limit: { context: 128000 },
- },
- o1: { id: 'o1', name: 'o1', limit: { context: 200000 } },
- 'o1-pro': { id: 'o1-pro', name: 'o1-pro', limit: { context: 200000 } },
- 'gpt-5.4': { id: 'gpt-5.4', name: 'GPT-5.4', limit: { context: 1050000 } },
- 'gpt-5.4-mini': { id: 'gpt-5.4-mini', name: 'GPT-5.4 mini', limit: { context: 400000 } },
- 'gpt-4.1': { id: 'gpt-4.1', name: 'GPT-4.1', limit: { context: 1047576 } },
- 'o3-deep-research': {
- id: 'o3-deep-research',
- name: 'o3-deep-research',
- limit: { context: 200000 },
- },
- 'gpt-5-mini': { id: 'gpt-5-mini', name: 'GPT-5 Mini', limit: { context: 400000 } },
- 'gpt-image-1': { id: 'gpt-image-1', name: 'gpt-image-1' },
- 'gpt-4.1-mini': { id: 'gpt-4.1-mini', name: 'GPT-4.1 mini', limit: { context: 1047576 } },
- 'gpt-4-turbo': { id: 'gpt-4-turbo', name: 'GPT-4 Turbo', limit: { context: 128000 } },
- 'gpt-image-1-mini': { id: 'gpt-image-1-mini', name: 'gpt-image-1-mini' },
- 'gpt-5-nano': { id: 'gpt-5-nano', name: 'GPT-5 Nano', limit: { context: 400000 } },
- 'gpt-5.4-pro': { id: 'gpt-5.4-pro', name: 'GPT-5.4 Pro', limit: { context: 1050000 } },
- 'gpt-5.5-pro': { id: 'gpt-5.5-pro', name: 'GPT-5.5 Pro', limit: { context: 1050000 } },
- 'gpt-4o-mini': { id: 'gpt-4o-mini', name: 'GPT-4o mini', limit: { context: 128000 } },
- 'gpt-5.6-sol': { id: 'gpt-5.6-sol', name: 'GPT-5.6 Sol', limit: { context: 1050000 } },
- 'gpt-5-codex': { id: 'gpt-5-codex', name: 'GPT-5-Codex', limit: { context: 400000 } },
- 'gpt-5.2-codex': { id: 'gpt-5.2-codex', name: 'GPT-5.2 Codex', limit: { context: 400000 } },
- 'gpt-image-2': { id: 'gpt-image-2', name: 'gpt-image-2' },
- 'gpt-5.1': { id: 'gpt-5.1', name: 'GPT-5.1', limit: { context: 400000 } },
- 'gpt-5.5': { id: 'gpt-5.5', name: 'GPT-5.5', limit: { context: 1050000 } },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
},
},
anthropic: {
name: 'Anthropic',
models: {
+ 'claude-sonnet-4-6': {
+ id: 'claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'claude-opus-5': {
+ id: 'claude-opus-5',
+ name: 'Claude Opus 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
'claude-opus-4-5': {
id: 'claude-opus-4-5',
name: 'Claude Opus 4.5 (latest)',
- limit: { context: 200000 },
- },
- 'claude-haiku-4-5-20251001': {
- id: 'claude-haiku-4-5-20251001',
- name: 'Claude Haiku 4.5',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'claude-fable-5-1': {
+ id: 'claude-fable-5-1',
+ name: 'Claude Fable 5.1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-opus-4-1-20250805': {
- id: 'claude-opus-4-1-20250805',
- name: 'Claude Opus 4.1',
- limit: { context: 200000 },
+ 'claude-opus-4-6': {
+ id: 'claude-opus-4-6',
+ name: 'Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-4-5': {
- id: 'claude-sonnet-4-5',
- name: 'Claude Sonnet 4.5 (latest)',
- limit: { context: 1000000 },
+ 'claude-sonnet-4-5-20250929': {
+ id: 'claude-sonnet-4-5-20250929',
+ name: 'Claude Sonnet 4.5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'claude-opus-4-7': {
id: 'claude-opus-4-7',
name: 'Claude Opus 4.7',
- limit: { context: 1000000 },
- },
- 'claude-sonnet-5': {
- id: 'claude-sonnet-5',
- name: 'Claude Sonnet 5',
- limit: { context: 1000000 },
- },
- 'claude-opus-4-5-20251101': {
- id: 'claude-opus-4-5-20251101',
- name: 'Claude Opus 4.5',
- limit: { context: 200000 },
- },
- 'claude-opus-4-8': {
- id: 'claude-opus-4-8',
- name: 'Claude Opus 4.8',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-opus-4-1': {
- id: 'claude-opus-4-1',
- name: 'Claude Opus 4.1 (latest)',
- limit: { context: 200000 },
+ 'claude-haiku-4-5-20251001': {
+ id: 'claude-haiku-4-5-20251001',
+ name: 'Claude Haiku 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'claude-fable-5': {
id: 'claude-fable-5',
name: 'Claude Fable 5',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'claude-haiku-4-5': {
id: 'claude-haiku-4-5',
name: 'Claude Haiku 4.5 (latest)',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-opus-4-6': {
- id: 'claude-opus-4-6',
- name: 'Claude Opus 4.6',
- limit: { context: 1000000 },
+ 'claude-sonnet-4-5': {
+ id: 'claude-sonnet-4-5',
+ name: 'Claude Sonnet 4.5 (latest)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-4-5-20250929': {
- id: 'claude-sonnet-4-5-20250929',
- name: 'Claude Sonnet 4.5',
- limit: { context: 1000000 },
+ 'claude-opus-4-8': {
+ id: 'claude-opus-4-8',
+ name: 'Claude Opus 4.8',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-4-6': {
- id: 'claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6',
- limit: { context: 1000000 },
+ 'claude-sonnet-5': {
+ id: 'claude-sonnet-5',
+ name: 'Claude Sonnet 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'claude-opus-4-5-20251101': {
+ id: 'claude-opus-4-5-20251101',
+ name: 'Claude Opus 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
},
},
'zai-coding-plan': {
name: 'Z.AI Coding Plan',
models: {
- 'glm-4.7': { id: 'glm-4.7', name: 'GLM-4.7', limit: { context: 204800 } },
- 'glm-5.1': { id: 'glm-5.1', name: 'GLM-5.1', limit: { context: 200000 } },
- 'glm-5.2': { id: 'glm-5.2', name: 'GLM-5.2', limit: { context: 1000000 } },
- 'glm-5v-turbo': { id: 'glm-5v-turbo', name: 'GLM-5V-Turbo', limit: { context: 200000 } },
- 'glm-4.5-air': { id: 'glm-4.5-air', name: 'GLM-4.5-Air', limit: { context: 131072 } },
- 'glm-5-turbo': { id: 'glm-5-turbo', name: 'GLM-5-Turbo', limit: { context: 200000 } },
+ 'glm-5.2-highspeed': {
+ id: 'glm-5.2-highspeed',
+ name: 'GLM-5.2 Highspeed',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-4.7': {
+ id: 'glm-4.7',
+ name: 'GLM-4.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-5.2': {
+ id: 'glm-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-5.3-highspeed': {
+ id: 'glm-5.3-highspeed',
+ name: 'GLM-5.3 Highspeed',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-5.3-flash': {
+ id: 'glm-5.3-flash',
+ name: 'GLM-5.3-Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'glm-5-turbo': {
+ id: 'glm-5-turbo',
+ name: 'GLM-5-Turbo',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-5.3': {
+ id: 'glm-5.3',
+ name: 'GLM-5.3',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
},
},
alibaba: {
name: 'Alibaba',
models: {
- 'qwen3-omni-flash': {
- id: 'qwen3-omni-flash',
- name: 'Qwen3-Omni Flash',
- limit: { context: 65536 },
+ 'qwen3.7-max': {
+ id: 'qwen3.7-max',
+ name: 'Qwen3.7 Max',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen2-5-72b-instruct': {
+ id: 'qwen2-5-72b-instruct',
+ name: 'Qwen2.5 72B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-v4-flash-0731': {
+ id: 'deepseek-v4-flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen3-coder-plus': {
id: 'qwen3-coder-plus',
name: 'Qwen3 Coder Plus',
- limit: { context: 1048576 },
- },
- 'qwen-plus': { id: 'qwen-plus', name: 'Qwen Plus', limit: { context: 1000000 } },
- 'qwen3-coder-30b-a3b-instruct': {
- id: 'qwen3-coder-30b-a3b-instruct',
- name: 'Qwen3-Coder 30B-A3B Instruct',
- limit: { context: 262144 },
- },
- 'qwen3-omni-flash-realtime': {
- id: 'qwen3-omni-flash-realtime',
- name: 'Qwen3-Omni Flash Realtime',
- limit: { context: 65536 },
- },
- 'qwen3-32b': { id: 'qwen3-32b', name: 'Qwen3 32B', limit: { context: 131072 } },
- 'qwen-omni-turbo-realtime': {
- id: 'qwen-omni-turbo-realtime',
- name: 'Qwen-Omni Turbo Realtime',
- limit: { context: 32768 },
- },
- 'qwen-plus-character-ja': {
- id: 'qwen-plus-character-ja',
- name: 'Qwen Plus Character (Japanese)',
- limit: { context: 8192 },
- },
- 'qwen3-next-80b-a3b-instruct': {
- id: 'qwen3-next-80b-a3b-instruct',
- name: 'Qwen3-Next 80B-A3B Instruct',
- limit: { context: 131072 },
- },
- 'qwen3.7-plus': { id: 'qwen3.7-plus', name: 'Qwen3.7 Plus', limit: { context: 1000000 } },
- 'qwen3.6-35b-a3b': {
- id: 'qwen3.6-35b-a3b',
- name: 'Qwen3.6 35B-A3B',
- limit: { context: 262144 },
- },
- 'qwen3.7-max': { id: 'qwen3.7-max', name: 'Qwen3.7 Max', limit: { context: 1000000 } },
- 'qwen3-max': { id: 'qwen3-max', name: 'Qwen3 Max', limit: { context: 262144 } },
- 'qwen2-5-omni-7b': {
- id: 'qwen2-5-omni-7b',
- name: 'Qwen2.5-Omni 7B',
- limit: { context: 32768 },
- },
- 'qwen3-8b': { id: 'qwen3-8b', name: 'Qwen3 8B', limit: { context: 131072 } },
- 'qwen2-5-14b-instruct': {
- id: 'qwen2-5-14b-instruct',
- name: 'Qwen2.5 14B Instruct',
- limit: { context: 131072 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen3-next-80b-a3b-thinking': {
id: 'qwen3-next-80b-a3b-thinking',
name: 'Qwen3-Next 80B-A3B (Thinking)',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qvq-max': { id: 'qvq-max', name: 'QVQ Max', limit: { context: 131072 } },
- 'qwen3.6-flash': { id: 'qwen3.6-flash', name: 'Qwen3.6 Flash', limit: { context: 1000000 } },
- 'qwen2-5-vl-72b-instruct': {
- id: 'qwen2-5-vl-72b-instruct',
- name: 'Qwen2.5-VL 72B Instruct',
- limit: { context: 131072 },
- },
- 'qwen3-vl-plus': { id: 'qwen3-vl-plus', name: 'Qwen3-VL Plus', limit: { context: 262144 } },
- 'qwen-vl-ocr': { id: 'qwen-vl-ocr', name: 'Qwen-VL OCR', limit: { context: 34096 } },
- 'qwen-mt-turbo': { id: 'qwen-mt-turbo', name: 'Qwen-MT Turbo', limit: { context: 16384 } },
- 'qwen-mt-plus': { id: 'qwen-mt-plus', name: 'Qwen-MT Plus', limit: { context: 16384 } },
- 'qwen3.5-plus': { id: 'qwen3.5-plus', name: 'Qwen3.5 Plus', limit: { context: 1000000 } },
- 'qwen-omni-turbo': {
- id: 'qwen-omni-turbo',
- name: 'Qwen-Omni Turbo',
- limit: { context: 32768 },
+ 'qwen2-5-omni-7b': {
+ id: 'qwen2-5-omni-7b',
+ name: 'Qwen2.5-Omni 7B',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
+ },
+ 'qwen-mt-turbo': {
+ id: 'qwen-mt-turbo',
+ name: 'Qwen-MT Turbo',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen-vl-max': {
+ id: 'qwen-vl-max',
+ name: 'Qwen-VL Max',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen2-5-72b-instruct': {
- id: 'qwen2-5-72b-instruct',
- name: 'Qwen2.5 72B Instruct',
- limit: { context: 131072 },
+ 'qwen3-next-80b-a3b-instruct': {
+ id: 'qwen3-next-80b-a3b-instruct',
+ name: 'Qwen3-Next 80B-A3B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen-flash': { id: 'qwen-flash', name: 'Qwen Flash', limit: { context: 1000000 } },
- 'qwen3-vl-235b-a22b': {
- id: 'qwen3-vl-235b-a22b',
- name: 'Qwen3-VL 235B-A22B',
- limit: { context: 131072 },
+ 'qwen3-coder-flash': {
+ id: 'qwen3-coder-flash',
+ name: 'Qwen3 Coder Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3-14b': {
+ id: 'qwen3-14b',
+ name: 'Qwen3 14B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen-max': {
+ id: 'qwen-max',
+ name: 'Qwen Max',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3.6-plus': {
+ id: 'qwen3.6-plus',
+ name: 'Qwen3.6 Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen-vl-plus': {
+ id: 'qwen-vl-plus',
+ name: 'Qwen-VL Plus',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen3-vl-30b-a3b': {
- id: 'qwen3-vl-30b-a3b',
- name: 'Qwen3-VL 30B-A3B',
- limit: { context: 131072 },
+ 'qwen-omni-turbo-realtime': {
+ id: 'qwen-omni-turbo-realtime',
+ name: 'Qwen-Omni Turbo Realtime',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'qwen3.5-27b': {
+ id: 'qwen3.5-27b',
+ name: 'Qwen3.5 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
},
- 'qwen-vl-max': { id: 'qwen-vl-max', name: 'Qwen-VL Max', limit: { context: 131072 } },
- 'qwen3.5-27b': { id: 'qwen3.5-27b', name: 'Qwen3.5 27B', limit: { context: 262144 } },
- 'qwen-max': { id: 'qwen-max', name: 'Qwen Max', limit: { context: 32768 } },
- 'qwen3-235b-a22b': {
- id: 'qwen3-235b-a22b',
- name: 'Qwen3 235B-A22B',
- limit: { context: 131072 },
+ 'qwen3.5-35b-a3b': {
+ id: 'qwen3.5-35b-a3b',
+ name: 'Qwen3.5 35B-A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'qwen-flash': {
+ id: 'qwen-flash',
+ name: 'Qwen Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'glm-5.2': {
+ id: 'glm-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen-turbo': {
+ id: 'qwen-turbo',
+ name: 'Qwen Turbo',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen3-livetranslate-flash-realtime': {
id: 'qwen3-livetranslate-flash-realtime',
name: 'Qwen3-LiveTranslate Flash Realtime',
- limit: { context: 53248 },
+ limit: {
+ context: 53248,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
},
- 'qwen3.6-27b': { id: 'qwen3.6-27b', name: 'Qwen3.6 27B', limit: { context: 262144 } },
- 'qwen3.5-35b-a3b': {
- id: 'qwen3.5-35b-a3b',
- name: 'Qwen3.5 35B-A3B',
- limit: { context: 262144 },
+ 'qwen3-vl-30b-a3b': {
+ id: 'qwen3-vl-30b-a3b',
+ name: 'Qwen3-VL 30B-A3B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen-vl-ocr': {
+ id: 'qwen-vl-ocr',
+ name: 'Qwen-VL OCR',
+ limit: {
+ context: 34096,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen3-32b': {
+ id: 'qwen3-32b',
+ name: 'Qwen3 32B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwq-plus': {
+ id: 'qwq-plus',
+ name: 'QwQ Plus',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3-vl-plus': {
+ id: 'qwen3-vl-plus',
+ name: 'Qwen3-VL Plus',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen3-coder-480b-a35b-instruct': {
- id: 'qwen3-coder-480b-a35b-instruct',
- name: 'Qwen3-Coder 480B-A35B Instruct',
- limit: { context: 262144 },
+ 'qwen2-5-7b-instruct': {
+ id: 'qwen2-5-7b-instruct',
+ name: 'Qwen2.5 7B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwq-plus': { id: 'qwq-plus', name: 'QwQ Plus', limit: { context: 131072 } },
- 'qwen2-5-32b-instruct': {
- id: 'qwen2-5-32b-instruct',
- name: 'Qwen2.5 32B Instruct',
- limit: { context: 131072 },
+ 'qwen3-coder-30b-a3b-instruct': {
+ id: 'qwen3-coder-30b-a3b-instruct',
+ name: 'Qwen3-Coder 30B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen3.5-397b-a17b': {
id: 'qwen3.5-397b-a17b',
name: 'Qwen3.5 397B-A17B',
- limit: { context: 262144 },
- },
- 'qwen3-coder-flash': {
- id: 'qwen3-coder-flash',
- name: 'Qwen3 Coder Flash',
- limit: { context: 1000000 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'qwen3.6-27b': {
+ id: 'qwen3.6-27b',
+ name: 'Qwen3.6 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
},
- 'qwen3-14b': { id: 'qwen3-14b', name: 'Qwen3 14B', limit: { context: 131072 } },
'qwen3-asr-flash': {
id: 'qwen3-asr-flash',
name: 'Qwen3-ASR Flash',
- limit: { context: 53248 },
+ limit: {
+ context: 53248,
+ },
+ modalities: {
+ input: ['audio'],
+ },
},
- 'qwen-turbo': { id: 'qwen-turbo', name: 'Qwen Turbo', limit: { context: 1000000 } },
- 'qwen2-5-7b-instruct': {
- id: 'qwen2-5-7b-instruct',
- name: 'Qwen2.5 7B Instruct',
- limit: { context: 131072 },
+ 'qwen3-omni-flash': {
+ id: 'qwen3-omni-flash',
+ name: 'Qwen3-Omni Flash',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
+ },
+ 'kimi-k3': {
+ id: 'kimi-k3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen2-5-vl-72b-instruct': {
+ id: 'qwen2-5-vl-72b-instruct',
+ name: 'Qwen2.5-VL 72B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen3.6-35b-a3b': {
+ id: 'qwen3.6-35b-a3b',
+ name: 'Qwen3.6 35B-A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'qwen3-max': {
+ id: 'qwen3-max',
+ name: 'Qwen3 Max',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen-plus': {
+ id: 'qwen-plus',
+ name: 'Qwen Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3.5-122b-a10b': {
+ id: 'qwen3.5-122b-a10b',
+ name: 'Qwen3.5 122B-A10B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'qwen3-omni-flash-realtime': {
+ id: 'qwen3-omni-flash-realtime',
+ name: 'Qwen3-Omni Flash Realtime',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
},
'qwen2-5-vl-7b-instruct': {
id: 'qwen2-5-vl-7b-instruct',
name: 'Qwen2.5-VL 7B Instruct',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen3.6-flash': {
+ id: 'qwen3.6-flash',
+ name: 'Qwen3.6 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen3.8-flash': {
+ id: 'qwen3.8-flash',
+ name: 'Qwen3.8 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen2-5-14b-instruct': {
+ id: 'qwen2-5-14b-instruct',
+ name: 'Qwen2.5 14B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen3.6-max-preview': {
id: 'qwen3.6-max-preview',
name: 'Qwen3.6 Max Preview',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen3.5-122b-a10b': {
- id: 'qwen3.5-122b-a10b',
- name: 'Qwen3.5 122B-A10B',
- limit: { context: 262144 },
+ 'qwen-plus-character-ja': {
+ id: 'qwen-plus-character-ja',
+ name: 'Qwen Plus Character (Japanese)',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3.8-max': {
+ id: 'qwen3.8-max',
+ name: 'Qwen3.8 Max',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'qwen3-8b': {
+ id: 'qwen3-8b',
+ name: 'Qwen3 8B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen-vl-plus': { id: 'qwen-vl-plus', name: 'Qwen-VL Plus', limit: { context: 131072 } },
- 'qwen3.6-plus': { id: 'qwen3.6-plus', name: 'Qwen3.6 Plus', limit: { context: 1000000 } },
- },
- },
+ 'qwen3-235b-a22b': {
+ id: 'qwen3-235b-a22b',
+ name: 'Qwen3 235B-A22B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3.7-plus': {
+ id: 'qwen3.7-plus',
+ name: 'Qwen3.7 Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen-omni-turbo': {
+ id: 'qwen-omni-turbo',
+ name: 'Qwen-Omni Turbo',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
+ },
+ 'qwen3-coder-480b-a35b-instruct': {
+ id: 'qwen3-coder-480b-a35b-instruct',
+ name: 'Qwen3-Coder 480B-A35B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen2-5-32b-instruct': {
+ id: 'qwen2-5-32b-instruct',
+ name: 'Qwen2.5 32B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen3-vl-235b-a22b': {
+ id: 'qwen3-vl-235b-a22b',
+ name: 'Qwen3-VL 235B-A22B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen3.5-plus': {
+ id: 'qwen3.5-plus',
+ name: 'Qwen3.5 Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen-mt-plus': {
+ id: 'qwen-mt-plus',
+ name: 'Qwen-MT Plus',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qvq-max': {
+ id: 'qvq-max',
+ name: 'QVQ Max',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ },
+ },
'google-vertex': {
name: 'Vertex',
models: {
+ 'gemini-2.5-flash-tts': {
+ id: 'gemini-2.5-flash-tts',
+ name: 'Gemini 2.5 Flash TTS',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gemini-3.1-pro-preview-customtools': {
+ id: 'gemini-3.1-pro-preview-customtools',
+ name: 'Gemini 3.1 Pro Preview Custom Tools',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
'gemini-2.5-pro-tts': {
id: 'gemini-2.5-pro-tts',
name: 'Gemini 2.5 Pro TTS',
- limit: { context: 32768 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'claude-haiku-4-5@20251001': {
- id: 'claude-haiku-4-5@20251001',
- name: 'Claude Haiku 4.5',
- limit: { context: 200000 },
+ 'claude-sonnet-4@20250514': {
+ id: 'claude-sonnet-4@20250514',
+ name: 'Claude Sonnet 4',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gemini-2.5-flash-image': {
+ id: 'gemini-2.5-flash-image',
+ name: 'Nano Banana',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'claude-opus-4-5@20251101': {
+ id: 'claude-opus-4-5@20251101',
+ name: 'Claude Opus 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gemini-3-pro-image': {
+ id: 'gemini-3-pro-image',
+ name: 'Nano Banana Pro',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-3.1-pro-preview': {
+ id: 'gemini-3.1-pro-preview',
+ name: 'Gemini 3.1 Pro Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-2.5-flash-lite': {
+ id: 'gemini-2.5-flash-lite',
+ name: 'Gemini 2.5 Flash-Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
+ },
+ 'claude-sonnet-4-6@default': {
+ id: 'claude-sonnet-4-6@default',
+ name: 'Claude Sonnet 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gemini-3.6-flash': {
+ id: 'gemini-3.6-flash',
+ name: 'Gemini 3.6 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'claude-fable-5@default': {
+ id: 'claude-fable-5@default',
+ name: 'Claude Fable 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'gemini-3.1-flash-lite': {
id: 'gemini-3.1-flash-lite',
name: 'Gemini 3.1 Flash Lite',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'gemini-3.1-flash-image': {
- id: 'gemini-3.1-flash-image',
- name: 'Nano Banana 2',
- limit: { context: 131072 },
+ 'claude-opus-4-6@default': {
+ id: 'claude-opus-4-6@default',
+ name: 'Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gemini-2.5-pro': {
- id: 'gemini-2.5-pro',
- name: 'Gemini 2.5 Pro',
- limit: { context: 1048576 },
+ 'claude-opus-4@20250514': {
+ id: 'claude-opus-4@20250514',
+ name: 'Claude Opus 4',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gemini-2.5-flash-tts': {
- id: 'gemini-2.5-flash-tts',
- name: 'Gemini 2.5 Flash TTS',
- limit: { context: 32768 },
+ 'claude-haiku-4-5@20251001': {
+ id: 'claude-haiku-4-5@20251001',
+ name: 'Claude Haiku 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gemini-2.5-flash': {
- id: 'gemini-2.5-flash',
- name: 'Gemini 2.5 Flash',
- limit: { context: 1048576 },
+ 'claude-sonnet-5@default': {
+ id: 'claude-sonnet-5@default',
+ name: 'Claude Sonnet 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'gemini-3.5-flash': {
id: 'gemini-3.5-flash',
name: 'Gemini 3.5 Flash',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'claude-opus-4@20250514': {
- id: 'claude-opus-4@20250514',
- name: 'Claude Opus 4',
- limit: { context: 200000 },
+ 'gemini-3.1-flash-lite-preview': {
+ id: 'gemini-3.1-flash-lite-preview',
+ name: 'Gemini 3.1 Flash Lite Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
'claude-opus-4-1@20250805': {
id: 'claude-opus-4-1@20250805',
name: 'Claude Opus 4.1',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'gemini-embedding-001': {
id: 'gemini-embedding-001',
name: 'Gemini Embedding 001',
- limit: { context: 2048 },
- },
- 'claude-opus-4-5@20251101': {
- id: 'claude-opus-4-5@20251101',
- name: 'Claude Opus 4.5',
- limit: { context: 200000 },
+ limit: {
+ context: 2048,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'claude-3-5-haiku@20241022': {
- id: 'claude-3-5-haiku@20241022',
- name: 'Claude Haiku 3.5',
- limit: { context: 200000 },
- },
- 'gemini-3.1-pro-preview-customtools': {
- id: 'gemini-3.1-pro-preview-customtools',
- name: 'Gemini 3.1 Pro Preview Custom Tools',
- limit: { context: 1048576 },
- },
- 'gemini-flash-lite-latest': {
- id: 'gemini-flash-lite-latest',
- name: 'Gemini Flash-Lite Latest',
- limit: { context: 1048576 },
- },
- 'gemini-2.5-flash-image': {
- id: 'gemini-2.5-flash-image',
- name: 'Nano Banana',
- limit: { context: 32768 },
- },
- 'claude-sonnet-4@20250514': {
- id: 'claude-sonnet-4@20250514',
- name: 'Claude Sonnet 4',
- limit: { context: 200000 },
- },
- 'gemini-2.5-flash-lite': {
- id: 'gemini-2.5-flash-lite',
- name: 'Gemini 2.5 Flash-Lite',
- limit: { context: 1048576 },
+ 'gemini-3.1-flash-image': {
+ id: 'gemini-3.1-flash-image',
+ name: 'Nano Banana 2',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'gemini-3.5-flash-lite': {
+ id: 'gemini-3.5-flash-lite',
+ name: 'Gemini 3.5 Flash Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'claude-fable-5-1@default': {
+ id: 'claude-fable-5-1@default',
+ name: 'Claude Fable 5.1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'claude-opus-4-7@default': {
id: 'claude-opus-4-7@default',
name: 'Claude Opus 4.7',
- limit: { context: 1000000 },
- },
- 'gemini-3.1-pro-preview': {
- id: 'gemini-3.1-pro-preview',
- name: 'Gemini 3.1 Pro Preview',
- limit: { context: 1048576 },
- },
- 'claude-sonnet-4-5@20250929': {
- id: 'claude-sonnet-4-5@20250929',
- name: 'Claude Sonnet 4.5',
- limit: { context: 200000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-5@default': {
- id: 'claude-sonnet-5@default',
- name: 'Claude Sonnet 5',
- limit: { context: 1000000 },
+ 'gemini-flash-lite-latest': {
+ id: 'gemini-flash-lite-latest',
+ name: 'Gemini Flash-Lite Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'claude-opus-5@default': {
+ id: 'claude-opus-5@default',
+ name: 'Claude Opus 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'gemini-3-flash-preview': {
id: 'gemini-3-flash-preview',
name: 'Gemini 3 Flash Preview',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.8-flash': {
+ id: 'gemini-3.8-flash',
+ name: 'Gemini 3.8 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.7-flash': {
+ id: 'gemini-3.7-flash',
+ name: 'Gemini 3.7 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'claude-opus-4-6@default': {
- id: 'claude-opus-4-6@default',
- name: 'Claude Opus 4.6',
- limit: { context: 1000000 },
+ 'gemini-2.5-pro': {
+ id: 'gemini-2.5-pro',
+ name: 'Gemini 2.5 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
'gemini-flash-latest': {
id: 'gemini-flash-latest',
name: 'Gemini Flash Latest',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-2.5-flash': {
+ id: 'gemini-2.5-flash',
+ name: 'Gemini 2.5 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
'claude-opus-4-8@default': {
id: 'claude-opus-4-8@default',
name: 'Claude Opus 4.8',
- limit: { context: 1000000 },
- },
- 'gemini-3-pro-image': {
- id: 'gemini-3-pro-image',
- name: 'Nano Banana Pro',
- limit: { context: 65536 },
- },
- 'claude-sonnet-4-6@default': {
- id: 'claude-sonnet-4-6@default',
- name: 'Claude Sonnet 4.6',
- limit: { context: 1000000 },
- },
- 'gemini-3.1-flash-lite-preview': {
- id: 'gemini-3.1-flash-lite-preview',
- name: 'Gemini 3.1 Flash Lite Preview',
- limit: { context: 1048576 },
- },
- 'moonshotai/kimi-k2-thinking-maas': {
- id: 'moonshotai/kimi-k2-thinking-maas',
- name: 'Kimi K2 Thinking',
- limit: { context: 262144 },
- },
- 'openai/gpt-oss-120b-maas': {
- id: 'openai/gpt-oss-120b-maas',
- name: 'GPT OSS 120B',
- limit: { context: 131072 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai/gpt-oss-20b-maas': {
- id: 'openai/gpt-oss-20b-maas',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
+ 'claude-sonnet-4-5@20250929': {
+ id: 'claude-sonnet-4-5@20250929',
+ name: 'Claude Sonnet 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'zai-org/glm-4.7-maas': {
- id: 'zai-org/glm-4.7-maas',
- name: 'GLM-4.7',
- limit: { context: 200000 },
+ 'qwen/qwen3-235b-a22b-instruct-2507-maas': {
+ id: 'qwen/qwen3-235b-a22b-instruct-2507-maas',
+ name: 'Qwen3 235B A22B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai-org/glm-5-maas': { id: 'zai-org/glm-5-maas', name: 'GLM-5', limit: { context: 202752 } },
'deepseek-ai/deepseek-v3.1-maas': {
id: 'deepseek-ai/deepseek-v3.1-maas',
name: 'DeepSeek V3.1',
- limit: { context: 163840 },
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
'deepseek-ai/deepseek-v3.2-maas': {
id: 'deepseek-ai/deepseek-v3.2-maas',
name: 'DeepSeek V3.2',
- limit: { context: 163840 },
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
+ },
+ 'zai-org/glm-5.2-maas': {
+ id: 'zai-org/glm-5.2-maas',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/glm-5-maas': {
+ id: 'zai-org/glm-5-maas',
+ name: 'GLM-5',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-235b-a22b-instruct-2507-maas': {
- id: 'qwen/qwen3-235b-a22b-instruct-2507-maas',
- name: 'Qwen3 235B A22B Instruct',
- limit: { context: 262144 },
+ 'zai-org/glm-4.7-maas': {
+ id: 'zai-org/glm-4.7-maas',
+ name: 'GLM-4.7',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
+ },
+ 'meta/llama-4-maverick-17b-128e-instruct-maas': {
+ id: 'meta/llama-4-maverick-17b-128e-instruct-maas',
+ name: 'Llama 4 Maverick 17B 128E Instruct',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'meta/llama-3.3-70b-instruct-maas': {
id: 'meta/llama-3.3-70b-instruct-maas',
name: 'Llama 3.3 70B Instruct',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta/llama-4-maverick-17b-128e-instruct-maas': {
- id: 'meta/llama-4-maverick-17b-128e-instruct-maas',
- name: 'Llama 4 Maverick 17B 128E Instruct',
- limit: { context: 524288 },
+ 'openai/gpt-oss-120b-maas': {
+ id: 'openai/gpt-oss-120b-maas',
+ name: 'GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-oss-20b-maas': {
+ id: 'openai/gpt-oss-20b-maas',
+ name: 'GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k2-thinking-maas': {
+ id: 'moonshotai/kimi-k2-thinking-maas',
+ name: 'Kimi K2 Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'xai/grok-4.20-reasoning': {
+ id: 'xai/grok-4.20-reasoning',
+ name: 'Grok 4.20 (Reasoning)',
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'xai/grok-4.3': {
+ id: 'xai/grok-4.3',
+ name: 'Grok 4.3',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'xai/grok-4.20-non-reasoning': {
+ id: 'xai/grok-4.20-non-reasoning',
+ name: 'Grok 4.20 (Non-Reasoning)',
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'xai/grok-4.1-fast-non-reasoning': {
+ id: 'xai/grok-4.1-fast-non-reasoning',
+ name: 'Grok 4.1 Fast',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'xai/grok-4.1-fast-reasoning': {
+ id: 'xai/grok-4.1-fast-reasoning',
+ name: 'Grok 4.1 Fast (Reasoning)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'xai/grok-4.6': {
+ id: 'xai/grok-4.6',
+ name: 'Grok 4.6',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
},
},
'amazon-bedrock': {
name: 'Amazon Bedrock',
models: {
+ 'moonshotai.kimi-k2.5': {
+ id: 'moonshotai.kimi-k2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262143,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
'global.anthropic.claude-haiku-4-5-20251001-v1:0': {
id: 'global.anthropic.claude-haiku-4-5-20251001-v1:0',
name: 'Claude Haiku 4.5 (Global)',
- limit: { context: 200000 },
- },
- 'global.anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5 (Global)',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.anthropic.claude-opus-5': {
+ id: 'us.anthropic.claude-opus-5',
+ name: 'Claude Opus 5 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'eu.amazon.nova-pro-v1:0': {
+ id: 'eu.amazon.nova-pro-v1:0',
+ name: 'Nova Pro (EU)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'us.writer.palmyra-x4-v1:0': {
+ id: 'us.writer.palmyra-x4-v1:0',
+ name: 'Palmyra X4 (US)',
+ limit: {
+ context: 122880,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'jp.anthropic.claude-haiku-4-5-20251001-v1:0': {
- id: 'jp.anthropic.claude-haiku-4-5-20251001-v1:0',
- name: 'Claude Haiku 4.5 (JP)',
- limit: { context: 200000 },
+ 'us.anthropic.claude-opus-4-6-v1': {
+ id: 'us.anthropic.claude-opus-4-6-v1',
+ name: 'Claude Opus 4.6 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'google.gemma-4-31b': {
+ id: 'google.gemma-4-31b',
+ name: 'Gemma 4 31B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'us.xai.grok-4.6': {
+ id: 'us.xai.grok-4.6',
+ name: 'Grok 4.6 (US)',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'eu.mistral.pixtral-large-2502-v1:0': {
+ id: 'eu.mistral.pixtral-large-2502-v1:0',
+ name: 'Pixtral Large (25.02) (EU)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'us.meta.llama4-scout-17b-instruct-v1:0': {
- id: 'us.meta.llama4-scout-17b-instruct-v1:0',
- name: 'Llama 4 Scout 17B Instruct (US)',
- limit: { context: 3500000 },
+ 'qwen.qwen3-coder-next': {
+ id: 'qwen.qwen3-coder-next',
+ name: 'Qwen3 Coder Next',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'global.openai.gpt-5.6-luna': {
+ id: 'global.openai.gpt-5.6-luna',
+ name: 'GPT-5.6 Luna (Global)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'minimax.minimax-m2': {
- id: 'minimax.minimax-m2',
- name: 'MiniMax M2',
- limit: { context: 204608 },
+ 'global.anthropic.claude-opus-4-6-v1': {
+ id: 'global.anthropic.claude-opus-4-6-v1',
+ name: 'Claude Opus 4.6 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai.gpt-5.5': {
+ id: 'openai.gpt-5.5',
+ name: 'GPT-5.5',
+ limit: {
+ context: 272000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us-gov.openai.gpt-oss-20b-1:0': {
+ id: 'us-gov.openai.gpt-oss-20b-1:0',
+ name: 'gpt-oss-20b (GovCloud)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic.claude-opus-4-7': {
- id: 'anthropic.claude-opus-4-7',
- name: 'Claude Opus 4.7',
- limit: { context: 1000000 },
+ 'qwen.qwen3-coder-30b-a3b-v1:0': {
+ id: 'qwen.qwen3-coder-30b-a3b-v1:0',
+ name: 'Qwen3-Coder 30B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'eu.anthropic.claude-sonnet-4-6': {
- id: 'eu.anthropic.claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6 (EU)',
- limit: { context: 1000000 },
+ 'global.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5 (Global)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'mistral.voxtral-small-24b-2507': {
- id: 'mistral.voxtral-small-24b-2507',
- name: 'Voxtral Small 24B 2507',
- limit: { context: 32000 },
+ 'qwen.qwen3-235b-a22b-2507-v1:0': {
+ id: 'qwen.qwen3-235b-a22b-2507-v1:0',
+ name: 'Qwen3 235B-A22B Instruct 2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'mistral.ministral-3-3b-instruct': {
id: 'mistral.ministral-3-3b-instruct',
name: 'Ministral 3 3B',
- limit: { context: 256000 },
- },
- 'openai.gpt-oss-20b': {
- id: 'openai.gpt-oss-20b',
- name: 'gpt-oss-20b',
- limit: { context: 128000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'us-gov.openai.gpt-oss-120b-1:0': {
+ id: 'us-gov.openai.gpt-oss-120b-1:0',
+ name: 'gpt-oss-120b (GovCloud)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic.claude-opus-4-6-v1': {
- id: 'anthropic.claude-opus-4-6-v1',
- name: 'Claude Opus 4.6',
- limit: { context: 1000000 },
+ 'global.anthropic.claude-sonnet-4-6': {
+ id: 'global.anthropic.claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai.gpt-5.4': {
+ id: 'openai.gpt-5.4',
+ name: 'GPT-5.4',
+ limit: {
+ context: 272000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai.gpt-oss-safeguard-20b': {
- id: 'openai.gpt-oss-safeguard-20b',
- name: 'GPT OSS Safeguard 20B',
- limit: { context: 128000 },
+ 'mistral.pixtral-large-2502-v1:0': {
+ id: 'mistral.pixtral-large-2502-v1:0',
+ name: 'Pixtral Large (25.02)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'mistral.mistral-large-3-675b-instruct': {
+ id: 'mistral.mistral-large-3-675b-instruct',
+ name: 'Mistral Large 3',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'anthropic.claude-opus-4-5-20251101-v1:0': {
id: 'anthropic.claude-opus-4-5-20251101-v1:0',
name: 'Claude Opus 4.5',
- limit: { context: 200000 },
- },
- 'global.anthropic.claude-fable-5': {
- id: 'global.anthropic.claude-fable-5',
- name: 'Claude Fable 5 (Global)',
- limit: { context: 1000000 },
- },
- 'openai.gpt-oss-120b-1:0': {
- id: 'openai.gpt-oss-120b-1:0',
- name: 'gpt-oss-120b',
- limit: { context: 128000 },
- },
- 'anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5',
- limit: { context: 200000 },
- },
- 'amazon.nova-pro-v1:0': {
- id: 'amazon.nova-pro-v1:0',
- name: 'Nova Pro',
- limit: { context: 300000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.amazon.nova-micro-v1:0': {
+ id: 'us.amazon.nova-micro-v1:0',
+ name: 'Nova Micro (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen.qwen3-coder-next': {
- id: 'qwen.qwen3-coder-next',
- name: 'Qwen3 Coder Next',
- limit: { context: 131072 },
+ 'jp.anthropic.claude-opus-4-7': {
+ id: 'jp.anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7 (JP)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'us.anthropic.claude-opus-4-7': {
- id: 'us.anthropic.claude-opus-4-7',
- name: 'Claude Opus 4.7 (US)',
- limit: { context: 1000000 },
+ 'eu.anthropic.claude-sonnet-5': {
+ id: 'eu.anthropic.claude-sonnet-5',
+ name: 'Claude Sonnet 5 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'apac.amazon.nova-micro-v1:0': {
+ id: 'apac.amazon.nova-micro-v1:0',
+ name: 'Nova Micro (APAC)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'nvidia.nemotron-nano-9b-v2': {
id: 'nvidia.nemotron-nano-9b-v2',
name: 'NVIDIA Nemotron Nano 9B v2',
- limit: { context: 128000 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen.qwen3-32b-v1:0': {
- id: 'qwen.qwen3-32b-v1:0',
- name: 'Qwen3 32B (dense)',
- limit: { context: 16384 },
+ 'au.anthropic.claude-sonnet-4-6': {
+ id: 'au.anthropic.claude-sonnet-4-6',
+ name: 'AU Anthropic Claude Sonnet 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'jp.anthropic.claude-sonnet-4-6': {
- id: 'jp.anthropic.claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6 (JP)',
- limit: { context: 1000000 },
+ 'anthropic.claude-opus-4-7': {
+ id: 'anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'deepseek.r1-v1:0': {
- id: 'deepseek.r1-v1:0',
- name: 'DeepSeek-R1',
- limit: { context: 128000 },
+ 'mistral.ministral-3-8b-instruct': {
+ id: 'mistral.ministral-3-8b-instruct',
+ name: 'Ministral 3 8B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistral.mistral-large-3-675b-instruct': {
- id: 'mistral.mistral-large-3-675b-instruct',
- name: 'Mistral Large 3',
- limit: { context: 256000 },
+ 'au.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'au.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5 (AU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.openai.gpt-5.6-sol': {
+ id: 'us.openai.gpt-5.6-sol',
+ name: 'GPT-5.6 Sol (US)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'eu.amazon.nova-lite-v1:0': {
+ id: 'eu.amazon.nova-lite-v1:0',
+ name: 'Nova Lite (EU)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'anthropic.claude-opus-5': {
+ id: 'anthropic.claude-opus-5',
+ name: 'Claude Opus 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'google.gemma-3-27b-it': {
- id: 'google.gemma-3-27b-it',
- name: 'Google Gemma 3 27B Instruct',
- limit: { context: 202752 },
+ 'eu.anthropic.claude-opus-4-6-v1': {
+ id: 'eu.anthropic.claude-opus-4-6-v1',
+ name: 'Claude Opus 4.6 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'apac.amazon.nova-pro-v1:0': {
+ id: 'apac.amazon.nova-pro-v1:0',
+ name: 'Nova Pro (APAC)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
'anthropic.claude-sonnet-4-6': {
id: 'anthropic.claude-sonnet-4-6',
name: 'Claude Sonnet 4.6',
- limit: { context: 1000000 },
- },
- 'amazon.nova-2-lite-v1:0': {
- id: 'amazon.nova-2-lite-v1:0',
- name: 'Nova 2 Lite',
- limit: { context: 128000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'apac.amazon.nova-lite-v1:0': {
+ id: 'apac.amazon.nova-lite-v1:0',
+ name: 'Nova Lite (APAC)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'openai.gpt-oss-safeguard-120b': {
- id: 'openai.gpt-oss-safeguard-120b',
- name: 'GPT OSS Safeguard 120B',
- limit: { context: 128000 },
+ 'mistral.voxtral-mini-3b-2507': {
+ id: 'mistral.voxtral-mini-3b-2507',
+ name: 'Voxtral Mini 3B 2507',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
+ },
+ 'google.gemma-4-26b-a4b': {
+ id: 'google.gemma-4-26b-a4b',
+ name: 'Gemma 4 26B A4B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'mistral.ministral-3-8b-instruct': {
- id: 'mistral.ministral-3-8b-instruct',
- name: 'Ministral 3 8B',
- limit: { context: 128000 },
+ 'nvidia.nemotron-nano-12b-v2': {
+ id: 'nvidia.nemotron-nano-12b-v2',
+ name: 'NVIDIA Nemotron Nano 12B v2 VL BF16',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'eu.anthropic.claude-opus-4-6-v1': {
- id: 'eu.anthropic.claude-opus-4-6-v1',
- name: 'Claude Opus 4.6 (EU)',
- limit: { context: 1000000 },
+ 'nvidia.nemotron-nano-3-30b': {
+ id: 'nvidia.nemotron-nano-3-30b',
+ name: 'NVIDIA Nemotron Nano 3 30B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'au.anthropic.claude-opus-4-6-v1': {
- id: 'au.anthropic.claude-opus-4-6-v1',
- name: 'AU Anthropic Claude Opus 4.6',
- limit: { context: 1000000 },
+ 'eu.anthropic.claude-opus-4-5-20251101-v1:0': {
+ id: 'eu.anthropic.claude-opus-4-5-20251101-v1:0',
+ name: 'Claude Opus 4.5 (EU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'jp.anthropic.claude-sonnet-5': {
- id: 'jp.anthropic.claude-sonnet-5',
- name: 'Claude Sonnet 5 (JP)',
- limit: { context: 1000000 },
+ 'minimax.minimax-m2.1': {
+ id: 'minimax.minimax-m2.1',
+ name: 'MiniMax-M2.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai.gpt-oss-120b': {
- id: 'openai.gpt-oss-120b',
- name: 'gpt-oss-120b',
- limit: { context: 128000 },
+ 'meta.llama3-3-70b-instruct-v1:0': {
+ id: 'meta.llama3-3-70b-instruct-v1:0',
+ name: 'Llama 3.3 70B Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'global.anthropic.claude-sonnet-5': {
- id: 'global.anthropic.claude-sonnet-5',
- name: 'Claude Sonnet 5 (Global)',
- limit: { context: 1000000 },
+ 'deepseek.v3-v1:0': {
+ id: 'deepseek.v3-v1:0',
+ name: 'DeepSeek-V3.1',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'eu.anthropic.claude-opus-5': {
+ id: 'eu.anthropic.claude-opus-5',
+ name: 'Claude Opus 5 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'global.anthropic.claude-opus-4-8': {
- id: 'global.anthropic.claude-opus-4-8',
- name: 'Claude Opus 4.8 (Global)',
- limit: { context: 1000000 },
+ 'anthropic.claude-sonnet-5': {
+ id: 'anthropic.claude-sonnet-5',
+ name: 'Claude Sonnet 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.writer.palmyra-x5-v1:0': {
+ id: 'us.writer.palmyra-x5-v1:0',
+ name: 'Palmyra X5 (US)',
+ limit: {
+ context: 1040000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'google.gemma-4-e2b': {
+ id: 'google.gemma-4-e2b',
+ name: 'Gemma 4 E2B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
},
'us.meta.llama4-maverick-17b-instruct-v1:0': {
id: 'us.meta.llama4-maverick-17b-instruct-v1:0',
name: 'Llama 4 Maverick 17B Instruct (US)',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai.gpt-5.4': { id: 'openai.gpt-5.4', name: 'GPT-5.4', limit: { context: 272000 } },
- 'anthropic.claude-sonnet-5': {
- id: 'anthropic.claude-sonnet-5',
- name: 'Claude Sonnet 5',
- limit: { context: 1000000 },
+ 'meta.llama3-1-8b-instruct-v1:0': {
+ id: 'meta.llama3-1-8b-instruct-v1:0',
+ name: 'Llama 3.1 8B Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'mistral.devstral-2-123b': {
- id: 'mistral.devstral-2-123b',
- name: 'Devstral 2 123B',
- limit: { context: 256000 },
+ 'minimax.minimax-m2': {
+ id: 'minimax.minimax-m2',
+ name: 'MiniMax-M2',
+ limit: {
+ context: 204608,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'global.anthropic.claude-opus-5': {
+ id: 'global.anthropic.claude-opus-5',
+ name: 'Claude Opus 5 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'eu.anthropic.claude-sonnet-4-20250514-v1:0': {
+ id: 'eu.anthropic.claude-sonnet-4-20250514-v1:0',
+ name: 'Claude Sonnet 4 (EU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'zai.glm-4.7': { id: 'zai.glm-4.7', name: 'GLM-4.7', limit: { context: 204800 } },
- 'anthropic.claude-fable-5': {
- id: 'anthropic.claude-fable-5',
- name: 'Claude Fable 5',
- limit: { context: 1000000 },
+ 'qwen.qwen3-32b-v1:0': {
+ id: 'qwen.qwen3-32b-v1:0',
+ name: 'Qwen3 32B',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'writer.palmyra-x4-v1:0': {
id: 'writer.palmyra-x4-v1:0',
name: 'Palmyra X4',
- limit: { context: 122880 },
+ limit: {
+ context: 122880,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'us.amazon.nova-pro-v1:0': {
+ id: 'us.amazon.nova-pro-v1:0',
+ name: 'Nova Pro (US)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'mistral.magistral-small-2509': {
- id: 'mistral.magistral-small-2509',
- name: 'Magistral Small 1.2',
- limit: { context: 128000 },
+ 'google.gemma-3-12b-it': {
+ id: 'google.gemma-3-12b-it',
+ name: 'Gemma 3 12B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen.qwen3-coder-480b-a35b-v1:0': {
- id: 'qwen.qwen3-coder-480b-a35b-v1:0',
- name: 'Qwen3 Coder 480B A35B Instruct',
- limit: { context: 131072 },
+ 'au.anthropic.claude-opus-4-8': {
+ id: 'au.anthropic.claude-opus-4-8',
+ name: 'Claude Opus 4.8 (AU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'amazon.nova-micro-v1:0': {
- id: 'amazon.nova-micro-v1:0',
- name: 'Nova Micro',
- limit: { context: 128000 },
+ 'jp.anthropic.claude-haiku-4-5-20251001-v1:0': {
+ id: 'jp.anthropic.claude-haiku-4-5-20251001-v1:0',
+ name: 'Claude Haiku 4.5 (JP)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'eu.amazon.nova-2-lite-v1:0': {
+ id: 'eu.amazon.nova-2-lite-v1:0',
+ name: 'Nova 2 Lite (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'mistral.pixtral-large-2502-v1:0': {
- id: 'mistral.pixtral-large-2502-v1:0',
- name: 'Pixtral Large (25.02)',
- limit: { context: 128000 },
+ 'eu.anthropic.claude-opus-4-8': {
+ id: 'eu.anthropic.claude-opus-4-8',
+ name: 'Claude Opus 4.8 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'jp.anthropic.claude-opus-5': {
+ id: 'jp.anthropic.claude-opus-5',
+ name: 'Claude Opus 5 (JP)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'us.anthropic.claude-opus-4-6-v1': {
- id: 'us.anthropic.claude-opus-4-6-v1',
- name: 'Claude Opus 4.6 (US)',
- limit: { context: 1000000 },
+ 'mistral.ministral-3-14b-instruct': {
+ id: 'mistral.ministral-3-14b-instruct',
+ name: 'Ministral 14B 3.0',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'jp.anthropic.claude-opus-4-7': {
- id: 'jp.anthropic.claude-opus-4-7',
- name: 'Claude Opus 4.7 (JP)',
- limit: { context: 1000000 },
+ 'openai.gpt-oss-safeguard-20b': {
+ id: 'openai.gpt-oss-safeguard-20b',
+ name: 'GPT OSS Safeguard 20B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'global.anthropic.claude-sonnet-4-20250514-v1:0': {
+ id: 'global.anthropic.claude-sonnet-4-20250514-v1:0',
+ name: 'Claude Sonnet 4 (Global)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'global.amazon.nova-2-lite-v1:0': {
+ id: 'global.amazon.nova-2-lite-v1:0',
+ name: 'Nova 2 Lite (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'eu.amazon.nova-micro-v1:0': {
+ id: 'eu.amazon.nova-micro-v1:0',
+ name: 'Nova Micro (EU)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai.gpt-5.6-luna': {
+ id: 'openai.gpt-5.6-luna',
+ name: 'GPT-5.6 Luna',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'au.anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'au.anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5 (AU)',
- limit: { context: 200000 },
+ 'anthropic.claude-opus-4-6-v1': {
+ id: 'anthropic.claude-opus-4-6-v1',
+ name: 'Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'deepseek.v3-v1:0': {
- id: 'deepseek.v3-v1:0',
- name: 'DeepSeek-V3.1',
- limit: { context: 163840 },
+ 'openai.gpt-oss-20b-1:0': {
+ id: 'openai.gpt-oss-20b-1:0',
+ name: 'gpt-oss-20b',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'us.amazon.nova-premier-v1:0': {
+ id: 'us.amazon.nova-premier-v1:0',
+ name: 'Nova Premier (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'anthropic.claude-opus-4-1-20250805-v1:0': {
- id: 'anthropic.claude-opus-4-1-20250805-v1:0',
- name: 'Claude Opus 4.1',
- limit: { context: 200000 },
+ 'qwen.qwen3-vl-235b-a22b': {
+ id: 'qwen.qwen3-vl-235b-a22b',
+ name: 'Qwen3 VL 235B A22B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'jp.anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'jp.anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5 (JP)',
- limit: { context: 200000 },
+ 'amazon.nova-2-lite-v1:0': {
+ id: 'amazon.nova-2-lite-v1:0',
+ name: 'Nova 2 Lite',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'global.xai.grok-4.6': {
+ id: 'global.xai.grok-4.6',
+ name: 'Grok 4.6 (Global)',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'google.gemma-3-4b-it': {
- id: 'google.gemma-3-4b-it',
- name: 'Gemma 3 4B IT',
- limit: { context: 128000 },
+ 'global.anthropic.claude-opus-4-5-20251101-v1:0': {
+ id: 'global.anthropic.claude-opus-4-5-20251101-v1:0',
+ name: 'Claude Opus 4.5 (Global)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'eu.anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'eu.anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5 (EU)',
- limit: { context: 200000 },
+ 'amazon.nova-lite-v1:0': {
+ id: 'amazon.nova-lite-v1:0',
+ name: 'Nova Lite',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'qwen.qwen3-vl-235b-a22b': {
- id: 'qwen.qwen3-vl-235b-a22b',
- name: 'Qwen/Qwen3-VL-235B-A22B-Instruct',
- limit: { context: 262000 },
+ 'anthropic.claude-opus-4-8': {
+ id: 'anthropic.claude-opus-4-8',
+ name: 'Claude Opus 4.8',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.amazon.nova-2-lite-v1:0': {
+ id: 'us.amazon.nova-2-lite-v1:0',
+ name: 'Nova 2 Lite (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'us.openai.gpt-5.6-terra': {
+ id: 'us.openai.gpt-5.6-terra',
+ name: 'GPT-5.6 Terra (US)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'us.meta.llama3-3-70b-instruct-v1:0': {
+ id: 'us.meta.llama3-3-70b-instruct-v1:0',
+ name: 'Llama 3.3 70B Instruct (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'us.meta.llama3-1-70b-instruct-v1:0': {
+ id: 'us.meta.llama3-1-70b-instruct-v1:0',
+ name: 'Llama 3.1 70B Instruct (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'amazon.nova-pro-v1:0': {
+ id: 'amazon.nova-pro-v1:0',
+ name: 'Nova Pro',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'us.anthropic.claude-opus-4-7': {
+ id: 'us.anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'au.anthropic.claude-opus-4-6-v1': {
+ id: 'au.anthropic.claude-opus-4-6-v1',
+ name: 'AU Anthropic Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'writer.palmyra-x5-v1:0': {
id: 'writer.palmyra-x5-v1:0',
name: 'Palmyra X5',
- limit: { context: 1040000 },
+ limit: {
+ context: 1040000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'global.openai.gpt-5.6-sol': {
+ id: 'global.openai.gpt-5.6-sol',
+ name: 'GPT-5.6 Sol (Global)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'openai.gpt-5.6-sol': {
+ id: 'openai.gpt-5.6-sol',
+ name: 'GPT-5.6 Sol',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'us.anthropic.claude-sonnet-4-6': {
- id: 'us.anthropic.claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6 (US)',
- limit: { context: 1000000 },
+ 'global.anthropic.claude-opus-4-8': {
+ id: 'global.anthropic.claude-opus-4-8',
+ name: 'Claude Opus 4.8 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'au.anthropic.claude-haiku-4-5-20251001-v1:0': {
- id: 'au.anthropic.claude-haiku-4-5-20251001-v1:0',
- name: 'Claude Haiku 4.5 (AU)',
- limit: { context: 200000 },
+ 'minimax.minimax-m2.5': {
+ id: 'minimax.minimax-m2.5',
+ name: 'MiniMax-M2.5',
+ limit: {
+ context: 196608,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta.llama3-3-70b-instruct-v1:0': {
- id: 'meta.llama3-3-70b-instruct-v1:0',
- name: 'Llama 3.3 70B Instruct',
- limit: { context: 128000 },
+ 'openai.gpt-oss-120b-1:0': {
+ id: 'openai.gpt-oss-120b-1:0',
+ name: 'gpt-oss-120b',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai.glm-5': { id: 'zai.glm-5', name: 'GLM-5', limit: { context: 202752 } },
- 'us.anthropic.claude-opus-4-8': {
- id: 'us.anthropic.claude-opus-4-8',
- name: 'Claude Opus 4.8 (US)',
- limit: { context: 1000000 },
+ 'eu.anthropic.claude-opus-4-7': {
+ id: 'eu.anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'global.anthropic.claude-opus-4-7': {
- id: 'global.anthropic.claude-opus-4-7',
- name: 'Claude Opus 4.7 (Global)',
- limit: { context: 1000000 },
- },
- 'us.anthropic.claude-fable-5': {
- id: 'us.anthropic.claude-fable-5',
- name: 'Claude Fable 5 (US)',
- limit: { context: 1000000 },
- },
- 'amazon.nova-lite-v1:0': {
- id: 'amazon.nova-lite-v1:0',
- name: 'Nova Lite',
- limit: { context: 300000 },
- },
- 'us.anthropic.claude-haiku-4-5-20251001-v1:0': {
- id: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
- name: 'Claude Haiku 4.5 (US)',
- limit: { context: 200000 },
- },
- 'xai.grok-4.3': { id: 'xai.grok-4.3', name: 'Grok 4.3', limit: { context: 1000000 } },
- 'mistral.voxtral-mini-3b-2507': {
- id: 'mistral.voxtral-mini-3b-2507',
- name: 'Voxtral Mini 3B 2507',
- limit: { context: 128000 },
+ 'us.meta.llama4-scout-17b-instruct-v1:0': {
+ id: 'us.meta.llama4-scout-17b-instruct-v1:0',
+ name: 'Llama 4 Scout 17B Instruct (US)',
+ limit: {
+ context: 10000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'us.openai.gpt-5.6-luna': {
+ id: 'us.openai.gpt-5.6-luna',
+ name: 'GPT-5.6 Luna (US)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'us.anthropic.claude-sonnet-4-20250514-v1:0': {
+ id: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+ name: 'Claude Sonnet 4 (US)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'moonshot.kimi-k2-thinking': {
id: 'moonshot.kimi-k2-thinking',
name: 'Kimi K2 Thinking',
- limit: { context: 262143 },
- },
- 'meta.llama3-1-70b-instruct-v1:0': {
- id: 'meta.llama3-1-70b-instruct-v1:0',
- name: 'Llama 3.1 70B Instruct',
- limit: { context: 128000 },
- },
- 'us.deepseek.r1-v1:0': {
- id: 'us.deepseek.r1-v1:0',
- name: 'DeepSeek-R1 (US)',
- limit: { context: 128000 },
- },
- 'global.anthropic.claude-sonnet-4-6': {
- id: 'global.anthropic.claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6 (Global)',
- limit: { context: 1000000 },
+ limit: {
+ context: 262143,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'anthropic.claude-haiku-4-5-20251001-v1:0': {
id: 'anthropic.claude-haiku-4-5-20251001-v1:0',
name: 'Claude Haiku 4.5',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'moonshotai.kimi-k2.5': {
- id: 'moonshotai.kimi-k2.5',
- name: 'Kimi K2.5',
- limit: { context: 262143 },
+ 'deepseek.r1-v1:0': {
+ id: 'deepseek.r1-v1:0',
+ name: 'DeepSeek-R1',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'au.anthropic.claude-opus-4-8': {
- id: 'au.anthropic.claude-opus-4-8',
- name: 'Claude Opus 4.8 (AU)',
- limit: { context: 1000000 },
+ 'mistral.magistral-small-2509': {
+ id: 'mistral.magistral-small-2509',
+ name: 'Magistral Small 1.2',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'nvidia.nemotron-nano-12b-v2': {
- id: 'nvidia.nemotron-nano-12b-v2',
- name: 'NVIDIA Nemotron Nano 12B v2 VL BF16',
- limit: { context: 128000 },
+ 'us.anthropic.claude-fable-5': {
+ id: 'us.anthropic.claude-fable-5',
+ name: 'Claude Fable 5 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'zai.glm-4.7-flash': {
- id: 'zai.glm-4.7-flash',
- name: 'GLM-4.7-Flash',
- limit: { context: 200000 },
+ 'eu.anthropic.claude-fable-5': {
+ id: 'eu.anthropic.claude-fable-5',
+ name: 'Claude Fable 5 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.openai.gpt-6-astra': {
+ id: 'us.openai.gpt-6-astra',
+ name: 'GPT-6 Astra (US)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'us.anthropic.claude-fable-5-1': {
+ id: 'us.anthropic.claude-fable-5-1',
+ name: 'Claude Fable 5.1 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'meta.llama4-scout-17b-instruct-v1:0': {
id: 'meta.llama4-scout-17b-instruct-v1:0',
name: 'Llama 4 Scout 17B Instruct',
- limit: { context: 3500000 },
+ limit: {
+ context: 10000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'jp.amazon.nova-2-lite-v1:0': {
+ id: 'jp.amazon.nova-2-lite-v1:0',
+ name: 'Nova 2 Lite (JP)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'au.anthropic.claude-sonnet-5': {
- id: 'au.anthropic.claude-sonnet-5',
- name: 'Claude Sonnet 5 (AU)',
- limit: { context: 1000000 },
+ 'google.gemma-3-27b-it': {
+ id: 'google.gemma-3-27b-it',
+ name: 'Gemma 3 27B IT',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen.qwen3-235b-a22b-2507-v1:0': {
- id: 'qwen.qwen3-235b-a22b-2507-v1:0',
- name: 'Qwen3 235B A22B 2507',
- limit: { context: 262144 },
+ 'amazon.nova-micro-v1:0': {
+ id: 'amazon.nova-micro-v1:0',
+ name: 'Nova Micro',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'us.mistral.pixtral-large-2502-v1:0': {
+ id: 'us.mistral.pixtral-large-2502-v1:0',
+ name: 'Pixtral Large (25.02) (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'eu.anthropic.claude-haiku-4-5-20251001-v1:0': {
- id: 'eu.anthropic.claude-haiku-4-5-20251001-v1:0',
- name: 'Claude Haiku 4.5 (EU)',
- limit: { context: 200000 },
+ 'anthropic.claude-fable-5': {
+ id: 'anthropic.claude-fable-5',
+ name: 'Claude Fable 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'xai.grok-4.6': {
+ id: 'xai.grok-4.6',
+ name: 'Grok 4.6',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai.gpt-oss-20b-1:0': {
- id: 'openai.gpt-oss-20b-1:0',
- name: 'gpt-oss-20b',
- limit: { context: 128000 },
+ 'global.anthropic.claude-fable-5': {
+ id: 'global.anthropic.claude-fable-5',
+ name: 'Claude Fable 5 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'au.anthropic.claude-haiku-4-5-20251001-v1:0': {
+ id: 'au.anthropic.claude-haiku-4-5-20251001-v1:0',
+ name: 'Claude Haiku 4.5 (AU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'eu.anthropic.claude-sonnet-4-6': {
+ id: 'eu.anthropic.claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6 (EU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'in.openai.gpt-5.6-terra': {
+ id: 'in.openai.gpt-5.6-terra',
+ name: 'GPT-5.6 Terra (India)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'jp.anthropic.claude-opus-4-8': {
id: 'jp.anthropic.claude-opus-4-8',
name: 'Claude Opus 4.8 (JP)',
- limit: { context: 1000000 },
- },
- 'anthropic.claude-opus-4-8': {
- id: 'anthropic.claude-opus-4-8',
- name: 'Claude Opus 4.8',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen.qwen3-coder-30b-a3b-v1:0': {
- id: 'qwen.qwen3-coder-30b-a3b-v1:0',
- name: 'Qwen3 Coder 30B A3B Instruct',
- limit: { context: 262144 },
+ 'eu.anthropic.claude-haiku-4-5-20251001-v1:0': {
+ id: 'eu.anthropic.claude-haiku-4-5-20251001-v1:0',
+ name: 'Claude Haiku 4.5 (EU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'qwen.qwen3-next-80b-a3b': {
id: 'qwen.qwen3-next-80b-a3b',
- name: 'Qwen/Qwen3-Next-80B-A3B-Instruct',
- limit: { context: 262000 },
- },
- 'openai.gpt-5.5': { id: 'openai.gpt-5.5', name: 'GPT-5.5', limit: { context: 272000 } },
- 'au.anthropic.claude-sonnet-4-6': {
- id: 'au.anthropic.claude-sonnet-4-6',
- name: 'AU Anthropic Claude Sonnet 4.6',
- limit: { context: 1000000 },
+ name: 'Qwen3-Next 80B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'us.anthropic.claude-sonnet-5': {
id: 'us.anthropic.claude-sonnet-5',
name: 'Claude Sonnet 5 (US)',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'us.anthropic.claude-opus-4-5-20251101-v1:0': {
- id: 'us.anthropic.claude-opus-4-5-20251101-v1:0',
- name: 'Claude Opus 4.5 (US)',
- limit: { context: 200000 },
+ 'anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.amazon.nova-lite-v1:0': {
+ id: 'us.amazon.nova-lite-v1:0',
+ name: 'Nova Lite (US)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'minimax.minimax-m2.5': {
- id: 'minimax.minimax-m2.5',
- name: 'MiniMax M2.5',
- limit: { context: 196608 },
+ 'global.anthropic.claude-opus-4-7': {
+ id: 'global.anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'eu.anthropic.claude-opus-4-8': {
- id: 'eu.anthropic.claude-opus-4-8',
- name: 'Claude Opus 4.8 (EU)',
- limit: { context: 1000000 },
+ 'qwen.qwen3-coder-480b-a35b-v1:0': {
+ id: 'qwen.qwen3-coder-480b-a35b-v1:0',
+ name: 'Qwen3-Coder 480B-A35B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai.gpt-5.6-terra': {
+ id: 'openai.gpt-5.6-terra',
+ name: 'GPT-5.6 Terra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'eu.anthropic.claude-opus-4-7': {
- id: 'eu.anthropic.claude-opus-4-7',
- name: 'Claude Opus 4.7 (EU)',
- limit: { context: 1000000 },
+ 'nvidia.nemotron-super-3-120b': {
+ id: 'nvidia.nemotron-super-3-120b',
+ name: 'NVIDIA Nemotron 3 Super 120B A12B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta.llama3-1-8b-instruct-v1:0': {
- id: 'meta.llama3-1-8b-instruct-v1:0',
- name: 'Llama 3.1 8B Instruct',
- limit: { context: 128000 },
+ 'zai.glm-4.7-flash': {
+ id: 'zai.glm-4.7-flash',
+ name: 'GLM-4.7-Flash',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'google.gemma-3-4b-it': {
+ id: 'google.gemma-3-4b-it',
+ name: 'Gemma 3 4B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'global.openai.gpt-5.6-terra': {
+ id: 'global.openai.gpt-5.6-terra',
+ name: 'GPT-5.6 Terra (Global)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai.glm-5': {
+ id: 'zai.glm-5',
+ name: 'GLM-5',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai.gpt-oss-safeguard-120b': {
+ id: 'openai.gpt-oss-safeguard-120b',
+ name: 'GPT OSS Safeguard 120B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistral.devstral-2-123b': {
+ id: 'mistral.devstral-2-123b',
+ name: 'Devstral 2 123B',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai.gpt-6-astra': {
+ id: 'openai.gpt-6-astra',
+ name: 'GPT-6 Astra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'us.anthropic.claude-opus-4-1-20250805-v1:0': {
id: 'us.anthropic.claude-opus-4-1-20250805-v1:0',
name: 'Claude Opus 4.1 (US)',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.anthropic.claude-sonnet-4-6': {
+ id: 'us.anthropic.claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'mistral.voxtral-small-24b-2507': {
+ id: 'mistral.voxtral-small-24b-2507',
+ name: 'Voxtral Small 24B 2507',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
+ },
+ 'openai.gpt-oss-20b': {
+ id: 'openai.gpt-oss-20b',
+ name: 'gpt-oss-20b',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'meta.llama4-maverick-17b-instruct-v1:0': {
id: 'meta.llama4-maverick-17b-instruct-v1:0',
name: 'Llama 4 Maverick 17B Instruct',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai.glm-4.7': {
+ id: 'zai.glm-4.7',
+ name: 'GLM-4.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'ca.amazon.nova-lite-v1:0': {
+ id: 'ca.amazon.nova-lite-v1:0',
+ name: 'Nova Lite (CA)',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'global.anthropic.claude-opus-4-5-20251101-v1:0': {
- id: 'global.anthropic.claude-opus-4-5-20251101-v1:0',
- name: 'Claude Opus 4.5 (Global)',
- limit: { context: 200000 },
+ 'us.anthropic.claude-opus-4-5-20251101-v1:0': {
+ id: 'us.anthropic.claude-opus-4-5-20251101-v1:0',
+ name: 'Claude Opus 4.5 (US)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'au.anthropic.claude-opus-4-7': {
+ id: 'au.anthropic.claude-opus-4-7',
+ name: 'Claude Opus 4.7 (AU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'nvidia.nemotron-super-3-120b': {
- id: 'nvidia.nemotron-super-3-120b',
- name: 'NVIDIA Nemotron 3 Super 120B A12B',
- limit: { context: 262144 },
+ 'jp.anthropic.claude-sonnet-4-6': {
+ id: 'jp.anthropic.claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6 (JP)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'eu.anthropic.claude-sonnet-5': {
- id: 'eu.anthropic.claude-sonnet-5',
- name: 'Claude Sonnet 5 (EU)',
- limit: { context: 1000000 },
+ 'us.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5 (US)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'nvidia.nemotron-nano-3-30b': {
- id: 'nvidia.nemotron-nano-3-30b',
- name: 'NVIDIA Nemotron Nano 3 30B',
- limit: { context: 128000 },
+ 'us.deepseek.r1-v1:0': {
+ id: 'us.deepseek.r1-v1:0',
+ name: 'DeepSeek-R1 (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'eu.anthropic.claude-opus-4-5-20251101-v1:0': {
- id: 'eu.anthropic.claude-opus-4-5-20251101-v1:0',
- name: 'Claude Opus 4.5 (EU)',
- limit: { context: 200000 },
+ 'us.anthropic.claude-opus-4-8': {
+ id: 'us.anthropic.claude-opus-4-8',
+ name: 'Claude Opus 4.8 (US)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'au.anthropic.claude-opus-5': {
+ id: 'au.anthropic.claude-opus-5',
+ name: 'Claude Opus 5 (AU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'global.anthropic.claude-opus-4-6-v1': {
- id: 'global.anthropic.claude-opus-4-6-v1',
- name: 'Claude Opus 4.6 (Global)',
- limit: { context: 1000000 },
+ 'anthropic.claude-opus-4-1-20250805-v1:0': {
+ id: 'anthropic.claude-opus-4-1-20250805-v1:0',
+ name: 'Claude Opus 4.1',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'apac.anthropic.claude-sonnet-4-20250514-v1:0': {
+ id: 'apac.anthropic.claude-sonnet-4-20250514-v1:0',
+ name: 'Claude Sonnet 4 (APAC)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'us.anthropic.claude-sonnet-4-5-20250929-v1:0': {
- id: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
- name: 'Claude Sonnet 4.5 (US)',
- limit: { context: 200000 },
+ 'jp.anthropic.claude-sonnet-5': {
+ id: 'jp.anthropic.claude-sonnet-5',
+ name: 'Claude Sonnet 5 (JP)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'google.gemma-3-12b-it': {
- id: 'google.gemma-3-12b-it',
- name: 'Google Gemma 3 12B',
- limit: { context: 131072 },
+ 'au.anthropic.claude-sonnet-5': {
+ id: 'au.anthropic.claude-sonnet-5',
+ name: 'Claude Sonnet 5 (AU)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'xai.grok-4.3': {
+ id: 'xai.grok-4.3',
+ name: 'Grok 4.3',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'minimax.minimax-m2.1': {
- id: 'minimax.minimax-m2.1',
- name: 'MiniMax M2.1',
- limit: { context: 204800 },
+ 'openai.gpt-oss-120b': {
+ id: 'openai.gpt-oss-120b',
+ name: 'gpt-oss-120b',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'eu.anthropic.claude-fable-5': {
- id: 'eu.anthropic.claude-fable-5',
- name: 'Claude Fable 5 (EU)',
- limit: { context: 1000000 },
+ 'meta.llama3-1-70b-instruct-v1:0': {
+ id: 'meta.llama3-1-70b-instruct-v1:0',
+ name: 'Llama 3.1 70B Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'global.anthropic.claude-fable-5-1': {
+ id: 'global.anthropic.claude-fable-5-1',
+ name: 'Claude Fable 5.1 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'deepseek.v3.2': { id: 'deepseek.v3.2', name: 'DeepSeek-V3.2', limit: { context: 163840 } },
- 'mistral.ministral-3-14b-instruct': {
- id: 'mistral.ministral-3-14b-instruct',
- name: 'Ministral 14B 3.0',
- limit: { context: 128000 },
+ 'us.anthropic.claude-haiku-4-5-20251001-v1:0': {
+ id: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+ name: 'Claude Haiku 4.5 (US)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic.claude-fable-5-1': {
+ id: 'anthropic.claude-fable-5-1',
+ name: 'Claude Fable 5.1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'global.anthropic.claude-sonnet-5': {
+ id: 'global.anthropic.claude-sonnet-5',
+ name: 'Claude Sonnet 5 (Global)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'us.meta.llama3-1-8b-instruct-v1:0': {
+ id: 'us.meta.llama3-1-8b-instruct-v1:0',
+ name: 'Llama 3.1 8B Instruct (US)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'jp.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'jp.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5 (JP)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'global.openai.gpt-6-astra': {
+ id: 'global.openai.gpt-6-astra',
+ name: 'GPT-6 Astra (Global)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'in.openai.gpt-5.6-luna': {
+ id: 'in.openai.gpt-5.6-luna',
+ name: 'GPT-5.6 Luna (India)',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'eu.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+ id: 'eu.anthropic.claude-sonnet-4-5-20250929-v1:0',
+ name: 'Claude Sonnet 4.5 (EU)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'deepseek.v3.2': {
+ id: 'deepseek.v3.2',
+ name: 'DeepSeek V3.2',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
},
},
openrouter: {
name: 'OpenRouter',
models: {
- 'inclusionai/ling-2.6-1t': {
- id: 'inclusionai/ling-2.6-1t',
- name: 'Ling-2.6-1T',
- limit: { context: 262144 },
+ 'qwen/qwen3.7-max': {
+ id: 'qwen/qwen3.7-max',
+ name: 'Qwen3.7 Max',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'inclusionai/ring-2.6-1t': {
- id: 'inclusionai/ring-2.6-1t',
- name: 'Ring-2.6-1T',
- limit: { context: 262144 },
+ 'qwen/qwen3-coder-plus': {
+ id: 'qwen/qwen3-coder-plus',
+ name: 'Qwen3 Coder Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'inclusionai/ling-2.6-flash': {
- id: 'inclusionai/ling-2.6-flash',
- name: 'Ling-2.6-flash',
- limit: { context: 262144 },
+ 'qwen/qwen3-next-80b-a3b-thinking': {
+ id: 'qwen/qwen3-next-80b-a3b-thinking',
+ name: 'Qwen3-Next 80B-A3B (Thinking)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'ibm-granite/granite-4.0-h-micro': {
- id: 'ibm-granite/granite-4.0-h-micro',
- name: 'Granite 4.0 Micro',
- limit: { context: 131000 },
+ 'qwen/qwen3-235b-a22b-thinking-2507': {
+ id: 'qwen/qwen3-235b-a22b-thinking-2507',
+ name: 'Qwen3 235B A22B Thinking 2507',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3.5-9b': {
+ id: 'qwen/qwen3.5-9b',
+ name: 'Qwen3.5 9B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'ibm-granite/granite-4.1-8b': {
- id: 'ibm-granite/granite-4.1-8b',
- name: 'Granite 4.1 8B',
- limit: { context: 131072 },
+ 'qwen/qwen3-next-80b-a3b-instruct': {
+ id: 'qwen/qwen3-next-80b-a3b-instruct',
+ name: 'Qwen3-Next 80B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta-llama/llama-3.1-8b-instruct': {
- id: 'meta-llama/llama-3.1-8b-instruct',
- name: 'Llama 3.1 8B Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.1-70b-instruct': {
- id: 'meta-llama/llama-3.1-70b-instruct',
- name: 'Llama 3.1 70B Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.2-1b-instruct': {
- id: 'meta-llama/llama-3.2-1b-instruct',
- name: 'Llama 3.2 1B Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-4-maverick': {
- id: 'meta-llama/llama-4-maverick',
- name: 'Llama 4 Maverick',
- limit: { context: 1048576 },
- },
- 'meta-llama/llama-3.2-11b-vision-instruct': {
- id: 'meta-llama/llama-3.2-11b-vision-instruct',
- name: 'Llama 3.2 11B Vision Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.3-70b-instruct:free': {
- id: 'meta-llama/llama-3.3-70b-instruct:free',
- name: 'Llama 3.3 70B Instruct (free)',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.3-70b-instruct': {
- id: 'meta-llama/llama-3.3-70b-instruct',
- name: 'Llama-3.3-70B-Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.2-3b-instruct:free': {
- id: 'meta-llama/llama-3.2-3b-instruct:free',
- name: 'Llama 3.2 3B Instruct (free)',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-guard-4-12b': {
- id: 'meta-llama/llama-guard-4-12b',
- name: 'Llama Guard 4 12B',
- limit: { context: 163840 },
- },
- 'meta-llama/llama-4-scout': {
- id: 'meta-llama/llama-4-scout',
- name: 'Llama 4 Scout',
- limit: { context: 10000000 },
- },
- 'meta-llama/llama-3.2-3b-instruct': {
- id: 'meta-llama/llama-3.2-3b-instruct',
- name: 'Llama 3.2 3B Instruct',
- limit: { context: 131072 },
- },
- '~anthropic/claude-haiku-latest': {
- id: '~anthropic/claude-haiku-latest',
- name: 'Anthropic Claude Haiku Latest',
- limit: { context: 200000 },
- },
- '~anthropic/claude-fable-latest': {
- id: '~anthropic/claude-fable-latest',
- name: 'Claude Fable Latest',
- limit: { context: 1000000 },
- },
- '~anthropic/claude-sonnet-latest': {
- id: '~anthropic/claude-sonnet-latest',
- name: 'Anthropic Claude Sonnet Latest',
- limit: { context: 1000000 },
- },
- '~anthropic/claude-opus-latest': {
- id: '~anthropic/claude-opus-latest',
- name: 'Claude Opus Latest',
- limit: { context: 1000000 },
- },
- 'moonshotai/kimi-k2': {
- id: 'moonshotai/kimi-k2',
- name: 'Kimi K2 0711',
- limit: { context: 131072 },
- },
- 'moonshotai/kimi-k2.7-code': {
- id: 'moonshotai/kimi-k2.7-code',
- name: 'Kimi K2.7 Code',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2-thinking': {
- id: 'moonshotai/kimi-k2-thinking',
- name: 'Kimi K2 Thinking',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2.5': {
- id: 'moonshotai/kimi-k2.5',
- name: 'Kimi K2.5',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2.6': {
- id: 'moonshotai/kimi-k2.6',
- name: 'Kimi K2.6',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2-0905': {
- id: 'moonshotai/kimi-k2-0905',
- name: 'Kimi K2 0905',
- limit: { context: 262144 },
- },
- 'baidu/ernie-4.5-vl-424b-a47b': {
- id: 'baidu/ernie-4.5-vl-424b-a47b',
- name: 'ERNIE 4.5 VL 424B A47B ',
- limit: { context: 131072 },
- },
- 'perceptron/perceptron-mk1': {
- id: 'perceptron/perceptron-mk1',
- name: 'Perceptron Mk1',
- limit: { context: 32768 },
- },
- 'google/gemini-3.1-flash-lite': {
- id: 'google/gemini-3.1-flash-lite',
- name: 'Gemini 3.1 Flash Lite',
- limit: { context: 1048576 },
- },
- 'google/gemini-3.1-flash-image': {
- id: 'google/gemini-3.1-flash-image',
- name: 'Nano Banana 2',
- limit: { context: 131072 },
- },
- 'google/gemma-3n-e4b-it': {
- id: 'google/gemma-3n-e4b-it',
- name: 'Gemma 3n 4B',
- limit: { context: 32768 },
- },
- 'google/gemma-4-26b-a4b-it:free': {
- id: 'google/gemma-4-26b-a4b-it:free',
- name: 'Gemma 4 26B A4B (free)',
- limit: { context: 262144 },
- },
- 'google/gemini-2.5-pro': {
- id: 'google/gemini-2.5-pro',
- name: 'Gemini 2.5 Pro',
- limit: { context: 1048576 },
- },
- 'google/gemini-2.5-flash': {
- id: 'google/gemini-2.5-flash',
- name: 'Gemini 2.5 Flash',
- limit: { context: 1048576 },
- },
- 'google/gemini-3.5-flash': {
- id: 'google/gemini-3.5-flash',
- name: 'Gemini 3.5 Flash',
- limit: { context: 1048576 },
- },
- 'google/gemma-4-31b-it': {
- id: 'google/gemma-4-31b-it',
- name: 'Gemma 4 31B IT',
- limit: { context: 262144 },
- },
- 'google/lyria-3-clip-preview': {
- id: 'google/lyria-3-clip-preview',
- name: 'Lyria 3 Clip Preview',
- limit: { context: 1048576 },
- },
- 'google/gemini-3.1-pro-preview-customtools': {
- id: 'google/gemini-3.1-pro-preview-customtools',
- name: 'Gemini 3.1 Pro Preview Custom Tools',
- limit: { context: 1048756 },
- },
- 'google/gemini-3.1-flash-lite-image': {
- id: 'google/gemini-3.1-flash-lite-image',
- name: 'Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)',
- limit: { context: 65536 },
- },
- 'google/gemini-3-pro-image-preview': {
- id: 'google/gemini-3-pro-image-preview',
- name: 'Nano Banana Pro',
- limit: { context: 65536 },
- },
- 'google/gemini-2.5-flash-image': {
- id: 'google/gemini-2.5-flash-image',
- name: 'Nano Banana',
- limit: { context: 32768 },
- },
- 'google/gemini-2.5-flash-lite': {
- id: 'google/gemini-2.5-flash-lite',
- name: 'Gemini 2.5 Flash-Lite',
- limit: { context: 1048576 },
- },
- 'google/gemini-3.1-flash-image-preview': {
- id: 'google/gemini-3.1-flash-image-preview',
- name: 'Nano Banana 2',
- limit: { context: 131072 },
- },
- 'google/gemini-2.5-pro-preview-05-06': {
- id: 'google/gemini-2.5-pro-preview-05-06',
- name: 'Gemini 2.5 Pro Preview 05-06',
- limit: { context: 1048576 },
- },
- 'google/gemini-3.1-pro-preview': {
- id: 'google/gemini-3.1-pro-preview',
- name: 'Gemini 3.1 Pro Preview',
- limit: { context: 1048576 },
- },
- 'google/gemma-4-26b-a4b-it': {
- id: 'google/gemma-4-26b-a4b-it',
- name: 'Gemma 4 26B A4B IT',
- limit: { context: 262144 },
- },
- 'google/gemini-2.5-pro-preview': {
- id: 'google/gemini-2.5-pro-preview',
- name: 'Gemini 2.5 Pro Preview 06-05',
- limit: { context: 1048576 },
- },
- 'google/gemini-3-flash-preview': {
- id: 'google/gemini-3-flash-preview',
- name: 'Gemini 3 Flash Preview',
- limit: { context: 1048576 },
- },
- 'google/gemma-3-12b-it': {
- id: 'google/gemma-3-12b-it',
- name: 'Gemma 3 12B',
- limit: { context: 131072 },
- },
- 'google/gemma-3-4b-it': {
- id: 'google/gemma-3-4b-it',
- name: 'Gemma 3 4B',
- limit: { context: 131072 },
- },
- 'google/gemma-3-27b-it': {
- id: 'google/gemma-3-27b-it',
- name: 'Gemma 3 27B',
- limit: { context: 131072 },
- },
- 'google/lyria-3-pro-preview': {
- id: 'google/lyria-3-pro-preview',
- name: 'Lyria 3 Pro Preview',
- limit: { context: 1048576 },
- },
- 'google/gemma-4-31b-it:free': {
- id: 'google/gemma-4-31b-it:free',
- name: 'Gemma 4 31B (free)',
- limit: { context: 262144 },
- },
- 'google/gemma-2-27b-it': {
- id: 'google/gemma-2-27b-it',
- name: 'Gemma 2 27B',
- limit: { context: 8192 },
- },
- 'google/gemini-3-pro-image': {
- id: 'google/gemini-3-pro-image',
- name: 'Nano Banana Pro',
- limit: { context: 65536 },
- },
- 'google/gemini-3.1-flash-lite-preview': {
- id: 'google/gemini-3.1-flash-lite-preview',
- name: 'Gemini 3.1 Flash Lite Preview',
- limit: { context: 1048576 },
- },
- 'liquid/lfm-2.5-1.2b-thinking:free': {
- id: 'liquid/lfm-2.5-1.2b-thinking:free',
- name: 'LFM2.5-1.2B-Thinking (free)',
- limit: { context: 32768 },
- },
- 'liquid/lfm-2.5-1.2b-instruct:free': {
- id: 'liquid/lfm-2.5-1.2b-instruct:free',
- name: 'LFM2.5-1.2B-Instruct (free)',
- limit: { context: 32768 },
- },
- 'x-ai/grok-4.20': { id: 'x-ai/grok-4.20', name: 'Grok 4.20', limit: { context: 2000000 } },
- 'x-ai/grok-4.3': { id: 'x-ai/grok-4.3', name: 'Grok 4.3', limit: { context: 1000000 } },
- 'x-ai/grok-4.5': { id: 'x-ai/grok-4.5', name: 'Grok 4.5', limit: { context: 500000 } },
- 'x-ai/grok-4.20-multi-agent': {
- id: 'x-ai/grok-4.20-multi-agent',
- name: 'Grok 4.20 Multi-Agent',
- limit: { context: 2000000 },
- },
- 'x-ai/grok-build-0.1': {
- id: 'x-ai/grok-build-0.1',
- name: 'Grok Build 0.1',
- limit: { context: 256000 },
- },
- '~google/gemini-pro-latest': {
- id: '~google/gemini-pro-latest',
- name: 'Google Gemini Pro Latest',
- limit: { context: 1048576 },
- },
- '~google/gemini-flash-latest': {
- id: '~google/gemini-flash-latest',
- name: 'Google Gemini Flash Latest',
- limit: { context: 1048576 },
- },
- 'microsoft/phi-4': { id: 'microsoft/phi-4', name: 'Phi 4', limit: { context: 16384 } },
- 'microsoft/wizardlm-2-8x22b': {
- id: 'microsoft/wizardlm-2-8x22b',
- name: 'WizardLM-2 8x22B',
- limit: { context: 65536 },
- },
- 'poolside/laguna-xs-2.1:free': {
- id: 'poolside/laguna-xs-2.1:free',
- name: 'Laguna XS 2.1 (free)',
- limit: { context: 262144 },
- },
- 'poolside/laguna-m.1': {
- id: 'poolside/laguna-m.1',
- name: 'Laguna M.1',
- limit: { context: 262144 },
- },
- 'poolside/laguna-xs-2.1': {
- id: 'poolside/laguna-xs-2.1',
- name: 'Laguna XS 2.1',
- limit: { context: 262144 },
- },
- 'poolside/laguna-m.1:free': {
- id: 'poolside/laguna-m.1:free',
- name: 'Laguna M.1 (free)',
- limit: { context: 262144 },
- },
- 'writer/palmyra-x5': {
- id: 'writer/palmyra-x5',
- name: 'Palmyra X5',
- limit: { context: 1040000 },
- },
- 'z-ai/glm-4.7': { id: 'z-ai/glm-4.7', name: 'GLM-4.7', limit: { context: 202752 } },
- 'z-ai/glm-4.5v': { id: 'z-ai/glm-4.5v', name: 'GLM-4.5V', limit: { context: 65536 } },
- 'z-ai/glm-4.5': { id: 'z-ai/glm-4.5', name: 'GLM-4.5', limit: { context: 131072 } },
- 'z-ai/glm-5.1': { id: 'z-ai/glm-5.1', name: 'GLM-5.1', limit: { context: 202752 } },
- 'z-ai/glm-4.6': { id: 'z-ai/glm-4.6', name: 'GLM-4.6', limit: { context: 200000 } },
- 'z-ai/glm-5.2': { id: 'z-ai/glm-5.2', name: 'GLM-5.2', limit: { context: 1048576 } },
- 'z-ai/glm-4.6v': { id: 'z-ai/glm-4.6v', name: 'GLM-4.6V', limit: { context: 131072 } },
- 'z-ai/glm-5v-turbo': {
- id: 'z-ai/glm-5v-turbo',
- name: 'GLM-5V-Turbo',
- limit: { context: 202752 },
- },
- 'z-ai/glm-4.5-air': {
- id: 'z-ai/glm-4.5-air',
- name: 'GLM-4.5-Air',
- limit: { context: 131072 },
- },
- 'z-ai/glm-4.7-flash': {
- id: 'z-ai/glm-4.7-flash',
- name: 'GLM-4.7-Flash',
- limit: { context: 202752 },
- },
- 'z-ai/glm-5': { id: 'z-ai/glm-5', name: 'GLM-5', limit: { context: 202752 } },
- 'z-ai/glm-5-turbo': {
- id: 'z-ai/glm-5-turbo',
- name: 'GLM-5-Turbo',
- limit: { context: 262144 },
- },
- 'openai/gpt-4o-mini-2024-07-18': {
- id: 'openai/gpt-4o-mini-2024-07-18',
- name: 'GPT-4o-mini (2024-07-18)',
- limit: { context: 128000 },
+ 'qwen/qwen3-coder-flash': {
+ id: 'qwen/qwen3-coder-flash',
+ name: 'Qwen3 Coder Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3-14b': {
+ id: 'qwen/qwen3-14b',
+ name: 'Qwen3 14B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-safeguard-20b': {
- id: 'openai/gpt-oss-safeguard-20b',
- name: 'gpt-oss-safeguard-20b',
- limit: { context: 131072 },
+ 'qwen/qwen3.6-plus': {
+ id: 'qwen/qwen3.6-plus',
+ name: 'Qwen3.6 Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-3.5-turbo-instruct': {
- id: 'openai/gpt-3.5-turbo-instruct',
- name: 'GPT-3.5 Turbo Instruct',
- limit: { context: 4095 },
+ 'qwen/qwen3.5-27b': {
+ id: 'qwen/qwen3.5-27b',
+ name: 'Qwen3.5 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3.8-27b': {
+ id: 'qwen/qwen3.8-27b',
+ name: 'Qwen3.8 27B',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.2-chat': {
- id: 'openai/gpt-5.2-chat',
- name: 'GPT-5.2 Chat',
- limit: { context: 128000 },
+ 'qwen/qwen3.5-35b-a3b': {
+ id: 'qwen/qwen3.5-35b-a3b',
+ name: 'Qwen3.5 35B-A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.6-luna-pro': {
- id: 'openai/gpt-5.6-luna-pro',
- name: 'GPT-5.6 Luna Pro',
- limit: { context: 1050000 },
+ 'qwen/qwen3.5-plus-20260420': {
+ id: 'qwen/qwen3.5-plus-20260420',
+ name: 'Qwen3.5 Plus 2026-04-20',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-32b': {
+ id: 'qwen/qwen3-32b',
+ name: 'Qwen3 32B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/o3': { id: 'openai/o3', name: 'o3', limit: { context: 200000 } },
- 'openai/gpt-5.6-sol-pro': {
- id: 'openai/gpt-5.6-sol-pro',
- name: 'GPT-5.6 Sol Pro',
- limit: { context: 1050000 },
+ 'qwen/qwen3.5-plus-02-15': {
+ id: 'qwen/qwen3.5-plus-02-15',
+ name: 'Qwen3.5 Plus 2026-02-15',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/o4-mini-high': {
- id: 'openai/o4-mini-high',
- name: 'o4 Mini High',
- limit: { context: 200000 },
+ 'qwen/qwen-plus-2025-07-28': {
+ id: 'qwen/qwen-plus-2025-07-28',
+ name: 'Qwen Plus 0728',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-audio': { id: 'openai/gpt-audio', name: 'GPT Audio', limit: { context: 128000 } },
- 'openai/gpt-5.2-pro': {
- id: 'openai/gpt-5.2-pro',
- name: 'GPT-5.2 Pro',
- limit: { context: 400000 },
+ 'qwen/qwen3-coder': {
+ id: 'qwen/qwen3-coder',
+ name: 'Qwen3 Coder 480B A35B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4o-mini-search-preview': {
- id: 'openai/gpt-4o-mini-search-preview',
- name: 'GPT-4o-mini Search Preview',
- limit: { context: 128000 },
+ 'qwen/qwen2.5-vl-72b-instruct': {
+ id: 'qwen/qwen2.5-vl-72b-instruct',
+ name: 'Qwen2.5 VL 72B Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-5.6-terra-pro': {
- id: 'openai/gpt-5.6-terra-pro',
- name: 'GPT-5.6 Terra Pro',
- limit: { context: 1050000 },
+ 'qwen/qwen3-coder-next': {
+ id: 'qwen/qwen3-coder-next',
+ name: 'Qwen3 Coder Next',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5': { id: 'openai/gpt-5', name: 'GPT-5', limit: { context: 400000 } },
- 'openai/gpt-5-chat': {
- id: 'openai/gpt-5-chat',
- name: 'GPT-5 Chat',
- limit: { context: 128000 },
+ 'qwen/qwen3-coder-30b-a3b-instruct': {
+ id: 'qwen/qwen3-coder-30b-a3b-instruct',
+ name: 'Qwen3-Coder 30B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-3.5-turbo': {
- id: 'openai/gpt-3.5-turbo',
- name: 'GPT-3.5-turbo',
- limit: { context: 16385 },
+ 'qwen/qwen3-235b-a22b-2507': {
+ id: 'qwen/qwen3-235b-a22b-2507',
+ name: 'Qwen3 235B A22B Instruct 2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5-pro': { id: 'openai/gpt-5-pro', name: 'GPT-5 Pro', limit: { context: 400000 } },
- 'openai/gpt-4o': { id: 'openai/gpt-4o', name: 'GPT-4o', limit: { context: 128000 } },
- 'openai/gpt-4': { id: 'openai/gpt-4', name: 'GPT-4', limit: { context: 8191 } },
- 'openai/o4-mini': { id: 'openai/o4-mini', name: 'o4-mini', limit: { context: 200000 } },
- 'openai/gpt-3.5-turbo-16k': {
- id: 'openai/gpt-3.5-turbo-16k',
- name: 'GPT-3.5 Turbo 16k',
- limit: { context: 16385 },
+ 'qwen/qwen3.5-flash-02-23': {
+ id: 'qwen/qwen3.5-flash-02-23',
+ name: 'Qwen3.5-Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/o3-pro': { id: 'openai/o3-pro', name: 'o3-pro', limit: { context: 200000 } },
- 'openai/gpt-5.1-chat': {
- id: 'openai/gpt-5.1-chat',
- name: 'GPT-5.1 Chat',
- limit: { context: 128000 },
+ 'qwen/qwen3.5-397b-a17b': {
+ id: 'qwen/qwen3.5-397b-a17b',
+ name: 'Qwen3.5 397B-A17B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-4o-2024-05-13': {
- id: 'openai/gpt-4o-2024-05-13',
- name: 'GPT-4o (2024-05-13)',
- limit: { context: 128000 },
+ 'qwen/qwen3-vl-8b-thinking': {
+ id: 'qwen/qwen3-vl-8b-thinking',
+ name: 'Qwen3 VL 8B Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
},
- 'openai/gpt-5.4-nano': {
- id: 'openai/gpt-5.4-nano',
- name: 'GPT-5.4 nano',
- limit: { context: 400000 },
+ 'qwen/qwen3.6-27b': {
+ id: 'qwen/qwen3.6-27b',
+ name: 'Qwen3.6 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3.7-flash': {
+ id: 'qwen/qwen3.7-flash',
+ name: 'Qwen3.7 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.3-chat': {
- id: 'openai/gpt-5.3-chat',
- name: 'GPT-5.3 Chat',
- limit: { context: 128000 },
+ 'qwen/qwen3-30b-a3b-thinking-2507': {
+ id: 'qwen/qwen3-30b-a3b-thinking-2507',
+ name: 'Qwen3 30B A3B Thinking 2507',
+ limit: {
+ context: 81920,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-3.5-turbo-0613': {
- id: 'openai/gpt-3.5-turbo-0613',
- name: 'GPT-3.5 Turbo (older v0613)',
- limit: { context: 4095 },
+ 'qwen/qwen3.6-35b-a3b': {
+ id: 'qwen/qwen3.6-35b-a3b',
+ name: 'Qwen3.6 35B-A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5-image-mini': {
- id: 'openai/gpt-5-image-mini',
- name: 'GPT-5 Image Mini',
- limit: { context: 400000 },
+ 'qwen/qwen3-max-thinking': {
+ id: 'qwen/qwen3-max-thinking',
+ name: 'Qwen3 Max Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3.8-max-0902': {
+ id: 'qwen/qwen3.8-max-0902',
+ name: 'Qwen3.8 Max 0902',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-max': {
+ id: 'qwen/qwen3-max',
+ name: 'Qwen3 Max',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.1-codex': {
- id: 'openai/gpt-5.1-codex',
- name: 'GPT-5.1 Codex',
- limit: { context: 400000 },
+ 'qwen/qwen3-vl-8b-instruct': {
+ id: 'qwen/qwen3-vl-8b-instruct',
+ name: 'Qwen3 VL 8B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
+ },
+ 'qwen/qwen3.8-2.4t-a95b': {
+ id: 'qwen/qwen3.8-2.4t-a95b',
+ name: 'Qwen3.8 2.4T A95B',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.1-codex-max': {
- id: 'openai/gpt-5.1-codex-max',
- name: 'GPT-5.1 Codex Max',
- limit: { context: 400000 },
+ 'qwen/qwen3-vl-30b-a3b-instruct': {
+ id: 'qwen/qwen3-vl-30b-a3b-instruct',
+ name: 'Qwen3 VL 30B A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen/qwen-plus': {
+ id: 'qwen/qwen-plus',
+ name: 'Qwen Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-120b:free': {
- id: 'openai/gpt-oss-120b:free',
- name: 'gpt-oss-120b (free)',
- limit: { context: 131072 },
+ 'qwen/qwen3.5-122b-a10b': {
+ id: 'qwen/qwen3.5-122b-a10b',
+ name: 'Qwen3.5 122B-A10B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3.8-27b:free': {
+ id: 'qwen/qwen3.8-27b:free',
+ name: 'Qwen3.8 27B (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-4o-2024-08-06': {
- id: 'openai/gpt-4o-2024-08-06',
- name: 'GPT-4o (2024-08-06)',
- limit: { context: 128000 },
+ 'qwen/qwen-2.5-coder-32b-instruct': {
+ id: 'qwen/qwen-2.5-coder-32b-instruct',
+ name: 'Qwen2.5 Coder 32B Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/o3-mini': { id: 'openai/o3-mini', name: 'o3-mini', limit: { context: 200000 } },
- 'openai/gpt-5.2': { id: 'openai/gpt-5.2', name: 'GPT-5.2', limit: { context: 400000 } },
- 'openai/gpt-5.3-codex': {
- id: 'openai/gpt-5.3-codex',
- name: 'GPT-5.3 Codex',
- limit: { context: 400000 },
+ 'qwen/qwen3-30b-a3b-instruct-2507': {
+ id: 'qwen/qwen3-30b-a3b-instruct-2507',
+ name: 'Qwen3 30B A3B Instruct 2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-audio-mini': {
- id: 'openai/gpt-audio-mini',
- name: 'GPT Audio Mini',
- limit: { context: 128000 },
+ 'qwen/qwen3.6-flash': {
+ id: 'qwen/qwen3.6-flash',
+ name: 'Qwen3.6 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.6-luna': {
- id: 'openai/gpt-5.6-luna',
- name: 'GPT-5.6 Luna',
- limit: { context: 1050000 },
+ 'qwen/qwen3-30b-a3b': {
+ id: 'qwen/qwen3-30b-a3b',
+ name: 'Qwen3 30B A3B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.1-codex-mini': {
- id: 'openai/gpt-5.1-codex-mini',
- name: 'GPT-5.1 Codex mini',
- limit: { context: 400000 },
+ 'qwen/qwen-2.5-7b-instruct': {
+ id: 'qwen/qwen-2.5-7b-instruct',
+ name: 'Qwen2.5 7B Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3.8-flash': {
+ id: 'qwen/qwen3.8-flash',
+ name: 'Qwen3.8 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.6-terra': {
- id: 'openai/gpt-5.6-terra',
- name: 'GPT-5.6 Terra',
- limit: { context: 1050000 },
+ 'qwen/qwen3-vl-30b-a3b-thinking': {
+ id: 'qwen/qwen3-vl-30b-a3b-thinking',
+ name: 'Qwen3 VL 30B A3B Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/o4-mini-deep-research': {
- id: 'openai/o4-mini-deep-research',
- name: 'o4-mini-deep-research',
- limit: { context: 200000 },
+ 'qwen/qwen3.6-max-preview': {
+ id: 'qwen/qwen3.6-max-preview',
+ name: 'Qwen3.6 Max Preview',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4.1-nano': {
- id: 'openai/gpt-4.1-nano',
- name: 'GPT-4.1 nano',
- limit: { context: 1047576 },
+ 'qwen/qwen-2.5-72b-instruct': {
+ id: 'qwen/qwen-2.5-72b-instruct',
+ name: 'Qwen2.5 72B Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3-8b': {
+ id: 'qwen/qwen3-8b',
+ name: 'Qwen3 8B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-120b': {
- id: 'openai/gpt-oss-120b',
- name: 'GPT OSS 120B',
- limit: { context: 131072 },
+ 'qwen/qwen3-235b-a22b': {
+ id: 'qwen/qwen3-235b-a22b',
+ name: 'Qwen3 235B-A22B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4o-2024-11-20': {
- id: 'openai/gpt-4o-2024-11-20',
- name: 'GPT-4o (2024-11-20)',
- limit: { context: 128000 },
+ 'qwen/qwen3-vl-235b-a22b-thinking': {
+ id: 'qwen/qwen3-vl-235b-a22b-thinking',
+ name: 'Qwen3 VL 235B A22B Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/o1': { id: 'openai/o1', name: 'o1', limit: { context: 200000 } },
- 'openai/o1-pro': { id: 'openai/o1-pro', name: 'o1-pro', limit: { context: 200000 } },
- 'openai/gpt-chat-latest': {
- id: 'openai/gpt-chat-latest',
- name: 'GPT Chat Latest',
- limit: { context: 400000 },
+ 'qwen/qwen3-vl-235b-a22b-instruct': {
+ id: 'qwen/qwen3-vl-235b-a22b-instruct',
+ name: 'Qwen3 VL 235B A22B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-5-image': {
- id: 'openai/gpt-5-image',
- name: 'GPT-5 Image',
- limit: { context: 400000 },
+ 'qwen/qwen3.7-plus': {
+ id: 'qwen/qwen3.7-plus',
+ name: 'Qwen3.7 Plus',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-5.4': { id: 'openai/gpt-5.4', name: 'GPT-5.4', limit: { context: 1050000 } },
- 'openai/gpt-5.4-mini': {
- id: 'openai/gpt-5.4-mini',
- name: 'GPT-5.4 mini',
- limit: { context: 400000 },
+ 'qwen/qwen3-vl-32b-instruct': {
+ id: 'qwen/qwen3-vl-32b-instruct',
+ name: 'Qwen3 VL 32B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-4.1': { id: 'openai/gpt-4.1', name: 'GPT-4.1', limit: { context: 1047576 } },
- 'openai/o3-deep-research': {
- id: 'openai/o3-deep-research',
- name: 'o3-deep-research',
- limit: { context: 200000 },
+ 'baidu/ernie-4.5-vl-424b-a47b': {
+ id: 'baidu/ernie-4.5-vl-424b-a47b',
+ name: 'ERNIE 4.5 VL 424B A47B ',
+ limit: {
+ context: 123000,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
+ },
+ 'unbiased/pareto': {
+ id: 'unbiased/pareto',
+ name: 'Pareto',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-4-turbo-preview': {
- id: 'openai/gpt-4-turbo-preview',
- name: 'GPT-4 Turbo Preview',
- limit: { context: 128000 },
+ 'aion-labs/aion-2.0': {
+ id: 'aion-labs/aion-2.0',
+ name: 'Aion-2.0',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5-mini': {
- id: 'openai/gpt-5-mini',
- name: 'GPT-5 Mini',
- limit: { context: 400000 },
+ 'aion-labs/aion-rp-llama-3.1-8b': {
+ id: 'aion-labs/aion-rp-llama-3.1-8b',
+ name: 'Aion-RP 1.0 (8B)',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4.1-mini': {
- id: 'openai/gpt-4.1-mini',
- name: 'GPT-4.1 mini',
- limit: { context: 1047576 },
+ 'aion-labs/aion-3.0': {
+ id: 'aion-labs/aion-3.0',
+ name: 'Aion-3.0',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4-turbo': {
- id: 'openai/gpt-4-turbo',
- name: 'GPT-4 Turbo',
- limit: { context: 128000 },
+ 'aion-labs/aion-3.0-mini': {
+ id: 'aion-labs/aion-3.0-mini',
+ name: 'Aion-3.0-Mini',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5-nano': {
- id: 'openai/gpt-5-nano',
- name: 'GPT-5 Nano',
- limit: { context: 400000 },
+ '~anthropic/claude-fable-latest': {
+ id: '~anthropic/claude-fable-latest',
+ name: 'Claude Fable Latest',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai/gpt-5.4-pro': {
- id: 'openai/gpt-5.4-pro',
- name: 'GPT-5.4 Pro',
- limit: { context: 1050000 },
+ '~anthropic/claude-opus-latest': {
+ id: '~anthropic/claude-opus-latest',
+ name: 'Claude Opus Latest',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai/o3-mini-high': {
- id: 'openai/o3-mini-high',
- name: 'o3 Mini High',
- limit: { context: 200000 },
+ '~anthropic/claude-haiku-latest': {
+ id: '~anthropic/claude-haiku-latest',
+ name: 'Claude Haiku Latest',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai/gpt-5.4-image-2': {
- id: 'openai/gpt-5.4-image-2',
- name: 'GPT-5.4 Image 2',
- limit: { context: 272000 },
+ '~anthropic/claude-sonnet-latest': {
+ id: '~anthropic/claude-sonnet-latest',
+ name: 'Claude Sonnet Latest',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'openai/gpt-4o-search-preview': {
- id: 'openai/gpt-4o-search-preview',
- name: 'GPT-4o Search Preview',
- limit: { context: 128000 },
+ 'morph/morph-v3-large': {
+ id: 'morph/morph-v3-large',
+ name: 'Morph V3 Large',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.5-pro': {
- id: 'openai/gpt-5.5-pro',
- name: 'GPT-5.5 Pro',
- limit: { context: 1050000 },
+ 'morph/morph-v3-fast': {
+ id: 'morph/morph-v3-fast',
+ name: 'Morph V3 Fast',
+ limit: {
+ context: 81920,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-4o-mini': {
- id: 'openai/gpt-4o-mini',
- name: 'GPT-4o mini',
- limit: { context: 128000 },
+ 'undi95/remm-slerp-l2-13b': {
+ id: 'undi95/remm-slerp-l2-13b',
+ name: 'ReMM SLERP 13B',
+ limit: {
+ context: 6144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ '~deepseek/deepseek-v4-flash-latest': {
+ id: '~deepseek/deepseek-v4-flash-latest',
+ name: 'DeepSeek V4 Flash Latest',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ '~deepseek/deepseek-pro-latest': {
+ id: '~deepseek/deepseek-pro-latest',
+ name: 'DeepSeek Pro Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ '~deepseek/deepseek-flash-latest': {
+ id: '~deepseek/deepseek-flash-latest',
+ name: 'DeepSeek Flash Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'dots-studio/dots-3-note-preview:free': {
+ id: 'dots-studio/dots-3-note-preview:free',
+ name: 'Dots3-Note Preview (free)',
+ limit: {
+ context: 512000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openai/gpt-oss-20b': {
- id: 'openai/gpt-oss-20b',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
+ '~x-ai/grok-latest': {
+ id: '~x-ai/grok-latest',
+ name: 'Grok Latest',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'meituan/longcat-2.0': {
+ id: 'meituan/longcat-2.0',
+ name: 'LongCat 2.0',
+ limit: {
+ context: 1048756,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.6-sol': {
- id: 'openai/gpt-5.6-sol',
- name: 'GPT-5.6 Sol',
- limit: { context: 1050000 },
+ 'poolside/laguna-xs-2.1': {
+ id: 'poolside/laguna-xs-2.1',
+ name: 'Laguna XS 2.1',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5-codex': {
- id: 'openai/gpt-5-codex',
- name: 'GPT-5-Codex',
- limit: { context: 400000 },
+ 'poolside/laguna-xs-2.1:free': {
+ id: 'poolside/laguna-xs-2.1:free',
+ name: 'Laguna XS 2.1 (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'poolside/laguna-s-2.1:free': {
+ id: 'poolside/laguna-s-2.1:free',
+ name: 'Laguna S 2.1 (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'poolside/laguna-s-2.1': {
+ id: 'poolside/laguna-s-2.1',
+ name: 'Laguna S 2.1',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-5.2-codex': {
- id: 'openai/gpt-5.2-codex',
- name: 'GPT-5.2 Codex',
- limit: { context: 400000 },
+ 'kwaipilot/kat-coder-pro-v2': {
+ id: 'kwaipilot/kat-coder-pro-v2',
+ name: 'KAT-Coder-Pro V2',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'kwaipilot/kat-coder-pro-v2.5': {
+ id: 'kwaipilot/kat-coder-pro-v2.5',
+ name: 'KAT-Coder-Pro V2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-20b:free': {
- id: 'openai/gpt-oss-20b:free',
- name: 'gpt-oss-20b (free)',
- limit: { context: 131072 },
+ 'stepfun/step-3.7-flash': {
+ id: 'stepfun/step-3.7-flash',
+ name: 'Step 3.7 Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openai/gpt-5.1': { id: 'openai/gpt-5.1', name: 'GPT-5.1', limit: { context: 400000 } },
- 'openai/gpt-5.5': { id: 'openai/gpt-5.5', name: 'GPT-5.5', limit: { context: 1050000 } },
- 'thedrummer/cydonia-24b-v4.1': {
- id: 'thedrummer/cydonia-24b-v4.1',
- name: 'Cydonia 24B V4.1',
- limit: { context: 131072 },
+ 'stepfun/step-3.5-flash': {
+ id: 'stepfun/step-3.5-flash',
+ name: 'Step 3.5 Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'thedrummer/skyfall-36b-v2': {
- id: 'thedrummer/skyfall-36b-v2',
- name: 'Skyfall 36B V2',
- limit: { context: 32768 },
+ 'mistralai/ministral-14b-2512': {
+ id: 'mistralai/ministral-14b-2512',
+ name: 'Ministral 3 14B 2512',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'thedrummer/unslopnemo-12b': {
- id: 'thedrummer/unslopnemo-12b',
- name: 'UnslopNemo 12B',
- limit: { context: 32768 },
+ 'mistralai/mistral-large': {
+ id: 'mistralai/mistral-large',
+ name: 'Mistral Large',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
- 'thedrummer/rocinante-12b': {
- id: 'thedrummer/rocinante-12b',
- name: 'Rocinante 12B',
- limit: { context: 65536 },
+ 'mistralai/codestral-2508': {
+ id: 'mistralai/codestral-2508',
+ name: 'Codestral 2508',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
- 'bytedance/ui-tars-1.5-7b': {
- id: 'bytedance/ui-tars-1.5-7b',
- name: 'UI-TARS 7B ',
- limit: { context: 128000 },
+ 'mistralai/mistral-medium-3-5': {
+ id: 'mistralai/mistral-medium-3-5',
+ name: 'Mistral Medium 3.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'rekaai/reka-flash-3': {
- id: 'rekaai/reka-flash-3',
- name: 'Reka Flash 3',
- limit: { context: 65536 },
+ 'mistralai/devstral-2512': {
+ id: 'mistralai/devstral-2512',
+ name: 'Devstral 2',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
- 'rekaai/reka-edge': { id: 'rekaai/reka-edge', name: 'Reka Edge', limit: { context: 16384 } },
'mistralai/mistral-large-2407': {
id: 'mistralai/mistral-large-2407',
name: 'Mistral Large 2407',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
'mistralai/mistral-small-3.2-24b-instruct': {
id: 'mistralai/mistral-small-3.2-24b-instruct',
name: 'Mistral Small 3.2 24B',
- limit: { context: 128000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
},
- 'mistralai/mistral-nemo': {
- id: 'mistralai/mistral-nemo',
- name: 'Mistral Nemo',
- limit: { context: 131072 },
- },
- 'mistralai/mistral-medium-3-5': {
- id: 'mistralai/mistral-medium-3-5',
- name: 'Mistral Medium 3.5',
- limit: { context: 262144 },
- },
- 'mistralai/ministral-8b-2512': {
- id: 'mistralai/ministral-8b-2512',
- name: 'Ministral 3 8B 2512',
- limit: { context: 262144 },
- },
- 'mistralai/mistral-small-3.1-24b-instruct': {
- id: 'mistralai/mistral-small-3.1-24b-instruct',
- name: 'Mistral Small 3.1 24B',
- limit: { context: 128000 },
+ 'mistralai/mixtral-8x22b-instruct': {
+ id: 'mistralai/mixtral-8x22b-instruct',
+ name: 'Mixtral 8x22B Instruct',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
'mistralai/mistral-saba': {
id: 'mistralai/mistral-saba',
name: 'Saba',
- limit: { context: 32768 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
- 'mistralai/mistral-large': {
- id: 'mistralai/mistral-large',
- name: 'Mistral Large',
- limit: { context: 128000 },
+ 'mistralai/ministral-3b-2512': {
+ id: 'mistralai/ministral-3b-2512',
+ name: 'Ministral 3 3B 2512',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistralai/mistral-medium-3.1': {
- id: 'mistralai/mistral-medium-3.1',
- name: 'Mistral Medium 3.1',
- limit: { context: 131072 },
+ 'mistralai/mistral-nemo': {
+ id: 'mistralai/mistral-nemo',
+ name: 'Mistral Nemo',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistralai/mistral-medium-3': {
+ id: 'mistralai/mistral-medium-3',
+ name: 'Mistral Medium 3',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'mistralai/mistral-small-24b-instruct-2501': {
id: 'mistralai/mistral-small-24b-instruct-2501',
name: 'Mistral Small 3',
- limit: { context: 32768 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'mistralai/ministral-3b-2512': {
- id: 'mistralai/ministral-3b-2512',
- name: 'Ministral 3 3B 2512',
- limit: { context: 131072 },
+ 'mistralai/mistral-small-3.1-24b-instruct': {
+ id: 'mistralai/mistral-small-3.1-24b-instruct',
+ name: 'Mistral Small 3.1 24B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'mistralai/mistral-small-2603': {
id: 'mistralai/mistral-small-2603',
name: 'Mistral Small 4',
- limit: { context: 262144 },
- },
- 'mistralai/ministral-14b-2512': {
- id: 'mistralai/ministral-14b-2512',
- name: 'Ministral 3 14B 2512',
- limit: { context: 262144 },
- },
- 'mistralai/devstral-2512': {
- id: 'mistralai/devstral-2512',
- name: 'Devstral 2',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistralai/mixtral-8x22b-instruct': {
- id: 'mistralai/mixtral-8x22b-instruct',
- name: 'Mixtral 8x22B Instruct',
- limit: { context: 65536 },
- },
- 'mistralai/mistral-medium-3': {
- id: 'mistralai/mistral-medium-3',
- name: 'Mistral Medium 3',
- limit: { context: 131072 },
+ 'mistralai/ministral-8b-2512': {
+ id: 'mistralai/ministral-8b-2512',
+ name: 'Ministral 3 8B 2512',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'mistralai/voxtral-small-24b-2507': {
id: 'mistralai/voxtral-small-24b-2507',
name: 'Voxtral Small 24B 2507',
- limit: { context: 32000 },
- },
- 'mistralai/mistral-large-2512': {
- id: 'mistralai/mistral-large-2512',
- name: 'Mistral Large 3',
- limit: { context: 262144 },
- },
- 'mistralai/codestral-2508': {
- id: 'mistralai/codestral-2508',
- name: 'Codestral 2508',
- limit: { context: 256000 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'audio', 'pdf'],
+ },
},
- 'morph/morph-v3-fast': {
- id: 'morph/morph-v3-fast',
- name: 'Morph V3 Fast',
- limit: { context: 81920 },
+ 'mistralai/mistral-medium-3.1': {
+ id: 'mistralai/mistral-medium-3.1',
+ name: 'Mistral Medium 3.1',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'morph/morph-v3-large': {
- id: 'morph/morph-v3-large',
- name: 'Morph V3 Large',
- limit: { context: 262144 },
+ 'xiaomi/mimo-v2.5': {
+ id: 'xiaomi/mimo-v2.5',
+ name: 'MiMo-V2.5',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
},
- 'bytedance-seed/seed-1.6-flash': {
- id: 'bytedance-seed/seed-1.6-flash',
- name: 'Seed 1.6 Flash',
- limit: { context: 262144 },
+ 'xiaomi/mimo-v2.5-pro': {
+ id: 'xiaomi/mimo-v2.5-pro',
+ name: 'MiMo-V2.5-Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'bytedance-seed/seed-1.6': {
- id: 'bytedance-seed/seed-1.6',
- name: 'Seed 1.6',
- limit: { context: 262144 },
+ 'minimax/minimax-m2.1': {
+ id: 'minimax/minimax-m2.1',
+ name: 'MiniMax-M2.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'bytedance-seed/seed-2.0-mini': {
- id: 'bytedance-seed/seed-2.0-mini',
- name: 'Seed-2.0-Mini',
- limit: { context: 262144 },
+ 'minimax/minimax-m2': {
+ id: 'minimax/minimax-m2',
+ name: 'MiniMax-M2',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'bytedance-seed/seed-2.0-lite': {
- id: 'bytedance-seed/seed-2.0-lite',
- name: 'Seed-2.0-Lite',
- limit: { context: 262144 },
+ 'minimax/minimax-m2.7': {
+ id: 'minimax/minimax-m2.7',
+ name: 'MiniMax-M2.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sakana/fugu-ultra': {
- id: 'sakana/fugu-ultra',
- name: 'Fugu Ultra',
- limit: { context: 1000000 },
+ 'minimax/minimax-m2.5': {
+ id: 'minimax/minimax-m2.5',
+ name: 'MiniMax-M2.5',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthracite-org/magnum-v4-72b': {
- id: 'anthracite-org/magnum-v4-72b',
- name: 'Magnum v4 72B',
- limit: { context: 32768 },
+ 'minimax/minimax-m3': {
+ id: 'minimax/minimax-m3',
+ name: 'MiniMax-M3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'nvidia/nemotron-3-nano-30b-a3b:free': {
- id: 'nvidia/nemotron-3-nano-30b-a3b:free',
- name: 'Nemotron 3 Nano 30B A3B (free)',
- limit: { context: 256000 },
+ 'minimax/minimax-m2-her': {
+ id: 'minimax/minimax-m2-her',
+ name: 'MiniMax-M2 Her',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/nemotron-nano-9b-v2:free': {
- id: 'nvidia/nemotron-nano-9b-v2:free',
- name: 'Nemotron Nano 9B V2 (free)',
- limit: { context: 128000 },
+ 'minimax/minimax-m1': {
+ id: 'minimax/minimax-m1',
+ name: 'MiniMax M1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/nemotron-nano-12b-v2-vl:free': {
- id: 'nvidia/nemotron-nano-12b-v2-vl:free',
- name: 'Nemotron Nano 12B 2 VL (free)',
- limit: { context: 128000 },
+ 'minimax/minimax-01': {
+ id: 'minimax/minimax-01',
+ name: 'MiniMax-01',
+ limit: {
+ context: 1000192,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'nvidia/nemotron-3.5-lightning:free': {
+ id: 'nvidia/nemotron-3.5-lightning:free',
+ name: 'Nemotron 3.5 Lightning (free)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/nemotron-3.5-content-safety': {
+ id: 'nvidia/nemotron-3.5-content-safety',
+ name: 'Nemotron 3.5 Content Safety',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'nvidia/nemotron-3.5-lightning': {
+ id: 'nvidia/nemotron-3.5-lightning',
+ name: 'Nemotron 3.5 Lightning 30B A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free': {
id: 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free',
name: 'Nemotron 3 Nano Omni (free)',
- limit: { context: 256000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'nvidia/nemotron-3-super-120b-a12b': {
+ id: 'nvidia/nemotron-3-super-120b-a12b',
+ name: 'Nemotron 3 Super 120B A12B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'nvidia/nemotron-3-ultra-550b-a55b:free': {
id: 'nvidia/nemotron-3-ultra-550b-a55b:free',
name: 'Nemotron 3 Ultra (free)',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/nemotron-3-ultra-550b-a55b': {
- id: 'nvidia/nemotron-3-ultra-550b-a55b',
- name: 'Nemotron 3 Ultra 550B A55B',
- limit: { context: 1000000 },
+ 'nvidia/nemotron-3-super-120b-a12b:free': {
+ id: 'nvidia/nemotron-3-super-120b-a12b:free',
+ name: 'Nemotron 3 Super (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'nvidia/nemotron-3.5-content-safety:free': {
id: 'nvidia/nemotron-3.5-content-safety:free',
name: 'Nemotron 3.5 Content Safety (free)',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'nvidia/nemotron-3-ultra-550b-a55b': {
+ id: 'nvidia/nemotron-3-ultra-550b-a55b',
+ name: 'Nemotron 3 Ultra 550B A55B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'nvidia/nemotron-3-nano-30b-a3b': {
id: 'nvidia/nemotron-3-nano-30b-a3b',
name: 'Nemotron 3 Nano 30B A3B',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/llama-3.3-nemotron-super-49b-v1.5': {
- id: 'nvidia/llama-3.3-nemotron-super-49b-v1.5',
- name: 'Llama 3.3 Nemotron Super 49B v1.5',
- limit: { context: 131072 },
+ 'anthropic/claude-opus-4.8': {
+ id: 'anthropic/claude-opus-4.8',
+ name: 'Claude Opus 4.8',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'nvidia/nemotron-3-super-120b-a12b:free': {
- id: 'nvidia/nemotron-3-super-120b-a12b:free',
- name: 'Nemotron 3 Super (free)',
- limit: { context: 1000000 },
+ 'anthropic/claude-opus-4.7': {
+ id: 'anthropic/claude-opus-4.7',
+ name: 'Claude Opus 4.7',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-opus-5': {
+ id: 'anthropic/claude-opus-5',
+ name: 'Claude Opus 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-opus-4.1': {
+ id: 'anthropic/claude-opus-4.1',
+ name: 'Claude Opus 4.1 (latest)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-sonnet-4.6': {
+ id: 'anthropic/claude-sonnet-4.6',
+ name: 'Claude Sonnet 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-3-haiku': {
+ id: 'anthropic/claude-3-haiku',
+ name: 'Claude 3 Haiku',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'anthropic/claude-haiku-4.5': {
+ id: 'anthropic/claude-haiku-4.5',
+ name: 'Claude Haiku 4.5 (latest)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-opus-4.6': {
+ id: 'anthropic/claude-opus-4.6',
+ name: 'Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-fable-5': {
+ id: 'anthropic/claude-fable-5',
+ name: 'Claude Fable 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-opus-4': {
+ id: 'anthropic/claude-opus-4',
+ name: 'Claude Opus 4',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
+ },
+ 'anthropic/claude-sonnet-4.5': {
+ id: 'anthropic/claude-sonnet-4.5',
+ name: 'Claude Sonnet 4.5 (latest)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-opus-4.5': {
+ id: 'anthropic/claude-opus-4.5',
+ name: 'Claude Opus 4.5 (latest)',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-sonnet-4': {
+ id: 'anthropic/claude-sonnet-4',
+ name: 'Claude Sonnet 4',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
+ },
+ 'anthropic/claude-sonnet-5': {
+ id: 'anthropic/claude-sonnet-5',
+ name: 'Claude Sonnet 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'anthropic/claude-fable-5.1': {
+ id: 'anthropic/claude-fable-5.1',
+ name: 'Claude Fable 5.1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'google/gemma-4-26b-a4b-it': {
+ id: 'google/gemma-4-26b-a4b-it',
+ name: 'Gemma 4 26B A4B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
+ },
+ 'google/gemini-3.1-pro-preview-customtools': {
+ id: 'google/gemini-3.1-pro-preview-customtools',
+ name: 'Gemini 3.1 Pro Preview Custom Tools',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-3.1-flash-lite-image': {
+ id: 'google/gemini-3.1-flash-lite-image',
+ name: 'Nano Banana 2 Lite',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemma-3-4b-it': {
+ id: 'google/gemma-3-4b-it',
+ name: 'Gemma 3 4B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/lyria-3-clip-preview': {
+ id: 'google/lyria-3-clip-preview',
+ name: 'Lyria 3 Clip Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemini-2.5-flash-image': {
+ id: 'google/gemini-2.5-flash-image',
+ name: 'Nano Banana',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemini-3-pro-image': {
+ id: 'google/gemini-3-pro-image',
+ name: 'Nano Banana Pro',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemini-3.1-pro-preview': {
+ id: 'google/gemini-3.1-pro-preview',
+ name: 'Gemini 3.1 Pro Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-2.5-flash-lite': {
+ id: 'google/gemini-2.5-flash-lite',
+ name: 'Gemini 2.5 Flash-Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
+ },
+ 'google/gemini-3.6-flash': {
+ id: 'google/gemini-3.6-flash',
+ name: 'Gemini 3.6 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-3.1-flash-lite': {
+ id: 'google/gemini-3.1-flash-lite',
+ name: 'Gemini 3.1 Flash Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-3.5-flash': {
+ id: 'google/gemini-3.5-flash',
+ name: 'Gemini 3.5 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-3.1-flash-lite-preview': {
+ id: 'google/gemini-3.1-flash-lite-preview',
+ name: 'Gemini 3.1 Flash Lite Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemma-3-27b-it': {
+ id: 'google/gemma-3-27b-it',
+ name: 'Gemma 3 27B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemini-3.1-flash-image': {
+ id: 'google/gemini-3.1-flash-image',
+ name: 'Nano Banana 2',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
+ },
+ 'google/gemini-3.5-flash-lite': {
+ id: 'google/gemini-3.5-flash-lite',
+ name: 'Gemini 3.5 Flash Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'nvidia/nemotron-3-super-120b-a12b': {
- id: 'nvidia/nemotron-3-super-120b-a12b',
- name: 'Nemotron 3 Super 120B A12B',
- limit: { context: 1000000 },
+ 'google/gemini-2.5-pro-preview': {
+ id: 'google/gemini-2.5-pro-preview',
+ name: 'Gemini 2.5 Pro Preview 06-05',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text', 'audio'],
+ },
},
- 'cognitivecomputations/dolphin-mistral-24b-venice-edition': {
- id: 'cognitivecomputations/dolphin-mistral-24b-venice-edition',
- name: 'Uncensored',
- limit: { context: 128000 },
+ 'google/gemini-3-pro-image-preview': {
+ id: 'google/gemini-3-pro-image-preview',
+ name: 'Nano Banana Pro Preview',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'cognitivecomputations/dolphin-mistral-24b-venice-edition:free': {
- id: 'cognitivecomputations/dolphin-mistral-24b-venice-edition:free',
- name: 'Uncensored (free)',
- limit: { context: 32768 },
+ 'google/gemma-4-31b-it:free': {
+ id: 'google/gemma-4-31b-it:free',
+ name: 'Gemma 4 31B (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'xiaomi/mimo-v2.5': {
- id: 'xiaomi/mimo-v2.5',
- name: 'MiMo-V2.5',
- limit: { context: 1048576 },
+ 'google/gemma-4-31b-it': {
+ id: 'google/gemma-4-31b-it',
+ name: 'Gemma 4 31B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'xiaomi/mimo-v2.5-pro': {
- id: 'xiaomi/mimo-v2.5-pro',
- name: 'MiMo-V2.5-Pro',
- limit: { context: 1048576 },
+ 'google/gemini-3-flash-preview': {
+ id: 'google/gemini-3-flash-preview',
+ name: 'Gemini 3 Flash Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'google/gemini-3.8-flash': {
+ id: 'google/gemini-3.8-flash',
+ name: 'Gemini 3.8 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'inception/mercury-2': {
- id: 'inception/mercury-2',
- name: 'Mercury 2',
- limit: { context: 128000 },
+ 'google/lyria-3-pro-preview': {
+ id: 'google/lyria-3-pro-preview',
+ name: 'Lyria 3 Pro Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'google/gemini-3.7-flash': {
+ id: 'google/gemini-3.7-flash',
+ name: 'Gemini 3.7 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'anthropic/claude-sonnet-4.5': {
- id: 'anthropic/claude-sonnet-4.5',
- name: 'Claude Sonnet 4.5 (latest)',
- limit: { context: 1000000 },
+ 'google/gemini-2.5-pro': {
+ id: 'google/gemini-2.5-pro',
+ name: 'Gemini 2.5 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
- 'anthropic/claude-sonnet-4': {
- id: 'anthropic/claude-sonnet-4',
- name: 'Claude Sonnet 4',
- limit: { context: 1000000 },
+ 'google/gemini-3.1-flash-image-preview': {
+ id: 'google/gemini-3.1-flash-image-preview',
+ name: 'Nano Banana 2 Preview',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
},
- 'anthropic/claude-haiku-4.5': {
- id: 'anthropic/claude-haiku-4.5',
- name: 'Claude Haiku 4.5 (latest)',
- limit: { context: 200000 },
+ 'google/gemini-2.5-flash': {
+ id: 'google/gemini-2.5-flash',
+ name: 'Gemini 2.5 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
- 'anthropic/claude-opus-4.7-fast': {
- id: 'anthropic/claude-opus-4.7-fast',
- name: 'Claude Opus 4.7 (Fast)',
- limit: { context: 1000000 },
+ 'google/gemma-3-12b-it': {
+ id: 'google/gemma-3-12b-it',
+ name: 'Gemma 3 12B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'anthropic/claude-sonnet-5': {
- id: 'anthropic/claude-sonnet-5',
- name: 'Claude Sonnet 5',
- limit: { context: 1000000 },
+ 'google/gemma-4-26b-a4b-it:free': {
+ id: 'google/gemma-4-26b-a4b-it:free',
+ name: 'Gemma 4 26B A4B (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'anthropic/claude-opus-4.7': {
- id: 'anthropic/claude-opus-4.7',
- name: 'Claude Opus 4.7',
- limit: { context: 1000000 },
+ 'google/gemma-2-27b-it': {
+ id: 'google/gemma-2-27b-it',
+ name: 'Gemma 2 27B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic/claude-opus-4.8': {
- id: 'anthropic/claude-opus-4.8',
- name: 'Claude Opus 4.8',
- limit: { context: 1000000 },
+ 'relace/relace-apply-3': {
+ id: 'relace/relace-apply-3',
+ name: 'Relace Apply 3',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic/claude-fable-5': {
- id: 'anthropic/claude-fable-5',
- name: 'Claude Fable 5',
- limit: { context: 1000000 },
+ 'relace/relace-search': {
+ id: 'relace/relace-search',
+ name: 'Relace Search',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nex-agi/nex-n2.5-mini:free': {
+ id: 'nex-agi/nex-n2.5-mini:free',
+ name: 'Nex-N2.5-Mini (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'nex-agi/nex-n2.5-pro:free': {
+ id: 'nex-agi/nex-n2.5-pro:free',
+ name: 'Nex-N2.5-Pro (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'thinkingmachines/inkling-small': {
+ id: 'thinkingmachines/inkling-small',
+ name: 'Inkling Small',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'thinkingmachines/inkling-small:free': {
+ id: 'thinkingmachines/inkling-small:free',
+ name: 'Inkling Small (free)',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'thinkingmachines/inkling:free': {
+ id: 'thinkingmachines/inkling:free',
+ name: 'Inkling (free)',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'thinkingmachines/inkling': {
+ id: 'thinkingmachines/inkling',
+ name: 'Inkling',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
},
- 'anthropic/claude-opus-4.1': {
- id: 'anthropic/claude-opus-4.1',
- name: 'Claude Opus 4.1 (latest)',
- limit: { context: 200000 },
+ 'gryphe/mythomax-l2-13b': {
+ id: 'gryphe/mythomax-l2-13b',
+ name: 'MythoMax 13B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta/muse-spark-1.3': {
+ id: 'meta/muse-spark-1.3',
+ name: 'Muse Spark 1.3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'meta/muse-spark-1.2': {
+ id: 'meta/muse-spark-1.2',
+ name: 'Muse Spark 1.2',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'meta/muse-spark-1.2-contributor': {
+ id: 'meta/muse-spark-1.2-contributor',
+ name: 'Muse Spark 1.2 Contributor',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'meta/muse-spark-1.3-contributor': {
+ id: 'meta/muse-spark-1.3-contributor',
+ name: 'Muse Spark 1.3 Contributor',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'meta/muse-spark-1.1': {
+ id: 'meta/muse-spark-1.1',
+ name: 'Muse Spark 1.1',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'meta/muse-glimmer-30b': {
+ id: 'meta/muse-glimmer-30b',
+ name: 'Muse Glimmer 30B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'anthropic/claude-opus-4.5': {
- id: 'anthropic/claude-opus-4.5',
- name: 'Claude Opus 4.5 (latest)',
- limit: { context: 200000 },
+ 'perceptron/perceptron-mk1': {
+ id: 'perceptron/perceptron-mk1',
+ name: 'Perceptron Mk1',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'anthropic/claude-sonnet-4.6': {
- id: 'anthropic/claude-sonnet-4.6',
- name: 'Claude Sonnet 4.6',
- limit: { context: 1000000 },
+ 'thedrummer/skyfall-36b-v2': {
+ id: 'thedrummer/skyfall-36b-v2',
+ name: 'Skyfall 36B V2',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic/claude-3-haiku': {
- id: 'anthropic/claude-3-haiku',
- name: 'Claude 3 Haiku',
- limit: { context: 200000 },
+ 'thedrummer/unslopnemo-12b': {
+ id: 'thedrummer/unslopnemo-12b',
+ name: 'UnslopNemo 12B',
+ limit: {
+ context: 1024000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic/claude-opus-4': {
- id: 'anthropic/claude-opus-4',
- name: 'Claude Opus 4',
- limit: { context: 200000 },
+ 'thedrummer/cydonia-24b-v4.1': {
+ id: 'thedrummer/cydonia-24b-v4.1',
+ name: 'Cydonia 24B V4.1',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'anthropic/claude-opus-4.8-fast': {
- id: 'anthropic/claude-opus-4.8-fast',
- name: 'Claude Opus 4.8 (Fast)',
- limit: { context: 1000000 },
+ 'bytedance/ui-tars-1.5-7b': {
+ id: 'bytedance/ui-tars-1.5-7b',
+ name: 'UI-TARS 7B ',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
},
- 'anthropic/claude-opus-4.6': {
- id: 'anthropic/claude-opus-4.6',
- name: 'Claude Opus 4.6',
- limit: { context: 1000000 },
+ 'bytedance-seed/seed-1.6-flash': {
+ id: 'bytedance-seed/seed-1.6-flash',
+ name: 'Seed 1.6 Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
+ },
+ 'bytedance-seed/seed-2-1-turbo': {
+ id: 'bytedance-seed/seed-2-1-turbo',
+ name: 'Seed 2.1 Turbo',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'bytedance-seed/seed-2.0-code': {
+ id: 'bytedance-seed/seed-2.0-code',
+ name: 'Seed 2.0 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'tencent/hy3:free': {
- id: 'tencent/hy3:free',
- name: 'Hy3 (free)',
- limit: { context: 262144 },
+ 'bytedance-seed/seed-1.6': {
+ id: 'bytedance-seed/seed-1.6',
+ name: 'Seed 1.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'tencent/hy3': { id: 'tencent/hy3', name: 'Hy3', limit: { context: 262144 } },
- 'tencent/hunyuan-a13b-instruct': {
- id: 'tencent/hunyuan-a13b-instruct',
- name: 'Hunyuan A13B Instruct',
- limit: { context: 131072 },
+ 'bytedance-seed/seed-2.0-mini': {
+ id: 'bytedance-seed/seed-2.0-mini',
+ name: 'Seed 2.0 Mini',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'tencent/hy3-preview': {
- id: 'tencent/hy3-preview',
- name: 'Hy3 preview',
- limit: { context: 262144 },
+ 'bytedance-seed/seed-2.0-lite': {
+ id: 'bytedance-seed/seed-2.0-lite',
+ name: 'Seed 2.0 Lite',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'inception/mercury-2.5': {
+ id: 'inception/mercury-2.5',
+ name: 'Mercury 2.5',
+ limit: {
+ context: 260000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepcogito/cogito-v2.1-671b': {
- id: 'deepcogito/cogito-v2.1-671b',
- name: 'Cogito v2.1 671B',
- limit: { context: 128000 },
+ 'inception/mercury-2': {
+ id: 'inception/mercury-2',
+ name: 'Mercury 2',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'cohere/command-a': { id: 'cohere/command-a', name: 'Command A', limit: { context: 256000 } },
- 'cohere/command-r-08-2024': {
- id: 'cohere/command-r-08-2024',
- name: 'Command R',
- limit: { context: 128000 },
+ 'writer/palmyra-x5': {
+ id: 'writer/palmyra-x5',
+ name: 'Palmyra X5',
+ limit: {
+ context: 1040000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'cohere/command-r7b-12-2024': {
- id: 'cohere/command-r7b-12-2024',
- name: 'Command R7B',
- limit: { context: 128000 },
+ '~google/gemini-pro-latest': {
+ id: '~google/gemini-pro-latest',
+ name: 'Gemini Pro Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['audio', 'pdf', 'image', 'text', 'video'],
+ },
},
- 'cohere/command-r-plus-08-2024': {
- id: 'cohere/command-r-plus-08-2024',
- name: 'Command R+',
- limit: { context: 128000 },
+ '~google/gemini-flash-latest': {
+ id: '~google/gemini-flash-latest',
+ name: 'Gemini Flash Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf', 'audio'],
+ },
+ },
+ 'microsoft/phi-4': {
+ id: 'microsoft/phi-4',
+ name: 'Phi 4',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'cohere/north-mini-code:free': {
- id: 'cohere/north-mini-code:free',
- name: 'North Mini Code (free)',
- limit: { context: 256000 },
+ 'microsoft/wizardlm-2-8x22b': {
+ id: 'microsoft/wizardlm-2-8x22b',
+ name: 'WizardLM-2 8x22B',
+ limit: {
+ context: 65535,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- '~x-ai/grok-latest': {
- id: '~x-ai/grok-latest',
- name: 'Grok Latest',
- limit: { context: 500000 },
+ 'sakana/fugu-ultra': {
+ id: 'sakana/fugu-ultra',
+ name: 'Fugu Ultra',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'sakana/fugu-max': {
+ id: 'sakana/fugu-max',
+ name: 'Fugu Max',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'sakana/sakana-namazu': {
+ id: 'sakana/sakana-namazu',
+ name: 'Sakana Namazu',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'sakana/fugu-ultra-v2': {
+ id: 'sakana/fugu-ultra-v2',
+ name: 'Fugu Ultra v2',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gryphe/mythomax-l2-13b': {
- id: 'gryphe/mythomax-l2-13b',
- name: 'MythoMax 13B',
- limit: { context: 4096 },
+ '~moonshotai/kimi-latest': {
+ id: '~moonshotai/kimi-latest',
+ name: 'Kimi Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'ibm-granite/granite-4.2-8b': {
+ id: 'ibm-granite/granite-4.2-8b',
+ name: 'Granite 4.2 8B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'stepfun/step-3.7-flash': {
- id: 'stepfun/step-3.7-flash',
- name: 'Step 3.7 Flash',
- limit: { context: 256000 },
+ 'ibm-granite/granite-4.0-h-micro': {
+ id: 'ibm-granite/granite-4.0-h-micro',
+ name: 'Granite 4.0 Micro',
+ limit: {
+ context: 131000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'stepfun/step-3.5-flash': {
- id: 'stepfun/step-3.5-flash',
- name: 'Step 3.5 Flash',
- limit: { context: 262144 },
+ 'deepseek/deepseek-chat-v3.1': {
+ id: 'deepseek/deepseek-chat-v3.1',
+ name: 'DeepSeek V3.1',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v4-flash-vision-exp': {
+ id: 'deepseek/deepseek-v4-flash-vision-exp',
+ name: 'DeepSeek V4 Flash Vision Exp',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'deepseek/deepseek-v4-pro-0813': {
+ id: 'deepseek/deepseek-v4-pro-0813',
+ name: 'DeepSeek V4 Pro 0813',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v4-flash-0731': {
+ id: 'deepseek/deepseek-v4-flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nex-agi/nex-n2-mini': {
- id: 'nex-agi/nex-n2-mini',
- name: 'Nex-N2-Mini',
- limit: { context: 262144 },
+ 'deepseek/deepseek-v4-flash': {
+ id: 'deepseek/deepseek-v4-flash',
+ name: 'DeepSeek V4 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v4-flash-0731:free': {
+ id: 'deepseek/deepseek-v4-flash-0731:free',
+ name: 'DeepSeek V4 Flash 0731 (free)',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v4.1-flash': {
+ id: 'deepseek/deepseek-v4.1-flash',
+ name: 'DeepSeek V4.1 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'nex-agi/nex-n2-pro': {
- id: 'nex-agi/nex-n2-pro',
- name: 'Nex-N2-Pro',
- limit: { context: 262144 },
+ 'deepseek/deepseek-r1': {
+ id: 'deepseek/deepseek-r1',
+ name: 'DeepSeek-R1',
+ limit: {
+ context: 64000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'undi95/remm-slerp-l2-13b': {
- id: 'undi95/remm-slerp-l2-13b',
- name: 'ReMM SLERP 13B',
- limit: { context: 6144 },
+ 'deepseek/deepseek-chat': {
+ id: 'deepseek/deepseek-chat',
+ name: 'DeepSeek Chat',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- '~openai/gpt-mini-latest': {
- id: '~openai/gpt-mini-latest',
- name: 'OpenAI GPT Mini Latest',
- limit: { context: 400000 },
+ 'deepseek/deepseek-r1-0528': {
+ id: 'deepseek/deepseek-r1-0528',
+ name: 'R1 0528',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- '~openai/gpt-latest': {
- id: '~openai/gpt-latest',
- name: 'OpenAI GPT Latest',
- limit: { context: 1050000 },
+ 'deepseek/deepseek-v3.2': {
+ id: 'deepseek/deepseek-v3.2',
+ name: 'DeepSeek V3.2',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- '~moonshotai/kimi-latest': {
- id: '~moonshotai/kimi-latest',
- name: 'MoonshotAI Kimi Latest',
- limit: { context: 262144 },
+ 'deepseek/deepseek-r1-distill-llama-70b': {
+ id: 'deepseek/deepseek-r1-distill-llama-70b',
+ name: 'R1 Distill Llama 70B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'relace/relace-search': {
- id: 'relace/relace-search',
- name: 'Relace Search',
- limit: { context: 256000 },
+ 'deepseek/deepseek-v3.2-exp': {
+ id: 'deepseek/deepseek-v3.2-exp',
+ name: 'DeepSeek V3.2 Exp',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'relace/relace-apply-3': {
- id: 'relace/relace-apply-3',
- name: 'Relace Apply 3',
- limit: { context: 256000 },
+ 'deepseek/deepseek-v3.1-terminus': {
+ id: 'deepseek/deepseek-v3.1-terminus',
+ name: 'DeepSeek V3.1 Terminus',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'ai21/jamba-large-1.7': {
- id: 'ai21/jamba-large-1.7',
- name: 'Jamba Large 1.7',
- limit: { context: 256000 },
+ 'deepseek/deepseek-v4-pro': {
+ id: 'deepseek/deepseek-v4-pro',
+ name: 'DeepSeek V4 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'arcee-ai/coder-large': {
- id: 'arcee-ai/coder-large',
- name: 'Coder Large',
- limit: { context: 32768 },
+ 'deepseek/deepseek-chat-v3-0324': {
+ id: 'deepseek/deepseek-chat-v3-0324',
+ name: 'DeepSeek V3 0324',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ '~openai/gpt-terra-latest': {
+ id: '~openai/gpt-terra-latest',
+ name: 'GPT Terra Latest',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
+ },
+ '~openai/gpt-sol-latest': {
+ id: '~openai/gpt-sol-latest',
+ name: 'GPT Sol Latest',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
+ },
+ '~openai/gpt-luna-latest': {
+ id: '~openai/gpt-luna-latest',
+ name: 'GPT Luna Latest',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
+ },
+ '~openai/gpt-astra-latest': {
+ id: '~openai/gpt-astra-latest',
+ name: 'GPT Astra Latest',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'arcee-ai/virtuoso-large': {
- id: 'arcee-ai/virtuoso-large',
- name: 'Virtuoso Large',
- limit: { context: 131072 },
+ '~openai/gpt-mini-latest': {
+ id: '~openai/gpt-mini-latest',
+ name: 'GPT Mini Latest',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'arcee-ai/trinity-large-thinking': {
- id: 'arcee-ai/trinity-large-thinking',
- name: 'Trinity Large Thinking',
- limit: { context: 262144 },
+ 'amazon/nova-2-lite-v1': {
+ id: 'amazon/nova-2-lite-v1',
+ name: 'Nova 2 Lite',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
},
- 'mancer/weaver': { id: 'mancer/weaver', name: 'Weaver (alpha)', limit: { context: 8000 } },
- 'perplexity/sonar-reasoning-pro': {
- id: 'perplexity/sonar-reasoning-pro',
- name: 'Sonar Reasoning Pro',
- limit: { context: 128000 },
+ 'amazon/nova-micro-v1': {
+ id: 'amazon/nova-micro-v1',
+ name: 'Nova Micro 1.0',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'perplexity/sonar': { id: 'perplexity/sonar', name: 'Sonar', limit: { context: 127072 } },
- 'perplexity/sonar-pro': {
- id: 'perplexity/sonar-pro',
- name: 'Sonar Pro',
- limit: { context: 200000 },
+ 'amazon/nova-pro-v1': {
+ id: 'amazon/nova-pro-v1',
+ name: 'Nova Pro 1.0',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'perplexity/sonar-pro-search': {
- id: 'perplexity/sonar-pro-search',
- name: 'Sonar Pro Search',
- limit: { context: 200000 },
+ 'amazon/nova-premier-v1': {
+ id: 'amazon/nova-premier-v1',
+ name: 'Nova Premier 1.0',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'perplexity/sonar-deep-research': {
- id: 'perplexity/sonar-deep-research',
- name: 'Sonar Deep Research',
- limit: { context: 128000 },
+ 'amazon/nova-lite-v1': {
+ id: 'amazon/nova-lite-v1',
+ name: 'Nova Lite 1.0',
+ limit: {
+ context: 300000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash': {
+ id: 'inclusionai/ling-3.0-flash',
+ name: 'Ling 3.0 Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash-fin': {
+ id: 'inclusionai/ling-3.0-flash-fin',
+ name: 'Ling 3.0 Flash Fin',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash-fin:free': {
+ id: 'inclusionai/ling-3.0-flash-fin:free',
+ name: 'Ling 3.0 Flash Fin (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash-sante:free': {
+ id: 'inclusionai/ling-3.0-flash-sante:free',
+ name: 'Ling 3.0 Flash Sante (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash-vl:free': {
+ id: 'inclusionai/ling-3.0-flash-vl:free',
+ name: 'Ling 3.0 Flash VL (free)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'inclusionai/ling-3.0-flash-vl': {
+ id: 'inclusionai/ling-3.0-flash-vl',
+ name: 'Ling 3.0 Flash VL',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'openrouter/bodybuilder': {
- id: 'openrouter/bodybuilder',
- name: 'Body Builder (beta)',
- limit: { context: 128000 },
+ 'anthracite-org/magnum-v4-72b': {
+ id: 'anthracite-org/magnum-v4-72b',
+ name: 'Magnum v4 72B',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mancer/weaver': {
+ id: 'mancer/weaver',
+ name: 'Weaver (alpha)',
+ limit: {
+ context: 8000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'openrouter/free': {
id: 'openrouter/free',
name: 'Free Models Router',
- limit: { context: 200000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'openrouter/fusion': { id: 'openrouter/fusion', name: 'Fusion', limit: { context: 1000000 } },
'openrouter/pareto-code': {
id: 'openrouter/pareto-code',
name: 'Pareto Code Router',
- limit: { context: 2000000 },
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openrouter/bodybuilder': {
+ id: 'openrouter/bodybuilder',
+ name: 'Body Builder (beta)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openrouter/fusion': {
+ id: 'openrouter/fusion',
+ name: 'Fusion',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'openrouter/auto': {
id: 'openrouter/auto',
name: 'Auto Router',
- limit: { context: 2000000 },
- },
- 'qwen/qwen3.5-plus-20260420': {
- id: 'qwen/qwen3.5-plus-20260420',
- name: 'Qwen3.5 Plus 2026-04-20',
- limit: { context: 1000000 },
- },
- 'qwen/qwen3-next-80b-a3b-instruct:free': {
- id: 'qwen/qwen3-next-80b-a3b-instruct:free',
- name: 'Qwen3 Next 80B A3B Instruct (free)',
- limit: { context: 262144 },
- },
- 'qwen/qwen3-vl-235b-a22b-thinking': {
- id: 'qwen/qwen3-vl-235b-a22b-thinking',
- name: 'Qwen3 VL 235B A22B Thinking',
- limit: { context: 131072 },
- },
- 'qwen/qwen3-vl-30b-a3b-thinking': {
- id: 'qwen/qwen3-vl-30b-a3b-thinking',
- name: 'Qwen3 VL 30B A3B Thinking',
- limit: { context: 131072 },
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'pdf', 'video'],
+ },
},
- 'qwen/qwen3-coder-plus': {
- id: 'qwen/qwen3-coder-plus',
- name: 'Qwen3 Coder Plus',
- limit: { context: 1000000 },
+ 'sao10k/l3.3-euryale-70b': {
+ id: 'sao10k/l3.3-euryale-70b',
+ name: 'Llama 3.3 Euryale 70B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen-plus': { id: 'qwen/qwen-plus', name: 'Qwen Plus', limit: { context: 1000000 } },
- 'qwen/qwen3-coder-30b-a3b-instruct': {
- id: 'qwen/qwen3-coder-30b-a3b-instruct',
- name: 'Qwen3-Coder 30B-A3B Instruct',
- limit: { context: 160000 },
+ 'sao10k/l3-lunaris-8b': {
+ id: 'sao10k/l3-lunaris-8b',
+ name: 'Llama 3 8B Lunaris',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-32b': { id: 'qwen/qwen3-32b', name: 'Qwen3 32B', limit: { context: 131072 } },
- 'qwen/qwen3-next-80b-a3b-instruct': {
- id: 'qwen/qwen3-next-80b-a3b-instruct',
- name: 'Qwen3-Next 80B-A3B Instruct',
- limit: { context: 262144 },
+ 'sao10k/l3.1-euryale-70b': {
+ id: 'sao10k/l3.1-euryale-70b',
+ name: 'Llama 3.1 Euryale 70B v2.2',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-vl-8b-instruct': {
- id: 'qwen/qwen3-vl-8b-instruct',
- name: 'Qwen3 VL 8B Instruct',
- limit: { context: 256000 },
+ 'x-ai/grok-4.20-multi-agent': {
+ id: 'x-ai/grok-4.20-multi-agent',
+ name: 'Grok 4.20 Multi-Agent',
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'x-ai/grok-4.3': {
+ id: 'x-ai/grok-4.3',
+ name: 'Grok 4.3',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'x-ai/grok-4.20': {
+ id: 'x-ai/grok-4.20',
+ name: 'Grok 4.20',
+ limit: {
+ context: 2000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'x-ai/grok-4.5': {
+ id: 'x-ai/grok-4.5',
+ name: 'Grok 4.5',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3.7-plus': {
- id: 'qwen/qwen3.7-plus',
- name: 'Qwen3.7 Plus',
- limit: { context: 1000000 },
+ 'x-ai/grok-build-0.1': {
+ id: 'x-ai/grok-build-0.1',
+ name: 'Grok Build 0.1',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'x-ai/grok-4.6': {
+ id: 'x-ai/grok-4.6',
+ name: 'Grok 4.6',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3.6-35b-a3b': {
- id: 'qwen/qwen3.6-35b-a3b',
- name: 'Qwen3.6 35B-A3B',
- limit: { context: 262144 },
+ 'meta-llama/llama-3.1-8b-instruct': {
+ id: 'meta-llama/llama-3.1-8b-instruct',
+ name: 'Llama-3.1-8B-Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.7-max': {
- id: 'qwen/qwen3.7-max',
- name: 'Qwen3.7 Max',
- limit: { context: 1000000 },
+ 'meta-llama/llama-guard-4-12b': {
+ id: 'meta-llama/llama-guard-4-12b',
+ name: 'Llama Guard 4 12B',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['image', 'text'],
+ },
},
- 'qwen/qwen3-max': { id: 'qwen/qwen3-max', name: 'Qwen3 Max', limit: { context: 262144 } },
- 'qwen/qwen3-8b': { id: 'qwen/qwen3-8b', name: 'Qwen3 8B', limit: { context: 131072 } },
- 'qwen/qwen-plus-2025-07-28': {
- id: 'qwen/qwen-plus-2025-07-28',
- name: 'Qwen Plus 0728',
- limit: { context: 1000000 },
+ 'meta-llama/llama-3.2-3b-instruct': {
+ id: 'meta-llama/llama-3.2-3b-instruct',
+ name: 'Llama 3.2 3B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.5-flash-02-23': {
- id: 'qwen/qwen3.5-flash-02-23',
- name: 'Qwen3.5-Flash',
- limit: { context: 1000000 },
+ 'meta-llama/llama-3.2-1b-instruct': {
+ id: 'meta-llama/llama-3.2-1b-instruct',
+ name: 'Llama 3.2 1B Instruct',
+ limit: {
+ context: 60000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-coder:free': {
- id: 'qwen/qwen3-coder:free',
- name: 'Qwen3 Coder 480B A35B (free)',
- limit: { context: 1048576 },
+ 'meta-llama/llama-4-maverick': {
+ id: 'meta-llama/llama-4-maverick',
+ name: 'Llama 4 Maverick',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3-30b-a3b-instruct-2507': {
- id: 'qwen/qwen3-30b-a3b-instruct-2507',
- name: 'Qwen3 30B A3B Instruct 2507',
- limit: { context: 131072 },
+ 'meta-llama/llama-4-scout': {
+ id: 'meta-llama/llama-4-scout',
+ name: 'Llama 4 Scout',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen-2.5-coder-32b-instruct': {
- id: 'qwen/qwen-2.5-coder-32b-instruct',
- name: 'Qwen2.5 Coder 32B Instruct',
- limit: { context: 128000 },
+ 'meta-llama/llama-3.1-70b-instruct': {
+ id: 'meta-llama/llama-3.1-70b-instruct',
+ name: 'Llama-3.1-70B-Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-next-80b-a3b-thinking': {
- id: 'qwen/qwen3-next-80b-a3b-thinking',
- name: 'Qwen3-Next 80B-A3B (Thinking)',
- limit: { context: 262144 },
+ 'meta-llama/llama-3.3-70b-instruct': {
+ id: 'meta-llama/llama-3.3-70b-instruct',
+ name: 'Llama-3.3-70B-Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-235b-a22b-thinking-2507': {
- id: 'qwen/qwen3-235b-a22b-thinking-2507',
- name: 'Qwen3 235B A22B Thinking 2507',
- limit: { context: 262144 },
+ 'nousresearch/hermes-3-llama-3.1-70b': {
+ id: 'nousresearch/hermes-3-llama-3.1-70b',
+ name: 'Hermes 3 70B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-vl-32b-instruct': {
- id: 'qwen/qwen3-vl-32b-instruct',
- name: 'Qwen3 VL 32B Instruct',
- limit: { context: 262144 },
+ 'nousresearch/hermes-3-llama-3.1-405b': {
+ id: 'nousresearch/hermes-3-llama-3.1-405b',
+ name: 'Hermes 3 405B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-coder': {
- id: 'qwen/qwen3-coder',
- name: 'Qwen3 Coder 480B A35B',
- limit: { context: 1048576 },
+ 'nousresearch/hermes-4-405b': {
+ id: 'nousresearch/hermes-4-405b',
+ name: 'Hermes 4 405B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.6-flash': {
- id: 'qwen/qwen3.6-flash',
- name: 'Qwen3.6 Flash',
- limit: { context: 1000000 },
+ 'openai/o4-mini-high': {
+ id: 'openai/o4-mini-high',
+ name: 'o4 Mini High',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3.5-plus-02-15': {
- id: 'qwen/qwen3.5-plus-02-15',
- name: 'Qwen3.5 Plus 2026-02-15',
- limit: { context: 1000000 },
+ 'openai/gpt-5-nano': {
+ id: 'openai/gpt-5-nano',
+ name: 'GPT-5 Nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen-2.5-7b-instruct': {
- id: 'qwen/qwen-2.5-7b-instruct',
- name: 'Qwen2.5 7B Instruct',
- limit: { context: 131072 },
+ 'openai/gpt-4.1-nano': {
+ id: 'openai/gpt-4.1-nano',
+ name: 'GPT-4.1 nano',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3-vl-8b-thinking': {
- id: 'qwen/qwen3-vl-8b-thinking',
- name: 'Qwen3 VL 8B Thinking',
- limit: { context: 256000 },
+ 'openai/gpt-4o-2024-05-13': {
+ id: 'openai/gpt-4o-2024-05-13',
+ name: 'GPT-4o (2024-05-13)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/gpt-5-pro': {
+ id: 'openai/gpt-5-pro',
+ name: 'GPT-5 Pro',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3-max-thinking': {
- id: 'qwen/qwen3-max-thinking',
- name: 'Qwen3 Max Thinking',
- limit: { context: 262144 },
+ 'openai/gpt-4o-mini-2024-07-18': {
+ id: 'openai/gpt-4o-mini-2024-07-18',
+ name: 'GPT-4o-mini (2024-07-18)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3-30b-a3b-thinking-2507': {
- id: 'qwen/qwen3-30b-a3b-thinking-2507',
- name: 'Qwen3 30B A3B Thinking 2507',
- limit: { context: 131072 },
+ 'openai/o3-mini-high': {
+ id: 'openai/o3-mini-high',
+ name: 'o3 Mini High',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
},
- 'qwen/qwen2.5-vl-72b-instruct': {
- id: 'qwen/qwen2.5-vl-72b-instruct',
- name: 'Qwen2.5 VL 72B Instruct',
- limit: { context: 131072 },
+ 'openai/gpt-5.1-codex-mini': {
+ id: 'openai/gpt-5.1-codex-mini',
+ name: 'GPT-5.1 Codex mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'openai/gpt-6-astra-pro': {
+ id: 'openai/gpt-6-astra-pro',
+ name: 'GPT-6 Astra Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'qwen/qwen3.5-27b': {
- id: 'qwen/qwen3.5-27b',
- name: 'Qwen3.5 27B',
- limit: { context: 262144 },
+ 'openai/gpt-audio-mini': {
+ id: 'openai/gpt-audio-mini',
+ name: 'GPT Audio Mini',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
},
- 'qwen/qwen3-235b-a22b': {
- id: 'qwen/qwen3-235b-a22b',
- name: 'Qwen3 235B-A22B',
- limit: { context: 131072 },
+ 'openai/gpt-5.1-codex': {
+ id: 'openai/gpt-5.1-codex',
+ name: 'GPT-5.1 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen-2.5-72b-instruct': {
- id: 'qwen/qwen-2.5-72b-instruct',
- name: 'Qwen2.5 72B Instruct',
- limit: { context: 131072 },
+ 'openai/gpt-5.6-sol': {
+ id: 'openai/gpt-5.6-sol',
+ name: 'GPT-5.6 Sol',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen-plus-2025-07-28:thinking': {
- id: 'qwen/qwen-plus-2025-07-28:thinking',
- name: 'Qwen Plus 0728 (thinking)',
- limit: { context: 1000000 },
+ 'openai/gpt-4o-2024-08-06': {
+ id: 'openai/gpt-4o-2024-08-06',
+ name: 'GPT-4o (2024-08-06)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3-coder-next': {
- id: 'qwen/qwen3-coder-next',
- name: 'Qwen3 Coder Next',
- limit: { context: 262144 },
+ 'openai/gpt-5.2-codex': {
+ id: 'openai/gpt-5.2-codex',
+ name: 'GPT-5.2 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'openai/gpt-6-astra': {
+ id: 'openai/gpt-6-astra',
+ name: 'GPT-6 Astra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3.6-27b': {
- id: 'qwen/qwen3.6-27b',
- name: 'Qwen3.6 27B',
- limit: { context: 262144 },
+ 'openai/gpt-5.2-chat': {
+ id: 'openai/gpt-5.2-chat',
+ name: 'GPT-5.2 Chat',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'qwen/qwen3.5-35b-a3b': {
- id: 'qwen/qwen3.5-35b-a3b',
- name: 'Qwen3.5 35B-A3B',
- limit: { context: 262144 },
+ 'openai/gpt-5.6-luna-pro': {
+ id: 'openai/gpt-5.6-luna-pro',
+ name: 'GPT-5.6 Luna Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3.5-9b': { id: 'qwen/qwen3.5-9b', name: 'Qwen3.5 9B', limit: { context: 262144 } },
- 'qwen/qwen3.5-397b-a17b': {
- id: 'qwen/qwen3.5-397b-a17b',
- name: 'Qwen3.5 397B-A17B',
- limit: { context: 256000 },
+ 'openai/gpt-5.2-pro': {
+ id: 'openai/gpt-5.2-pro',
+ name: 'GPT-5.2 Pro',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3-vl-30b-a3b-instruct': {
- id: 'qwen/qwen3-vl-30b-a3b-instruct',
- name: 'Qwen3 VL 30B A3B Instruct',
- limit: { context: 262144 },
+ 'openai/gpt-4.1-mini': {
+ id: 'openai/gpt-4.1-mini',
+ name: 'GPT-4.1 mini',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/gpt-5.4': {
+ id: 'openai/gpt-5.4',
+ name: 'GPT-5.4',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3-235b-a22b-2507': {
- id: 'qwen/qwen3-235b-a22b-2507',
- name: 'Qwen3 235B A22B Instruct 2507',
- limit: { context: 262144 },
+ 'openai/gpt-oss-20b': {
+ id: 'openai/gpt-oss-20b',
+ name: 'GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-coder-flash': {
- id: 'qwen/qwen3-coder-flash',
- name: 'Qwen3 Coder Flash',
- limit: { context: 1000000 },
+ 'openai/gpt-4-turbo': {
+ id: 'openai/gpt-4-turbo',
+ name: 'GPT-4 Turbo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3-14b': { id: 'qwen/qwen3-14b', name: 'Qwen3 14B', limit: { context: 131702 } },
- 'qwen/qwen3-vl-235b-a22b-instruct': {
- id: 'qwen/qwen3-vl-235b-a22b-instruct',
- name: 'Qwen3 VL 235B A22B Instruct',
- limit: { context: 262144 },
+ 'openai/gpt-5-image': {
+ id: 'openai/gpt-5-image',
+ name: 'GPT-5 Image',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3-30b-a3b': {
- id: 'qwen/qwen3-30b-a3b',
- name: 'Qwen3 30B A3B',
- limit: { context: 131072 },
+ 'openai/gpt-5.6-sol-pro': {
+ id: 'openai/gpt-5.6-sol-pro',
+ name: 'GPT-5.6 Sol Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'qwen/qwen3.6-max-preview': {
- id: 'qwen/qwen3.6-max-preview',
- name: 'Qwen3.6 Max Preview',
- limit: { context: 262144 },
+ 'openai/gpt-oss-safeguard-20b': {
+ id: 'openai/gpt-oss-safeguard-20b',
+ name: 'GPT OSS Safeguard 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-5.1': {
+ id: 'openai/gpt-5.1',
+ name: 'GPT-5.1',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'qwen/qwen3.5-122b-a10b': {
- id: 'qwen/qwen3.5-122b-a10b',
- name: 'Qwen3.5 122B-A10B',
- limit: { context: 262144 },
+ 'openai/gpt-5.1-codex-max': {
+ id: 'openai/gpt-5.1-codex-max',
+ name: 'GPT-5.1 Codex Max',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3.6-plus': {
- id: 'qwen/qwen3.6-plus',
- name: 'Qwen3.6 Plus',
- limit: { context: 1000000 },
+ 'openai/gpt-5.4-image-2': {
+ id: 'openai/gpt-5.4-image-2',
+ name: 'GPT-5.4 Image 2',
+ limit: {
+ context: 272000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
},
- 'amazon/nova-lite-v1': {
- id: 'amazon/nova-lite-v1',
- name: 'Nova Lite 1.0',
- limit: { context: 300000 },
+ 'openai/gpt-3.5-turbo-0613': {
+ id: 'openai/gpt-3.5-turbo-0613',
+ name: 'GPT-3.5 Turbo (older v0613)',
+ limit: {
+ context: 4095,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-audio': {
+ id: 'openai/gpt-audio',
+ name: 'GPT Audio',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
+ },
+ 'openai/o1': {
+ id: 'openai/o1',
+ name: 'o1',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/gpt-4o': {
+ id: 'openai/gpt-4o',
+ name: 'GPT-4o',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'amazon/nova-premier-v1': {
- id: 'amazon/nova-premier-v1',
- name: 'Nova Premier 1.0',
- limit: { context: 1000000 },
+ 'openai/gpt-5.6-luna': {
+ id: 'openai/gpt-5.6-luna',
+ name: 'GPT-5.6 Luna',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'amazon/nova-pro-v1': {
- id: 'amazon/nova-pro-v1',
- name: 'Nova Pro 1.0',
- limit: { context: 300000 },
+ 'openai/gpt-5.3-codex': {
+ id: 'openai/gpt-5.3-codex',
+ name: 'GPT-5.3 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'amazon/nova-micro-v1': {
- id: 'amazon/nova-micro-v1',
- name: 'Nova Micro 1.0',
- limit: { context: 128000 },
+ 'openai/gpt-4o-mini': {
+ id: 'openai/gpt-4o-mini',
+ name: 'GPT-4o mini',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/o1-pro': {
+ id: 'openai/o1-pro',
+ name: 'o1-pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/gpt-4.1': {
+ id: 'openai/gpt-4.1',
+ name: 'GPT-4.1',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'amazon/nova-2-lite-v1': {
- id: 'amazon/nova-2-lite-v1',
- name: 'Nova 2 Lite',
- limit: { context: 1000000 },
+ 'openai/gpt-5.4-nano': {
+ id: 'openai/gpt-5.4-nano',
+ name: 'GPT-5.4 nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'aion-labs/aion-3.0-mini': {
- id: 'aion-labs/aion-3.0-mini',
- name: 'Aion-3.0-Mini',
- limit: { context: 131072 },
+ 'openai/gpt-5.6-terra-pro': {
+ id: 'openai/gpt-5.6-terra-pro',
+ name: 'GPT-5.6 Terra Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'aion-labs/aion-rp-llama-3.1-8b': {
- id: 'aion-labs/aion-rp-llama-3.1-8b',
- name: 'Aion-RP 1.0 (8B)',
- limit: { context: 32768 },
+ 'openai/gpt-5.5-pro': {
+ id: 'openai/gpt-5.5-pro',
+ name: 'GPT-5.5 Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'aion-labs/aion-3.0': {
- id: 'aion-labs/aion-3.0',
- name: 'Aion-3.0',
- limit: { context: 131072 },
+ 'openai/gpt-chat-latest': {
+ id: 'openai/gpt-chat-latest',
+ name: 'GPT Chat Latest',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'aion-labs/aion-2.0': {
- id: 'aion-labs/aion-2.0',
- name: 'Aion-2.0',
- limit: { context: 131072 },
+ 'openai/gpt-5.4-mini': {
+ id: 'openai/gpt-5.4-mini',
+ name: 'GPT-5.4 mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'inflection/inflection-3-pi': {
- id: 'inflection/inflection-3-pi',
- name: 'Inflection 3 Pi',
- limit: { context: 8000 },
+ 'openai/gpt-3.5-turbo-16k': {
+ id: 'openai/gpt-3.5-turbo-16k',
+ name: 'GPT-3.5 Turbo 16k',
+ limit: {
+ context: 16385,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'inflection/inflection-3-productivity': {
- id: 'inflection/inflection-3-productivity',
- name: 'Inflection 3 Productivity',
- limit: { context: 8000 },
+ 'openai/gpt-5-image-mini': {
+ id: 'openai/gpt-5-image-mini',
+ name: 'GPT-5 Image Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
},
- 'sao10k/l3.1-euryale-70b': {
- id: 'sao10k/l3.1-euryale-70b',
- name: 'Llama 3.1 Euryale 70B v2.2',
- limit: { context: 131072 },
+ 'openai/gpt-3.5-turbo': {
+ id: 'openai/gpt-3.5-turbo',
+ name: 'GPT-3.5-turbo',
+ limit: {
+ context: 16385,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10k/l3.3-euryale-70b': {
- id: 'sao10k/l3.3-euryale-70b',
- name: 'Llama 3.3 Euryale 70B',
- limit: { context: 131072 },
+ 'openai/gpt-5-mini': {
+ id: 'openai/gpt-5-mini',
+ name: 'GPT-5 Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'sao10k/l3-lunaris-8b': {
- id: 'sao10k/l3-lunaris-8b',
- name: 'Llama 3 8B Lunaris',
- limit: { context: 8192 },
+ 'openai/gpt-oss-120b': {
+ id: 'openai/gpt-oss-120b',
+ name: 'GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10k/l3.1-70b-hanami-x1': {
- id: 'sao10k/l3.1-70b-hanami-x1',
- name: 'Llama 3.1 70B Hanami x1',
- limit: { context: 16000 },
+ 'openai/gpt-5.4-pro': {
+ id: 'openai/gpt-5.4-pro',
+ name: 'GPT-5.4 Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'upstage/solar-pro-3': {
- id: 'upstage/solar-pro-3',
- name: 'Solar Pro 3',
- limit: { context: 128000 },
+ 'openai/gpt-3.5-turbo-instruct': {
+ id: 'openai/gpt-3.5-turbo-instruct',
+ name: 'GPT-3.5 Turbo Instruct',
+ limit: {
+ context: 4095,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'allenai/olmo-3-32b-think': {
- id: 'allenai/olmo-3-32b-think',
- name: 'Olmo 3 32B Think',
- limit: { context: 65536 },
+ 'openai/gpt-5.6-terra': {
+ id: 'openai/gpt-5.6-terra',
+ name: 'GPT-5.6 Terra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/gpt-4': {
+ id: 'openai/gpt-4',
+ name: 'GPT-4',
+ limit: {
+ context: 8191,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-5.2': {
+ id: 'openai/gpt-5.2',
+ name: 'GPT-5.2',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['pdf', 'image', 'text'],
+ },
+ },
+ 'openai/gpt-5': {
+ id: 'openai/gpt-5',
+ name: 'GPT-5',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/o4-mini': {
+ id: 'openai/o4-mini',
+ name: 'o4-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['image', 'text', 'pdf'],
+ },
+ },
+ 'openai/o3-mini': {
+ id: 'openai/o3-mini',
+ name: 'o3-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'pdf'],
+ },
+ },
+ 'openai/o3': {
+ id: 'openai/o3',
+ name: 'o3',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'openai/o3-pro': {
+ id: 'openai/o3-pro',
+ name: 'o3-pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'pdf', 'image'],
+ },
+ },
+ 'openai/gpt-5.5': {
+ id: 'openai/gpt-5.5',
+ name: 'GPT-5.5',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'deepseek/deepseek-r1-0528': {
- id: 'deepseek/deepseek-r1-0528',
- name: 'R1 0528',
- limit: { context: 163840 },
+ 'openai/gpt-4o-2024-11-20': {
+ id: 'openai/gpt-4o-2024-11-20',
+ name: 'GPT-4o (2024-11-20)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ '~z-ai/glm-flash-latest': {
+ id: '~z-ai/glm-flash-latest',
+ name: 'GLM Flash Latest',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ '~z-ai/glm-latest': {
+ id: '~z-ai/glm-latest',
+ name: 'GLM Latest',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v4-flash': {
- id: 'deepseek/deepseek-v4-flash',
- name: 'DeepSeek V4 Flash',
- limit: { context: 1048576 },
+ 'moonshotai/kimi-k2-0905': {
+ id: 'moonshotai/kimi-k2-0905',
+ name: 'Kimi K2 0905',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3.1-terminus': {
- id: 'deepseek/deepseek-v3.1-terminus',
- name: 'DeepSeek V3.1 Terminus',
- limit: { context: 163840 },
+ 'moonshotai/kimi-k2.6': {
+ id: 'moonshotai/kimi-k2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'deepseek/deepseek-r1-distill-llama-70b': {
- id: 'deepseek/deepseek-r1-distill-llama-70b',
- name: 'R1 Distill Llama 70B',
- limit: { context: 128000 },
+ 'moonshotai/kimi-k2.7-code': {
+ id: 'moonshotai/kimi-k2.7-code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'deepseek/deepseek-v4-pro': {
- id: 'deepseek/deepseek-v4-pro',
- name: 'DeepSeek V4 Pro',
- limit: { context: 1048576 },
+ 'moonshotai/kimi-k2-thinking': {
+ id: 'moonshotai/kimi-k2-thinking',
+ name: 'Kimi K2 Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k3': {
+ id: 'moonshotai/kimi-k3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'deepseek/deepseek-r1': {
- id: 'deepseek/deepseek-r1',
- name: 'DeepSeek-R1',
- limit: { context: 163840 },
+ 'moonshotai/kimi-k2': {
+ id: 'moonshotai/kimi-k2',
+ name: 'Kimi K2 0711',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3.2-exp': {
- id: 'deepseek/deepseek-v3.2-exp',
- name: 'DeepSeek V3.2 Exp',
- limit: { context: 163840 },
+ 'moonshotai/kimi-k2.5': {
+ id: 'moonshotai/kimi-k2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'inference-net/schematron-v2-small': {
+ id: 'inference-net/schematron-v2-small',
+ name: 'Schematron V2 Small',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'inference-net/schematron-v2-turbo': {
+ id: 'inference-net/schematron-v2-turbo',
+ name: 'Schematron V2 Turbo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-chat-v3-0324': {
- id: 'deepseek/deepseek-chat-v3-0324',
- name: 'DeepSeek V3 0324',
- limit: { context: 163840 },
+ 'cohere/north-mini-code:free': {
+ id: 'cohere/north-mini-code:free',
+ name: 'North Mini Code (free)',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-chat': {
- id: 'deepseek/deepseek-chat',
- name: 'DeepSeek Chat',
- limit: { context: 131072 },
+ 'cohere/command-r-plus-08-2024': {
+ id: 'cohere/command-r-plus-08-2024',
+ name: 'Command R+',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'cohere/command-a': {
+ id: 'cohere/command-a',
+ name: 'Command A',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3.2': {
- id: 'deepseek/deepseek-v3.2',
- name: 'DeepSeek V3.2',
- limit: { context: 131072 },
+ 'cohere/command-r7b-12-2024': {
+ id: 'cohere/command-r7b-12-2024',
+ name: 'Command R7B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-chat-v3.1': {
- id: 'deepseek/deepseek-chat-v3.1',
- name: 'DeepSeek V3.1',
- limit: { context: 163840 },
+ 'cohere/command-r-08-2024': {
+ id: 'cohere/command-r-08-2024',
+ name: 'Command R',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.5': {
- id: 'minimax/minimax-m2.5',
- name: 'MiniMax-M2.5',
- limit: { context: 204800 },
+ 'upstage/solar-pro-3': {
+ id: 'upstage/solar-pro-3',
+ name: 'Solar Pro 3',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'upstage/solar-pro4': {
+ id: 'upstage/solar-pro4',
+ name: 'Solar Pro 4',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.1': {
- id: 'minimax/minimax-m2.1',
- name: 'MiniMax-M2.1',
- limit: { context: 204800 },
+ 'arcee-ai/trinity-large-thinking': {
+ id: 'arcee-ai/trinity-large-thinking',
+ name: 'Trinity Large Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'tencent/hy3': {
+ id: 'tencent/hy3',
+ name: 'Hy3',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'tencent/hy4-preview': {
+ id: 'tencent/hy4-preview',
+ name: 'Hy4 preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'tencent/hy-mt2-30b-a3b': {
+ id: 'tencent/hy-mt2-30b-a3b',
+ name: 'Hy-MT2-30B-A3B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'tencent/hy-mt2-7b': {
+ id: 'tencent/hy-mt2-7b',
+ name: 'Hy-MT2-7B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'tencent/hy-mt2-1.8b': {
+ id: 'tencent/hy-mt2-1.8b',
+ name: 'Hy-MT2-1.8B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-01': {
- id: 'minimax/minimax-01',
- name: 'MiniMax-01',
- limit: { context: 1000192 },
+ 'tencent/hy3-preview': {
+ id: 'tencent/hy3-preview',
+ name: 'Hy3 preview',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m3': {
- id: 'minimax/minimax-m3',
- name: 'MiniMax-M3',
- limit: { context: 1048576 },
+ 'tencent/hunyuan-a13b-instruct': {
+ id: 'tencent/hunyuan-a13b-instruct',
+ name: 'Hunyuan A13B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'liquid/lfm-2.5-2.6b:free': {
+ id: 'liquid/lfm-2.5-2.6b:free',
+ name: 'LFM2.5-2.6B (free)',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-4.7': {
+ id: 'z-ai/glm-4.7',
+ name: 'GLM-4.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2': {
- id: 'minimax/minimax-m2',
- name: 'MiniMax-M2',
- limit: { context: 204800 },
+ 'z-ai/glm-4.5-air': {
+ id: 'z-ai/glm-4.5-air',
+ name: 'GLM-4.5-Air',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-4.6': {
+ id: 'z-ai/glm-4.6',
+ name: 'GLM-4.6',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-4.6v': {
+ id: 'z-ai/glm-4.6v',
+ name: 'GLM-4.6V',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'z-ai/glm-5.2': {
+ id: 'z-ai/glm-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-5.3-flash': {
+ id: 'z-ai/glm-5.3-flash',
+ name: 'GLM-5.3-Flash',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'z-ai/glm-4.5': {
+ id: 'z-ai/glm-4.5',
+ name: 'GLM-4.5',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-4.5v': {
+ id: 'z-ai/glm-4.5v',
+ name: 'GLM-4.5V',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'z-ai/glm-5.2:free': {
+ id: 'z-ai/glm-5.2:free',
+ name: 'GLM 5.2 (free)',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-5': {
+ id: 'z-ai/glm-5',
+ name: 'GLM-5',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-5.1': {
+ id: 'z-ai/glm-5.1',
+ name: 'GLM-5.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2-her': {
- id: 'minimax/minimax-m2-her',
- name: 'MiniMax M2-her',
- limit: { context: 65536 },
+ 'z-ai/glm-5-turbo': {
+ id: 'z-ai/glm-5-turbo',
+ name: 'GLM-5-Turbo',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'z-ai/glm-5.3': {
+ id: 'z-ai/glm-5.3',
+ name: 'GLM-5.3',
+ limit: {
+ context: 1310720,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.7': {
- id: 'minimax/minimax-m2.7',
- name: 'MiniMax-M2.7',
- limit: { context: 204800 },
+ 'z-ai/glm-5v-turbo': {
+ id: 'z-ai/glm-5v-turbo',
+ name: 'GLM-5V-Turbo',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'minimax/minimax-m1': {
- id: 'minimax/minimax-m1',
- name: 'MiniMax M1',
- limit: { context: 1000000 },
+ 'z-ai/glm-4.7-flash': {
+ id: 'z-ai/glm-4.7-flash',
+ name: 'GLM-4.7-Flash',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'kwaipilot/kat-coder-pro-v2': {
- id: 'kwaipilot/kat-coder-pro-v2',
- name: 'KAT-Coder-Pro V2',
- limit: { context: 256000 },
+ 'cognitivecomputations/dolphin-mistral-24b-venice-edition': {
+ id: 'cognitivecomputations/dolphin-mistral-24b-venice-edition',
+ name: 'Uncensored',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nousresearch/hermes-3-llama-3.1-405b:free': {
- id: 'nousresearch/hermes-3-llama-3.1-405b:free',
- name: 'Hermes 3 405B Instruct (free)',
- limit: { context: 131072 },
+ 'perplexity/sonar-pro-search': {
+ id: 'perplexity/sonar-pro-search',
+ name: 'Sonar Pro Search',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'perplexity/sonar': {
+ id: 'perplexity/sonar',
+ name: 'Sonar',
+ limit: {
+ context: 127072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'nousresearch/hermes-4-405b': {
- id: 'nousresearch/hermes-4-405b',
- name: 'Hermes 4 405B',
- limit: { context: 131072 },
+ 'perplexity/sonar-reasoning-pro': {
+ id: 'perplexity/sonar-reasoning-pro',
+ name: 'Sonar Reasoning Pro',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'nousresearch/hermes-3-llama-3.1-70b': {
- id: 'nousresearch/hermes-3-llama-3.1-70b',
- name: 'Hermes 3 70B Instruct',
- limit: { context: 131072 },
+ 'perplexity/sonar-pro': {
+ id: 'perplexity/sonar-pro',
+ name: 'Sonar Pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'nousresearch/hermes-3-llama-3.1-405b': {
- id: 'nousresearch/hermes-3-llama-3.1-405b',
- name: 'Hermes 3 405B Instruct',
- limit: { context: 131072 },
+ 'perplexity/sonar-deep-research': {
+ id: 'perplexity/sonar-deep-research',
+ name: 'Sonar Deep Research',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'rekaai/reka-edge': {
+ id: 'rekaai/reka-edge',
+ name: 'Reka Edge',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['image', 'text', 'video'],
+ },
},
- 'nousresearch/hermes-4-70b': {
- id: 'nousresearch/hermes-4-70b',
- name: 'Hermes 4 70B',
- limit: { context: 131072 },
+ 'rekaai/reka-flash-3': {
+ id: 'rekaai/reka-flash-3',
+ name: 'Reka Flash 3',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
},
},
google: {
name: 'Google',
models: {
- 'gemini-3.1-flash-lite': {
- id: 'gemini-3.1-flash-lite',
- name: 'Gemini 3.1 Flash Lite',
- limit: { context: 1048576 },
+ 'gemma-4-26b-a4b-it': {
+ id: 'gemma-4-26b-a4b-it',
+ name: 'Gemma 4 26B A4B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gemini-2.5-flash-preview-tts': {
- id: 'gemini-2.5-flash-preview-tts',
- name: 'Gemini 2.5 Flash Preview TTS',
- limit: { context: 8192 },
+ 'gemini-3.1-pro-preview-customtools': {
+ id: 'gemini-3.1-pro-preview-customtools',
+ name: 'Gemini 3.1 Pro Preview Custom Tools',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.1-flash-lite-image': {
+ id: 'gemini-3.1-flash-lite-image',
+ name: 'Nano Banana 2 Lite',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'lyria-3-clip-preview': {
+ id: 'lyria-3-clip-preview',
+ name: 'Lyria 3 Clip Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gemini-2.5-pro': {
- id: 'gemini-2.5-pro',
- name: 'Gemini 2.5 Pro',
- limit: { context: 1048576 },
+ 'gemini-2.5-flash-image': {
+ id: 'gemini-2.5-flash-image',
+ name: 'Nano Banana',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'deep-research-max-preview-04-2026': {
+ id: 'deep-research-max-preview-04-2026',
+ name: 'Deep Research Max Preview (Apr-21-2026)',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3-pro-image': {
+ id: 'gemini-3-pro-image',
+ name: 'Nano Banana Pro',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-3.1-pro-preview': {
+ id: 'gemini-3.1-pro-preview',
+ name: 'Gemini 3.1 Pro Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'deep-research-preview-04-2026': {
+ id: 'deep-research-preview-04-2026',
+ name: 'Deep Research Preview (Apr-21-2026)',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-2.5-flash-lite': {
+ id: 'gemini-2.5-flash-lite',
+ name: 'Gemini 2.5 Flash-Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
+ },
+ 'gemini-2.5-computer-use-preview-10-2025': {
+ id: 'gemini-2.5-computer-use-preview-10-2025',
+ name: 'Gemini 2.5 Computer Use Preview 10-2025',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-3.6-flash': {
+ id: 'gemini-3.6-flash',
+ name: 'Gemini 3.6 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.1-flash-lite': {
+ id: 'gemini-3.1-flash-lite',
+ name: 'Gemini 3.1 Flash Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.1-flash-live-preview': {
+ id: 'gemini-3.1-flash-live-preview',
+ name: 'Gemini 3.1 Flash Live Preview',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
},
- 'gemini-2.5-flash': {
- id: 'gemini-2.5-flash',
- name: 'Gemini 2.5 Flash',
- limit: { context: 1048576 },
+ 'gemini-2.5-pro-preview-tts': {
+ id: 'gemini-2.5-pro-preview-tts',
+ name: 'Gemini 2.5 Pro Preview TTS',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'gemini-3.5-flash': {
id: 'gemini-3.5-flash',
name: 'Gemini 3.5 Flash',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'veo-3.1-generate-preview': {
+ id: 'veo-3.1-generate-preview',
+ name: 'Veo 3.1',
+ limit: {
+ context: 480,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gemma-4-31b-it': {
- id: 'gemma-4-31b-it',
- name: 'Gemma 4 31B IT',
- limit: { context: 262144 },
+ 'gemini-3.1-flash-lite-preview': {
+ id: 'gemini-3.1-flash-lite-preview',
+ name: 'Gemini 3.1 Flash Lite Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'veo-3.1-fast-generate-preview': {
+ id: 'veo-3.1-fast-generate-preview',
+ name: 'Veo 3.1 fast',
+ limit: {
+ context: 480,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'gemini-2.0-flash': {
- id: 'gemini-2.0-flash',
- name: 'Gemini 2.0 Flash',
- limit: { context: 1048576 },
+ 'gemini-2.5-flash-preview-tts': {
+ id: 'gemini-2.5-flash-preview-tts',
+ name: 'Gemini 2.5 Flash Preview TTS',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'gemini-embedding-001': {
id: 'gemini-embedding-001',
name: 'Gemini Embedding 001',
- limit: { context: 2048 },
- },
- 'gemini-3.1-pro-preview-customtools': {
- id: 'gemini-3.1-pro-preview-customtools',
- name: 'Gemini 3.1 Pro Preview Custom Tools',
- limit: { context: 1048576 },
+ limit: {
+ context: 2048,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'gemini-flash-lite-latest': {
- id: 'gemini-flash-lite-latest',
- name: 'Gemini Flash-Lite Latest',
- limit: { context: 1048576 },
+ 'gemini-3.1-flash-image': {
+ id: 'gemini-3.1-flash-image',
+ name: 'Nano Banana 2',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'gemini-3.5-flash-lite': {
+ id: 'gemini-3.5-flash-lite',
+ name: 'Gemini 3.5 Flash Lite',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
'gemini-3-pro-image-preview': {
id: 'gemini-3-pro-image-preview',
name: 'Nano Banana Pro',
- limit: { context: 131072 },
- },
- 'gemini-2.5-flash-image': {
- id: 'gemini-2.5-flash-image',
- name: 'Nano Banana',
- limit: { context: 32768 },
- },
- 'gemini-2.5-flash-lite': {
- id: 'gemini-2.5-flash-lite',
- name: 'Gemini 2.5 Flash-Lite',
- limit: { context: 1048576 },
- },
- 'gemini-omni-flash-preview': {
- id: 'gemini-omni-flash-preview',
- name: 'Gemini Omni Flash Preview',
- limit: { context: 131072 },
- },
- 'gemini-3.1-flash-image-preview': {
- id: 'gemini-3.1-flash-image-preview',
- name: 'Nano Banana 2',
- limit: { context: 65536 },
- },
- 'gemini-3.1-pro-preview': {
- id: 'gemini-3.1-pro-preview',
- name: 'Gemini 3.1 Pro Preview',
- limit: { context: 1048576 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-3.1-flash-tts-preview': {
+ id: 'gemini-3.1-flash-tts-preview',
+ name: 'Gemini 3.1 Flash TTS Preview',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'veo-3.1-lite-generate-preview': {
+ id: 'veo-3.1-lite-generate-preview',
+ name: 'Veo 3.1 lite',
+ limit: {
+ context: 480,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gemma-4-26b-a4b-it': {
- id: 'gemma-4-26b-a4b-it',
- name: 'Gemma 4 26B A4B IT',
- limit: { context: 262144 },
+ 'gemini-flash-lite-latest': {
+ id: 'gemini-flash-lite-latest',
+ name: 'Gemini Flash-Lite Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'gemini-3-pro-preview': {
- id: 'gemini-3-pro-preview',
- name: 'Gemini 3 Pro Preview',
- limit: { context: 1048576 },
+ 'gemma-4-31b-it': {
+ id: 'gemma-4-31b-it',
+ name: 'Gemma 4 31B IT',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-embedding-2': {
+ id: 'gemini-embedding-2',
+ name: 'Gemini Embedding 2',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
'gemini-3-flash-preview': {
id: 'gemini-3-flash-preview',
name: 'Gemini 3 Flash Preview',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.8-flash': {
+ id: 'gemini-3.8-flash',
+ name: 'Gemini 3.8 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
+ },
+ 'gemini-3.5-live-translate-preview': {
+ id: 'gemini-3.5-live-translate-preview',
+ name: 'Gemini 3.5 Live Translate Preview',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['audio'],
+ },
+ },
+ 'lyria-3-pro-preview': {
+ id: 'lyria-3-pro-preview',
+ name: 'Lyria 3 Pro Preview',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gemini-3.7-flash': {
+ id: 'gemini-3.7-flash',
+ name: 'Gemini 3.7 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'gemini-2.5-pro-preview-tts': {
- id: 'gemini-2.5-pro-preview-tts',
- name: 'Gemini 2.5 Pro Preview TTS',
- limit: { context: 8192 },
+ 'gemini-2.5-pro': {
+ id: 'gemini-2.5-pro',
+ name: 'Gemini 2.5 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
'gemini-flash-latest': {
id: 'gemini-flash-latest',
name: 'Gemini Flash Latest',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio', 'pdf'],
+ },
},
- 'gemini-3.1-flash-lite-preview': {
- id: 'gemini-3.1-flash-lite-preview',
- name: 'Gemini 3.1 Flash Lite Preview',
- limit: { context: 1048576 },
+ 'gemini-3.1-flash-image-preview': {
+ id: 'gemini-3.1-flash-image-preview',
+ name: 'Nano Banana 2',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gemini-omni-flash-preview': {
+ id: 'gemini-omni-flash-preview',
+ name: 'Gemini Omni Flash Preview',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'gemini-2.0-flash-lite': {
- id: 'gemini-2.0-flash-lite',
- name: 'Gemini 2.0 Flash-Lite',
- limit: { context: 1048576 },
+ 'gemini-2.5-flash': {
+ id: 'gemini-2.5-flash',
+ name: 'Gemini 2.5 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video', 'pdf'],
+ },
},
},
},
deepseek: {
name: 'DeepSeek',
models: {
+ 'deepseek-v4-flash-vision-exp': {
+ id: 'deepseek-v4-flash-vision-exp',
+ name: 'DeepSeek V4 Flash Vision Exp',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
'deepseek-v4-flash': {
id: 'deepseek-v4-flash',
name: 'DeepSeek V4 Flash',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'deepseek-v4-pro': {
id: 'deepseek-v4-pro',
name: 'DeepSeek V4 Pro',
- limit: { context: 1000000 },
- },
- 'deepseek-reasoner': {
- id: 'deepseek-reasoner',
- name: 'DeepSeek Reasoner',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-flash': {
+ id: 'deepseek-flash',
+ name: 'DeepSeek V4.1 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'deepseek-chat': { id: 'deepseek-chat', name: 'DeepSeek Chat', limit: { context: 1000000 } },
},
},
groq: {
name: 'Groq',
models: {
- 'llama-3.3-70b-versatile': {
- id: 'llama-3.3-70b-versatile',
- name: 'Llama 3.3 70B',
- limit: { context: 131072 },
+ 'whisper-large-v3': {
+ id: 'whisper-large-v3',
+ name: 'Whisper',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['audio'],
+ },
+ },
+ 'whisper-large-v3-turbo': {
+ id: 'whisper-large-v3-turbo',
+ name: 'Whisper Large V3 Turbo',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['audio'],
+ },
},
'llama-3.1-8b-instant': {
id: 'llama-3.1-8b-instant',
name: 'Llama 3.1 8B',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'allam-2-7b': {
+ id: 'allam-2-7b',
+ name: 'ALLaM-2-7b',
+ limit: {
+ context: 4096,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'llama-3.3-70b-versatile': {
+ id: 'llama-3.3-70b-versatile',
+ name: 'Llama 3.3 70B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3.8-27b': {
+ id: 'qwen/qwen3.8-27b',
+ name: 'Qwen3.8 27B',
+ limit: {
+ context: 131042,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'qwen/qwen3.6-27b': {
+ id: 'qwen/qwen3.6-27b',
+ name: 'Qwen3.6 27B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'groq/compound': {
+ id: 'groq/compound',
+ name: 'Compound',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'groq/compound-mini': {
+ id: 'groq/compound-mini',
+ name: 'Compound Mini',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'whisper-large-v3-turbo': { id: 'whisper-large-v3-turbo', name: 'Whisper Large V3 Turbo' },
- 'whisper-large-v3': { id: 'whisper-large-v3', name: 'Whisper' },
'meta-llama/llama-prompt-guard-2-86m': {
id: 'meta-llama/llama-prompt-guard-2-86m',
name: 'Prompt Guard 2 86M',
- limit: { context: 512 },
+ limit: {
+ context: 512,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'meta-llama/llama-prompt-guard-2-22m': {
id: 'meta-llama/llama-prompt-guard-2-22m',
name: 'Llama Prompt Guard 2 22M',
- limit: { context: 512 },
+ limit: {
+ context: 512,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta-llama/llama-4-scout-17b-16e-instruct': {
- id: 'meta-llama/llama-4-scout-17b-16e-instruct',
- name: 'Llama 4 Scout 17B 16E',
- limit: { context: 131072 },
+ 'openai/gpt-oss-20b': {
+ id: 'openai/gpt-oss-20b',
+ name: 'GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'openai/gpt-oss-safeguard-20b': {
id: 'openai/gpt-oss-safeguard-20b',
name: 'Safety GPT OSS 20B',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'openai/gpt-oss-120b': {
id: 'openai/gpt-oss-120b',
name: 'GPT OSS 120B',
- limit: { context: 131072 },
- },
- 'openai/gpt-oss-20b': {
- id: 'openai/gpt-oss-20b',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'canopylabs/orpheus-v1-english': {
id: 'canopylabs/orpheus-v1-english',
name: 'Canopy Labs Orpheus V1 English',
- limit: { context: 4000 },
+ limit: {
+ context: 4000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'canopylabs/orpheus-arabic-saudi': {
id: 'canopylabs/orpheus-arabic-saudi',
name: 'Canopy Labs Orpheus Arabic Saudi',
- limit: { context: 4000 },
- },
- 'groq/compound': { id: 'groq/compound', name: 'Compound', limit: { context: 131072 } },
- 'groq/compound-mini': {
- id: 'groq/compound-mini',
- name: 'Compound Mini',
- limit: { context: 131072 },
+ limit: {
+ context: 4000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-32b': { id: 'qwen/qwen3-32b', name: 'Qwen3-32B', limit: { context: 131072 } },
},
},
togetherai: {
name: 'Together AI',
models: {
- 'LiquidAI/LFM2-24B-A2B': {
- id: 'LiquidAI/LFM2-24B-A2B',
- name: 'LFM2-24B-A2B',
- limit: { context: 32768 },
+ 'essentialai/Rnj-1-Instruct': {
+ id: 'essentialai/Rnj-1-Instruct',
+ name: 'Rnj-1 Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta-llama/Meta-Llama-3-8B-Instruct-Lite': {
- id: 'meta-llama/Meta-Llama-3-8B-Instruct-Lite',
- name: 'Meta Llama 3 8B Instruct Lite',
- limit: { context: 8192 },
+ 'deepseek-ai/DeepSeek-V3-1': {
+ id: 'deepseek-ai/DeepSeek-V3-1',
+ name: 'DeepSeek V3.1',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta-llama/Llama-3.3-70B-Instruct-Turbo': {
- id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
- name: 'Llama 3.3 70B',
- limit: { context: 131072 },
+ 'deepseek-ai/DeepSeek-V3': {
+ id: 'deepseek-ai/DeepSeek-V3',
+ name: 'DeepSeek-V3',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4-Flash-0731': {
+ id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4.1-Flash': {
+ id: 'deepseek-ai/DeepSeek-V4.1-Flash',
+ name: 'DeepSeek V4.1 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4-Pro-0813': {
+ id: 'deepseek-ai/DeepSeek-V4-Pro-0813',
+ name: 'DeepSeek V4 Pro 0813',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.6': {
- id: 'moonshotai/Kimi-K2.6',
- name: 'Kimi K2.6',
- limit: { context: 262144 },
+ 'deepseek-ai/DeepSeek-R1': {
+ id: 'deepseek-ai/DeepSeek-R1',
+ name: 'DeepSeek-R1',
+ limit: {
+ context: 163839,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.5': {
- id: 'moonshotai/Kimi-K2.5',
- name: 'Kimi K2.5',
- limit: { context: 262144 },
+ 'deepseek-ai/DeepSeek-V4-Pro': {
+ id: 'deepseek-ai/DeepSeek-V4-Pro',
+ name: 'DeepSeek V4 Pro',
+ limit: {
+ context: 512000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.7-Code': {
- id: 'moonshotai/Kimi-K2.7-Code',
- name: 'Kimi K2.7 Code',
- limit: { context: 262144 },
+ 'pearl-ai/gemma-4-31b-it': {
+ id: 'pearl-ai/gemma-4-31b-it',
+ name: 'Pearl AI Gemma 4 31B Instruct',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/nemotron-3-ultra-550b-a55b': {
+ id: 'nvidia/nemotron-3-ultra-550b-a55b',
+ name: 'Nemotron 3 Ultra 550B A55B',
+ limit: {
+ context: 512300,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'google/gemma-4-31B-it': {
id: 'google/gemma-4-31B-it',
name: 'Gemma 4 31B Instruct',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'google/gemma-3n-E4B-it': {
id: 'google/gemma-3n-E4B-it',
name: 'Gemma 3N E4B Instruct',
- limit: { context: 32768 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.1': {
+ id: 'zai-org/GLM-5.1',
+ name: 'GLM-5.1',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.3': {
+ id: 'zai-org/GLM-5.3',
+ name: 'GLM-5.3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.2': {
+ id: 'zai-org/GLM-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 512000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5': {
+ id: 'zai-org/GLM-5',
+ name: 'GLM-5',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.3-Flash': {
+ id: 'zai-org/GLM-5.3-Flash',
+ name: 'GLM-5.3-Flash',
+ limit: {
+ context: 1048575,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'LiquidAI/LFM2-24B-A2B': {
+ id: 'LiquidAI/LFM2-24B-A2B',
+ name: 'LFM2-24B-A2B',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'thinkingmachines/Inkling': {
+ id: 'thinkingmachines/Inkling',
+ name: 'Inkling',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
},
'Qwen/Qwen3.7-Max': {
id: 'Qwen/Qwen3.7-Max',
name: 'Qwen3.7 Max',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput': {
+ id: 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput',
+ name: 'Qwen3 235B A22B Instruct 2507 FP8',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'Qwen/Qwen3.6-Plus': {
id: 'Qwen/Qwen3.6-Plus',
name: 'Qwen3.6 Plus',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'Qwen/Qwen3.5-9B': {
+ id: 'Qwen/Qwen3.5-9B',
+ name: 'Qwen3.5 9B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'Qwen/Qwen3.5-397B-A17B': {
id: 'Qwen/Qwen3.5-397B-A17B',
name: 'Qwen3.5 397B A17B',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3-Coder-Next-FP8': {
- id: 'Qwen/Qwen3-Coder-Next-FP8',
- name: 'Qwen3 Coder Next FP8',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8': {
id: 'Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8',
name: 'Qwen3 Coder 480B A35B Instruct',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput': {
- id: 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput',
- name: 'Qwen3 235B A22B Instruct 2507 FP8',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'Qwen/Qwen2.5-7B-Instruct-Turbo': {
id: 'Qwen/Qwen2.5-7B-Instruct-Turbo',
name: 'Qwen 2.5 7B Instruct Turbo',
- limit: { context: 32768 },
- },
- 'Qwen/Qwen3.5-9B': { id: 'Qwen/Qwen3.5-9B', name: 'Qwen3.5 9B', limit: { context: 262144 } },
- 'openai/gpt-oss-120b': {
- id: 'openai/gpt-oss-120b',
- name: 'GPT OSS 120B',
- limit: { context: 131072 },
- },
- 'openai/gpt-oss-20b': {
- id: 'openai/gpt-oss-20b',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
- },
- 'pearl-ai/gemma-4-31b-it': {
- id: 'pearl-ai/gemma-4-31b-it',
- name: 'Pearl AI Gemma 4 31B Instruct',
- limit: { context: 32000 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/nemotron-3-ultra-550b-a55b': {
- id: 'nvidia/nemotron-3-ultra-550b-a55b',
- name: 'Nemotron 3 Ultra 550B A55B',
- limit: { context: 512300 },
+ 'Qwen/Qwen3-Coder-Next-FP8': {
+ id: 'Qwen/Qwen3-Coder-Next-FP8',
+ name: 'Qwen3 Coder Next FP8',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepcogito/cogito-v2-1-671b': {
id: 'deepcogito/cogito-v2-1-671b',
name: 'Cogito v2.1 671B',
- limit: { context: 163840 },
- },
- 'zai-org/GLM-5': { id: 'zai-org/GLM-5', name: 'GLM-5', limit: { context: 202752 } },
- 'zai-org/GLM-5.2': { id: 'zai-org/GLM-5.2', name: 'GLM-5.2', limit: { context: 262144 } },
- 'zai-org/GLM-5.1': { id: 'zai-org/GLM-5.1', name: 'GLM-5.1', limit: { context: 202752 } },
- 'deepseek-ai/DeepSeek-R1': {
- id: 'deepseek-ai/DeepSeek-R1',
- name: 'DeepSeek-R1',
- limit: { context: 163839 },
- },
- 'deepseek-ai/DeepSeek-V3-1': {
- id: 'deepseek-ai/DeepSeek-V3-1',
- name: 'DeepSeek V3.1',
- limit: { context: 131072 },
- },
- 'deepseek-ai/DeepSeek-V4-Pro': {
- id: 'deepseek-ai/DeepSeek-V4-Pro',
- name: 'DeepSeek V4 Pro',
- limit: { context: 512000 },
- },
- 'deepseek-ai/DeepSeek-V3': {
- id: 'deepseek-ai/DeepSeek-V3',
- name: 'DeepSeek-V3',
- limit: { context: 131072 },
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'MiniMaxAI/MiniMax-M2.5': {
id: 'MiniMaxAI/MiniMax-M2.5',
name: 'MiniMax-M2.5',
- limit: { context: 204800 },
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'MiniMaxAI/MiniMax-M3': {
id: 'MiniMaxAI/MiniMax-M3',
name: 'MiniMax-M3',
- limit: { context: 524288 },
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'MiniMaxAI/MiniMax-M2.7': {
id: 'MiniMaxAI/MiniMax-M2.7',
name: 'MiniMax-M2.7',
- limit: { context: 202752 },
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'essentialai/Rnj-1-Instruct': {
- id: 'essentialai/Rnj-1-Instruct',
- name: 'Rnj-1 Instruct',
- limit: { context: 32768 },
+ 'meta-llama/Llama-3.3-70B-Instruct-Turbo': {
+ id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+ name: 'Llama 3.3 70B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta-llama/Meta-Llama-3-8B-Instruct-Lite': {
+ id: 'meta-llama/Meta-Llama-3-8B-Instruct-Lite',
+ name: 'Meta Llama 3 8B Instruct Lite',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-oss-20b': {
+ id: 'openai/gpt-oss-20b',
+ name: 'GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-oss-120b': {
+ id: 'openai/gpt-oss-120b',
+ name: 'GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/Kimi-K2.5': {
+ id: 'moonshotai/Kimi-K2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'moonshotai/Kimi-K2.7-Code': {
+ id: 'moonshotai/Kimi-K2.7-Code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/Kimi-K2.6': {
+ id: 'moonshotai/Kimi-K2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/Kimi-K3': {
+ id: 'moonshotai/Kimi-K3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
},
},
'fireworks-ai': {
name: 'Fireworks AI',
models: {
- 'accounts/fireworks/routers/kimi-k2p6-turbo': {
- id: 'accounts/fireworks/routers/kimi-k2p6-turbo',
- name: 'Kimi K2.6 Turbo',
- limit: { context: 262000 },
+ 'accounts/fireworks/routers/kimi-latest': {
+ id: 'accounts/fireworks/routers/kimi-latest',
+ name: 'Kimi Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/routers/qwen-max-latest': {
+ id: 'accounts/fireworks/routers/qwen-max-latest',
+ name: 'Qwen Max Latest (Qwen3.8 Max)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/routers/kimi-k3-fast': {
+ id: 'accounts/fireworks/routers/kimi-k3-fast',
+ name: 'Kimi K3 Fast',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/routers/glm-flash-latest': {
+ id: 'accounts/fireworks/routers/glm-flash-latest',
+ name: 'GLM Flash Latest (GLM 5.3 Flash)',
+ limit: {
+ context: 1048573,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/routers/minimax-latest': {
+ id: 'accounts/fireworks/routers/minimax-latest',
+ name: 'MiniMax Latest',
+ limit: {
+ context: 512000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/glm-fast-latest': {
+ id: 'accounts/fireworks/routers/glm-fast-latest',
+ name: 'GLM 5.3 Fast (Latest)',
+ limit: {
+ context: 1048572,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/deepseek-pro-latest': {
+ id: 'accounts/fireworks/routers/deepseek-pro-latest',
+ name: 'DeepSeek Pro Latest',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/glm-5p3-fast': {
+ id: 'accounts/fireworks/routers/glm-5p3-fast',
+ name: 'GLM 5.3 Fast',
+ limit: {
+ context: 1048572,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/glm-latest': {
+ id: 'accounts/fireworks/routers/glm-latest',
+ name: 'GLM Latest',
+ limit: {
+ context: 1048573,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/kimi-fast-latest': {
+ id: 'accounts/fireworks/routers/kimi-fast-latest',
+ name: 'Kimi Fast Latest',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'accounts/fireworks/routers/glm-5p2-fast': {
id: 'accounts/fireworks/routers/glm-5p2-fast',
name: 'GLM 5.2 Fast',
- limit: { context: 1048575 },
- },
- 'accounts/fireworks/routers/kimi-k2p7-code-fast': {
- id: 'accounts/fireworks/routers/kimi-k2p7-code-fast',
- name: 'Kimi K2.7 Code Fast',
- limit: { context: 262000 },
- },
- 'accounts/fireworks/routers/glm-5p1-fast': {
- id: 'accounts/fireworks/routers/glm-5p1-fast',
- name: 'GLM 5.1 Fast',
- limit: { context: 202800 },
- },
- 'accounts/fireworks/routers/kimi-k2p6-fast': {
- id: 'accounts/fireworks/routers/kimi-k2p6-fast',
- name: 'Kimi K2.6 Fast',
- limit: { context: 262000 },
- },
- 'accounts/fireworks/models/deepseek-v4-flash': {
- id: 'accounts/fireworks/models/deepseek-v4-flash',
- name: 'DeepSeek V4 Flash',
- limit: { context: 1000000 },
- },
- 'accounts/fireworks/models/deepseek-v4-pro': {
- id: 'accounts/fireworks/models/deepseek-v4-pro',
- name: 'DeepSeek V4 Pro',
- limit: { context: 1000000 },
+ limit: {
+ context: 1048575,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/routers/deepseek-flash-latest': {
+ id: 'accounts/fireworks/routers/deepseek-flash-latest',
+ name: 'DeepSeek Flash Latest',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'accounts/fireworks/models/minimax-m2p7': {
- id: 'accounts/fireworks/models/minimax-m2p7',
- name: 'MiniMax-M2.7',
- limit: { context: 196608 },
+ 'accounts/fireworks/models/qwen3p7-plus': {
+ id: 'accounts/fireworks/models/qwen3p7-plus',
+ name: 'Qwen 3.7 Plus',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/deepseek-v4-flash-vision-exp': {
+ id: 'accounts/fireworks/models/deepseek-v4-flash-vision-exp',
+ name: 'DeepSeek V4 Flash Vision Exp',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/deepseek-v4-pro-0813': {
+ id: 'accounts/fireworks/models/deepseek-v4-pro-0813',
+ name: 'DeepSeek V4 Pro 0813',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/deepseek-v4-flash-0731': {
+ id: 'accounts/fireworks/models/deepseek-v4-flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'accounts/fireworks/models/minimax-m3': {
id: 'accounts/fireworks/models/minimax-m3',
name: 'MiniMax-M3',
- limit: { context: 512000 },
+ limit: {
+ context: 512000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/deepseek-v4p1-flash': {
+ id: 'accounts/fireworks/models/deepseek-v4p1-flash',
+ name: 'DeepSeek V4.1 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'accounts/fireworks/models/kimi-k2p6': {
id: 'accounts/fireworks/models/kimi-k2p6',
name: 'Kimi K2.6',
- limit: { context: 262000 },
+ limit: {
+ context: 262000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/nemotron-3-ultra-nvfp4': {
+ id: 'accounts/fireworks/models/nemotron-3-ultra-nvfp4',
+ name: 'Nemotron 3 Ultra 550B A55B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/kimi-k3': {
+ id: 'accounts/fireworks/models/kimi-k3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/glm-5p3': {
+ id: 'accounts/fireworks/models/glm-5p3',
+ name: 'GLM 5.3',
+ limit: {
+ context: 1048573,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'accounts/fireworks/models/qwen3p7-plus': {
- id: 'accounts/fireworks/models/qwen3p7-plus',
- name: 'Qwen 3.7 Plus',
- limit: { context: 262144 },
+ 'accounts/fireworks/models/kimi-k2p7-code': {
+ id: 'accounts/fireworks/models/kimi-k2p7-code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/glm-5p3-flash': {
+ id: 'accounts/fireworks/models/glm-5p3-flash',
+ name: 'GLM 5.3 Flash',
+ limit: {
+ context: 1048573,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'accounts/fireworks/models/glm-5p1': {
- id: 'accounts/fireworks/models/glm-5p1',
- name: 'GLM 5.1',
- limit: { context: 202800 },
+ 'accounts/fireworks/models/minimax-m2p7': {
+ id: 'accounts/fireworks/models/minimax-m2p7',
+ name: 'MiniMax-M2.7',
+ limit: {
+ context: 196608,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/qwen3p8-2p4t-a95b': {
+ id: 'accounts/fireworks/models/qwen3p8-2p4t-a95b',
+ name: 'Qwen3.8 2.4T A95B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/muse-glimmer-30b': {
+ id: 'accounts/fireworks/models/muse-glimmer-30b',
+ name: 'Muse Glimmer 30B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/inkling': {
+ id: 'accounts/fireworks/models/inkling',
+ name: 'Inkling',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
},
- 'accounts/fireworks/models/glm-5p2': {
- id: 'accounts/fireworks/models/glm-5p2',
- name: 'GLM 5.2',
- limit: { context: 1048575 },
+ 'accounts/fireworks/models/deepseek-v4-pro': {
+ id: 'accounts/fireworks/models/deepseek-v4-pro',
+ name: 'DeepSeek V4 Pro',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'accounts/fireworks/models/gpt-oss-120b': {
id: 'accounts/fireworks/models/gpt-oss-120b',
name: 'GPT OSS 120B',
- limit: { context: 131072 },
- },
- 'accounts/fireworks/models/gpt-oss-20b': {
- id: 'accounts/fireworks/models/gpt-oss-20b',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'accounts/fireworks/models/kimi-k2p7-code': {
- id: 'accounts/fireworks/models/kimi-k2p7-code',
- name: 'Kimi K2.7 Code',
- limit: { context: 262000 },
+ 'accounts/fireworks/models/glm-5p2': {
+ id: 'accounts/fireworks/models/glm-5p2',
+ name: 'GLM 5.2',
+ limit: {
+ context: 1048575,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'accounts/fireworks/models/qwen3p8-max': {
+ id: 'accounts/fireworks/models/qwen3p8-max',
+ name: 'Qwen3.8 Max',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b': {
+ id: 'accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b',
+ name: 'Nemotron 3.5 Lightning 30B A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
},
},
mistral: {
name: 'Mistral',
models: {
- 'codestral-latest': {
- id: 'codestral-latest',
- name: 'Codestral (latest)',
- limit: { context: 256000 },
- },
- 'mistral-large-latest': {
- id: 'mistral-large-latest',
- name: 'Mistral Large (latest)',
- limit: { context: 262144 },
+ 'pixtral-12b': {
+ id: 'pixtral-12b',
+ name: 'Pixtral 12B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'open-mistral-7b': { id: 'open-mistral-7b', name: 'Mistral 7B', limit: { context: 8000 } },
'devstral-small-2507': {
id: 'devstral-small-2507',
name: 'Devstral Small',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'ministral-3b-latest': {
- id: 'ministral-3b-latest',
- name: 'Ministral 3B (latest)',
- limit: { context: 128000 },
- },
- 'pixtral-large-latest': {
- id: 'pixtral-large-latest',
- name: 'Pixtral Large (latest)',
- limit: { context: 128000 },
- },
- 'mistral-nemo': { id: 'mistral-nemo', name: 'Mistral Nemo', limit: { context: 128000 } },
- 'mistral-embed': { id: 'mistral-embed', name: 'Mistral Embed', limit: { context: 8000 } },
'mistral-small-2506': {
id: 'mistral-small-2506',
name: 'Mistral Small 3.2',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'ministral-8b-latest': {
- id: 'ministral-8b-latest',
- name: 'Ministral 8B (latest)',
- limit: { context: 128000 },
+ 'magistral-small': {
+ id: 'magistral-small',
+ name: 'Magistral Small',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'devstral-2512': {
+ id: 'devstral-2512',
+ name: 'Devstral 2',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistral-embed': {
+ id: 'mistral-embed',
+ name: 'Mistral Embed',
+ limit: {
+ context: 8000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'devstral-small-2505': {
+ id: 'devstral-small-2505',
+ name: 'Devstral Small 2505',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'labs-devstral-small-2512': {
+ id: 'labs-devstral-small-2512',
+ name: 'Devstral Small 2',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'magistral-medium-latest': {
+ id: 'magistral-medium-latest',
+ name: 'Magistral Medium (latest)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-glm-5-3': {
+ id: 'zai-glm-5-3',
+ name: 'GLM-5.3',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'open-mixtral-8x22b': {
id: 'open-mixtral-8x22b',
name: 'Mixtral 8x22B',
- limit: { context: 64000 },
+ limit: {
+ context: 64000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'open-mixtral-8x7b': {
+ id: 'open-mixtral-8x7b',
+ name: 'Mixtral 8x7B',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'open-mistral-7b': {
+ id: 'open-mistral-7b',
+ name: 'Mistral 7B',
+ limit: {
+ context: 8000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'mistral-medium-latest': {
id: 'mistral-medium-latest',
name: 'Mistral Medium (latest)',
- limit: { context: 262144 },
- },
- 'devstral-small-2505': {
- id: 'devstral-small-2505',
- name: 'Devstral Small 2505',
- limit: { context: 128000 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'magistral-small': {
- id: 'magistral-small',
- name: 'Magistral Small',
- limit: { context: 128000 },
+ 'devstral-medium-2507': {
+ id: 'devstral-medium-2507',
+ name: 'Devstral Medium',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'mistral-medium-2604': {
id: 'mistral-medium-2604',
name: 'Mistral Medium 3.5',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'mistral-large-2512': {
+ id: 'mistral-large-2512',
+ name: 'Mistral Large 3',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'devstral-medium-latest': {
+ id: 'devstral-medium-latest',
+ name: 'Devstral 2 (latest)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'voxtral-small-latest': {
+ id: 'voxtral-small-latest',
+ name: 'Voxtral Small (latest)',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
+ },
+ 'ministral-8b-latest': {
+ id: 'ministral-8b-latest',
+ name: 'Ministral 8B (latest)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistral-nemo': {
+ id: 'mistral-nemo',
+ name: 'Mistral Nemo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'voxtral-mini-tts-latest': {
+ id: 'voxtral-mini-tts-latest',
+ name: 'Voxtral Mini TTS (latest)',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'mistral-small-latest': {
id: 'mistral-small-latest',
name: 'Mistral Small (latest)',
- limit: { context: 256000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'open-mixtral-8x7b': {
- id: 'open-mixtral-8x7b',
- name: 'Mixtral 8x7B',
- limit: { context: 32000 },
+ 'open-mistral-nemo': {
+ id: 'open-mistral-nemo',
+ name: 'Open Mistral Nemo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistral-large-latest': {
+ id: 'mistral-large-latest',
+ name: 'Mistral Large (latest)',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'voxtral-mini-latest': {
+ id: 'voxtral-mini-latest',
+ name: 'Voxtral Mini (latest)',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['audio'],
+ },
+ },
+ 'mistral-large-2411': {
+ id: 'mistral-large-2411',
+ name: 'Mistral Large 2.1',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'devstral-latest': {
+ id: 'devstral-latest',
+ name: 'Devstral 2',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-glm-5-2': {
+ id: 'zai-glm-5-2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'devstral-latest': { id: 'devstral-latest', name: 'Devstral 2', limit: { context: 262144 } },
'mistral-small-2603': {
id: 'mistral-small-2603',
name: 'Mistral Small 4',
- limit: { context: 256000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'mistral-medium-2505': {
id: 'mistral-medium-2505',
name: 'Mistral Medium 3',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistral-large-2411': {
- id: 'mistral-large-2411',
- name: 'Mistral Large 2.1',
- limit: { context: 131072 },
+ 'codestral-latest': {
+ id: 'codestral-latest',
+ name: 'Codestral (latest)',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'ministral-3b-latest': {
+ id: 'ministral-3b-latest',
+ name: 'Ministral 3B (latest)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'mistral-medium-2508': {
id: 'mistral-medium-2508',
name: 'Mistral Medium 3.1',
- limit: { context: 262144 },
- },
- 'open-mistral-nemo': {
- id: 'open-mistral-nemo',
- name: 'Open Mistral Nemo',
- limit: { context: 128000 },
- },
- 'magistral-medium-latest': {
- id: 'magistral-medium-latest',
- name: 'Magistral Medium (latest)',
- limit: { context: 128000 },
- },
- 'devstral-medium-latest': {
- id: 'devstral-medium-latest',
- name: 'Devstral 2 (latest)',
- limit: { context: 262144 },
- },
- 'devstral-2512': { id: 'devstral-2512', name: 'Devstral 2', limit: { context: 262144 } },
- 'labs-devstral-small-2512': {
- id: 'labs-devstral-small-2512',
- name: 'Devstral Small 2',
- limit: { context: 256000 },
- },
- 'pixtral-12b': { id: 'pixtral-12b', name: 'Pixtral 12B', limit: { context: 128000 } },
- 'mistral-large-2512': {
- id: 'mistral-large-2512',
- name: 'Mistral Large 3',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'devstral-medium-2507': {
- id: 'devstral-medium-2507',
- name: 'Devstral Medium',
- limit: { context: 128000 },
+ 'pixtral-large-latest': {
+ id: 'pixtral-large-latest',
+ name: 'Pixtral Large (latest)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
},
},
xai: {
name: 'xAI',
models: {
- 'grok-4.20-multi-agent-0309': {
- id: 'grok-4.20-multi-agent-0309',
- name: 'Grok 4.20 Multi-Agent',
- limit: { context: 1000000 },
- },
- 'grok-4.20-0309-non-reasoning': {
- id: 'grok-4.20-0309-non-reasoning',
- name: 'Grok 4.20 (Non-Reasoning)',
- limit: { context: 1000000 },
+ 'grok-4.3': {
+ id: 'grok-4.3',
+ name: 'Grok 4.3',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'grok-4.3': { id: 'grok-4.3', name: 'Grok 4.3', limit: { context: 1000000 } },
- 'grok-imagine-image-quality': {
- id: 'grok-imagine-image-quality',
- name: 'Grok Imagine Image Quality',
- limit: { context: 8000 },
- },
- 'grok-imagine-video': {
- id: 'grok-imagine-video',
- name: 'Grok Imagine Video',
- limit: { context: 1024 },
- },
- 'grok-4.5': { id: 'grok-4.5', name: 'Grok 4.5', limit: { context: 500000 } },
'grok-4.20-0309-reasoning': {
id: 'grok-4.20-0309-reasoning',
name: 'Grok 4.20 (Reasoning)',
- limit: { context: 1000000 },
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'grok-4.20-multi-agent-0309': {
+ id: 'grok-4.20-multi-agent-0309',
+ name: 'Grok 4.20 Multi-Agent',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'grok-imagine-image': {
id: 'grok-imagine-image',
name: 'Grok Imagine Image',
- limit: { context: 8000 },
+ limit: {
+ context: 16000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'grok-imagine-video': {
+ id: 'grok-imagine-video',
+ name: 'Grok Imagine Video',
+ limit: {
+ context: 1024,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'grok-4.5': {
+ id: 'grok-4.5',
+ name: 'Grok 4.5',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
'grok-build-0.1': {
id: 'grok-build-0.1',
name: 'Grok Build 0.1',
- limit: { context: 256000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'grok-imagine-video-1.5': {
+ id: 'grok-imagine-video-1.5',
+ name: 'Grok Imagine Video 1.5',
+ limit: {
+ context: 1024,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'pdf'],
+ },
+ },
+ 'grok-4.6': {
+ id: 'grok-4.6',
+ name: 'Grok 4.6',
+ limit: {
+ context: 500000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'grok-4.20-0309-non-reasoning': {
+ id: 'grok-4.20-0309-non-reasoning',
+ name: 'Grok 4.20 (Non-Reasoning)',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
},
},
cerebras: {
name: 'Cerebras',
models: {
- 'gemma-4-31b': { id: 'gemma-4-31b', name: 'Gemma 4 31B IT', limit: { context: 131072 } },
- 'gpt-oss-120b': { id: 'gpt-oss-120b', name: 'GPT OSS 120B', limit: { context: 131072 } },
- 'zai-glm-4.7': { id: 'zai-glm-4.7', name: 'Z.AI GLM-4.7', limit: { context: 131072 } },
+ 'gpt-oss-120b': {
+ id: 'gpt-oss-120b',
+ name: 'GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen-3.8-27b': {
+ id: 'qwen-3.8-27b',
+ name: 'Qwen3.8 27B',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
},
},
deepinfra: {
name: 'Deep Infra',
models: {
- 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8': {
- id: 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8',
- name: 'Llama 4 Maverick 17B FP8',
- limit: { context: 1048576 },
+ 'ByteDance/Seed-2.0-mini': {
+ id: 'ByteDance/Seed-2.0-mini',
+ name: 'Seed 2.0 Mini',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'ByteDance/Seed-2.0-code': {
+ id: 'ByteDance/Seed-2.0-code',
+ name: 'Seed 2.0 Code',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'ByteDance/Seed-2.0-pro': {
+ id: 'ByteDance/Seed-2.0-pro',
+ name: 'Seed 2.0 Pro',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'stepfun-ai/Step-3.7-Flash': {
+ id: 'stepfun-ai/Step-3.7-Flash',
+ name: 'Step 3.7 Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'meta-llama/Llama-4-Scout-17B-16E-Instruct': {
- id: 'meta-llama/Llama-4-Scout-17B-16E-Instruct',
- name: 'Llama 4 Scout 17B',
- limit: { context: 327680 },
+ 'deepseek-ai/DeepSeek-V3': {
+ id: 'deepseek-ai/DeepSeek-V3',
+ name: 'DeepSeek-V3',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'meta-llama/Llama-3.3-70B-Instruct-Turbo': {
- id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
- name: 'Llama 3.3 70B Turbo',
- limit: { context: 131072 },
+ 'deepseek-ai/DeepSeek-V4-Flash': {
+ id: 'deepseek-ai/DeepSeek-V4-Flash',
+ name: 'DeepSeek V4 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V3-0324': {
+ id: 'deepseek-ai/DeepSeek-V3-0324',
+ name: 'DeepSeek V3 0324',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4-Flash-Vision-Exp': {
+ id: 'deepseek-ai/DeepSeek-V4-Flash-Vision-Exp',
+ name: 'DeepSeek V4 Flash Vision Exp',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4-Flash-0731': {
+ id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V3.1': {
+ id: 'deepseek-ai/DeepSeek-V3.1',
+ name: 'DeepSeek-V3.1',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.6': {
- id: 'moonshotai/Kimi-K2.6',
- name: 'Kimi K2.6',
- limit: { context: 262144 },
+ 'deepseek-ai/DeepSeek-R1-0528': {
+ id: 'deepseek-ai/DeepSeek-R1-0528',
+ name: 'DeepSeek-R1-0528',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4.1-Flash': {
+ id: 'deepseek-ai/DeepSeek-V4.1-Flash',
+ name: 'DeepSeek V4.1 Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'deepseek-ai/DeepSeek-V4-Pro-0813': {
+ id: 'deepseek-ai/DeepSeek-V4-Pro-0813',
+ name: 'DeepSeek V4 Pro 0813',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.5': {
- id: 'moonshotai/Kimi-K2.5',
- name: 'Kimi K2.5',
- limit: { context: 262144 },
+ 'deepseek-ai/DeepSeek-V3.2': {
+ id: 'deepseek-ai/DeepSeek-V3.2',
+ name: 'DeepSeek-V3.2',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'moonshotai/Kimi-K2.7-Code': {
- id: 'moonshotai/Kimi-K2.7-Code',
- name: 'Kimi K2.7 Code',
- limit: { context: 262144 },
+ 'deepseek-ai/DeepSeek-V4-Pro': {
+ id: 'deepseek-ai/DeepSeek-V4-Pro',
+ name: 'DeepSeek V4 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning': {
+ id: 'nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning',
+ name: 'Nemotron 3 Nano Omni 30B A3B Reasoning',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'nvidia/Llama-3.3-Nemotron-Super-49B-v1.5': {
+ id: 'nvidia/Llama-3.3-Nemotron-Super-49B-v1.5',
+ name: 'Llama 3.3 Nemotron Super 49B v1.5',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/Nemotron-3-Nano-30B-A3B': {
+ id: 'nvidia/Nemotron-3-Nano-30B-A3B',
+ name: 'Nemotron 3 Nano 30B A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'google/gemma-3-4b-it': {
+ id: 'google/gemma-3-4b-it',
+ name: 'Gemma 3 4B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'google/gemma-4-31B-it': {
id: 'google/gemma-4-31B-it',
name: 'Gemma 4 31B IT',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'google/gemma-4-E4B-it': {
+ id: 'google/gemma-4-E4B-it',
+ name: 'Gemma 4 E4B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'google/gemma-3-27b-it': {
+ id: 'google/gemma-3-27b-it',
+ name: 'Gemma 3 27B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'google/gemma-4-26B-A4B-it': {
id: 'google/gemma-4-26B-A4B-it',
name: 'Gemma 4 26B A4B IT',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'Qwen/Qwen3.6-35B-A3B': {
- id: 'Qwen/Qwen3.6-35B-A3B',
- name: 'Qwen3.6 35B A3B',
- limit: { context: 262144 },
+ 'google/gemma-3-12b-it': {
+ id: 'google/gemma-3-12b-it',
+ name: 'Gemma 3 12B IT',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai-org/GLM-5.1': {
+ id: 'zai-org/GLM-5.1',
+ name: 'GLM-5.1',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.3': {
+ id: 'zai-org/GLM-5.3',
+ name: 'GLM-5.3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.2': {
+ id: 'zai-org/GLM-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-4.7-Flash': {
+ id: 'zai-org/GLM-4.7-Flash',
+ name: 'GLM-4.7-Flash',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-4.7': {
+ id: 'zai-org/GLM-4.7',
+ name: 'GLM-4.7',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5': {
+ id: 'zai-org/GLM-5',
+ name: 'GLM-5',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-4.6': {
+ id: 'zai-org/GLM-4.6',
+ name: 'GLM-4.6',
+ limit: {
+ context: 202752,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.3-Flash': {
+ id: 'zai-org/GLM-5.3-Flash',
+ name: 'GLM-5.3-Flash',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'thinkingmachines/Inkling-Small': {
+ id: 'thinkingmachines/Inkling-Small',
+ name: 'Inkling Small',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'thinkingmachines/Inkling': {
+ id: 'thinkingmachines/Inkling',
+ name: 'Inkling',
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
},
'Qwen/Qwen3.7-Max': {
id: 'Qwen/Qwen3.7-Max',
name: 'Qwen3.7 Max',
- limit: { context: 256000 },
- },
- 'Qwen/Qwen3.6-27B': {
- id: 'Qwen/Qwen3.6-27B',
- name: 'Qwen3.6 27B',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3-Next-80B-A3B-Instruct': {
- id: 'Qwen/Qwen3-Next-80B-A3B-Instruct',
- name: 'Qwen3-Next 80B-A3B Instruct',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3-Max': { id: 'Qwen/Qwen3-Max', name: 'Qwen3 Max', limit: { context: 256000 } },
- 'Qwen/Qwen3.5-397B-A17B': {
- id: 'Qwen/Qwen3.5-397B-A17B',
- name: 'Qwen 3.5 397B A17B',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3.5-122B-A10B': {
- id: 'Qwen/Qwen3.5-122B-A10B',
- name: 'Qwen3.5 122B-A10B',
- limit: { context: 262144 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'Qwen/Qwen3.8-27B': {
+ id: 'Qwen/Qwen3.8-27B',
+ name: 'Qwen3.8 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
'Qwen/Qwen3.5-27B': {
id: 'Qwen/Qwen3.5-27B',
name: 'Qwen3.5 27B',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
},
- 'Qwen/Qwen3.5-9B': { id: 'Qwen/Qwen3.5-9B', name: 'Qwen3.5 9B', limit: { context: 262144 } },
- 'Qwen/Qwen3-32B': { id: 'Qwen/Qwen3-32B', name: 'Qwen3 32B', limit: { context: 40960 } },
'Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo': {
id: 'Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo',
name: 'Qwen3 Coder 480B A35B Instruct Turbo',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3.5-35B-A3B': {
- id: 'Qwen/Qwen3.5-35B-A3B',
- name: 'Qwen 3.5 35B A3B',
- limit: { context: 262144 },
- },
- 'openai/gpt-oss-120b': {
- id: 'openai/gpt-oss-120b',
- name: 'GPT OSS 120B',
- limit: { context: 131072 },
- },
- 'openai/gpt-oss-20b': {
- id: 'openai/gpt-oss-20b',
- name: 'GPT OSS 20B',
- limit: { context: 131072 },
- },
- 'XiaomiMiMo/MiMo-V2.5': {
- id: 'XiaomiMiMo/MiMo-V2.5',
- name: 'MiMo-V2.5',
- limit: { context: 262144 },
- },
- 'XiaomiMiMo/MiMo-V2.5-Pro': {
- id: 'XiaomiMiMo/MiMo-V2.5-Pro',
- name: 'MiMo-V2.5-Pro',
- limit: { context: 1048576 },
- },
- 'nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning': {
- id: 'nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning',
- name: 'Nemotron 3 Nano Omni 30B A3B Reasoning',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'Qwen/Qwen3.8-Max': {
+ id: 'Qwen/Qwen3.8-Max',
+ name: 'Qwen3.8 Max',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'pdf'],
+ },
+ },
+ 'Qwen/Qwen3.5-9B': {
+ id: 'Qwen/Qwen3.5-9B',
+ name: 'Qwen3.5 9B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'Qwen/Qwen3-30B-A3B': {
+ id: 'Qwen/Qwen3-30B-A3B',
+ name: 'Qwen3 30B A3B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/Nemotron-3-Nano-30B-A3B': {
- id: 'nvidia/Nemotron-3-Nano-30B-A3B',
- name: 'Nemotron 3 Nano 30B A3B',
- limit: { context: 262144 },
+ 'Qwen/Qwen3.5-122B-A10B': {
+ id: 'Qwen/Qwen3.5-122B-A10B',
+ name: 'Qwen3.5 122B-A10B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
+ },
+ 'Qwen/Qwen3.8-2.4T-A95B': {
+ id: 'Qwen/Qwen3.8-2.4T-A95B',
+ name: 'Qwen3.8 2.4T A95B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'nvidia/Llama-3.3-Nemotron-Super-49B-v1.5': {
- id: 'nvidia/Llama-3.3-Nemotron-Super-49B-v1.5',
- name: 'Llama 3.3 Nemotron Super 49B v1.5',
- limit: { context: 131072 },
+ 'Qwen/Qwen3-235B-A22B-Instruct-2507': {
+ id: 'Qwen/Qwen3-235B-A22B-Instruct-2507',
+ name: 'Qwen3 235B-A22B Instruct 2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'Qwen/Qwen3.8-Flash': {
+ id: 'Qwen/Qwen3.8-Flash',
+ name: 'Qwen3.8 Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'Qwen/Qwen3-VL-235B-A22B-Instruct': {
+ id: 'Qwen/Qwen3-VL-235B-A22B-Instruct',
+ name: 'Qwen3 VL 235B A22B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'zai-org/GLM-4.7-Flash': {
- id: 'zai-org/GLM-4.7-Flash',
- name: 'GLM-4.7-Flash',
- limit: { context: 202752 },
+ 'Qwen/Qwen3-Next-80B-A3B-Instruct': {
+ id: 'Qwen/Qwen3-Next-80B-A3B-Instruct',
+ name: 'Qwen3-Next 80B-A3B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai-org/GLM-4.6': { id: 'zai-org/GLM-4.6', name: 'GLM-4.6', limit: { context: 202752 } },
- 'zai-org/GLM-5': { id: 'zai-org/GLM-5', name: 'GLM-5', limit: { context: 202752 } },
- 'zai-org/GLM-4.7': { id: 'zai-org/GLM-4.7', name: 'GLM-4.7', limit: { context: 202752 } },
- 'zai-org/GLM-5.2': { id: 'zai-org/GLM-5.2', name: 'GLM-5.2', limit: { context: 1048576 } },
- 'zai-org/GLM-5.1': { id: 'zai-org/GLM-5.1', name: 'GLM-5.1', limit: { context: 202752 } },
- 'deepseek-ai/DeepSeek-R1-0528': {
- id: 'deepseek-ai/DeepSeek-R1-0528',
- name: 'DeepSeek-R1-0528',
- limit: { context: 163840 },
+ 'Qwen/Qwen3.5-397B-A17B': {
+ id: 'Qwen/Qwen3.5-397B-A17B',
+ name: 'Qwen 3.5 397B A17B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'deepseek-ai/DeepSeek-V4-Flash': {
- id: 'deepseek-ai/DeepSeek-V4-Flash',
- name: 'DeepSeek V4 Flash',
- limit: { context: 1048576 },
+ 'Qwen/Qwen3.5-35B-A3B': {
+ id: 'Qwen/Qwen3.5-35B-A3B',
+ name: 'Qwen 3.5 35B A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'Qwen/Qwen3-32B': {
+ id: 'Qwen/Qwen3-32B',
+ name: 'Qwen3 32B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek-ai/DeepSeek-V4-Pro': {
- id: 'deepseek-ai/DeepSeek-V4-Pro',
- name: 'DeepSeek V4 Pro',
- limit: { context: 1048576 },
+ 'Qwen/Qwen3.6-27B': {
+ id: 'Qwen/Qwen3.6-27B',
+ name: 'Qwen3.6 27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video', 'audio'],
+ },
},
- 'deepseek-ai/DeepSeek-V3.2': {
- id: 'deepseek-ai/DeepSeek-V3.2',
- name: 'DeepSeek-V3.2',
- limit: { context: 163840 },
+ 'Qwen/Qwen3.6-35B-A3B': {
+ id: 'Qwen/Qwen3.6-35B-A3B',
+ name: 'Qwen3.6 35B A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'Qwen/Qwen3-Max': {
+ id: 'Qwen/Qwen3-Max',
+ name: 'Qwen3 Max',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'MiniMaxAI/MiniMax-M2.5': {
id: 'MiniMaxAI/MiniMax-M2.5',
name: 'MiniMax M2.5',
- limit: { context: 196608 },
+ limit: {
+ context: 196608,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'MiniMaxAI/MiniMax-M3': {
id: 'MiniMaxAI/MiniMax-M3',
name: 'MiniMax-M3',
- limit: { context: 524288 },
+ limit: {
+ context: 524288,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
'MiniMaxAI/MiniMax-M2.7': {
id: 'MiniMaxAI/MiniMax-M2.7',
name: 'MiniMax-M2.7',
- limit: { context: 196608 },
+ limit: {
+ context: 196608,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta-llama/Llama-4-Scout-17B-16E-Instruct': {
+ id: 'meta-llama/Llama-4-Scout-17B-16E-Instruct',
+ name: 'Llama 4 Scout 17B',
+ limit: {
+ context: 327680,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'meta-llama/Llama-3.3-70B-Instruct-Turbo': {
+ id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+ name: 'Llama 3.3 70B Turbo',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8': {
+ id: 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8',
+ name: 'Llama 4 Maverick 17B FP8',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'openai/gpt-oss-20b': {
+ id: 'openai/gpt-oss-20b',
+ name: 'GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-oss-120b': {
+ id: 'openai/gpt-oss-120b',
+ name: 'GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/Kimi-K2.5': {
+ id: 'moonshotai/Kimi-K2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/Kimi-K2.7-Code': {
+ id: 'moonshotai/Kimi-K2.7-Code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/Kimi-K2.6': {
+ id: 'moonshotai/Kimi-K2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/Kimi-K3': {
+ id: 'moonshotai/Kimi-K3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'tencent/Hy3': {
+ id: 'tencent/Hy3',
+ name: 'Hy3',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'XiaomiMiMo/MiMo-V2.5-Pro': {
+ id: 'XiaomiMiMo/MiMo-V2.5-Pro',
+ name: 'MiMo-V2.5-Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'audio'],
+ },
+ },
+ 'XiaomiMiMo/MiMo-V2.5': {
+ id: 'XiaomiMiMo/MiMo-V2.5',
+ name: 'MiMo-V2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio', 'video'],
+ },
},
},
},
perplexity: {
name: 'Perplexity',
models: {
+ sonar: {
+ id: 'sonar',
+ name: 'Sonar',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
'sonar-reasoning-pro': {
id: 'sonar-reasoning-pro',
name: 'Sonar Reasoning Pro',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'sonar-pro': {
+ id: 'sonar-pro',
+ name: 'Sonar Pro',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- sonar: { id: 'sonar', name: 'Sonar', limit: { context: 128000 } },
- 'sonar-pro': { id: 'sonar-pro', name: 'Sonar Pro', limit: { context: 200000 } },
'sonar-deep-research': {
id: 'sonar-deep-research',
name: 'Perplexity Sonar Deep Research',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
},
},
moonshotai: {
name: 'Moonshot AI',
models: {
- 'kimi-k2-0905-preview': {
- id: 'kimi-k2-0905-preview',
- name: 'Kimi K2 0905',
- limit: { context: 262144 },
- },
- 'kimi-k2-thinking-turbo': {
- id: 'kimi-k2-thinking-turbo',
- name: 'Kimi K2 Thinking Turbo',
- limit: { context: 262144 },
+ 'kimi-k2.7-code-highspeed': {
+ id: 'kimi-k2.7-code-highspeed',
+ name: 'Kimi K2.7 Code HighSpeed',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'kimi-k2.6': {
+ id: 'kimi-k2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
'kimi-k2.7-code': {
id: 'kimi-k2.7-code',
name: 'Kimi K2.7 Code',
- limit: { context: 262144 },
- },
- 'kimi-k2-thinking': {
- id: 'kimi-k2-thinking',
- name: 'Kimi K2 Thinking',
- limit: { context: 262144 },
- },
- 'kimi-k2-0711-preview': {
- id: 'kimi-k2-0711-preview',
- name: 'Kimi K2 0711',
- limit: { context: 131072 },
- },
- 'kimi-k2-turbo-preview': {
- id: 'kimi-k2-turbo-preview',
- name: 'Kimi K2 Turbo',
- limit: { context: 262144 },
- },
- 'kimi-k2.5': { id: 'kimi-k2.5', name: 'Kimi K2.5', limit: { context: 262144 } },
- 'kimi-k2.6': { id: 'kimi-k2.6', name: 'Kimi K2.6', limit: { context: 262144 } },
- 'kimi-k2.7-code-highspeed': {
- id: 'kimi-k2.7-code-highspeed',
- name: 'Kimi K2.7 Code HighSpeed',
- limit: { context: 262144 },
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'kimi-k3': {
+ id: 'kimi-k3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
},
},
nebius: {
name: 'Nebius Token Factory',
models: {
- 'meta-llama/Llama-3.3-70B-Instruct': {
- id: 'meta-llama/Llama-3.3-70B-Instruct',
- name: 'Llama-3.3-70B-Instruct',
- limit: { context: 128000 },
- },
- 'moonshotai/Kimi-K2.5-fast': {
- id: 'moonshotai/Kimi-K2.5-fast',
- name: 'Kimi-K2.5-fast',
- limit: { context: 256000 },
- },
- 'moonshotai/Kimi-K2.5': {
- id: 'moonshotai/Kimi-K2.5',
- name: 'Kimi-K2.5',
- limit: { context: 256000 },
- },
- 'google/gemma-3-27b-it': {
- id: 'google/gemma-3-27b-it',
- name: 'Gemma-3-27b-it',
- limit: { context: 110000 },
- },
- 'Qwen/Qwen3-Next-80B-A3B-Thinking-fast': {
- id: 'Qwen/Qwen3-Next-80B-A3B-Thinking-fast',
- name: 'Qwen3-Next-80B-A3B-Thinking-fast',
- limit: { context: 8000 },
- },
- 'Qwen/Qwen2.5-VL-72B-Instruct': {
- id: 'Qwen/Qwen2.5-VL-72B-Instruct',
- name: 'Qwen2.5-VL-72B-Instruct',
- limit: { context: 128000 },
- },
- 'Qwen/Qwen3-Embedding-8B': {
- id: 'Qwen/Qwen3-Embedding-8B',
- name: 'Qwen3-Embedding-8B',
- limit: { context: 32768 },
- },
- 'Qwen/Qwen3.5-397B-A17B': {
- id: 'Qwen/Qwen3.5-397B-A17B',
- name: 'Qwen3.5-397B-A17B',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3.5-397B-A17B-fast': {
- id: 'Qwen/Qwen3.5-397B-A17B-fast',
- name: 'Qwen3.5-397B-A17B-fast',
- limit: { context: 8000 },
- },
- 'Qwen/Qwen3-30B-A3B-Instruct-2507': {
- id: 'Qwen/Qwen3-30B-A3B-Instruct-2507',
- name: 'Qwen3-30B-A3B-Instruct-2507',
- limit: { context: 128000 },
- },
- 'Qwen/Qwen3-Next-80B-A3B-Thinking': {
- id: 'Qwen/Qwen3-Next-80B-A3B-Thinking',
- name: 'Qwen3-Next-80B-A3B-Thinking',
- limit: { context: 128000 },
- },
- 'Qwen/Qwen3-235B-A22B-Instruct-2507': {
- id: 'Qwen/Qwen3-235B-A22B-Instruct-2507',
- name: 'Qwen3 235B A22B Instruct 2507',
- limit: { context: 262144 },
- },
- 'Qwen/Qwen3-32B': { id: 'Qwen/Qwen3-32B', name: 'Qwen3-32B', limit: { context: 128000 } },
- 'Qwen/Qwen3-235B-A22B-Thinking-2507-fast': {
- id: 'Qwen/Qwen3-235B-A22B-Thinking-2507-fast',
- name: 'Qwen3-235B-A22B-Thinking-2507-fast',
- limit: { context: 8000 },
- },
- 'openai/gpt-oss-120b-fast': {
- id: 'openai/gpt-oss-120b-fast',
- name: 'gpt-oss-120b-fast',
- limit: { context: 8000 },
- },
- 'openai/gpt-oss-120b': {
- id: 'openai/gpt-oss-120b',
- name: 'gpt-oss-120b',
- limit: { context: 128000 },
- },
- 'NousResearch/Hermes-4-405B': {
- id: 'NousResearch/Hermes-4-405B',
- name: 'Hermes-4-405B',
- limit: { context: 128000 },
- },
- 'NousResearch/Hermes-4-70B': {
- id: 'NousResearch/Hermes-4-70B',
- name: 'Hermes-4-70B',
- limit: { context: 128000 },
- },
- 'nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B': {
- id: 'nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B',
- name: 'Nemotron-3-Nano-30B-A3B',
- limit: { context: 32000 },
- },
- 'nvidia/Nemotron-3-Nano-Omni': {
- id: 'nvidia/Nemotron-3-Nano-Omni',
- name: 'Nemotron-3-Nano-Omni',
- limit: { context: 65536 },
- },
- 'nvidia/Llama-3_1-Nemotron-Ultra-253B-v1': {
- id: 'nvidia/Llama-3_1-Nemotron-Ultra-253B-v1',
- name: 'Llama-3.1-Nemotron-Ultra-253B-v1',
- limit: { context: 128000 },
- },
- 'nvidia/nemotron-3-super-120b-a12b': {
- id: 'nvidia/nemotron-3-super-120b-a12b',
- name: 'Nemotron-3-Super-120B-A12B',
- limit: { context: 256000 },
- },
- 'zai-org/GLM-5': { id: 'zai-org/GLM-5', name: 'GLM-5', limit: { context: 200000 } },
- 'zai-org/GLM-5.2': { id: 'zai-org/GLM-5.2', name: 'GLM-5.2', limit: { context: 432000 } },
- 'deepseek-ai/DeepSeek-V3.2-fast': {
- id: 'deepseek-ai/DeepSeek-V3.2-fast',
- name: 'DeepSeek-V3.2-fast',
- limit: { context: 8000 },
+ 'deepseek-ai/DeepSeek-V4-Flash-0731': {
+ id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+ name: 'DeepSeek V4 Flash 0731',
+ limit: {
+ context: 1024000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek-ai/DeepSeek-V4-Pro': {
id: 'deepseek-ai/DeepSeek-V4-Pro',
name: 'DeepSeek V4 Pro',
- limit: { context: 1000000 },
- },
- 'deepseek-ai/DeepSeek-V3.2': {
- id: 'deepseek-ai/DeepSeek-V3.2',
- name: 'DeepSeek-V3.2',
- limit: { context: 163000 },
- },
- 'MiniMaxAI/MiniMax-M2.5': {
- id: 'MiniMaxAI/MiniMax-M2.5',
- name: 'MiniMax-M2.5',
- limit: { context: 196608 },
- },
- 'MiniMaxAI/MiniMax-M2.5-fast': {
- id: 'MiniMaxAI/MiniMax-M2.5-fast',
- name: 'MiniMax-M2.5-fast',
- limit: { context: 8000 },
- },
- 'PrimeIntellect/INTELLECT-3': {
- id: 'PrimeIntellect/INTELLECT-3',
- name: 'INTELLECT-3',
- limit: { context: 128000 },
- },
- },
- },
- 'novita-ai': {
- name: 'NovitaAI',
- models: {
- 'inclusionai/ling-2.6-1t': {
- id: 'inclusionai/ling-2.6-1t',
- name: 'Ling-2.6-1T',
- limit: { context: 262144 },
- },
- 'inclusionai/ring-2.6-1t': {
- id: 'inclusionai/ring-2.6-1t',
- name: 'Ring-2.6-1T',
- limit: { context: 262144 },
- },
- 'inclusionai/ling-2.6-flash': {
- id: 'inclusionai/ling-2.6-flash',
- name: 'Ling-2.6-flash',
- limit: { context: 262144 },
- },
- 'meta-llama/llama-3.1-8b-instruct': {
- id: 'meta-llama/llama-3.1-8b-instruct',
- name: 'Llama 3.1 8B Instruct',
- limit: { context: 16384 },
- },
- 'meta-llama/llama-3-70b-instruct': {
- id: 'meta-llama/llama-3-70b-instruct',
- name: 'Llama3 70B Instruct',
- limit: { context: 8192 },
- },
- 'meta-llama/llama-4-scout-17b-16e-instruct': {
- id: 'meta-llama/llama-4-scout-17b-16e-instruct',
- name: 'Llama 4 Scout Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3.3-70b-instruct': {
- id: 'meta-llama/llama-3.3-70b-instruct',
- name: 'Llama 3.3 70B Instruct',
- limit: { context: 131072 },
- },
- 'meta-llama/llama-3-8b-instruct': {
- id: 'meta-llama/llama-3-8b-instruct',
- name: 'Llama 3 8B Instruct',
- limit: { context: 8192 },
- },
- 'meta-llama/llama-3.2-3b-instruct': {
- id: 'meta-llama/llama-3.2-3b-instruct',
- name: 'Llama 3.2 3B Instruct',
- limit: { context: 32768 },
- },
- 'meta-llama/llama-4-maverick-17b-128e-instruct-fp8': {
- id: 'meta-llama/llama-4-maverick-17b-128e-instruct-fp8',
- name: 'Llama 4 Maverick Instruct',
- limit: { context: 1048576 },
- },
- 'moonshotai/kimi-k2-instruct': {
- id: 'moonshotai/kimi-k2-instruct',
- name: 'Kimi K2 Instruct',
- limit: { context: 131072 },
- },
- 'moonshotai/kimi-k2-thinking': {
- id: 'moonshotai/kimi-k2-thinking',
- name: 'Kimi K2 Thinking',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2.5': {
- id: 'moonshotai/kimi-k2.5',
- name: 'Kimi K2.5',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2.6': {
- id: 'moonshotai/kimi-k2.6',
- name: 'Kimi K2.6',
- limit: { context: 262144 },
- },
- 'moonshotai/kimi-k2-0905': {
- id: 'moonshotai/kimi-k2-0905',
- name: 'Kimi K2 0905',
- limit: { context: 262144 },
- },
- 'minimaxai/minimax-m1-80k': {
- id: 'minimaxai/minimax-m1-80k',
- name: 'MiniMax M1',
- limit: { context: 1000000 },
- },
- 'baidu/ernie-4.5-vl-28b-a3b': {
- id: 'baidu/ernie-4.5-vl-28b-a3b',
- name: 'ERNIE 4.5 VL 28B A3B',
- limit: { context: 30000 },
- },
- 'baidu/ernie-4.5-21B-a3b': {
- id: 'baidu/ernie-4.5-21B-a3b',
- name: 'ERNIE 4.5 21B A3B',
- limit: { context: 120000 },
- },
- 'baidu/ernie-4.5-vl-424b-a47b': {
- id: 'baidu/ernie-4.5-vl-424b-a47b',
- name: 'ERNIE 4.5 VL 424B A47B',
- limit: { context: 123000 },
- },
- 'baidu/ernie-4.5-21B-a3b-thinking': {
- id: 'baidu/ernie-4.5-21B-a3b-thinking',
- name: 'ERNIE-4.5-21B-A3B-Thinking',
- limit: { context: 131072 },
- },
- 'baidu/ernie-4.5-300b-a47b-paddle': {
- id: 'baidu/ernie-4.5-300b-a47b-paddle',
- name: 'ERNIE 4.5 300B A47B',
- limit: { context: 123000 },
- },
- 'baidu/ernie-4.5-vl-28b-a3b-thinking': {
- id: 'baidu/ernie-4.5-vl-28b-a3b-thinking',
- name: 'ERNIE-4.5-VL-28B-A3B-Thinking',
- limit: { context: 131072 },
- },
- 'google/gemma-4-31b-it': {
- id: 'google/gemma-4-31b-it',
- name: 'Gemma 4 31B',
- limit: { context: 262144 },
- },
- 'google/gemma-4-26b-a4b-it': {
- id: 'google/gemma-4-26b-a4b-it',
- name: 'Gemma 4 26B A4B',
- limit: { context: 262144 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/Nemotron-3_5-Lightning': {
+ id: 'nvidia/Nemotron-3_5-Lightning',
+ name: 'Nemotron 3.5 Lightning 30B A3B',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nvidia/Nemotron-3-Ultra-550b-a55b': {
+ id: 'nvidia/Nemotron-3-Ultra-550b-a55b',
+ name: 'Nemotron 3 Ultra 550B A55B',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'google/gemma-3-12b-it': {
- id: 'google/gemma-3-12b-it',
- name: 'Gemma 3 12B',
- limit: { context: 131072 },
+ 'nvidia/nemotron-3-super-120b-a12b': {
+ id: 'nvidia/nemotron-3-super-120b-a12b',
+ name: 'Nemotron-3-Super-120B-A12B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'google/gemma-3-27b-it': {
id: 'google/gemma-3-27b-it',
- name: 'Gemma 3 27B',
- limit: { context: 98304 },
+ name: 'Gemma-3-27b-it',
+ limit: {
+ context: 110000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai-org/GLM-5.2': {
+ id: 'zai-org/GLM-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/GLM-5.3-Flash': {
+ id: 'zai-org/GLM-5.3-Flash',
+ name: 'GLM-5.3-Flash',
+ limit: {
+ context: 1024000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'microsoft/wizardlm-2-8x22b': {
- id: 'microsoft/wizardlm-2-8x22b',
- name: 'Wizardlm 2 8x22B',
- limit: { context: 65535 },
+ 'Qwen/Qwen3-30B-A3B-Instruct-2507': {
+ id: 'Qwen/Qwen3-30B-A3B-Instruct-2507',
+ name: 'Qwen3-30B-A3B-Instruct-2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-120b': {
- id: 'openai/gpt-oss-120b',
- name: 'OpenAI GPT OSS 120B',
- limit: { context: 131072 },
+ 'Qwen/Qwen3-235B-A22B-Instruct-2507': {
+ id: 'Qwen/Qwen3-235B-A22B-Instruct-2507',
+ name: 'Qwen3 235B A22B Instruct 2507',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'openai/gpt-oss-20b': {
- id: 'openai/gpt-oss-20b',
- name: 'OpenAI: GPT OSS 20B',
- limit: { context: 131072 },
+ 'Qwen/Qwen3.5-397B-A17B': {
+ id: 'Qwen/Qwen3.5-397B-A17B',
+ name: 'Qwen3.5-397B-A17B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10K/l31-70b-euryale-v2.2': {
- id: 'sao10K/l31-70b-euryale-v2.2',
- name: 'L31 70B Euryale V2.2',
- limit: { context: 8192 },
+ 'Qwen/Qwen3-Embedding-8B': {
+ id: 'Qwen/Qwen3-Embedding-8B',
+ name: 'Qwen3-Embedding-8B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10K/L3-8B-stheno-v3.2': {
- id: 'sao10K/L3-8B-stheno-v3.2',
- name: 'L3 8B Stheno V3.2',
- limit: { context: 8192 },
+ 'NousResearch/Hermes-4-405B': {
+ id: 'NousResearch/Hermes-4-405B',
+ name: 'Hermes-4-405B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10K/l3-8b-lunaris': {
- id: 'sao10K/l3-8b-lunaris',
- name: 'Sao10k L3 8B Lunaris\t',
- limit: { context: 8192 },
+ 'MiniMaxAI/MiniMax-M3': {
+ id: 'MiniMaxAI/MiniMax-M3',
+ name: 'MiniMax-M3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'sao10K/l3-70b-euryale-v2.1': {
- id: 'sao10K/l3-70b-euryale-v2.1',
- name: 'L3 70B Euryale V2.1\t',
- limit: { context: 8192 },
+ 'openai/gpt-oss-120b': {
+ id: 'openai/gpt-oss-120b',
+ name: 'gpt-oss-120b',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'baichuan/baichuan-m2-32b': {
- id: 'baichuan/baichuan-m2-32b',
- name: 'baichuan-m2-32b',
- limit: { context: 131072 },
+ 'moonshotai/Kimi-K2.7-Code': {
+ id: 'moonshotai/Kimi-K2.7-Code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/Kimi-K3': {
+ id: 'moonshotai/Kimi-K3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'mistralai/mistral-nemo': {
- id: 'mistralai/mistral-nemo',
- name: 'Mistral Nemo',
- limit: { context: 60288 },
+ },
+ },
+ 'novita-ai': {
+ name: 'NovitaAI',
+ models: {
+ 'paddlepaddle/paddleocr-vl': {
+ id: 'paddlepaddle/paddleocr-vl',
+ name: 'PaddleOCR-VL',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'xiaomimimo/mimo-v2-flash': {
- id: 'xiaomimimo/mimo-v2-flash',
- name: 'XiaomiMiMo/MiMo-V2-Flash',
- limit: { context: 262144 },
+ 'qwen/qwen3.7-max': {
+ id: 'qwen/qwen3.7-max',
+ name: 'Qwen3.7-Max',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'xiaomimimo/mimo-v2-pro': {
- id: 'xiaomimimo/mimo-v2-pro',
- name: 'MiMo-V2-Pro',
- limit: { context: 1048576 },
+ 'qwen/qwen3-omni-30b-a3b-instruct': {
+ id: 'qwen/qwen3-omni-30b-a3b-instruct',
+ name: 'Qwen3 Omni 30B A3B Instruct',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'video', 'audio', 'image'],
+ },
},
- 'xiaomimimo/mimo-v2.5-pro': {
- id: 'xiaomimimo/mimo-v2.5-pro',
- name: 'MiMo-V2.5-Pro',
- limit: { context: 1048576 },
+ 'qwen/qwen3-30b-a3b-fp8': {
+ id: 'qwen/qwen3-30b-a3b-fp8',
+ name: 'Qwen3 30B A3B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'gryphe/mythomax-l2-13b': {
- id: 'gryphe/mythomax-l2-13b',
- name: 'Mythomax L2 13B',
- limit: { context: 4096 },
+ 'qwen/qwen3-next-80b-a3b-thinking': {
+ id: 'qwen/qwen3-next-80b-a3b-thinking',
+ name: 'Qwen3 Next 80B A3B Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai-org/glm-4.7': { id: 'zai-org/glm-4.7', name: 'GLM-4.7', limit: { context: 204800 } },
- 'zai-org/glm-4.5v': { id: 'zai-org/glm-4.5v', name: 'GLM 4.5V', limit: { context: 65536 } },
- 'zai-org/glm-4.5': { id: 'zai-org/glm-4.5', name: 'GLM-4.5', limit: { context: 131072 } },
- 'zai-org/autoglm-phone-9b-multilingual': {
- id: 'zai-org/autoglm-phone-9b-multilingual',
- name: 'AutoGLM-Phone-9B-Multilingual',
- limit: { context: 65536 },
+ 'qwen/qwen3-235b-a22b-thinking-2507': {
+ id: 'qwen/qwen3-235b-a22b-thinking-2507',
+ name: 'Qwen3 235B A22b Thinking 2507',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai-org/glm-5.1': { id: 'zai-org/glm-5.1', name: 'GLM-5.1', limit: { context: 204800 } },
- 'zai-org/glm-4.6': { id: 'zai-org/glm-4.6', name: 'GLM 4.6', limit: { context: 204800 } },
- 'zai-org/glm-5.2': { id: 'zai-org/glm-5.2', name: 'GLM-5.2', limit: { context: 1048576 } },
- 'zai-org/glm-4.6v': { id: 'zai-org/glm-4.6v', name: 'GLM 4.6V', limit: { context: 131072 } },
- 'zai-org/glm-4.5-air': {
- id: 'zai-org/glm-4.5-air',
- name: 'GLM 4.5 Air',
- limit: { context: 131072 },
+ 'qwen/qwen3-next-80b-a3b-instruct': {
+ id: 'qwen/qwen3-next-80b-a3b-instruct',
+ name: 'Qwen3 Next 80B A3B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'zai-org/glm-4.7-flash': {
- id: 'zai-org/glm-4.7-flash',
- name: 'GLM-4.7-Flash',
- limit: { context: 200000 },
+ 'qwen/qwen3.5-27b': {
+ id: 'qwen/qwen3.5-27b',
+ name: 'Qwen3.5-27B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'zai-org/glm-5': { id: 'zai-org/glm-5', name: 'GLM-5', limit: { context: 202800 } },
- 'paddlepaddle/paddleocr-vl': {
- id: 'paddlepaddle/paddleocr-vl',
- name: 'PaddleOCR-VL',
- limit: { context: 16384 },
+ 'qwen/qwen3.5-35b-a3b': {
+ id: 'qwen/qwen3.5-35b-a3b',
+ name: 'Qwen3.5-35B-A3B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'qwen/qwen3-vl-235b-a22b-thinking': {
- id: 'qwen/qwen3-vl-235b-a22b-thinking',
- name: 'Qwen3 VL 235B A22B Thinking',
- limit: { context: 131072 },
+ 'qwen/qwen3-235b-a22b-fp8': {
+ id: 'qwen/qwen3-235b-a22b-fp8',
+ name: 'Qwen3 235B A22B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-vl-30b-a3b-thinking': {
- id: 'qwen/qwen3-vl-30b-a3b-thinking',
- name: 'qwen/qwen3-vl-30b-a3b-thinking',
- limit: { context: 131072 },
+ 'qwen/qwen3-4b-fp8': {
+ id: 'qwen/qwen3-4b-fp8',
+ name: 'Qwen3 4B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-235b-a22b-instruct-2507': {
- id: 'qwen/qwen3-235b-a22b-instruct-2507',
- name: 'Qwen3 235B A22B Instruct 2507',
- limit: { context: 131072 },
+ 'qwen/qwen2.5-vl-72b-instruct': {
+ id: 'qwen/qwen2.5-vl-72b-instruct',
+ name: 'Qwen2.5 VL 72B Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-coder-next': {
+ id: 'qwen/qwen3-coder-next',
+ name: 'Qwen3 Coder Next',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'qwen/qwen3-coder-30b-a3b-instruct': {
id: 'qwen/qwen3-coder-30b-a3b-instruct',
name: 'Qwen3 Coder 30b A3B Instruct',
- limit: { context: 160000 },
+ limit: {
+ context: 160000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3.5-397b-a17b': {
+ id: 'qwen/qwen3.5-397b-a17b',
+ name: 'Qwen3.5-397B-A17B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-max': {
+ id: 'qwen/qwen3-max',
+ name: 'Qwen3 Max',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3-vl-8b-instruct': {
+ id: 'qwen/qwen3-vl-8b-instruct',
+ name: 'qwen/qwen3-vl-8b-instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
'qwen/qwen3-8b-fp8': {
id: 'qwen/qwen3-8b-fp8',
name: 'Qwen3 8B',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-next-80b-a3b-instruct': {
- id: 'qwen/qwen3-next-80b-a3b-instruct',
- name: 'Qwen3 Next 80B A3B Instruct',
- limit: { context: 131072 },
+ 'qwen/qwen3-vl-30b-a3b-instruct': {
+ id: 'qwen/qwen3-vl-30b-a3b-instruct',
+ name: 'qwen/qwen3-vl-30b-a3b-instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'video', 'image'],
+ },
},
- 'qwen/qwen3-vl-8b-instruct': {
- id: 'qwen/qwen3-vl-8b-instruct',
- name: 'qwen/qwen3-vl-8b-instruct',
- limit: { context: 131072 },
+ 'qwen/qwen3.5-122b-a10b': {
+ id: 'qwen/qwen3.5-122b-a10b',
+ name: 'Qwen3.5-122B-A10B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'qwen/qwen3-omni-30b-a3b-thinking': {
- id: 'qwen/qwen3-omni-30b-a3b-thinking',
- name: 'Qwen3 Omni 30B A3B Thinking',
- limit: { context: 65536 },
+ 'qwen/qwen3-32b-fp8': {
+ id: 'qwen/qwen3-32b-fp8',
+ name: 'Qwen3 32B',
+ limit: {
+ context: 40960,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.7-max': {
- id: 'qwen/qwen3.7-max',
- name: 'Qwen3.7-Max',
- limit: { context: 1000000 },
+ 'qwen/qwen3-vl-30b-a3b-thinking': {
+ id: 'qwen/qwen3-vl-30b-a3b-thinking',
+ name: 'qwen/qwen3-vl-30b-a3b-thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'qwen/qwen3-max': { id: 'qwen/qwen3-max', name: 'Qwen3 Max', limit: { context: 262144 } },
'qwen/qwen2.5-7b-instruct': {
id: 'qwen/qwen2.5-7b-instruct',
name: 'Qwen2.5 7B Instruct',
- limit: { context: 32000 },
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-next-80b-a3b-thinking': {
- id: 'qwen/qwen3-next-80b-a3b-thinking',
- name: 'Qwen3 Next 80B A3B Thinking',
- limit: { context: 131072 },
+ 'qwen/qwen-2.5-72b-instruct': {
+ id: 'qwen/qwen-2.5-72b-instruct',
+ name: 'Qwen 2.5 72B Instruct',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-235b-a22b-thinking-2507': {
- id: 'qwen/qwen3-235b-a22b-thinking-2507',
- name: 'Qwen3 235B A22b Thinking 2507',
- limit: { context: 131072 },
+ 'qwen/qwen3-vl-235b-a22b-thinking': {
+ id: 'qwen/qwen3-vl-235b-a22b-thinking',
+ name: 'Qwen3 VL 235B A22B Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-vl-235b-a22b-instruct': {
+ id: 'qwen/qwen3-vl-235b-a22b-instruct',
+ name: 'Qwen3 VL 235B A22B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'qwen/qwen3-235b-a22b-instruct-2507': {
+ id: 'qwen/qwen3-235b-a22b-instruct-2507',
+ name: 'Qwen3 235B A22B Instruct 2507',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3-coder-480b-a35b-instruct': {
+ id: 'qwen/qwen3-coder-480b-a35b-instruct',
+ name: 'Qwen3 Coder 480B A35B Instruct',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'qwen/qwen3-omni-30b-a3b-thinking': {
+ id: 'qwen/qwen3-omni-30b-a3b-thinking',
+ name: 'Qwen3 Omni 30B A3B Thinking',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'audio', 'video', 'image'],
+ },
},
'qwen/qwen-mt-plus': {
id: 'qwen/qwen-mt-plus',
name: 'Qwen MT Plus',
- limit: { context: 16384 },
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-32b-fp8': {
- id: 'qwen/qwen3-32b-fp8',
- name: 'Qwen3 32B',
- limit: { context: 40960 },
+ 'baidu/ernie-4.5-300b-a47b-paddle': {
+ id: 'baidu/ernie-4.5-300b-a47b-paddle',
+ name: 'ERNIE 4.5 300B A47B',
+ limit: {
+ context: 123000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-4b-fp8': {
- id: 'qwen/qwen3-4b-fp8',
- name: 'Qwen3 4B',
- limit: { context: 128000 },
+ 'baidu/ernie-4.5-vl-28b-a3b': {
+ id: 'baidu/ernie-4.5-vl-28b-a3b',
+ name: 'ERNIE 4.5 VL 28B A3B',
+ limit: {
+ context: 30000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen2.5-vl-72b-instruct': {
- id: 'qwen/qwen2.5-vl-72b-instruct',
- name: 'Qwen2.5 VL 72B Instruct',
- limit: { context: 32768 },
+ 'baidu/ernie-4.5-vl-424b-a47b': {
+ id: 'baidu/ernie-4.5-vl-424b-a47b',
+ name: 'ERNIE 4.5 VL 424B A47B',
+ limit: {
+ context: 123000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3-30b-a3b-fp8': {
- id: 'qwen/qwen3-30b-a3b-fp8',
- name: 'Qwen3 30B A3B',
- limit: { context: 40960 },
+ 'baidu/ernie-4.5-21B-a3b-thinking': {
+ id: 'baidu/ernie-4.5-21B-a3b-thinking',
+ name: 'ERNIE-4.5-21B-A3B-Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'baidu/ernie-4.5-21B-a3b': {
+ id: 'baidu/ernie-4.5-21B-a3b',
+ name: 'ERNIE 4.5 21B A3B',
+ limit: {
+ context: 120000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'baidu/ernie-4.5-vl-28b-a3b-thinking': {
+ id: 'baidu/ernie-4.5-vl-28b-a3b-thinking',
+ name: 'ERNIE-4.5-VL-28B-A3B-Thinking',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'kwaipilot/kat-coder-pro': {
+ id: 'kwaipilot/kat-coder-pro',
+ name: 'Kat Coder Pro',
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'mistralai/mistral-nemo': {
+ id: 'mistralai/mistral-nemo',
+ name: 'Mistral Nemo',
+ limit: {
+ context: 60288,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'minimax/minimax-m2.1': {
+ id: 'minimax/minimax-m2.1',
+ name: 'Minimax M2.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'minimax/minimax-m2': {
+ id: 'minimax/minimax-m2',
+ name: 'MiniMax-M2',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'minimax/minimax-m2.7-highspeed': {
+ id: 'minimax/minimax-m2.7-highspeed',
+ name: 'MiniMax-M2.7-highspeed',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'minimax/minimax-m2.7': {
+ id: 'minimax/minimax-m2.7',
+ name: 'MiniMax M2.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'minimax/minimax-m2.5': {
+ id: 'minimax/minimax-m2.5',
+ name: 'MiniMax M2.5',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.5-27b': {
- id: 'qwen/qwen3.5-27b',
- name: 'Qwen3.5-27B',
- limit: { context: 262144 },
+ 'minimax/minimax-m2.5-highspeed': {
+ id: 'minimax/minimax-m2.5-highspeed',
+ name: 'MiniMax M2.5 Highspeed',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen-2.5-72b-instruct': {
- id: 'qwen/qwen-2.5-72b-instruct',
- name: 'Qwen 2.5 72B Instruct',
- limit: { context: 32000 },
+ 'google/gemma-4-26b-a4b-it': {
+ id: 'google/gemma-4-26b-a4b-it',
+ name: 'Gemma 4 26B A4B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3-coder-next': {
- id: 'qwen/qwen3-coder-next',
- name: 'Qwen3 Coder Next',
- limit: { context: 262144 },
+ 'google/gemma-3-27b-it': {
+ id: 'google/gemma-3-27b-it',
+ name: 'Gemma 3 27B',
+ limit: {
+ context: 98304,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3.5-35b-a3b': {
- id: 'qwen/qwen3.5-35b-a3b',
- name: 'Qwen3.5-35B-A3B',
- limit: { context: 262144 },
+ 'google/gemma-4-31b-it': {
+ id: 'google/gemma-4-31b-it',
+ name: 'Gemma 4 31B',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'qwen/qwen3-coder-480b-a35b-instruct': {
- id: 'qwen/qwen3-coder-480b-a35b-instruct',
- name: 'Qwen3 Coder 480B A35B Instruct',
- limit: { context: 262144 },
+ 'google/gemma-3-12b-it': {
+ id: 'google/gemma-3-12b-it',
+ name: 'Gemma 3 12B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai-org/glm-4.7': {
+ id: 'zai-org/glm-4.7',
+ name: 'GLM-4.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.5-397b-a17b': {
- id: 'qwen/qwen3.5-397b-a17b',
- name: 'Qwen3.5-397B-A17B',
- limit: { context: 262144 },
+ 'zai-org/glm-4.5-air': {
+ id: 'zai-org/glm-4.5-air',
+ name: 'GLM 4.5 Air',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/glm-4.6': {
+ id: 'zai-org/glm-4.6',
+ name: 'GLM 4.6',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/glm-4.6v': {
+ id: 'zai-org/glm-4.6v',
+ name: 'GLM 4.6V',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'video', 'image'],
+ },
+ },
+ 'zai-org/glm-5.2': {
+ id: 'zai-org/glm-5.2',
+ name: 'GLM-5.2',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-vl-30b-a3b-instruct': {
- id: 'qwen/qwen3-vl-30b-a3b-instruct',
- name: 'qwen/qwen3-vl-30b-a3b-instruct',
- limit: { context: 131072 },
+ 'zai-org/autoglm-phone-9b-multilingual': {
+ id: 'zai-org/autoglm-phone-9b-multilingual',
+ name: 'AutoGLM-Phone-9B-Multilingual',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'zai-org/glm-4.5': {
+ id: 'zai-org/glm-4.5',
+ name: 'GLM-4.5',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/glm-4.5v': {
+ id: 'zai-org/glm-4.5v',
+ name: 'GLM 4.5V',
+ limit: {
+ context: 65536,
+ },
+ modalities: {
+ input: ['text', 'video', 'image'],
+ },
+ },
+ 'zai-org/glm-5': {
+ id: 'zai-org/glm-5',
+ name: 'GLM-5',
+ limit: {
+ context: 202800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'zai-org/glm-5.1': {
+ id: 'zai-org/glm-5.1',
+ name: 'GLM-5.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-omni-30b-a3b-instruct': {
- id: 'qwen/qwen3-omni-30b-a3b-instruct',
- name: 'Qwen3 Omni 30B A3B Instruct',
- limit: { context: 65536 },
+ 'zai-org/glm-4.7-flash': {
+ id: 'zai-org/glm-4.7-flash',
+ name: 'GLM-4.7-Flash',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-vl-235b-a22b-instruct': {
- id: 'qwen/qwen3-vl-235b-a22b-instruct',
- name: 'Qwen3 VL 235B A22B Instruct',
- limit: { context: 131072 },
+ 'gryphe/mythomax-l2-13b': {
+ id: 'gryphe/mythomax-l2-13b',
+ name: 'Mythomax L2 13B',
+ limit: {
+ context: 4096,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3.5-122b-a10b': {
- id: 'qwen/qwen3.5-122b-a10b',
- name: 'Qwen3.5-122B-A10B',
- limit: { context: 262144 },
+ 'microsoft/wizardlm-2-8x22b': {
+ id: 'microsoft/wizardlm-2-8x22b',
+ name: 'Wizardlm 2 8x22B',
+ limit: {
+ context: 65535,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'qwen/qwen3-235b-a22b-fp8': {
- id: 'qwen/qwen3-235b-a22b-fp8',
- name: 'Qwen3 235B A22B',
- limit: { context: 40960 },
+ 'minimaxai/minimax-m1-80k': {
+ id: 'minimaxai/minimax-m1-80k',
+ name: 'MiniMax M1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-r1-0528': {
- id: 'deepseek/deepseek-r1-0528',
- name: 'DeepSeek R1 0528',
- limit: { context: 163840 },
+ 'deepseek/deepseek-ocr': {
+ id: 'deepseek/deepseek-ocr',
+ name: 'DeepSeek-OCR',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'deepseek/deepseek-v4-flash': {
id: 'deepseek/deepseek-v4-flash',
name: 'DeepSeek V4 Flash',
- limit: { context: 1048576 },
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3.1-terminus': {
- id: 'deepseek/deepseek-v3.1-terminus',
- name: 'Deepseek V3.1 Terminus',
- limit: { context: 131072 },
+ 'deepseek/deepseek-prover-v2-671b': {
+ id: 'deepseek/deepseek-prover-v2-671b',
+ name: 'Deepseek Prover V2 671B',
+ limit: {
+ context: 160000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3-0324': {
- id: 'deepseek/deepseek-v3-0324',
- name: 'DeepSeek V3 0324',
- limit: { context: 163840 },
+ 'deepseek/deepseek-r1-0528': {
+ id: 'deepseek/deepseek-r1-0528',
+ name: 'DeepSeek R1 0528',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-ocr': {
- id: 'deepseek/deepseek-ocr',
- name: 'DeepSeek-OCR',
- limit: { context: 8192 },
+ 'deepseek/deepseek-v3.2': {
+ id: 'deepseek/deepseek-v3.2',
+ name: 'Deepseek V3.2',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-r1-distill-qwen-32b': {
+ id: 'deepseek/deepseek-r1-distill-qwen-32b',
+ name: 'DeepSeek R1 Distill Qwen 32B',
+ limit: {
+ context: 64000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek/deepseek-r1-distill-llama-70b': {
id: 'deepseek/deepseek-r1-distill-llama-70b',
name: 'DeepSeek R1 Distill LLama 70B',
- limit: { context: 8192 },
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek/deepseek-r1-turbo': {
id: 'deepseek/deepseek-r1-turbo',
name: 'DeepSeek R1 (Turbo)\t',
- limit: { context: 64000 },
- },
- 'deepseek/deepseek-prover-v2-671b': {
- id: 'deepseek/deepseek-prover-v2-671b',
- name: 'Deepseek Prover V2 671B',
- limit: { context: 160000 },
+ limit: {
+ context: 64000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v4-pro': {
- id: 'deepseek/deepseek-v4-pro',
- name: 'DeepSeek V4 Pro',
- limit: { context: 1048576 },
+ 'deepseek/deepseek-r1-0528-qwen3-8b': {
+ id: 'deepseek/deepseek-r1-0528-qwen3-8b',
+ name: 'DeepSeek R1 0528 Qwen3 8B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek/deepseek-v3.2-exp': {
id: 'deepseek/deepseek-v3.2-exp',
name: 'Deepseek V3.2 Exp',
- limit: { context: 163840 },
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v3.1-terminus': {
+ id: 'deepseek/deepseek-v3.1-terminus',
+ name: 'Deepseek V3.1 Terminus',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v3-turbo': {
+ id: 'deepseek/deepseek-v3-turbo',
+ name: 'DeepSeek V3 (Turbo)\t',
+ limit: {
+ context: 64000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v3-0324': {
+ id: 'deepseek/deepseek-v3-0324',
+ name: 'DeepSeek V3 0324',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'deepseek/deepseek-v4-pro': {
+ id: 'deepseek/deepseek-v4-pro',
+ name: 'DeepSeek V4 Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek/deepseek-ocr-2': {
id: 'deepseek/deepseek-ocr-2',
name: 'deepseek/deepseek-ocr-2',
- limit: { context: 8192 },
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'deepseek/deepseek-r1-distill-qwen-14b': {
id: 'deepseek/deepseek-r1-distill-qwen-14b',
name: 'DeepSeek R1 Distill Qwen 14B',
- limit: { context: 32768 },
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'deepseek/deepseek-v3.1': {
id: 'deepseek/deepseek-v3.1',
name: 'DeepSeek V3.1',
- limit: { context: 131072 },
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-r1-0528-qwen3-8b': {
- id: 'deepseek/deepseek-r1-0528-qwen3-8b',
- name: 'DeepSeek R1 0528 Qwen3 8B',
- limit: { context: 128000 },
+ 'inclusionai/ring-2.6-1t': {
+ id: 'inclusionai/ring-2.6-1t',
+ name: 'Ring-2.6-1T',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-r1-distill-qwen-32b': {
- id: 'deepseek/deepseek-r1-distill-qwen-32b',
- name: 'DeepSeek R1 Distill Qwen 32B',
- limit: { context: 64000 },
+ 'inclusionai/ling-2.6-1t': {
+ id: 'inclusionai/ling-2.6-1t',
+ name: 'Ling-2.6-1T',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3-turbo': {
- id: 'deepseek/deepseek-v3-turbo',
- name: 'DeepSeek V3 (Turbo)\t',
- limit: { context: 64000 },
+ 'inclusionai/ling-2.6-flash': {
+ id: 'inclusionai/ling-2.6-flash',
+ name: 'Ling-2.6-flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek/deepseek-v3.2': {
- id: 'deepseek/deepseek-v3.2',
- name: 'Deepseek V3.2',
- limit: { context: 163840 },
+ 'xiaomimimo/mimo-v2-flash': {
+ id: 'xiaomimimo/mimo-v2-flash',
+ name: 'XiaomiMiMo/MiMo-V2-Flash',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.7-highspeed': {
- id: 'minimax/minimax-m2.7-highspeed',
- name: 'MiniMax-M2.7-highspeed',
- limit: { context: 204800 },
+ 'xiaomimimo/mimo-v2-pro': {
+ id: 'xiaomimimo/mimo-v2-pro',
+ name: 'MiMo-V2-Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.5': {
- id: 'minimax/minimax-m2.5',
- name: 'MiniMax M2.5',
- limit: { context: 204800 },
+ 'xiaomimimo/mimo-v2.5-pro': {
+ id: 'xiaomimimo/mimo-v2.5-pro',
+ name: 'MiMo-V2.5-Pro',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.1': {
- id: 'minimax/minimax-m2.1',
- name: 'Minimax M2.1',
- limit: { context: 204800 },
+ 'meta-llama/llama-3.1-8b-instruct': {
+ id: 'meta-llama/llama-3.1-8b-instruct',
+ name: 'Llama 3.1 8B Instruct',
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2': {
- id: 'minimax/minimax-m2',
- name: 'MiniMax-M2',
- limit: { context: 204800 },
+ 'meta-llama/llama-4-maverick-17b-128e-instruct-fp8': {
+ id: 'meta-llama/llama-4-maverick-17b-128e-instruct-fp8',
+ name: 'Llama 4 Maverick Instruct',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'minimax/minimax-m2.7': {
- id: 'minimax/minimax-m2.7',
- name: 'MiniMax M2.7',
- limit: { context: 204800 },
+ 'meta-llama/llama-3.2-3b-instruct': {
+ id: 'meta-llama/llama-3.2-3b-instruct',
+ name: 'Llama 3.2 3B Instruct',
+ limit: {
+ context: 32768,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'minimax/minimax-m2.5-highspeed': {
- id: 'minimax/minimax-m2.5-highspeed',
- name: 'MiniMax M2.5 Highspeed',
- limit: { context: 204800 },
+ 'meta-llama/llama-3-8b-instruct': {
+ id: 'meta-llama/llama-3-8b-instruct',
+ name: 'Llama 3 8B Instruct',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta-llama/llama-4-scout-17b-16e-instruct': {
+ id: 'meta-llama/llama-4-scout-17b-16e-instruct',
+ name: 'Llama 4 Scout Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'meta-llama/llama-3.3-70b-instruct': {
+ id: 'meta-llama/llama-3.3-70b-instruct',
+ name: 'Llama 3.3 70B Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'meta-llama/llama-3-70b-instruct': {
+ id: 'meta-llama/llama-3-70b-instruct',
+ name: 'Llama3 70B Instruct',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'nousresearch/hermes-2-pro-llama-3-8b': {
+ id: 'nousresearch/hermes-2-pro-llama-3-8b',
+ name: 'Hermes 2 Pro Llama 3 8B',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'openai/gpt-oss-20b': {
+ id: 'openai/gpt-oss-20b',
+ name: 'OpenAI: GPT OSS 20B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'openai/gpt-oss-120b': {
+ id: 'openai/gpt-oss-120b',
+ name: 'OpenAI GPT OSS 120B',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'sao10K/l3-70b-euryale-v2.1': {
+ id: 'sao10K/l3-70b-euryale-v2.1',
+ name: 'L3 70B Euryale V2.1\t',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'sao10K/l3-8b-lunaris': {
+ id: 'sao10K/l3-8b-lunaris',
+ name: 'Sao10k L3 8B Lunaris\t',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'sao10K/L3-8B-stheno-v3.2': {
+ id: 'sao10K/L3-8B-stheno-v3.2',
+ name: 'L3 8B Stheno V3.2',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'sao10K/l31-70b-euryale-v2.2': {
+ id: 'sao10K/l31-70b-euryale-v2.2',
+ name: 'L31 70B Euryale V2.2',
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k2-0905': {
+ id: 'moonshotai/kimi-k2-0905',
+ name: 'Kimi K2 0905',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k2.6': {
+ id: 'moonshotai/kimi-k2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/kimi-k2.7-code': {
+ id: 'moonshotai/kimi-k2.7-code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/kimi-k2-thinking': {
+ id: 'moonshotai/kimi-k2-thinking',
+ name: 'Kimi K2 Thinking',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k3': {
+ id: 'moonshotai/kimi-k3',
+ name: 'Kimi K3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'moonshotai/kimi-k2-instruct': {
+ id: 'moonshotai/kimi-k2-instruct',
+ name: 'Kimi K2 Instruct',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'moonshotai/kimi-k2.5': {
+ id: 'moonshotai/kimi-k2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
+ },
+ 'baichuan/baichuan-m2-32b': {
+ id: 'baichuan/baichuan-m2-32b',
+ name: 'baichuan-m2-32b',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ },
+ },
+ minimax: {
+ name: 'MiniMax (minimax.io)',
+ models: {
+ 'MiniMax-M2': {
+ id: 'MiniMax-M2',
+ name: 'MiniMax-M2',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'MiniMax-M2.1': {
+ id: 'MiniMax-M2.1',
+ name: 'MiniMax-M2.1',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'MiniMax-M2.5': {
+ id: 'MiniMax-M2.5',
+ name: 'MiniMax-M2.5',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'kwaipilot/kat-coder-pro': {
- id: 'kwaipilot/kat-coder-pro',
- name: 'Kat Coder Pro',
- limit: { context: 256000 },
+ 'MiniMax-M2.5-highspeed': {
+ id: 'MiniMax-M2.5-highspeed',
+ name: 'MiniMax-M2.5-highspeed',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'MiniMax-M3': {
+ id: 'MiniMax-M3',
+ name: 'MiniMax-M3',
+ limit: {
+ context: 1048576,
+ },
+ modalities: {
+ input: ['text', 'image', 'video'],
+ },
},
- 'nousresearch/hermes-2-pro-llama-3-8b': {
- id: 'nousresearch/hermes-2-pro-llama-3-8b',
- name: 'Hermes 2 Pro Llama 3 8B',
- limit: { context: 8192 },
+ 'MiniMax-M2.7-highspeed': {
+ id: 'MiniMax-M2.7-highspeed',
+ name: 'MiniMax-M2.7-highspeed',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'MiniMax-M2.7': {
+ id: 'MiniMax-M2.7',
+ name: 'MiniMax-M2.7',
+ limit: {
+ context: 204800,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
},
},
azure: {
name: 'Azure',
models: {
- 'codex-mini': { id: 'codex-mini', name: 'Codex Mini', limit: { context: 200000 } },
- 'phi-3.5-moe-instruct': {
- id: 'phi-3.5-moe-instruct',
- name: 'Phi-3.5-MoE-instruct',
- limit: { context: 128000 },
- },
- 'gpt-3.5-turbo-instruct': {
- id: 'gpt-3.5-turbo-instruct',
- name: 'GPT-3.5 Turbo Instruct',
- limit: { context: 4096 },
- },
- 'deepseek-r1-0528': {
- id: 'deepseek-r1-0528',
- name: 'DeepSeek-R1-0528',
- limit: { context: 163840 },
- },
- 'deepseek-v4-flash': {
- id: 'deepseek-v4-flash',
- name: 'DeepSeek-V4-Flash',
- limit: { context: 1000000 },
- },
- 'gpt-5.2-chat': { id: 'gpt-5.2-chat', name: 'GPT-5.2 Chat', limit: { context: 128000 } },
- o3: { id: 'o3', name: 'o3', limit: { context: 200000 } },
- 'deepseek-v3-0324': {
- id: 'deepseek-v3-0324',
- name: 'DeepSeek-V3-0324',
- limit: { context: 131072 },
- },
- 'phi-3-small-128k-instruct': {
- id: 'phi-3-small-128k-instruct',
- name: 'Phi-3-small-instruct (128k)',
- limit: { context: 128000 },
- },
- 'meta-llama-3-8b-instruct': {
- id: 'meta-llama-3-8b-instruct',
- name: 'Meta-Llama-3-8B-Instruct',
- limit: { context: 8192 },
+ 'claude-sonnet-4-6': {
+ id: 'claude-sonnet-4-6',
+ name: 'Claude Sonnet 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5-nano': {
+ id: 'gpt-5-nano',
+ name: 'GPT-5 Nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'mistral-small-2503': {
id: 'mistral-small-2503',
name: 'Mistral Small 3.1',
- limit: { context: 128000 },
- },
- 'text-embedding-3-large': {
- id: 'text-embedding-3-large',
- name: 'text-embedding-3-large',
- limit: { context: 8191 },
- },
- 'o1-mini': { id: 'o1-mini', name: 'o1-mini', limit: { context: 128000 } },
- 'phi-3.5-mini-instruct': {
- id: 'phi-3.5-mini-instruct',
- name: 'Phi-3.5-mini-instruct',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistral-nemo': { id: 'mistral-nemo', name: 'Mistral Nemo', limit: { context: 128000 } },
- 'cohere-embed-v-4-0': {
- id: 'cohere-embed-v-4-0',
- name: 'Embed v4',
- limit: { context: 128000 },
- },
- 'claude-opus-4-5': {
- id: 'claude-opus-4-5',
- name: 'Claude Opus 4.5',
- limit: { context: 200000 },
- },
- 'gpt-5': { id: 'gpt-5', name: 'GPT-5', limit: { context: 272000 } },
- 'gpt-5-chat': { id: 'gpt-5-chat', name: 'GPT-5 Chat', limit: { context: 128000 } },
- 'cohere-command-a': { id: 'cohere-command-a', name: 'Command A', limit: { context: 256000 } },
- 'llama-3.2-11b-vision-instruct': {
- id: 'llama-3.2-11b-vision-instruct',
- name: 'Llama-3.2-11B-Vision-Instruct',
- limit: { context: 128000 },
- },
- 'gpt-5-pro': { id: 'gpt-5-pro', name: 'GPT-5 Pro', limit: { context: 400000 } },
- 'cohere-command-r-08-2024': {
- id: 'cohere-command-r-08-2024',
- name: 'Command R',
- limit: { context: 128000 },
- },
- 'gpt-4o': { id: 'gpt-4o', name: 'GPT-4o', limit: { context: 128000 } },
- 'gpt-4': { id: 'gpt-4', name: 'GPT-4', limit: { context: 8192 } },
- 'o4-mini': { id: 'o4-mini', name: 'o4-mini', limit: { context: 200000 } },
- 'phi-3-medium-128k-instruct': {
- id: 'phi-3-medium-128k-instruct',
- name: 'Phi-3-medium-instruct (128k)',
- limit: { context: 128000 },
- },
- 'gpt-4-32k': { id: 'gpt-4-32k', name: 'GPT-4 32K', limit: { context: 32768 } },
- 'meta-llama-3.1-405b-instruct': {
- id: 'meta-llama-3.1-405b-instruct',
- name: 'Meta-Llama-3.1-405B-Instruct',
- limit: { context: 128000 },
- },
- 'cohere-command-r-plus-08-2024': {
- id: 'cohere-command-r-plus-08-2024',
- name: 'Command R+',
- limit: { context: 128000 },
+ 'grok-4-1-fast-non-reasoning': {
+ id: 'grok-4-1-fast-non-reasoning',
+ name: 'Grok 4.1 Fast (Non-Reasoning)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'ministral-3b': {
+ id: 'ministral-3b',
+ name: 'Ministral 3B',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-4.1-nano': {
+ id: 'gpt-4.1-nano',
+ name: 'GPT-4.1 nano',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'phi-4-mini': { id: 'phi-4-mini', name: 'Phi-4-mini', limit: { context: 128000 } },
'gpt-3.5-turbo-1106': {
id: 'gpt-3.5-turbo-1106',
name: 'GPT-3.5 Turbo 1106',
- limit: { context: 16384 },
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5-codex': {
+ id: 'gpt-5-codex',
+ name: 'GPT-5-Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5-pro': {
+ id: 'gpt-5-pro',
+ name: 'GPT-5 Pro',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'llama-4-scout-17b-16e-instruct': {
- id: 'llama-4-scout-17b-16e-instruct',
- name: 'Llama 4 Scout 17B 16E Instruct',
- limit: { context: 128000 },
+ 'phi-4-mini-reasoning': {
+ id: 'phi-4-mini-reasoning',
+ name: 'Phi-4-mini-reasoning',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'codex-mini': {
+ id: 'codex-mini',
+ name: 'Codex Mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'llama-3.3-70b-instruct': {
- id: 'llama-3.3-70b-instruct',
- name: 'Llama-3.3-70B-Instruct',
- limit: { context: 128000 },
+ 'gpt-5.1-codex-mini': {
+ id: 'gpt-5.1-codex-mini',
+ name: 'GPT-5.1 Codex Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.1-codex': {
+ id: 'gpt-5.1-codex',
+ name: 'GPT-5.1 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'gpt-5.6-sol': {
+ id: 'gpt-5.6-sol',
+ name: 'GPT-5.6 Sol',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'grok-4-20-non-reasoning': {
- id: 'grok-4-20-non-reasoning',
- name: 'Grok 4.20 (Non-Reasoning)',
- limit: { context: 262000 },
+ 'phi-4-reasoning-plus': {
+ id: 'phi-4-reasoning-plus',
+ name: 'Phi-4-reasoning-plus',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'claude-opus-5': {
+ id: 'claude-opus-5',
+ name: 'Claude Opus 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'kimi-k2.6': {
+ id: 'kimi-k2.6',
+ name: 'Kimi K2.6',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'cohere-command-a': {
+ id: 'cohere-command-a',
+ name: 'Command A',
+ limit: {
+ context: 131072,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.2-codex': {
+ id: 'gpt-5.2-codex',
+ name: 'GPT-5.2 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-5.1-chat': { id: 'gpt-5.1-chat', name: 'GPT-5.1 Chat', limit: { context: 128000 } },
- 'deepseek-v4-pro': {
- id: 'deepseek-v4-pro',
- name: 'DeepSeek-V4-Pro',
- limit: { context: 1000000 },
+ 'llama-4-maverick-17b-128e-instruct-fp8': {
+ id: 'llama-4-maverick-17b-128e-instruct-fp8',
+ name: 'Llama 4 Maverick 17B 128E Instruct FP8',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'kimi-k2-thinking': {
- id: 'kimi-k2-thinking',
- name: 'Kimi K2 Thinking',
- limit: { context: 262144 },
+ 'cohere-embed-v3-english': {
+ id: 'cohere-embed-v3-english',
+ name: 'Embed v3 English',
+ limit: {
+ context: 512,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-6-astra': {
+ id: 'gpt-6-astra',
+ name: 'GPT-6 Astra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-4-5': {
- id: 'claude-sonnet-4-5',
- name: 'Claude Sonnet 4.5',
- limit: { context: 200000 },
+ 'claude-opus-4-5': {
+ id: 'claude-opus-4-5',
+ name: 'Claude Opus 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-sonnet-5': {
- id: 'claude-sonnet-5',
- name: 'Claude Sonnet 5',
- limit: { context: 1000000 },
+ 'deepseek-v4-flash': {
+ id: 'deepseek-v4-flash',
+ name: 'DeepSeek-V4-Flash',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'deepseek-r1': { id: 'deepseek-r1', name: 'DeepSeek-R1', limit: { context: 163840 } },
- 'grok-4-1-fast-non-reasoning': {
- id: 'grok-4-1-fast-non-reasoning',
- name: 'Grok 4.1 Fast (Non-Reasoning)',
- limit: { context: 128000 },
+ 'kimi-k2.7-code': {
+ id: 'kimi-k2.7-code',
+ name: 'Kimi K2.7 Code',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-5.4-nano': { id: 'gpt-5.4-nano', name: 'GPT-5.4 Nano', limit: { context: 400000 } },
- 'phi-3-small-8k-instruct': {
- id: 'phi-3-small-8k-instruct',
- name: 'Phi-3-small-instruct (8k)',
- limit: { context: 8192 },
+ 'cohere-embed-v-4-0': {
+ id: 'cohere-embed-v-4-0',
+ name: 'Embed v4',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'phi-4': {
+ id: 'phi-4',
+ name: 'Phi-4',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-4.1-mini': {
+ id: 'gpt-4.1-mini',
+ name: 'GPT-4.1 mini',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-5.3-chat': { id: 'gpt-5.3-chat', name: 'GPT-5.3 Chat', limit: { context: 128000 } },
'gpt-3.5-turbo-0125': {
id: 'gpt-3.5-turbo-0125',
name: 'GPT-3.5 Turbo 0125',
- limit: { context: 16384 },
+ limit: {
+ context: 16384,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'cohere-embed-v3-multilingual': {
- id: 'cohere-embed-v3-multilingual',
- name: 'Embed v3 Multilingual',
- limit: { context: 512 },
+ 'phi-4-multimodal': {
+ id: 'phi-4-multimodal',
+ name: 'Phi-4-multimodal',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
+ },
+ 'phi-4-mini': {
+ id: 'phi-4-mini',
+ name: 'Phi-4-mini',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.4': {
+ id: 'gpt-5.4',
+ name: 'GPT-5.4',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-4-turbo': {
+ id: 'gpt-4-turbo',
+ name: 'GPT-4 Turbo',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'gpt-3.5-turbo-0613': {
- id: 'gpt-3.5-turbo-0613',
- name: 'GPT-3.5 Turbo 0613',
- limit: { context: 16384 },
+ 'grok-4-1-fast-reasoning': {
+ id: 'grok-4-1-fast-reasoning',
+ name: 'Grok 4.1 Fast (Reasoning)',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'claude-fable-5-1': {
+ id: 'claude-fable-5-1',
+ name: 'Claude Fable 5.1',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-5.1': {
+ id: 'gpt-5.1',
+ name: 'GPT-5.1',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'audio'],
+ },
},
- 'gpt-5.1-codex': { id: 'gpt-5.1-codex', name: 'GPT-5.1 Codex', limit: { context: 400000 } },
'gpt-5.1-codex-max': {
id: 'gpt-5.1-codex-max',
name: 'GPT-5.1 Codex Max',
- limit: { context: 400000 },
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'phi-4-reasoning': {
- id: 'phi-4-reasoning',
- name: 'Phi-4-reasoning',
- limit: { context: 32000 },
+ 'claude-opus-4-6': {
+ id: 'claude-opus-4-6',
+ name: 'Claude Opus 4.6',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'deepseek-r1': {
+ id: 'deepseek-r1',
+ name: 'DeepSeek-R1',
+ limit: {
+ context: 163840,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ o1: {
+ id: 'o1',
+ name: 'o1',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-4o': {
+ id: 'gpt-4o',
+ name: 'GPT-4o',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.6-luna': {
+ id: 'gpt-5.6-luna',
+ name: 'GPT-5.6 Luna',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-opus-4-8': {
- id: 'claude-opus-4-8',
- name: 'Claude Opus 4.8',
- limit: { context: 200000 },
+ 'claude-opus-4-7': {
+ id: 'claude-opus-4-7',
+ name: 'Claude Opus 4.7',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'deepseek-v3.2': {
+ id: 'deepseek-v3.2',
+ name: 'DeepSeek-V3.2',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'mistral-medium-2505': {
- id: 'mistral-medium-2505',
- name: 'Mistral Medium 3',
- limit: { context: 128000 },
+ 'gpt-4-turbo-vision': {
+ id: 'gpt-4-turbo-vision',
+ name: 'GPT-4 Turbo Vision',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.3-codex': {
+ id: 'gpt-5.3-codex',
+ name: 'GPT-5.3 Codex',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'llama-4-scout-17b-16e-instruct': {
+ id: 'llama-4-scout-17b-16e-instruct',
+ name: 'Llama 4 Scout 17B 16E Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-4o-mini': {
+ id: 'gpt-4o-mini',
+ name: 'GPT-4o mini',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'meta-llama-3.1-70b-instruct': {
- id: 'meta-llama-3.1-70b-instruct',
- name: 'Meta-Llama-3.1-70B-Instruct',
- limit: { context: 128000 },
+ 'claude-fable-5': {
+ id: 'claude-fable-5',
+ name: 'Claude Fable 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-image-1.5': {
+ id: 'gpt-image-1.5',
+ name: 'GPT-Image-1.5',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-4.1': {
+ id: 'gpt-4.1',
+ name: 'GPT-4.1',
+ limit: {
+ context: 1047576,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'text-embedding-ada-002': {
id: 'text-embedding-ada-002',
name: 'text-embedding-ada-002',
- limit: { context: 8192 },
- },
- 'o3-mini': { id: 'o3-mini', name: 'o3-mini', limit: { context: 200000 } },
- 'gpt-5.2': { id: 'gpt-5.2', name: 'GPT-5.2', limit: { context: 400000 } },
- 'gpt-4-turbo-vision': {
- id: 'gpt-4-turbo-vision',
- name: 'GPT-4 Turbo Vision',
- limit: { context: 128000 },
+ limit: {
+ context: 8192,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-image-1': {
+ id: 'gpt-image-1',
+ name: 'GPT-Image-1',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.4-nano': {
+ id: 'gpt-5.4-nano',
+ name: 'GPT-5.4 Nano',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'model-router': {
+ id: 'model-router',
+ name: 'Model Router',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'mistral-large-2411': {
- id: 'mistral-large-2411',
- name: 'Mistral Large 24.11',
- limit: { context: 128000 },
+ 'gpt-chat-latest': {
+ id: 'gpt-chat-latest',
+ name: 'GPT Chat Latest',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gpt-5.3-codex': { id: 'gpt-5.3-codex', name: 'GPT-5.3 Codex', limit: { context: 400000 } },
- 'text-embedding-3-small': {
- id: 'text-embedding-3-small',
- name: 'text-embedding-3-small',
- limit: { context: 8191 },
+ 'cohere-embed-v3-multilingual': {
+ id: 'cohere-embed-v3-multilingual',
+ name: 'Embed v3 Multilingual',
+ limit: {
+ context: 512,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.4-mini': {
+ id: 'gpt-5.4-mini',
+ name: 'GPT-5.4 Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-image-2.5-sunburst': {
+ id: 'gpt-image-2.5-sunburst',
+ name: 'GPT Image 2.5 Sunburst',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'grok-4.6': {
+ id: 'grok-4.6',
+ name: 'Grok 4.6',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
'deepseek-v3.2-speciale': {
id: 'deepseek-v3.2-speciale',
name: 'DeepSeek-V3.2-Speciale',
- limit: { context: 128000 },
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'gpt-3.5-turbo-0301': {
- id: 'gpt-3.5-turbo-0301',
- name: 'GPT-3.5 Turbo 0301',
- limit: { context: 4096 },
+ 'claude-haiku-4-5': {
+ id: 'claude-haiku-4-5',
+ name: 'Claude Haiku 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'meta-llama-3.1-8b-instruct': {
- id: 'meta-llama-3.1-8b-instruct',
- name: 'Meta-Llama-3.1-8B-Instruct',
- limit: { context: 128000 },
+ 'claude-sonnet-4-5': {
+ id: 'claude-sonnet-4-5',
+ name: 'Claude Sonnet 4.5',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'gpt-5.6-luna': { id: 'gpt-5.6-luna', name: 'GPT-5.6 Luna', limit: { context: 1050000 } },
'claude-opus-4-1': {
id: 'claude-opus-4-1',
name: 'Claude Opus 4.1',
- limit: { context: 200000 },
- },
- 'gpt-5.1-codex-mini': {
- id: 'gpt-5.1-codex-mini',
- name: 'GPT-5.1 Codex Mini',
- limit: { context: 400000 },
- },
- 'kimi-k2.5': { id: 'kimi-k2.5', name: 'Kimi K2.5', limit: { context: 262144 } },
- 'phi-4': { id: 'phi-4', name: 'Phi-4', limit: { context: 128000 } },
- 'gpt-5.6-terra': { id: 'gpt-5.6-terra', name: 'GPT-5.6 Terra', limit: { context: 1050000 } },
- 'grok-4-fast-reasoning': {
- id: 'grok-4-fast-reasoning',
- name: 'Grok 4 Fast (Reasoning)',
- limit: { context: 2000000 },
- },
- 'gpt-image-1.5': { id: 'gpt-image-1.5', name: 'GPT-Image-1.5' },
- 'gpt-4.1-nano': { id: 'gpt-4.1-nano', name: 'GPT-4.1 nano', limit: { context: 1047576 } },
- 'claude-fable-5': {
- id: 'claude-fable-5',
- name: 'Claude Fable 5',
- limit: { context: 1000000 },
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'gpt-image-2': {
+ id: 'gpt-image-2',
+ name: 'GPT-Image-2',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'kimi-k2.5': {
+ id: 'kimi-k2.5',
+ name: 'Kimi K2.5',
+ limit: {
+ context: 262144,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- o1: { id: 'o1', name: 'o1', limit: { context: 200000 } },
- 'deepseek-v3.1': { id: 'deepseek-v3.1', name: 'DeepSeek-V3.1', limit: { context: 131072 } },
- 'gpt-chat-latest': {
- id: 'gpt-chat-latest',
- name: 'GPT Chat Latest',
- limit: { context: 128000 },
+ 'phi-4-reasoning': {
+ id: 'phi-4-reasoning',
+ name: 'Phi-4-reasoning',
+ limit: {
+ context: 32000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'llama-3.2-90b-vision-instruct': {
- id: 'llama-3.2-90b-vision-instruct',
- name: 'Llama-3.2-90B-Vision-Instruct',
- limit: { context: 128000 },
+ 'claude-opus-4-8': {
+ id: 'claude-opus-4-8',
+ name: 'Claude Opus 4.8',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'claude-haiku-4-5': {
- id: 'claude-haiku-4-5',
- name: 'Claude Haiku 4.5',
- limit: { context: 200000 },
+ 'deepseek-v4-pro': {
+ id: 'deepseek-v4-pro',
+ name: 'DeepSeek-V4-Pro',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'ministral-3b': { id: 'ministral-3b', name: 'Ministral 3B', limit: { context: 128000 } },
- 'gpt-5.4': { id: 'gpt-5.4', name: 'GPT-5.4', limit: { context: 1050000 } },
- 'gpt-5.4-mini': { id: 'gpt-5.4-mini', name: 'GPT-5.4 Mini', limit: { context: 400000 } },
- 'kimi-k2.6': { id: 'kimi-k2.6', name: 'Kimi K2.6', limit: { context: 262144 } },
- 'gpt-4.1': { id: 'gpt-4.1', name: 'GPT-4.1', limit: { context: 1047576 } },
- 'claude-opus-4-6': {
- id: 'claude-opus-4-6',
- name: 'Claude Opus 4.6',
- limit: { context: 200000 },
+ 'mistral-medium-2505': {
+ id: 'mistral-medium-2505',
+ name: 'Mistral Medium 3',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'grok-4-1-fast-reasoning': {
- id: 'grok-4-1-fast-reasoning',
- name: 'Grok 4.1 Fast (Reasoning)',
- limit: { context: 128000 },
- },
- 'gpt-5-mini': { id: 'gpt-5-mini', name: 'GPT-5 Mini', limit: { context: 272000 } },
- 'gpt-image-1': { id: 'gpt-image-1', name: 'GPT-Image-1' },
- 'gpt-4.1-mini': { id: 'gpt-4.1-mini', name: 'GPT-4.1 mini', limit: { context: 1047576 } },
- 'gpt-4-turbo': { id: 'gpt-4-turbo', name: 'GPT-4 Turbo', limit: { context: 128000 } },
- 'gpt-5-nano': { id: 'gpt-5-nano', name: 'GPT-5 Nano', limit: { context: 272000 } },
- 'phi-3-medium-4k-instruct': {
- id: 'phi-3-medium-4k-instruct',
- name: 'Phi-3-medium-instruct (4k)',
- limit: { context: 4096 },
- },
- 'gpt-5.4-pro': { id: 'gpt-5.4-pro', name: 'GPT-5.4 Pro', limit: { context: 1050000 } },
- 'cohere-embed-v3-english': {
- id: 'cohere-embed-v3-english',
- name: 'Embed v3 English',
- limit: { context: 512 },
+ 'text-embedding-3-small': {
+ id: 'text-embedding-3-small',
+ name: 'text-embedding-3-small',
+ limit: {
+ context: 8191,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5-mini': {
+ id: 'gpt-5-mini',
+ name: 'GPT-5 Mini',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.4-pro': {
+ id: 'gpt-5.4-pro',
+ name: 'GPT-5.4 Pro',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
},
- 'claude-sonnet-4-6': {
- id: 'claude-sonnet-4-6',
- name: 'Claude Sonnet 4.6',
- limit: { context: 1000000 },
+ 'text-embedding-3-large': {
+ id: 'text-embedding-3-large',
+ name: 'text-embedding-3-large',
+ limit: {
+ context: 8191,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
'codestral-2501': {
id: 'codestral-2501',
name: 'Codestral 25.01',
- limit: { context: 256000 },
+ limit: {
+ context: 256000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'phi-4-reasoning-plus': {
- id: 'phi-4-reasoning-plus',
- name: 'Phi-4-reasoning-plus',
- limit: { context: 32000 },
+ 'gpt-3.5-turbo-instruct': {
+ id: 'gpt-3.5-turbo-instruct',
+ name: 'GPT-3.5 Turbo Instruct',
+ limit: {
+ context: 4096,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-image-2.5-flare': {
+ id: 'gpt-image-2.5-flare',
+ name: 'GPT Image 2.5 Flare',
+ limit: {
+ context: 0,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.6-terra': {
+ id: 'gpt-5.6-terra',
+ name: 'GPT-5.6 Terra',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'phi-4-multimodal': {
- id: 'phi-4-multimodal',
- name: 'Phi-4-multimodal',
- limit: { context: 128000 },
+ 'grok-4-20-non-reasoning': {
+ id: 'grok-4-20-non-reasoning',
+ name: 'Grok 4.20 (Non-Reasoning)',
+ limit: {
+ context: 262000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'gpt-5.2': {
+ id: 'gpt-5.2',
+ name: 'GPT-5.2',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5': {
+ id: 'gpt-5',
+ name: 'GPT-5',
+ limit: {
+ context: 400000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'claude-sonnet-5': {
+ id: 'claude-sonnet-5',
+ name: 'Claude Sonnet 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'llama-3.3-70b-instruct': {
+ id: 'llama-3.3-70b-instruct',
+ name: 'Llama-3.3-70B-Instruct',
+ limit: {
+ context: 128000,
+ },
+ modalities: {
+ input: ['text'],
+ },
},
- 'gpt-4o-mini': { id: 'gpt-4o-mini', name: 'GPT-4o mini', limit: { context: 128000 } },
- 'gpt-5.6-sol': { id: 'gpt-5.6-sol', name: 'GPT-5.6 Sol', limit: { context: 1050000 } },
- 'model-router': { id: 'model-router', name: 'Model Router', limit: { context: 128000 } },
'grok-4-20-reasoning': {
id: 'grok-4-20-reasoning',
name: 'Grok 4.20 (Reasoning)',
- limit: { context: 262000 },
- },
- 'gpt-5-codex': { id: 'gpt-5-codex', name: 'GPT-5-Codex', limit: { context: 400000 } },
- 'deepseek-v3.2': { id: 'deepseek-v3.2', name: 'DeepSeek-V3.2', limit: { context: 128000 } },
- 'llama-4-maverick-17b-128e-instruct-fp8': {
- id: 'llama-4-maverick-17b-128e-instruct-fp8',
- name: 'Llama 4 Maverick 17B 128E Instruct FP8',
- limit: { context: 128000 },
- },
- 'gpt-5.2-codex': { id: 'gpt-5.2-codex', name: 'GPT-5.2 Codex', limit: { context: 400000 } },
- 'phi-4-mini-reasoning': {
- id: 'phi-4-mini-reasoning',
- name: 'Phi-4-mini-reasoning',
- limit: { context: 128000 },
- },
- 'phi-3-mini-128k-instruct': {
- id: 'phi-3-mini-128k-instruct',
- name: 'Phi-3-mini-instruct (128k)',
- limit: { context: 128000 },
- },
- 'gpt-image-2': { id: 'gpt-image-2', name: 'GPT-Image-2' },
- 'phi-3-mini-4k-instruct': {
- id: 'phi-3-mini-4k-instruct',
- name: 'Phi-3-mini-instruct (4k)',
- limit: { context: 4096 },
- },
- 'meta-llama-3-70b-instruct': {
- id: 'meta-llama-3-70b-instruct',
- name: 'Meta-Llama-3-70B-Instruct',
- limit: { context: 8192 },
- },
- 'gpt-5.1': { id: 'gpt-5.1', name: 'GPT-5.1', limit: { context: 272000 } },
- 'gpt-5.5': { id: 'gpt-5.5', name: 'GPT-5.5', limit: { context: 1050000 } },
- },
- },
- minimax: {
- name: 'MiniMax (minimax.io)',
- models: {
- 'MiniMax-M2.7': { id: 'MiniMax-M2.7', name: 'MiniMax-M2.7', limit: { context: 204800 } },
- 'MiniMax-M2.7-highspeed': {
- id: 'MiniMax-M2.7-highspeed',
- name: 'MiniMax-M2.7-highspeed',
- limit: { context: 204800 },
- },
- 'MiniMax-M2.1': { id: 'MiniMax-M2.1', name: 'MiniMax-M2.1', limit: { context: 204800 } },
- 'MiniMax-M2': { id: 'MiniMax-M2', name: 'MiniMax-M2', limit: { context: 196608 } },
- 'MiniMax-M2.5-highspeed': {
- id: 'MiniMax-M2.5-highspeed',
- name: 'MiniMax-M2.5-highspeed',
- limit: { context: 204800 },
+ limit: {
+ context: 262000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ 'o4-mini': {
+ id: 'o4-mini',
+ name: 'o4-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'claude-mythos-5': {
+ id: 'claude-mythos-5',
+ name: 'Claude Mythos 5',
+ limit: {
+ context: 1000000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
+ },
+ 'o3-mini': {
+ id: 'o3-mini',
+ name: 'o3-mini',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text'],
+ },
+ },
+ o3: {
+ id: 'o3',
+ name: 'o3',
+ limit: {
+ context: 200000,
+ },
+ modalities: {
+ input: ['text', 'image'],
+ },
+ },
+ 'gpt-5.5': {
+ id: 'gpt-5.5',
+ name: 'GPT-5.5',
+ limit: {
+ context: 1050000,
+ },
+ modalities: {
+ input: ['text', 'image', 'pdf'],
+ },
},
- 'MiniMax-M3': { id: 'MiniMax-M3', name: 'MiniMax-M3', limit: { context: 1000000 } },
- 'MiniMax-M2.5': { id: 'MiniMax-M2.5', name: 'MiniMax-M2.5', limit: { context: 204800 } },
},
},
}
diff --git a/control-api/src/db.ts b/control-api/src/db.ts
index 5ca72d8ab..04cc4f61f 100644
--- a/control-api/src/db.ts
+++ b/control-api/src/db.ts
@@ -6046,6 +6046,61 @@ export const CONTROL_API_MIGRATIONS: DbMigration[] = [
version: '0114_llm_provider_attempts_connection_integrity',
apply: applyLlmProviderAttemptConnectionIntegritySchema,
},
+ {
+ // Renumbered from 0109 when `dev` was merged: `dev` had already shipped
+ // `0109_grok_subscription_connections`, so this one moves to the end of the
+ // list rather than claiming a version another migration already uses.
+ version: '0115_llm_allowed_models_image_input',
+ apply: async db => {
+ // #654 — model-level image-input capability + evidence for the allowlist.
+ //
+ // ADDITIVE and NULLABLE. Every pre-existing row reads as `unknown` (no
+ // affirmative capability): the shared contract
+ // (`@clerum/llm-providers` normalizeImageInputCapability) maps absent or
+ // malformed metadata to `{ state: 'unknown' }`, so a legacy row can never
+ // become affirmative support by accident, and this migration alone changes
+ // no runtime behavior — enforcement acts only where a capability exists.
+ //
+ // The CHECK constrains the ONE field no reader may have to guess (`state`)
+ // against a non-object/scalar payload. The nested evidence is validated
+ // strictly on write by the service (shared parser) and normalized on read,
+ // so `state` here is a backstop, not the only gate.
+ //
+ // All three conjuncts are load-bearing, because a CHECK accepts NULL:
+ // `jsonb_typeof` alone would let `{}` through (`'{}'::jsonb->>'state'` is
+ // NULL, so the IN list yields NULL, not FALSE), and `? 'state'` alone
+ // would let `{"state": null}` through (`?` is true while `->>` is NULL).
+ // COALESCE is what turns that untyped NULL into a real FALSE.
+ await db.query(`
+ ALTER TABLE llm_allowed_models
+ ADD COLUMN IF NOT EXISTS image_input JSONB;
+ DO $$ BEGIN
+ ALTER TABLE llm_allowed_models
+ ADD CONSTRAINT llm_allowed_models_image_input_state_check
+ CHECK (
+ image_input IS NULL
+ OR (
+ jsonb_typeof(image_input) = 'object'
+ AND image_input ? 'state'
+ AND COALESCE(
+ image_input->>'state' IN ('supported','unsupported','unknown'),
+ false
+ )
+ )
+ );
+ EXCEPTION WHEN duplicate_object THEN NULL;
+ END $$;
+ `)
+
+ // This migration is PURELY ADDITIVE: it adds the column and the CHECK, and
+ // writes no data. It used to hand-curate two Z.AI ids from their public
+ // docs, which was a stand-in for not knowing any model's image capability.
+ // The catalog sync now derives that from models.dev `modalities.input` for
+ // every model, including those two (#654), so the seed would only have
+ // pinned `curated` provenance the sync is required never to overwrite —
+ // freezing exactly the rows a test harness needs to be able to refresh.
+ },
+ },
]
async function consolidateWorkflowAllowedUsersToTriggers(db: DbClient): Promise<void> {
diff --git a/control-api/src/main.ts b/control-api/src/main.ts
index 38fe4612a..c77b9d132 100644
--- a/control-api/src/main.ts
+++ b/control-api/src/main.ts
@@ -12,6 +12,7 @@ import {
startBudgetReservationSweepCron,
stopBudgetReservationSweepCron,
} from './services/budgetReservationSweepCron.js'
+import { syncDiscoveredModels } from './services/llmCatalogSync.js'
import { startLlmCatalogSyncCron, stopLlmCatalogSyncCron } from './services/llmCatalogSyncCron.js'
import { runBootEnrollment } from './services/memberRegistrationEnrollment.js'
import {
@@ -79,20 +80,6 @@ async function main(): Promise<void> {
startBudgetReservationSweepCron(config.budgetReservationSweepIntervalMs)
startWorkflowApprovalTraceProjector()
- // LLM catalog discovery sync cron (Fase 4). DEFAULT OFF — opt in with
- // LLM_CATALOG_SYNC_CRON_ENABLED=true. Non-destructive: inserts disabled
- // discovery rows, only stale-flags vanished ones under the §4.5 guards.
- if (config.llmCatalogSyncCronEnabled) {
- startLlmCatalogSyncCron({}, config.llmCatalogSyncIntervalMs)
- console.log(
- `[ControlAPI] LLM catalog sync cron enabled (interval=${config.llmCatalogSyncIntervalMs}ms)`
- )
- } else {
- console.log(
- '[ControlAPI] LLM catalog sync cron disabled (LLM_CATALOG_SYNC_CRON_ENABLED not "true")'
- )
- }
-
if (config.userApprovalRequestArchiveCronEnabled) {
startArchiveCron({
retentionDays: config.approvalRetentionDays,
@@ -107,6 +94,28 @@ async function main(): Promise<void> {
const gateway = new K8sGateway(config.namespace)
+ // LLM catalog discovery sync cron (Fase 4). Code default off; the base deploy
+ // sets LLM_CATALOG_SYNC_CRON_ENABLED=true. When on, the first sync runs a few
+ // seconds after start (not awaited — boot never waits on models.dev), then
+ // every interval. Non-destructive: inserts disabled discovery rows, only
+ // stale-flags vanished ones under the §4.5 guards.
+ // Started AFTER the gateway exists (#654): the sync publishes the allowlist
+ // ConfigMap when it changes image-input evidence on an enabled row, so it
+ // needs a materializer — the same one the admin routes use.
+ if (config.llmCatalogSyncCronEnabled) {
+ startLlmCatalogSyncCron(
+ { sync: () => syncDiscoveredModels({ materializer: gateway.llmAllowedModelsConfigMap() }) },
+ config.llmCatalogSyncIntervalMs
+ )
+ console.log(
+ `[ControlAPI] LLM catalog sync cron enabled (interval=${config.llmCatalogSyncIntervalMs}ms)`
+ )
+ } else {
+ console.log(
+ '[ControlAPI] LLM catalog sync cron disabled (LLM_CATALOG_SYNC_CRON_ENABLED not "true")'
+ )
+ }
+
// Assert the platform image-pull credential up front and then on a timer. WRC injects
// the reference for ANY WorkflowRecipe, including ones created by `kubectl apply` or the
// `deploy_recipe` tool that control-api never sees — so provisioning cannot only happen
diff --git a/control-api/src/observability/metrics.ts b/control-api/src/observability/metrics.ts
index a1155e5a9..4ad66acfa 100644
--- a/control-api/src/observability/metrics.ts
+++ b/control-api/src/observability/metrics.ts
@@ -537,5 +537,5 @@ export function recordGovernedTraceOperationalError(
export const llmAllowlistConfigMapWriteFailuresTotal = getOrCreateCounter({
name: 'clerum_llm_allowlist_configmap_write_failures_total',
help: 'Count of failed clerum-llm-allowed-models ConfigMap writes, labelled by phase.',
- labelNames: ['phase'] as const as Array<'phase'>, // mutation | boot
+ labelNames: ['phase'] as const as Array<'phase'>, // mutation | boot | sync
})
diff --git a/control-api/src/routes/admin/llmModels.ts b/control-api/src/routes/admin/llmModels.ts
index 6e8a857b4..4c482ff7f 100644
--- a/control-api/src/routes/admin/llmModels.ts
+++ b/control-api/src/routes/admin/llmModels.ts
@@ -205,14 +205,18 @@ export function createAdminLlmModelsRouter(gateway: K8sGateway): Router {
// only; a scheduled trigger is a follow-up). These routes inherit the same
// control-ui admin auth gate as the rest of `/admin/*` (app.ts).
//
- // The sync deliberately does NOT re-materialize the ConfigMap: it never
- // mutates a `WHERE enabled` / serialized column of an enabled row (new writes
- // are `enabled=false`), so the allowlist ConfigMap stays byte-identical until an
- // operator enables a discovered model through the normal PUT path.
+ // The sync owns the re-materialization decision (#654): it publishes only when
+ // it changed `image_input` on an enabled row, and never touches `enabled` or
+ // any other serialized column of one. The route hands it the same gateway
+ // materializer every mutation route uses; a failed write is reported by the
+ // service and surfaces here as a 500 (the DB commit is already durable and the
+ // boot reconcile converges).
router.post(
'/admin/llm-models/discovery/sync',
asyncHandler(async (_req: Request, res: Response) => {
- const result = await syncDiscoveredModels()
+ const result = await syncDiscoveredModels({
+ materializer: gateway.llmAllowedModelsConfigMap(),
+ })
res.status(200).json(result)
})
)
diff --git a/control-api/src/services/llmAllowedModels.ts b/control-api/src/services/llmAllowedModels.ts
index dfb979a23..5b27f38e0 100644
--- a/control-api/src/services/llmAllowedModels.ts
+++ b/control-api/src/services/llmAllowedModels.ts
@@ -14,6 +14,11 @@
* index surfaces as `LlmAllowedModelConflictError` so routes can answer 409.
*/
import { z } from 'zod'
+import {
+ type ImageInputCapability,
+ normalizeImageInputCapability,
+ parseImageInputCapability,
+} from '@clerum/llm-providers'
import type { DbClient } from '../db.js'
import { pool } from '../db.js'
@@ -35,6 +40,12 @@ export type LlmAllowedModel = {
discovered_at: string | null
last_seen_at: string | null
stale: boolean
+ /**
+ * Model-level image-input capability + evidence (#654). ALWAYS normalized
+ * through the shared contract: a NULL/malformed stored value reads as
+ * `{ state: 'unknown' }`, never as affirmative support.
+ */
+ image_input: ImageInputCapability
created_at: string
updated_at: string
}
@@ -45,6 +56,13 @@ export type AllowedModelEntry = {
displayName?: string
contextWindowTokens?: number
vendor?: string
+ /**
+ * Capability metadata for the runtime guard (#654). OMITTED when the row has
+ * no stored metadata — consumers must treat absence as `{ state: 'unknown' }`
+ * (the shared `normalizeImageInputCapability` does exactly that), which keeps
+ * the ConfigMap byte-identical for allowlists that predate the field.
+ */
+ imageInput?: ImageInputCapability
}
/** Thrown when an insert/update collides with the (provider, model) unique index. */
@@ -77,6 +95,29 @@ const contextWindowField = z
.min(1, 'must be >= 1')
.max(MAX_CONTEXT_WINDOW_TOKENS, `must be <= ${MAX_CONTEXT_WINDOW_TOKENS}`)
+// Image-input capability (#654). Shape validity is owned by the SHARED contract
+// (`parseImageInputCapability`), not by a second zod transcription: strict keys,
+// the state enum, ISO-8601 UTC dates, and the rule that a supported/unsupported
+// claim must carry evidence (plus `validUntil` when discovery-sourced) are all
+// enforced there, so admin writes and runtime reads cannot drift apart.
+//
+// `.refine` narrows the unknown input to the parsed shape; a valid input is
+// already key-complete and type-checked, so no transform is needed. The field is
+// `.nullable()` on the UPDATE schema (null = explicit clear) and `.optional()`
+// on both (absent = leave as-is / no evidence).
+const IMAGE_INPUT_HINT =
+ 'image_input must be { state: "supported" | "unsupported" | "unknown", evidence?: ' +
+ '{ source: "curated" | "discovery", reference: <public https URL or evidence:<id>>, ' +
+ 'checkedAt: <ISO-8601 UTC timestamp>, validUntil?: <later ISO-8601 UTC timestamp> } }. ' +
+ 'A supported/unsupported state requires evidence, and a discovery-sourced ' +
+ 'supported/unsupported state requires validUntil.'
+
+const imageInputField = z
+ .unknown()
+ .refine((value): value is ImageInputCapability => parseImageInputCapability(value) !== null, {
+ message: IMAGE_INPUT_HINT,
+ })
+
// `provider` becomes a Kubernetes ConfigMap `data` key in the materializer, so
// it MUST be a valid K8s key AND must never be an Object.prototype key
// (`__proto__`/`constructor`/`prototype`) that could poison the grouping map or
@@ -102,6 +143,7 @@ export const createLlmAllowedModelSchema = z.object({
vendor: z.string().trim().min(1).max(200).optional(),
display_name: z.string().trim().min(1).max(400).optional(),
context_window_tokens: contextWindowField.optional(),
+ image_input: imageInputField.optional(),
enabled: z.boolean().default(true),
})
@@ -115,6 +157,7 @@ export const updateLlmAllowedModelSchema = z
vendor: z.string().trim().min(1).max(200).nullable(),
display_name: z.string().trim().min(1).max(400).nullable(),
context_window_tokens: contextWindowField.nullable(),
+ image_input: imageInputField.nullable(),
enabled: z.boolean(),
})
.partial()
@@ -126,6 +169,20 @@ export type UpdateLlmAllowedModelInput = z.infer<typeof updateLlmAllowedModelSch
export type LlmAllowedModelAuditAction = 'create' | 'update' | 'disable' | 'delete'
+/**
+ * Canonical storage form for the capability column. `unknown` WITHOUT evidence
+ * is "no evidence", which the column already represents as NULL: the admin API
+ * always reads a row back normalized (a legacy row reads as `{ state: 'unknown' }`),
+ * so an unchanged round-trip must not turn into a stored value and change the
+ * materialized ConfigMap. Anything validated by `imageInputField` is stored
+ * verbatim as canonical JSON text for the `jsonb` column.
+ */
+function imageInputToColumn(value: ImageInputCapability | null | undefined): string | null {
+ if (value === null || value === undefined) return null
+ if (value.state === 'unknown' && value.evidence === undefined) return null
+ return JSON.stringify(value)
+}
+
function toIso(raw: unknown): string {
if (raw instanceof Date) return raw.toISOString()
if (typeof raw === 'string') {
@@ -171,6 +228,8 @@ function rowToModel(row: Record<string, unknown>): LlmAllowedModel {
discovered_at: toNullableIso(row.discovered_at),
last_seen_at: toNullableIso(row.last_seen_at),
stale: Boolean(row.stale),
+ // NULL / malformed / legacy → `{ state: 'unknown' }` (never affirmative).
+ image_input: normalizeImageInputCapability(row.image_input),
created_at: toIso(row.created_at),
updated_at: toIso(row.updated_at),
}
@@ -179,7 +238,7 @@ function rowToModel(row: Record<string, unknown>): LlmAllowedModel {
const MODEL_COLUMNS = `
id, provider, model, vendor, display_name,
context_window_tokens, enabled, source, discovered_at, last_seen_at, stale,
- created_at, updated_at
+ image_input, created_at, updated_at
`
async function writeAudit(
@@ -263,8 +322,8 @@ export async function createAllowedModel(
try {
const result = await db.query(
`INSERT INTO llm_allowed_models
- (provider, model, vendor, display_name, context_window_tokens, enabled)
- VALUES ($1, $2, $3, $4, $5, $6)
+ (provider, model, vendor, display_name, context_window_tokens, image_input, enabled)
+ VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7)
RETURNING ${MODEL_COLUMNS}`,
[
input.provider,
@@ -272,6 +331,7 @@ export async function createAllowedModel(
input.vendor ?? null,
input.display_name ?? null,
input.context_window_tokens ?? null,
+ imageInputToColumn(input.image_input),
input.enabled,
]
)
@@ -310,8 +370,16 @@ export async function updateAllowedModel(
vendor: 'vendor',
display_name: 'display_name',
context_window_tokens: 'context_window_tokens',
+ image_input: 'image_input',
enabled: 'enabled',
}
+ // Evidence belongs to the (provider, model) pair it was checked against, so a
+ // RENAME invalidates it — unless the same request carries fresh evidence for
+ // the new pair. Without this, a curated `supported` for model A would silently
+ // authorize images for model B after an operator renamed the row.
+ const renamed =
+ (input.provider !== undefined && input.provider !== existing.provider) ||
+ (input.model !== undefined && input.model !== existing.model)
const sets: string[] = []
const params: unknown[] = []
let idx = 1
@@ -321,9 +389,13 @@ export async function updateAllowedModel(
][]) {
const value = input[field]
if (value === undefined) continue
- sets.push(`${column} = $${idx++}`)
- params.push(value)
+ // `image_input` is `jsonb`; cast explicitly like the repo's other jsonb
+ // writes (`llmCatalogSync`, `pluginWorkloadSdkDb`) rather than relying on
+ // parameter-type inference.
+ sets.push(field === 'image_input' ? `${column} = $${idx++}::jsonb` : `${column} = $${idx++}`)
+ params.push(field === 'image_input' ? imageInputToColumn(input.image_input) : value)
}
+ if (renamed && input.image_input === undefined) sets.push('image_input = NULL')
if (sets.length === 0) return existing
sets.push(`updated_at = NOW()`)
@@ -469,7 +541,7 @@ export async function listEnabledGroupedByProvider(
db: DbClient = pool
): Promise<Record<string, AllowedModelEntry[]>> {
const result = await db.query(
- `SELECT provider, model, vendor, display_name, context_window_tokens
+ `SELECT provider, model, vendor, display_name, context_window_tokens, image_input
FROM llm_allowed_models
WHERE enabled
AND NOT (provider = 'codex-subscription' AND stale)
@@ -490,6 +562,12 @@ export async function listEnabledGroupedByProvider(
if (contextWindow !== null) entry.contextWindowTokens = contextWindow
const vendor = toNullableString(raw.vendor)
if (vendor) entry.vendor = vendor
+ // Projected only when the row actually carries metadata: absence stays
+ // absence so an allowlist without capabilities materializes byte-identically
+ // to the pre-#654 ConfigMap (consumers normalize absence to `unknown`).
+ if (raw.image_input !== null && raw.image_input !== undefined) {
+ entry.imageInput = normalizeImageInputCapability(raw.image_input)
+ }
;(grouped[provider] ??= []).push(entry)
}
return grouped
diff --git a/control-api/src/services/llmAllowedModelsConfigMap.ts b/control-api/src/services/llmAllowedModelsConfigMap.ts
index 514a95f03..d818842ae 100644
--- a/control-api/src/services/llmAllowedModelsConfigMap.ts
+++ b/control-api/src/services/llmAllowedModelsConfigMap.ts
@@ -8,7 +8,10 @@
* Contract (fixed, shared with mcp-host/WRC/control-ui):
* - name `clerum-llm-allowed-models`, namespace `mcp-host`
* - `data`: one key per provider whose value is a JSON array of
- * `{ model, displayName?, contextWindowTokens?, vendor? }` (enabled rows only)
+ * `{ model, displayName?, contextWindowTokens?, vendor?, imageInput? }`
+ * (enabled rows only). `imageInput` is omitted when the row carries no
+ * capability metadata, so an allowlist that predates #654 materializes
+ * byte-identically; a published capability changes the hash on purpose.
* - annotation `clerum.io/content-hash` = sha256 over the serialized `data`
*
* Anti-drift (spec §3-R3.4 / V7): the K8s write happens OUTSIDE the Postgres
diff --git a/control-api/src/services/llmCatalogSync.ts b/control-api/src/services/llmCatalogSync.ts
index 9d1f37617..92d17e212 100644
--- a/control-api/src/services/llmCatalogSync.ts
+++ b/control-api/src/services/llmCatalogSync.ts
@@ -5,8 +5,8 @@
*
* SOURCE-GUARDED reconciliation is the load-bearing invariant (§11.2). The
* `idx_llm_allowed_models_pm` UNIQUE (provider, model) is NON-partial, so a
- * blind `ON CONFLICT DO UPDATE` would clobber a `source='manual'` row (an Azure
- * deployment name, a hand-added id). Instead we SELECT the provider's rows and
+ * blind `ON CONFLICT DO UPDATE` would clobber a `source='manual'` row (a seeded
+ * allowlist pair, a hand-added id). Instead we SELECT the provider's rows and
* branch on `source` BEFORE writing:
*
* - NEW (provider, model) not in DB → INSERT source='discovery', enabled=false,
@@ -16,38 +16,106 @@
* - PRESENT with source='discovery' → UPDATE last_seen_at=now, stale=false and
* NULL-FILL ctx/display only (COALESCE keeps any operator-edited non-null).
* `enabled` is NEVER touched.
- * - PRESENT with source='manual' → INVISIBLE: skipped entirely, never touched.
+ * - PRESENT with source='manual' → INVISIBLE for everything an operator
+ * authored: `enabled`, `source`, `stale`, `last_seen_at`, `discovered_at`,
+ * ctx and display are never written. ONLY `image_input` is filled, under
+ * the same guard as a discovery row (NULL or not-newer discovery evidence),
+ * because the 44 seeded pairs are all `source='manual'` and are exactly the
+ * rows a fresh installation serves (#654).
* - discovery rows absent from this run → UPDATE stale=true. NEVER deleted,
* NEVER auto-disabled (R3.7): an enabled model that vanished stays enabled +
* served, only flagged stale for an operator decision.
*
- * The sync deliberately does NOT re-materialize the `clerum-llm-allowed-models`
- * ConfigMap, and never has to: the materializer only reads `enabled` rows and
- * only serializes provider/model/vendor/context_window_tokens/display_name, and
- * this sync never mutates any of those columns for an enabled row — new inserts
- * are `enabled=false`, the stale flag is not serialized, and the discovery
- * NULL-fill CASE-guards the serialized columns to disabled rows only. So an
- * enabled row's serialized projection is invariant across syncs → CM stays
- * byte-stable. A discovered model only reaches runtime once an operator enables
- * it via the normal PUT path (which re-materializes).
+ * The sync re-materializes the `clerum-llm-allowed-models` ConfigMap in exactly
+ * one case: it changed `image_input` on an ENABLED row (#654). That column is
+ * served, so leaving the ConfigMap behind would keep mcp-host refusing images
+ * for a model the catalog now says supports them. Every other serialized column
+ * of an enabled row is still invariant across syncs — new inserts are
+ * `enabled=false`, the stale flag is not serialized, and the NULL-fill CASE
+ * guards ctx/display to disabled rows — so a run that changes no enabled row's
+ * evidence writes nothing to the ConfigMap. `enabled` itself is never touched:
+ * a discovered model only reaches runtime once an operator enables it via the
+ * normal PUT path.
+ *
+ * Known race: an admin write to `image_input` that commits while the sync's
+ * UPDATE runs can make that row report no change, because `prev` reads the
+ * statement snapshot while the locked target row is re-checked at its newest
+ * version. The ConfigMap then catches up on the next change or boot reconcile
+ * (#687).
*
* Each run appends a summary row to `llm_catalog_sync_runs` (the UI's "last
* synced"). No per-model audit rows — that would flood `llm_allowed_models_audit`
* (which records operator actions) with 1000+ rows per run.
*/
-import { type LlmProviderId, PROVIDER_IDS } from '@clerum/llm-providers'
+import {
+ type ImageInputCapability,
+ type LlmProviderId,
+ PROVIDER_IDS,
+ parseImageInputCapability,
+} from '@clerum/llm-providers'
import { config } from '../config.js'
import { pool } from '../db.js'
import { rootLogger } from '../observability/logger.js'
+import { llmAllowlistConfigMapWriteFailuresTotal } from '../observability/metrics.js'
import { MAX_CONTEXT_WINDOW_TOKENS } from './llmAllowedModels.js'
+import type { AllowedModelsConfigMapMaterializer } from './llmAllowedModelsConfigMap.js'
import {
type DiscoveredModel,
type FetchLike,
+ type ImageInputState,
type ModelsDevCatalogResult,
loadModelsDevCatalog,
mapCatalogToProviders,
} from './modelsDevClient.js'
+/**
+ * Public reference recorded on discovery provenance. FIXED — deliberately not
+ * `MODELS_DEV_API_URL`, whose non-prod env override may point at a private stub
+ * and must never be persisted as evidence.
+ */
+export const MODELS_DEV_EVIDENCE_REFERENCE = 'https://models.dev/api.json'
+
+/**
+ * Discovery evidence for one catalog entry (#654).
+ *
+ * `unknown` carries provenance only — this run observed the source, and the
+ * entry said nothing usable about its input modalities. A KNOWN state carries
+ * `validUntil`, because the shared contract refuses a discovery-sourced claim
+ * without an expiry.
+ *
+ * `capturedAt` is the SOURCE capture time (live fetch time, or the vendored
+ * snapshot's baked date) — never "now", so loading an old snapshot cannot make
+ * stale data look freshly verified, and `validUntil` is derived from it for the
+ * same reason: a vendored run can only claim support for as long as its
+ * snapshot is fresh.
+ *
+ * Throws when the shared contract rejects what we built. Both inputs are ours
+ * (an ISO stamp this process produced and a TTL validated at boot), so a
+ * rejection is a programming error; storing NULL would hide it.
+ */
+export function discoveryImageInput(
+ state: ImageInputState,
+ capturedAt: string,
+ ttlMs: number
+): ImageInputCapability {
+ const base = {
+ source: 'discovery' as const,
+ reference: MODELS_DEV_EVIDENCE_REFERENCE,
+ checkedAt: capturedAt,
+ }
+ const evidence =
+ state === 'unknown'
+ ? base
+ : { ...base, validUntil: new Date(Date.parse(capturedAt) + ttlMs).toISOString() }
+ const parsed = parseImageInputCapability({ state, evidence })
+ if (!parsed) {
+ throw new Error(
+ `discoveryImageInput: shared contract rejected discovery evidence (state=${state}, capturedAt=${capturedAt}, ttlMs=${ttlMs})`
+ )
+ }
+ return parsed
+}
+
type SyncTxClient = {
query: (text: string, values?: unknown[]) => Promise<{ rows: unknown[]; rowCount: number | null }>
release: () => void
@@ -70,6 +138,10 @@ export interface CatalogSyncResult {
added: number
updated: number
staled: number
+ /** Enabled rows whose `image_input` this run actually changed (#654). */
+ enabledImageInputChanged: number
+ /** True when that count forced a ConfigMap re-materialization. */
+ materialized: boolean
}
/** The last persisted sync run, for the status endpoint. */
@@ -120,13 +192,35 @@ function usableContext(ctx: number | undefined): number | null {
* transient network blip (it would nudge the operator to disable a live model).
* New inserts + last_seen refresh from a vendored run are harmless and still run.
*/
+/**
+ * Read one UPDATE's RETURNING row. An ENABLED row whose `image_input` actually
+ * changed is the only thing this sync can do that makes the served ConfigMap
+ * wrong — hence the exact `IS DISTINCT FROM` flag rather than `rowCount`, so an
+ * idempotent re-run publishes nothing.
+ */
+function countEnabledEvidenceChange(
+ rows: unknown[],
+ counters: { enabledImageInputChanged: number }
+): void {
+ const row = rows[0] as { enabled?: unknown; image_input_changed?: unknown } | undefined
+ if (row?.enabled === true && row.image_input_changed === true) {
+ counters.enabledImageInputChanged += 1
+ }
+}
+
async function reconcileProvider(
client: SyncTxClient,
provider: LlmProviderId,
discovered: DiscoveredModel[],
markStale: boolean,
providerMinLive: number,
- counters: { added: number; updated: number; staled: number }
+ imageEvidence: { capturedAt: string; ttlMs: number },
+ counters: {
+ added: number
+ updated: number
+ staled: number
+ enabledImageInputChanged: number
+ }
): Promise<void> {
const existingRes = await client.query(
`SELECT id, model, source FROM llm_allowed_models WHERE provider = $1`,
@@ -150,6 +244,10 @@ async function reconcileProvider(
const existing = existingByModel.get(model.model_id)
const ctx = usableContext(model.context_window_tokens)
const display = model.display_name ?? null
+ // Per ROW, not per run: the payload now carries this model's own state.
+ const imageInputJson = JSON.stringify(
+ discoveryImageInput(model.image_input_state, imageEvidence.capturedAt, imageEvidence.ttlMs)
+ )
if (!existing) {
// NEW → insert a disabled discovery row. ON CONFLICT DO NOTHING guards only
@@ -157,17 +255,43 @@ async function reconcileProvider(
const ins = await client.query(
`INSERT INTO llm_allowed_models
(provider, model, enabled, source, discovered_at, last_seen_at, stale,
- context_window_tokens, display_name)
- VALUES ($1, $2, false, 'discovery', NOW(), NOW(), false, $3, $4)
+ context_window_tokens, display_name, image_input)
+ VALUES ($1, $2, false, 'discovery', NOW(), NOW(), false, $3, $4, $5::jsonb)
ON CONFLICT (provider, model) DO NOTHING`,
- [provider, model.model_id, ctx, display]
+ [provider, model.model_id, ctx, display, imageInputJson]
)
counters.added += ins.rowCount ?? 0
continue
}
if (existing.source === 'manual') {
- // INVISIBLE — never touch an operator/seed row (§2.2 / §11.2).
+ // A manual row stays invisible for everything an operator authored:
+ // `enabled`, `source`, `stale`, `last_seen_at`, `discovered_at`,
+ // `context_window_tokens`, `display_name` are all absent from the
+ // statement below. The §11.2 invariant exists to protect those.
+ //
+ // `image_input` is not among them (#654). 44 pairs are seeded as
+ // `source='manual'`, 29 of which models.dev lists; skipping them entirely
+ // would leave exactly the rows a fresh installation SERVES with no
+ // evidence at all, while rows an operator discovered later got some. The
+ // guard is the same as the discovery branch — NULL, or discovery-sourced
+ // evidence not newer than this capture — so an operator's `curated`
+ // verdict is still untouchable here.
+ const man = await client.query(
+ `UPDATE llm_allowed_models AS t
+ SET image_input = CASE
+ WHEN t.image_input IS NULL THEN $2::jsonb
+ WHEN t.image_input->'evidence'->>'source' = 'discovery'
+ AND (t.image_input->'evidence'->>'checkedAt')::timestamptz <= $3::timestamptz
+ THEN $2::jsonb
+ ELSE t.image_input
+ END
+ FROM llm_allowed_models AS prev
+ WHERE t.id = $1 AND prev.id = t.id AND t.source = 'manual'
+ RETURNING t.enabled, (t.image_input IS DISTINCT FROM prev.image_input) AS image_input_changed`,
+ [existing.id, imageInputJson, imageEvidence.capturedAt]
+ )
+ countEnabledEvidenceChange(man.rows, counters)
continue
}
@@ -180,22 +304,47 @@ async function reconcileProvider(
// re-materialize (its guarantee). COALESCE keeps any operator-edited
// non-null; `enabled` is never assigned. The freshest metadata for an
// enabled row lands on the operator's next edit (which re-materializes).
+ //
+ // `image_input` deliberately does NOT follow the enabled-row freeze (#654).
+ // It is not operator-authored (operator-authored evidence is `curated`, and
+ // that is never overwritten here); and because the evidence now expires, a
+ // frozen enabled row would be stamped once while disabled, never refreshed,
+ // and would expire exactly one TTL later with no way back short of manual
+ // curation — the feature would fail on its own schedule.
+ //
+ // Instead the write is guarded by MONOTONICITY: discovery evidence is only
+ // replaced by a capture at least as recent as the one already recorded,
+ // compared as `timestamptz` (the parser accepts both `…Z` and `….000Z`
+ // spellings, so a lexical comparison would be wrong). A vendored run can
+ // therefore never regress evidence a later live run stamped. `<=` rather
+ // than `<` so a re-run against the same capture rewrites; the RETURNING
+ // flag keeps the materialization count exact.
const upd = await client.query(
- `UPDATE llm_allowed_models
+ `UPDATE llm_allowed_models AS t
SET last_seen_at = NOW(),
stale = false,
context_window_tokens = CASE
- WHEN enabled THEN context_window_tokens
- ELSE COALESCE(context_window_tokens, $2)
+ WHEN t.enabled THEN t.context_window_tokens
+ ELSE COALESCE(t.context_window_tokens, $2)
END,
display_name = CASE
- WHEN enabled THEN display_name
- ELSE COALESCE(display_name, $3)
+ WHEN t.enabled THEN t.display_name
+ ELSE COALESCE(t.display_name, $3)
+ END,
+ image_input = CASE
+ WHEN t.image_input IS NULL THEN $4::jsonb
+ WHEN t.image_input->'evidence'->>'source' = 'discovery'
+ AND (t.image_input->'evidence'->>'checkedAt')::timestamptz <= $5::timestamptz
+ THEN $4::jsonb
+ ELSE t.image_input
END
- WHERE id = $1 AND source = 'discovery'`,
- [existing.id, ctx, display]
+ FROM llm_allowed_models AS prev
+ WHERE t.id = $1 AND prev.id = t.id AND t.source = 'discovery'
+ RETURNING t.enabled, (t.image_input IS DISTINCT FROM prev.image_input) AS image_input_changed`,
+ [existing.id, ctx, display, imageInputJson, imageEvidence.capturedAt]
)
counters.updated += upd.rowCount ?? 0
+ countEnabledEvidenceChange(upd.rows, counters)
}
// VANISHED discovery rows → flag stale (never delete, never disable). Only
@@ -243,9 +392,9 @@ async function reconcileProvider(
/**
* Run one catalog sync: load the models.dev catalog (live, else vendored), map
* it to our providers, and source-guarded-reconcile into `llm_allowed_models`
- * inside a single transaction, then persist a run summary. Never re-materializes
- * the ConfigMap — it never mutates a serialized column of an enabled row, so the
- * CM stays byte-stable (see the module header).
+ * inside a single transaction, then persist a run summary. Re-materializes the
+ * ConfigMap after COMMIT only when it changed `image_input` on an enabled row
+ * (see the module header).
*/
export async function syncDiscoveredModels(
opts: {
@@ -255,14 +404,26 @@ export async function syncDiscoveredModels(
minPlausibleLiveTotal?: number
/** §4.5 layer-2 per-provider floor (default from config). */
providerMinLive?: number
- } = {},
+ /**
+ * REQUIRED, with no no-op default: this sync can change what runtime is
+ * served, and a run that changes served capability with no way to publish it
+ * would be a silent failure. Every production caller has a gateway.
+ */
+ materializer: AllowedModelsConfigMapMaterializer
+ /** Image-evidence validity window (default from config). */
+ imageEvidenceTtlMs?: number
+ },
connector: SyncConnector = pool
): Promise<CatalogSyncResult> {
const load = opts.loadCatalog ?? loadModelsDevCatalog
const minPlausibleLiveTotal = opts.minPlausibleLiveTotal ?? config.modelsDevMinPlausibleLiveTotal
const providerMinLive = opts.providerMinLive ?? config.llmCatalogSyncProviderMinLive
- const { source, fetchedAt, catalog } = await load({ fetchImpl: opts.fetchImpl })
+ const imageEvidenceTtlMs = opts.imageEvidenceTtlMs ?? config.llmCatalogImageEvidenceTtlMs
+ const { source, fetchedAt, capturedAt, catalog } = await load({ fetchImpl: opts.fetchImpl })
const byProvider = mapCatalogToProviders(catalog)
+ // Stamped with the SOURCE capture time (see discoveryImageInput); the payload
+ // itself is built per row, because each model carries its own state now.
+ const imageEvidence = { capturedAt, ttlMs: imageEvidenceTtlMs }
// §4.5 sanity guard, LAYER 3 — absolute global plausibility floor. Compared
// BEFORE touching any row, against a config constant, with NO baseline / no
@@ -301,7 +462,7 @@ export async function syncDiscoveredModels(
// is applied inside reconcileProvider. A vendored fallback must not stale
// live models (see reconcileProvider).
const markStale = sourceIsLive && !globallyImplausible
- const counters = { added: 0, updated: 0, staled: 0 }
+ const counters = { added: 0, updated: 0, staled: 0, enabledImageInputChanged: 0 }
for (const provider of PROVIDER_IDS) {
await reconcileProvider(
client,
@@ -309,6 +470,7 @@ export async function syncDiscoveredModels(
byProvider[provider] ?? [],
markStale,
providerMinLive,
+ imageEvidence,
counters
)
}
@@ -327,6 +489,31 @@ export async function syncDiscoveredModels(
const rawRanAt = (runRes.rows[0] as { ran_at?: unknown } | undefined)?.ran_at
const ranAt = rawRanAt instanceof Date ? rawRanAt.toISOString() : String(rawRanAt)
+
+ // After COMMIT, never inside it: the rows are durable either way, and a
+ // ConfigMap write held inside the transaction would keep the advisory lock
+ // for the length of an API call to the cluster. On failure the run is
+ // reported as failed (the caller surfaces it) and the boot reconcile
+ // converges on restart — the write is never retried silently.
+ let materialized = false
+ if (counters.enabledImageInputChanged > 0) {
+ try {
+ await opts.materializer.materialize()
+ materialized = true
+ } catch (err) {
+ llmAllowlistConfigMapWriteFailuresTotal.inc({ phase: 'sync' })
+ log.error(
+ {
+ event: 'llm_catalog_sync_configmap_write_failed',
+ enabledImageInputChanged: counters.enabledImageInputChanged,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ 'llm allowed-models ConfigMap write failed after catalog sync commit'
+ )
+ throw err
+ }
+ }
+
// `fetchedAt` is the catalog acquisition time (from the loader) — how fresh
// the source data is; `ranAt` is the DB commit time of this run.
return {
@@ -336,6 +523,8 @@ export async function syncDiscoveredModels(
added: counters.added,
updated: counters.updated,
staled: counters.staled,
+ enabledImageInputChanged: counters.enabledImageInputChanged,
+ materialized,
}
} catch (err) {
if (inTransaction) {
diff --git a/control-api/src/services/llmCatalogSyncCron.ts b/control-api/src/services/llmCatalogSyncCron.ts
index b0e6c1c67..d4f2ac29a 100644
--- a/control-api/src/services/llmCatalogSyncCron.ts
+++ b/control-api/src/services/llmCatalogSyncCron.ts
@@ -21,13 +21,14 @@
* concurrent on-demand sync against this cron; the session lock here is an
* ADDITIONAL guard that avoids queuing redundant cron ticks behind it.
*
- * Modeled on budgetReservationSweepCron.ts / workflowScheduleWorkerCron.ts:
- * setInterval + unref, errors logged but NEVER thrown.
+ * Scheduling follows workflowScheduleWorkerCron.ts: the first tick runs shortly
+ * after start (random jitter up to LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS), then
+ * every `intervalMs`. Both timers are unref()'d, start is not awaited by boot,
+ * and errors are logged but NEVER thrown.
*/
import { pool } from '../db.js'
import { rootLogger } from '../observability/logger.js'
import type { CatalogSyncResult } from './llmCatalogSync.js'
-import { syncDiscoveredModels } from './llmCatalogSync.js'
const log = rootLogger.child({ service: 'llm_catalog_sync_cron' })
@@ -47,10 +48,15 @@ type LockClient = {
release: (destroy?: Error | boolean) => void
}
-/** Injectable dependencies (test seam). Both default to production wiring. */
+/**
+ * Injectable dependencies. `connector` defaults to production wiring; `sync` is
+ * REQUIRED because the sync now needs a ConfigMap materializer (#654) and the
+ * cron has no gateway of its own — `main.ts` owns that wiring and passes a
+ * closure. A default here could only be a call the sync would reject.
+ */
export interface LlmCatalogSyncCronDeps {
connector?: { connect: () => Promise<LockClient> }
- sync?: () => Promise<CatalogSyncResult>
+ sync: () => Promise<CatalogSyncResult>
}
/** Outcome of one tick — returned for tests/observability, never thrown. */
@@ -66,10 +72,10 @@ export interface LlmCatalogSyncTickResult {
* released in `finally` whether the tick ran, skipped, or failed.
*/
export async function runLlmCatalogSyncTick(
- deps: LlmCatalogSyncCronDeps = {}
+ deps: LlmCatalogSyncCronDeps
): Promise<LlmCatalogSyncTickResult> {
const connector = deps.connector ?? pool
- const sync = deps.sync ?? syncDiscoveredModels
+ const sync = deps.sync
let lockClient: LockClient | undefined
let locked = false
try {
@@ -141,10 +147,19 @@ export async function runLlmCatalogSyncTick(
}
let intervalHandle: ReturnType<typeof setInterval> | null = null
+let firstRunHandle: ReturnType<typeof setTimeout> | null = null
+
+/**
+ * Upper bound of the random delay before the first tick after start. Keeps the
+ * replicas of one rollout from all contending for the advisory lock at the same
+ * instant; the lock already makes a collision a harmless no-op.
+ */
+export const LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS = 5_000
export function startLlmCatalogSyncCron(deps: LlmCatalogSyncCronDeps, intervalMs: number): void {
- if (intervalHandle) return
- intervalHandle = setInterval(() => {
+ if (intervalHandle || firstRunHandle) return
+
+ const run = (): void => {
// runLlmCatalogSyncTick never rejects, but keep a defensive catch so an
// unexpected throw can never crash the timer.
void runLlmCatalogSyncTick(deps).catch(err => {
@@ -156,12 +171,31 @@ export function startLlmCatalogSyncCron(deps: LlmCatalogSyncCronDeps, intervalMs
'unhandled error in llm catalog sync cron'
)
})
- }, intervalMs)
- intervalHandle.unref()
- log.info({ event: 'llm_catalog_sync_cron_started', intervalMs }, 'llm catalog sync cron started')
+ }
+
+ // First tick shortly after start instead of one full interval later: rows
+ // with no image-input evidence refuse images until a sync runs, and every
+ // restart would otherwise push that first sync out by another interval.
+ // Not awaited — boot never waits on models.dev.
+ const firstDelay = Math.floor(Math.random() * LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS)
+ firstRunHandle = setTimeout(() => {
+ firstRunHandle = null
+ run()
+ intervalHandle = setInterval(run, intervalMs)
+ intervalHandle.unref()
+ }, firstDelay)
+ firstRunHandle.unref()
+ log.info(
+ { event: 'llm_catalog_sync_cron_started', intervalMs, firstRunInMs: firstDelay },
+ 'llm catalog sync cron started'
+ )
}
export function stopLlmCatalogSyncCron(): void {
+ if (firstRunHandle) {
+ clearTimeout(firstRunHandle)
+ firstRunHandle = null
+ }
if (intervalHandle) {
clearInterval(intervalHandle)
intervalHandle = null
diff --git a/control-api/src/services/modelsDevClient.ts b/control-api/src/services/modelsDevClient.ts
index f8c14ebeb..b0e7c364a 100644
--- a/control-api/src/services/modelsDevClient.ts
+++ b/control-api/src/services/modelsDevClient.ts
@@ -16,7 +16,10 @@
*/
import { isIP } from 'node:net'
import { type LlmProviderId, PROVIDER_IDS } from '@clerum/llm-providers'
-import { VENDORED_MODELS_DEV_SNAPSHOT } from '../data/modelsDevSnapshot.js'
+import {
+ VENDORED_MODELS_DEV_SNAPSHOT,
+ VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT,
+} from '../data/modelsDevSnapshot.js'
/**
* The catalog URL. Defaults to the fixed, trusted public endpoint. It is NOT
@@ -37,12 +40,24 @@ const MAX_RESPONSE_BYTES = 15 * 1024 * 1024 // ~15MB — api.json is ~3MB today.
/**
* One model entry as it appears in the (normalized) catalog. This is a subset
* of the models.dev per-model object — only the fields discovery consumes. The
- * live api.json carries many more fields; they are ignored, not parsed.
+ * live api.json carries many more fields; only `id`, `name`, `limit.context`
+ * and `modalities.input` are parsed.
*/
export interface RawModelsDevModel {
id?: string
name?: string
limit?: { context?: number }
+ /**
+ * models.dev per-model input modalities (e.g. `["text","image"]`). Only
+ * `input` is read; `attachment` ("accepts file attachments") is a DIFFERENT
+ * capability — today's catalog has 47 models where the two disagree,
+ * including audio-only models with `attachment: true` and vision models with
+ * `attachment: false` — so it is deliberately not consulted.
+ *
+ * Typed `unknown` on purpose: this is untrusted data at an API boundary and
+ * `imageInputStateFromModalities` is the only place allowed to narrow it.
+ */
+ modalities?: { input?: unknown }
}
/** One provider entry in the (normalized) catalog: a map of model id → entry. */
@@ -124,12 +139,42 @@ export interface DiscoveredModel {
context_window_tokens?: number
vendor?: string
display_name?: string
+ /** Tri-state derived from `modalities.input`; see `imageInputStateFromModalities`. */
+ image_input_state: ImageInputState
+}
+
+/** Image-input state derived from a models.dev entry — fail-closed. */
+export type ImageInputState = 'supported' | 'unsupported' | 'unknown'
+
+/**
+ * Tri-state read of one catalog entry's input modalities.
+ *
+ * `unknown` is the answer for everything the catalog does not state plainly:
+ * no `modalities`, no `input`, an `input` that is not an array of strings, or
+ * an empty one. The only path to `supported` is an array of strings containing
+ * the exact token `image` — no case folding, because the catalog is lowercase
+ * and folding would be a guess the data never asked for.
+ */
+export function imageInputStateFromModalities(model: RawModelsDevModel): ImageInputState {
+ const input = model.modalities?.input
+ if (!Array.isArray(input) || input.length === 0) return 'unknown'
+ if (!input.every(value => typeof value === 'string')) return 'unknown'
+ return input.includes('image') ? 'supported' : 'unsupported'
}
/** Result of loading the catalog: which source served it, when, and the data. */
export interface ModelsDevCatalogResult {
source: 'live' | 'vendored'
+ /** When THIS RUN acquired the catalog (live fetch time, or fallback time). */
fetchedAt: string
+ /**
+ * When the returned DATA was captured: the live fetch time, or the vendored
+ * snapshot's baked capture date. Distinct from `fetchedAt` on purpose — a
+ * vendored fallback is loaded today but its rows are as old as the file, so
+ * capability evidence derived from it must carry the capture date. Never
+ * rejuvenate a stale snapshot by stamping it with the load time.
+ */
+ capturedAt: string
catalog: RawModelsDevCatalog
}
@@ -346,7 +391,9 @@ export async function loadModelsDevCatalog(
const text = await readCappedText(res, MAX_RESPONSE_BYTES)
const parsed: unknown = JSON.parse(text)
if (!isRawCatalog(parsed)) throw new Error('models.dev response failed shape validation')
- return { source: 'live', fetchedAt: now().toISOString(), catalog: parsed }
+ const fetchedAt = now().toISOString()
+ // Live data IS the observation: capture time == acquisition time.
+ return { source: 'live', fetchedAt, capturedAt: fetchedAt, catalog: parsed }
} catch (err) {
// Do NOT log the body. A short reason is enough for operators.
console.warn(
@@ -356,6 +403,7 @@ export async function loadModelsDevCatalog(
return {
source: 'vendored',
fetchedAt: now().toISOString(),
+ capturedAt: VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT,
catalog: VENDORED_MODELS_DEV_SNAPSHOT,
}
} finally {
@@ -422,7 +470,10 @@ export function mapCatalogToProviders(
if (!modelId || seen.has(modelId)) continue
if (modelId.length > MAX_MODEL_ID_LEN || CONTROL_CHARS.test(modelId)) continue
seen.add(modelId)
- const discovered: DiscoveredModel = { model_id: modelId }
+ const discovered: DiscoveredModel = {
+ model_id: modelId,
+ image_input_state: imageInputStateFromModalities(m ?? {}),
+ }
const ctx = m?.limit?.context
if (typeof ctx === 'number' && Number.isInteger(ctx) && ctx > 0) {
discovered.context_window_tokens = ctx
diff --git a/control-api/test/config.llmCatalogImageEvidenceTtl.test.ts b/control-api/test/config.llmCatalogImageEvidenceTtl.test.ts
new file mode 100644
index 000000000..240a84ef7
--- /dev/null
+++ b/control-api/test/config.llmCatalogImageEvidenceTtl.test.ts
@@ -0,0 +1,70 @@
+/**
+ * Validity window for image-input evidence derived from models.dev (#654).
+ *
+ * The TTL is not cosmetic: it is counted from the catalog CAPTURE time, and once
+ * it lapses the shared contract resolves the row to `unknown` with reason
+ * `evidence_expired` and images are refused. A TTL shorter than two sync
+ * intervals therefore expires evidence the cron cannot possibly have renewed
+ * yet — the feature would fail on its own schedule, with no external cause.
+ * That cross-field rule only applies when the cron is the thing doing the
+ * refreshing, so it is asserted here in both directions.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const TTL = 'LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS'
+const INTERVAL = 'LLM_CATALOG_SYNC_INTERVAL_MS'
+const CRON = 'LLM_CATALOG_SYNC_CRON_ENABLED'
+const KEYS = [TTL, INTERVAL, CRON] as const
+
+async function loadConfigWith(env: Partial<Record<(typeof KEYS)[number], string>>) {
+ const original = Object.fromEntries(KEYS.map(k => [k, process.env[k]]))
+ for (const key of KEYS) delete process.env[key]
+ for (const [key, value] of Object.entries(env)) process.env[key] = value
+ vi.resetModules()
+ try {
+ const mod = await import('../src/config.js')
+ return mod.config
+ } finally {
+ for (const key of KEYS) {
+ const value = original[key]
+ if (value === undefined) delete process.env[key]
+ else process.env[key] = value
+ }
+ }
+}
+
+describe('control-api llm catalog image-evidence TTL config', () => {
+ afterEach(() => {
+ vi.resetModules()
+ })
+
+ it('defaults to 30 days when unset', async () => {
+ const config = await loadConfigWith({})
+ expect(config.llmCatalogImageEvidenceTtlMs).toBe(30 * 24 * 60 * 60 * 1000)
+ })
+
+ it('accepts an override at or above the floor', async () => {
+ const config = await loadConfigWith({ [TTL]: '120000' })
+ expect(config.llmCatalogImageEvidenceTtlMs).toBe(120_000)
+ })
+
+ it('rejects a TTL below the floor', async () => {
+ await expect(loadConfigWith({ [TTL]: '1000' })).rejects.toThrow(/must be an integer >= 120000/)
+ })
+
+ it('rejects a TTL shorter than twice the cron interval when the cron is enabled', async () => {
+ await expect(
+ loadConfigWith({ [CRON]: 'true', [INTERVAL]: '86400000', [TTL]: '100000000' })
+ ).rejects.toThrow(
+ 'LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS must be at least twice LLM_CATALOG_SYNC_INTERVAL_MS when LLM_CATALOG_SYNC_CRON_ENABLED=true'
+ )
+ })
+
+ it('accepts the same TTL when the cron is off (the guard is conditional)', async () => {
+ // Witness that the throw above came from the cross-field guard and not from
+ // the floor: identical TTL and interval, only the flag differs.
+ const config = await loadConfigWith({ [INTERVAL]: '86400000', [TTL]: '100000000' })
+ expect(config.llmCatalogImageEvidenceTtlMs).toBe(100_000_000)
+ expect(config.llmCatalogSyncCronEnabled).toBe(false)
+ })
+})
diff --git a/control-api/test/db.llmAllowedModelsMigration.test.ts b/control-api/test/db.llmAllowedModelsMigration.test.ts
index 2a7d9bb4e..3d6a5af72 100644
--- a/control-api/test/db.llmAllowedModelsMigration.test.ts
+++ b/control-api/test/db.llmAllowedModelsMigration.test.ts
@@ -155,4 +155,54 @@ describe('0056_llm_allowed_models migration', () => {
'GRANT SELECT, INSERT ON TABLE\n llm_allowed_models_audit,\n llm_catalog_sync_runs'
)
})
+
+ it('0115 adds the nullable image_input capability column idempotently (#654)', async () => {
+ const { initDb } = await import('../src/db.js')
+ await initDb()
+ const sqls = clientQuery.mock.calls.map(([sql]) => String(sql))
+
+ const alter = sqls.find(sql => /ADD COLUMN IF NOT EXISTS image_input JSONB/.test(sql))
+ expect(alter).toBeDefined()
+ // Nullable + no DEFAULT: every existing row reads as `unknown`, and the
+ // migration alone changes no runtime behavior.
+ expect(alter!).not.toMatch(/image_input JSONB\s+NOT NULL/)
+ expect(alter!).not.toMatch(/image_input JSONB\s+DEFAULT/)
+ // The state enum is the DB backstop; the nested evidence shape is validated
+ // by the service through the shared parser.
+ expect(alter!).toMatch(/jsonb_typeof\(image_input\) = 'object'/)
+ expect(alter!).toMatch(/image_input->>'state' IN \('supported','unsupported','unknown'\)/)
+ // The predicate must be TOTAL, because a CHECK accepts NULL: without these
+ // two guards a `{}` (or `{"state": null}`) payload evaluates to NULL and is
+ // ACCEPTED. The real database behaviour is covered by
+ // db.realPostgresMigration.integration.test.ts.
+ expect(alter!).toMatch(/image_input \? 'state'/)
+ expect(alter!).toMatch(
+ /COALESCE\(\s*image_input->>'state' IN \('supported','unsupported','unknown'\),\s*false\s*\)/
+ )
+ expect(alter!).toMatch(/EXCEPTION WHEN duplicate_object THEN NULL/)
+ // Additive only.
+ expect(alter!).not.toMatch(/DROP COLUMN/)
+ })
+
+ it('0115 is purely additive: it adds the column and writes no image_input data', async () => {
+ const { initDb } = await import('../src/db.js')
+ await initDb()
+ const calls = clientQuery.mock.calls.map(([sql, params]) => ({
+ sql: String(sql),
+ params: params as unknown[],
+ }))
+
+ // Liveness witness FIRST: the migration this test is about actually ran.
+ // Without it, deleting 0115 outright would satisfy both negatives below.
+ expect(calls.find(c => /ADD COLUMN IF NOT EXISTS image_input JSONB/.test(c.sql))).toBeDefined()
+
+ // Evidence is derived by the catalog sync from models.dev, never seeded by a
+ // migration: a seed can only write `curated` provenance, which the sync is
+ // required never to overwrite, so it would permanently freeze the very rows
+ // that need refreshing.
+ expect(calls.filter(c => /SET image_input/.test(c.sql))).toHaveLength(0)
+ expect(
+ calls.filter(c => /UPDATE llm_allowed_models/.test(c.sql) && /image_input/.test(c.sql))
+ ).toHaveLength(0)
+ })
})
diff --git a/control-api/test/db.oauthGrantsOwnerGeneralization.test.ts b/control-api/test/db.oauthGrantsOwnerGeneralization.test.ts
index 52ceedd6f..e4759a7f0 100644
--- a/control-api/test/db.oauthGrantsOwnerGeneralization.test.ts
+++ b/control-api/test/db.oauthGrantsOwnerGeneralization.test.ts
@@ -21,7 +21,7 @@ describe('0101 oauth_grants owner generalization migration', () => {
const { CONTROL_API_MIGRATIONS } = await import('../src/db.js')
const versions = CONTROL_API_MIGRATIONS.map(m => m.version)
expect(versions).toContain('0106_oauth_grants_owner_generalization')
- expect(versions.at(-1)).toBe('0114_llm_provider_attempts_connection_integrity')
+ expect(versions.at(-1)).toBe('0115_llm_allowed_models_image_input')
expect(versions.indexOf('0100_seed_minimax_allowed_model')).toBeLessThan(
versions.indexOf('0106_oauth_grants_owner_generalization')
)
diff --git a/control-api/test/db.realPostgresMigration.integration.test.ts b/control-api/test/db.realPostgresMigration.integration.test.ts
index 3c4074708..3ee3b2c85 100644
--- a/control-api/test/db.realPostgresMigration.integration.test.ts
+++ b/control-api/test/db.realPostgresMigration.integration.test.ts
@@ -2870,4 +2870,114 @@ describeRealPostgres('control-api real Postgres migrations', () => {
)
expect(rolledBack.rows[0]).toEqual({ usage_count: '0', trace_count: '0' })
})
+
+ it('#654 roundtrips capability through CRUD and the enabled ConfigMap projection', async () => {
+ const { initDb } = await import('../src/db.js')
+ const {
+ createAllowedModel,
+ getAllowedModel,
+ updateAllowedModel,
+ listEnabledGroupedByProvider,
+ } = await import('../src/services/llmAllowedModels.js')
+ await initDb({ connect: () => dbPool.connect() })
+ const db = await dbPool.connect()
+ await db.query('BEGIN')
+ const provider = `image-roundtrip-${randomBytes(4).toString('hex')}`
+ const capability = {
+ state: 'supported' as const,
+ evidence: {
+ source: 'curated' as const,
+ reference: 'evidence:image-input-roundtrip',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ }
+ try {
+ const created = await createAllowedModel(
+ {
+ provider,
+ model: 'visual',
+ enabled: true,
+ image_input: capability,
+ },
+ 'integration-test',
+ db
+ )
+ expect((await getAllowedModel(created.id, db))?.image_input).toEqual(capability)
+ expect((await listEnabledGroupedByProvider(db))[provider]).toEqual([
+ { model: 'visual', imageInput: capability },
+ ])
+ const renamed = await updateAllowedModel(
+ created.id,
+ { model: 'renamed' },
+ 'integration-test',
+ db
+ )
+ expect(renamed).toMatchObject({ enabled: true, image_input: { state: 'unknown' } })
+ expect((await listEnabledGroupedByProvider(db))[provider]).toEqual([{ model: 'renamed' }])
+ await updateAllowedModel(created.id, { image_input: capability }, 'integration-test', db)
+ const cleared = await updateAllowedModel(
+ created.id,
+ { image_input: null },
+ 'integration-test',
+ db
+ )
+ expect(cleared).toMatchObject({ enabled: true, image_input: { state: 'unknown' } })
+ expect((await listEnabledGroupedByProvider(db))[provider]).toEqual([{ model: 'renamed' }])
+ } finally {
+ await db.query('ROLLBACK')
+ db.release()
+ }
+ })
+
+ it('#654 rejects malformed image_input payloads in the database, not only in the service', async () => {
+ const { initDb } = await import('../src/db.js')
+ await initDb({ connect: () => dbPool.connect() })
+
+ const provider = `image-input-654-${randomBytes(4).toString('hex')}`
+ const model = 'migration-probe'
+ await dbPool.query(
+ `INSERT INTO llm_allowed_models (provider, model, enabled) VALUES ($1, $2, false)`,
+ [provider, model]
+ )
+ const setImageInput = (payload: string | null) =>
+ dbPool.query(
+ `UPDATE llm_allowed_models
+ SET image_input = $1::jsonb
+ WHERE provider = $2 AND model = $3`,
+ [payload, provider, model]
+ )
+
+ try {
+ // The CHECK must be TOTAL, because a CHECK accepts NULL. With only
+ // `jsonb_typeof(...) = 'object' AND image_input->>'state' IN (...)`, `{}`
+ // evaluates to TRUE AND NULL = NULL and the row is ACCEPTED; and
+ // `{"state": null}` satisfies `? 'state'` while `->>` is still NULL.
+ // Each of these is a malformed payload the service must never be able to
+ // persist through any writer, so the database is the backstop.
+ for (const malformed of [
+ '{}',
+ '{"state":null}',
+ '{"state":"bogus"}',
+ '{"state":5}',
+ '[]',
+ '"supported"',
+ 'null',
+ ]) {
+ await expect(setImageInput(malformed)).rejects.toMatchObject({ code: '23514' })
+ }
+
+ // The legacy NULL and every canonical state stay accepted.
+ await expect(setImageInput(null)).resolves.toBeDefined()
+ for (const state of ['supported', 'unsupported', 'unknown']) {
+ await expect(setImageInput(JSON.stringify({ state }))).resolves.toBeDefined()
+ }
+ const stored = await dbPool.query<{ image_input: unknown }>(
+ `SELECT image_input FROM llm_allowed_models WHERE provider = $1 AND model = $2`,
+ [provider, model]
+ )
+ expect(stored.rows[0].image_input).toEqual({ state: 'unknown' })
+ } finally {
+ await dbPool.query(`DELETE FROM llm_allowed_models WHERE provider = $1`, [provider])
+ }
+ })
})
diff --git a/control-api/test/helpers/llmCatalogSyncFakeDb.ts b/control-api/test/helpers/llmCatalogSyncFakeDb.ts
index 2f4db88cd..3cdf40ee5 100644
--- a/control-api/test/helpers/llmCatalogSyncFakeDb.ts
+++ b/control-api/test/helpers/llmCatalogSyncFakeDb.ts
@@ -11,7 +11,13 @@
* models the exact statement semantics the sync depends on. It intentionally
* implements ONLY those statements; anything else returns an empty result.
*/
-import { vi } from 'vitest'
+import { type Mock, vi } from 'vitest'
+import type { ImageInputCapability } from '@clerum/llm-providers'
+
+/** The statement spy's exact signature, so `connector` satisfies SyncConnector. */
+type FakeQuery = Mock<
+ (sql: string, params?: unknown[]) => Promise<{ rows: unknown[]; rowCount: number | null }>
+>
export interface FakeRow {
id: string
@@ -23,6 +29,7 @@ export interface FakeRow {
context_window_tokens: number | null
display_name: string | null
vendor: string | null
+ image_input: ImageInputCapability | null
}
export interface SeedRow {
@@ -34,14 +41,27 @@ export interface SeedRow {
context_window_tokens?: number | null
display_name?: string | null
vendor?: string | null
+ image_input?: ImageInputCapability | null
}
export interface FakeDb {
- connector: { connect: () => Promise<{ query: ReturnType<typeof vi.fn>; release: () => void }> }
+ connector: { connect: Mock<() => Promise<{ query: FakeQuery; release: () => void }>> }
/** Live view of the table after a run — assert against this. */
rows: FakeRow[]
/** Row lookup by (provider, model), for terse assertions. */
get: (provider: string, model: string) => FakeRow | undefined
+ /**
+ * The ConfigMap materializer the sync now requires (#654). Every suite that
+ * drives a run needs one; building it here keeps the call sites uniform and
+ * makes "was the ConfigMap republished?" a one-line assertion.
+ */
+ materializer: { materialize: Mock<(db?: unknown) => Promise<void>> }
+ /**
+ * Every statement the run issued, in order. The row state above is the primary
+ * assertion surface; this exists so a test that asserts a row is UNCHANGED can
+ * also witness that the run actually reached it.
+ */
+ calls: Array<{ sql: string; params: unknown[] }>
}
let idSeq = 0
@@ -57,9 +77,36 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
context_window_tokens: s.context_window_tokens ?? null,
display_name: s.display_name ?? null,
vendor: s.vendor ?? null,
+ image_input: s.image_input ?? null,
}))
+ /** JSONB parameters arrive as canonical JSON text (the services serialize them). */
+ const parseJsonb = (value: unknown): ImageInputCapability | null => {
+ if (value === null || value === undefined) return null
+ return JSON.parse(String(value)) as ImageInputCapability
+ }
+
+ /**
+ * The `image_input` CASE, shared by the discovery and manual statements
+ * because the service uses the SAME guard in both: a NULL column takes the
+ * new provenance, discovery evidence not newer than this capture is
+ * refreshed, and anything else (operator-`curated`, or a newer capture) is
+ * preserved. Modelling it once means a test cannot pass because the two
+ * branches drifted here in a way the production SQL did not.
+ */
+ const replaceableEvidence = (row: FakeRow, capturedAt: string): boolean => {
+ if (row.image_input === null) return true
+ const evidence = row.image_input.evidence
+ return (
+ evidence?.source === 'discovery' &&
+ Date.parse(String(evidence.checkedAt)) <= Date.parse(capturedAt)
+ )
+ }
+
+ const calls: Array<{ sql: string; params: unknown[] }> = []
+
const query = vi.fn(async (sql: string, params: unknown[] = []) => {
+ calls.push({ sql, params })
const empty = { rows: [] as unknown[], rowCount: 0 as number | null }
if (/^\s*(BEGIN|COMMIT|ROLLBACK)\s*$/i.test(sql)) return { rows: [], rowCount: null }
@@ -77,7 +124,7 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
// Materializer read (enabled rows). Static stale+enabled still
// materializes; Codex stale targets stay visible in DB but are not executable.
if (
- /SELECT provider, model, vendor, display_name, context_window_tokens\s+FROM llm_allowed_models\s+WHERE enabled/.test(
+ /SELECT provider, model, vendor, display_name, context_window_tokens, image_input\s+FROM llm_allowed_models\s+WHERE enabled/.test(
sql
)
) {
@@ -90,17 +137,19 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
vendor: r.vendor,
display_name: r.display_name,
context_window_tokens: r.context_window_tokens,
+ image_input: r.image_input,
}))
return { rows: out, rowCount: out.length }
}
// NEW row insert — ON CONFLICT (provider, model) DO NOTHING.
if (/INSERT INTO llm_allowed_models/.test(sql)) {
- const [provider, model, ctx, display] = params as [
+ const [provider, model, ctx, display, imageInput] = params as [
string,
string,
number | null,
string | null,
+ unknown,
]
if (rows.some(r => r.provider === provider && r.model === model)) return empty
rows.push({
@@ -113,14 +162,40 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
context_window_tokens: ctx ?? null,
display_name: display ?? null,
vendor: null,
+ image_input: parseJsonb(imageInput),
})
return { rows: [], rowCount: 1 }
}
+ // PRESENT manual row — `image_input` ONLY, through the same guard (#654).
+ // Everything an operator authored is absent from the statement, so this
+ // branch deliberately writes nothing else: if the service ever widened it,
+ // the suites asserting a manual row's other columns would still pass here,
+ // which is why the SQL-shape test asserts the statement's text too.
+ if (/UPDATE llm_allowed_models[\s\S]*t\.source = 'manual'/.test(sql)) {
+ const [id, imageInput, capturedAt] = params as [string, unknown, string]
+ const row = rows.find(r => r.id === id && r.source === 'manual')
+ if (!row) return empty
+ const before = JSON.stringify(row.image_input)
+ if (replaceableEvidence(row, capturedAt)) row.image_input = parseJsonb(imageInput)
+ return {
+ rows: [
+ { enabled: row.enabled, image_input_changed: before !== JSON.stringify(row.image_input) },
+ ],
+ rowCount: 1,
+ }
+ }
+
// PRESENT discovery row refresh — last_seen + stale=false + NULL-fill guarded
// to disabled rows (COALESCE), never touching `enabled`.
if (/UPDATE llm_allowed_models[\s\S]*SET\s+last_seen_at/.test(sql)) {
- const [id, ctx, display] = params as [string, number | null, string | null]
+ const [id, ctx, display, imageInput, capturedAt] = params as [
+ string,
+ number | null,
+ string | null,
+ unknown,
+ string,
+ ]
const row = rows.find(r => r.id === id && r.source === 'discovery')
if (!row) return empty
row.stale = false
@@ -128,7 +203,19 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
row.context_window_tokens = row.context_window_tokens ?? ctx ?? null
row.display_name = row.display_name ?? display ?? null
}
- return { rows: [], rowCount: 1 }
+ // `image_input` deliberately does NOT follow the enabled-row freeze the two
+ // columns above obey: it is written on enabled rows too, guarded by
+ // MONOTONICITY instead. Mirrors the SQL CASE — NULL gets the provenance,
+ // discovery evidence not newer than this capture is refreshed, and anything
+ // else (operator-curated, or a newer capture) is preserved.
+ const before = JSON.stringify(row.image_input)
+ if (replaceableEvidence(row, capturedAt)) row.image_input = parseJsonb(imageInput)
+ return {
+ rows: [
+ { enabled: row.enabled, image_input_changed: before !== JSON.stringify(row.image_input) },
+ ],
+ rowCount: 1,
+ }
}
// VANISHED → stale=true (never delete, never disable).
@@ -163,5 +250,7 @@ export function makeFakeDb(seed: SeedRow[] = []): FakeDb {
connector,
rows,
get: (provider, model) => rows.find(r => r.provider === provider && r.model === model),
+ materializer: { materialize: vi.fn(async () => {}) },
+ calls,
}
}
diff --git a/control-api/test/helpers/modelsDevFixtures.ts b/control-api/test/helpers/modelsDevFixtures.ts
index 229cd53f3..edc720477 100644
--- a/control-api/test/helpers/modelsDevFixtures.ts
+++ b/control-api/test/helpers/modelsDevFixtures.ts
@@ -54,6 +54,37 @@ export function trimSnapshot(spec: TrimSpec): RawModelsDevCatalog {
return out
}
+/**
+ * Overlay `modalities.input` on specific models of a trimmed catalog.
+ *
+ * The trim above keeps whatever the vendored snapshot carries, which is what a
+ * real fetch would give — but a test about the tri-state needs a KNOWN mix of
+ * supported/unsupported/absent entries that does not move when the snapshot is
+ * regenerated. The overlay writes the exact shape models.dev emits
+ * (`modalities: { input: string[] }`), and throws on an id the catalog does not
+ * contain so a typo cannot quietly produce an entry the test never exercises.
+ */
+export function withModalities(
+ catalog: RawModelsDevCatalog,
+ input: Record<string, string[]>
+): RawModelsDevCatalog {
+ const remaining = new Set(Object.keys(input))
+ const out: RawModelsDevCatalog = {}
+ for (const [key, provider] of Object.entries(catalog)) {
+ const models: RawModelsDevCatalog[string]['models'] = {}
+ for (const [id, model] of Object.entries(provider.models)) {
+ const override = input[id]
+ models[id] = override ? { ...model, modalities: { input: override } } : model
+ remaining.delete(id)
+ }
+ out[key] = { name: provider.name, models }
+ }
+ if (remaining.size > 0) {
+ throw new Error(`withModalities: model id(s) not in catalog: ${[...remaining].join(', ')}`)
+ }
+ return out
+}
+
/** Count of models.dev entries in a catalog (pre-mapping/dedup). */
export function catalogSize(catalog: RawModelsDevCatalog): number {
return Object.values(catalog).reduce((n, p) => n + Object.keys(p.models).length, 0)
@@ -62,7 +93,13 @@ export function catalogSize(catalog: RawModelsDevCatalog): number {
/** A `loadCatalog` stub for syncDiscoveredModels' DI seam. */
export function loadStub(
catalog: RawModelsDevCatalog,
- source: 'live' | 'vendored' = 'live'
+ source: 'live' | 'vendored' = 'live',
+ capturedAt = '2026-08-12T00:00:00.000Z'
): () => Promise<ModelsDevCatalogResult> {
- return async () => ({ source, fetchedAt: '2026-08-12T00:00:00.000Z', catalog })
+ return async () => ({
+ source,
+ fetchedAt: '2026-08-12T00:00:00.000Z',
+ capturedAt,
+ catalog,
+ })
}
diff --git a/control-api/test/routes.adminLlmModels.test.ts b/control-api/test/routes.adminLlmModels.test.ts
index 4dc1f9eb9..7593d0dcc 100644
--- a/control-api/test/routes.adminLlmModels.test.ts
+++ b/control-api/test/routes.adminLlmModels.test.ts
@@ -106,7 +106,7 @@ describe('admin llm-models routes', () => {
await request(app()).get('/api/v1/admin/llm-models').expect(401)
})
- it('POST /admin/llm-models/discovery/sync runs the sync and does NOT materialize the ConfigMap', async () => {
+ it('POST /admin/llm-models/discovery/sync passes the gateway materializer to the sync', async () => {
const summary = {
source: 'vendored' as const,
fetchedAt: '2026-07-13T00:00:00.000Z',
@@ -114,6 +114,8 @@ describe('admin llm-models routes', () => {
added: 3,
updated: 5,
staled: 1,
+ enabledImageInputChanged: 0,
+ materialized: false,
}
mockSyncDiscoveredModels.mockResolvedValueOnce(summary)
const gateway = new MockGateway('mcp-server')
@@ -123,9 +125,19 @@ describe('admin llm-models routes', () => {
const res = await authed('post', '/api/v1/admin/llm-models/discovery/sync', gateway).expect(200)
expect(res.body).toEqual(summary)
expect(mockSyncDiscoveredModels).toHaveBeenCalledTimes(1)
- // Discovery writes enabled=false rows → the allowlist ConfigMap must NOT be
- // re-materialized (it would be a no-op, but the invariant is asserted here).
+
+ // The route no longer decides whether to publish: it hands the sync the
+ // cluster-backed materializer and the SERVICE decides (it alone knows
+ // whether an enabled row's evidence changed). Assert the handed object is
+ // the gateway's, by exercising it — `llmAllowedModelsConfigMap()` returns a
+ // fresh wrapper each call, so identity would prove nothing.
+ const passed = mockSyncDiscoveredModels.mock.calls[0]?.[0] as {
+ materializer?: { materialize: () => Promise<void> }
+ }
+ expect(passed.materializer).toBeDefined()
expect(materialize).not.toHaveBeenCalled()
+ await passed.materializer!.materialize()
+ expect(materialize).toHaveBeenCalledTimes(1)
})
it('POST /admin/llm-models/discovery/sync requires admin auth (401 unauthenticated)', async () => {
@@ -219,6 +231,94 @@ describe('admin llm-models routes', () => {
expect(mockPoolQuery).not.toHaveBeenCalled()
})
+ it('POST /admin/llm-models accepts curated evidence and stores it (#654)', async () => {
+ const capability = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ }
+ mockPoolQuery
+ .mockResolvedValueOnce({
+ rows: [{ ...MODEL_ROW, provider: 'zai', model: 'glm-5.3-flash', image_input: capability }],
+ rowCount: 1,
+ })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 }) // audit
+ const res = await authed('post', '/api/v1/admin/llm-models')
+ .send({ provider: 'zai', model: 'glm-5.3-flash', image_input: capability })
+ .expect(201)
+ expect(res.body.image_input).toEqual(capability)
+ const insert = mockPoolQuery.mock.calls[0]
+ expect(String(insert[0])).toMatch(/image_input/)
+ expect((insert[1] as unknown[])[5]).toBe(JSON.stringify(capability))
+ })
+
+ it('POST /admin/llm-models rejects a known claim without evidence with 400 (#654)', async () => {
+ const res = await authed('post', '/api/v1/admin/llm-models')
+ .send({ provider: 'zai', model: 'glm-5.3', image_input: { state: 'supported' } })
+ .expect(400)
+ expect(res.body.error).toBe('invalid_request')
+ expect(res.body.details[0].field).toBe('image_input')
+ expect(mockPoolQuery).not.toHaveBeenCalled()
+ })
+
+ it('POST /admin/llm-models rejects a state-less payload without touching the database (#654)', async () => {
+ // `{}` and `{"state": null}` are exactly the payloads a total CHECK has to
+ // catch, so the writer must refuse them before the INSERT is attempted.
+ for (const image_input of [{}, { state: null }]) {
+ const res = await authed('post', '/api/v1/admin/llm-models')
+ .send({ provider: 'zai', model: 'glm-5.3', image_input })
+ .expect(400)
+ expect(res.body.error).toBe('invalid_request')
+ expect(res.body.details[0].field).toBe('image_input')
+ }
+ expect(mockPoolQuery).not.toHaveBeenCalled()
+ })
+
+ it('PUT /admin/llm-models/:id rejects discovery-sourced known support without validUntil', async () => {
+ const res = await authed('put', `/api/v1/admin/llm-models/${MODEL_ROW.id}`)
+ .send({
+ image_input: {
+ state: 'supported',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ },
+ })
+ .expect(400)
+ expect(res.body.details[0].field).toBe('image_input')
+ expect(mockPoolQuery).not.toHaveBeenCalled()
+ })
+
+ it('PUT /admin/llm-models/:id clears evidence on an explicit null (#654)', async () => {
+ // A metadata edit that keeps the pair enabled takes no gate/lock: route read,
+ // service read, UPDATE, audit.
+ mockPoolQuery
+ .mockResolvedValueOnce({
+ rows: [{ ...MODEL_ROW, image_input: { state: 'unknown' } }],
+ rowCount: 1,
+ })
+ .mockResolvedValueOnce({
+ rows: [{ ...MODEL_ROW, image_input: { state: 'unknown' } }],
+ rowCount: 1,
+ })
+ .mockResolvedValueOnce({ rows: [{ ...MODEL_ROW, image_input: null }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ const res = await authed('put', `/api/v1/admin/llm-models/${MODEL_ROW.id}`)
+ .send({ image_input: null })
+ .expect(200)
+ expect(res.body.image_input).toEqual({ state: 'unknown' })
+ const update = mockPoolQuery.mock.calls.find(c =>
+ /^UPDATE llm_allowed_models/.test(String(c[0]))
+ )
+ expect(update).toBeDefined()
+ expect((update![1] as unknown[])[0]).toBeNull()
+ })
+
it('POST /admin/llm-models maps a unique violation to 409', async () => {
mockPoolQuery.mockRejectedValueOnce(Object.assign(new Error('dup'), { code: '23505' }))
const res = await authed('post', '/api/v1/admin/llm-models')
diff --git a/control-api/test/services.llmAllowedModels.test.ts b/control-api/test/services.llmAllowedModels.test.ts
index c18486f17..f05f3d76a 100644
--- a/control-api/test/services.llmAllowedModels.test.ts
+++ b/control-api/test/services.llmAllowedModels.test.ts
@@ -30,6 +30,26 @@ const ROW = {
updated_at: new Date('2026-07-01T00:00:00Z'),
}
+// Curated evidence for an exact (provider, model) pair, as an operator would
+// enter it from the provider's own documentation.
+const CURATED_SUPPORTED = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+}
+
+const DISCOVERY_UNKNOWN = {
+ state: 'unknown',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-08-19T16:16:10.000Z',
+ },
+}
+
describe('llmAllowedModels service', () => {
describe('createLlmAllowedModelSchema', () => {
it('requires provider and model', () => {
@@ -95,6 +115,115 @@ describe('llmAllowedModels service', () => {
})
})
+ describe('image_input capability field (#654)', () => {
+ const withImage = (image_input: unknown) =>
+ createLlmAllowedModelSchema.safeParse({ provider: 'zai', model: 'glm-5.3', image_input })
+
+ it('accepts a curated known claim and an explicit unknown', () => {
+ expect(withImage(CURATED_SUPPORTED).success).toBe(true)
+ expect(withImage({ state: 'unknown' }).success).toBe(true)
+ expect(withImage(DISCOVERY_UNKNOWN).success).toBe(true)
+ expect(withImage(undefined).success).toBe(true)
+ })
+
+ it('rejects a known claim without evidence (invalid never becomes affirmative)', () => {
+ expect(withImage({ state: 'supported' }).success).toBe(false)
+ expect(withImage({ state: 'unsupported' }).success).toBe(false)
+ expect(withImage({ state: 'supported', evidence: {} }).success).toBe(false)
+ })
+
+ it('rejects a discovery-sourced known claim without validUntil', () => {
+ expect(
+ withImage({ state: 'supported', evidence: { ...DISCOVERY_UNKNOWN.evidence } }).success
+ ).toBe(false)
+ expect(
+ withImage({
+ state: 'supported',
+ evidence: {
+ ...DISCOVERY_UNKNOWN.evidence,
+ validUntil: '2026-12-01T00:00:00.000Z',
+ },
+ }).success
+ ).toBe(true)
+ })
+
+ it('rejects unknown keys, bad states, non-UTC dates and non-public references', () => {
+ // A payload with no `state` at all — including the `{}` an empty JSON body
+ // would produce — must never reach storage; the column CHECK is only the
+ // backstop, the writer rejects it first.
+ expect(withImage({}).success).toBe(false)
+ expect(withImage({ state: null }).success).toBe(false)
+ expect(withImage([]).success).toBe(false)
+ expect(withImage('supported').success).toBe(false)
+ expect(withImage({ state: 'bogus' }).success).toBe(false)
+ expect(withImage({ state: 'supported', extra: 1 }).success).toBe(false)
+ expect(withImage({ ...CURATED_SUPPORTED, extra: 1 }).success).toBe(false)
+ expect(
+ withImage({
+ ...CURATED_SUPPORTED,
+ evidence: { ...CURATED_SUPPORTED.evidence, checkedAt: '2026-09-16' },
+ }).success
+ ).toBe(false)
+ // A private/intranet reference must never be stored as evidence.
+ for (const reference of [
+ 'http://docs.z.ai/guides/llm/glm-5.3',
+ 'https://localhost/docs',
+ 'https://10.0.0.1/docs',
+ 'https://catalog.internal/docs',
+ ]) {
+ expect(
+ withImage({
+ ...CURATED_SUPPORTED,
+ evidence: { ...CURATED_SUPPORTED.evidence, reference },
+ }).success
+ ).toBe(false)
+ }
+ // A sanitized local evidence id is the non-URL form.
+ expect(
+ withImage({
+ ...CURATED_SUPPORTED,
+ evidence: { ...CURATED_SUPPORTED.evidence, reference: 'evidence:glm-eval-2026-09' },
+ }).success
+ ).toBe(true)
+ })
+
+ it('accepts an explicit null only on the UPDATE schema (clear)', () => {
+ expect(withImage(null).success).toBe(false)
+ expect(updateLlmAllowedModelSchema.safeParse({ image_input: null }).success).toBe(true)
+ expect(
+ updateLlmAllowedModelSchema.safeParse({ image_input: { state: 'nope' } }).success
+ ).toBe(false)
+ })
+
+ it('compares the DNS root dot for hostname policy and preserves the exact reference', () => {
+ const original = 'https://docs.z.ai./guides/vlm/glm-5.3-flash'
+ const dotted = {
+ ...CURATED_SUPPORTED,
+ evidence: { ...CURATED_SUPPORTED.evidence, reference: original },
+ }
+ const parsed = withImage(dotted)
+ // A public fully qualified hostname with the DNS root dot is still right.
+ expect(parsed.success).toBe(true)
+ if (parsed.success) {
+ expect(JSON.stringify(parsed.data)).toContain(original)
+ }
+ // The trailing dot cannot make an intranet, private, or single-label
+ // hostname pass: the policy compares the normalized hostname, and old
+ // evidence stored with such a reference must not produce a known claim.
+ for (const reference of [
+ 'https://localhost./docs',
+ 'https://10.0.0.1./docs',
+ 'https://catalog.internal./docs',
+ 'https://docs.local./docs',
+ 'https://web./docs',
+ ]) {
+ expect(
+ withImage({ ...CURATED_SUPPORTED, evidence: { ...dotted.evidence, reference } }).success
+ ).toBe(false)
+ }
+ })
+ })
+
describe('updateLlmAllowedModelSchema', () => {
it('rejects an empty body', () => {
expect(updateLlmAllowedModelSchema.safeParse({}).success).toBe(false)
@@ -136,6 +265,50 @@ describe('llmAllowedModels service', () => {
)
).rejects.toBeInstanceOf(LlmAllowedModelConflictError)
})
+
+ it('persists a validated capability and stores the normalized row value', async () => {
+ const query = vi
+ .fn()
+ .mockResolvedValueOnce({
+ rows: [
+ { ...ROW, provider: 'zai', model: 'glm-5.3-flash', image_input: CURATED_SUPPORTED },
+ ],
+ rowCount: 1,
+ })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ const created = await createAllowedModel(
+ createLlmAllowedModelSchema.parse({
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ image_input: CURATED_SUPPORTED,
+ }),
+ 'admin-1',
+ fakeDb(query)
+ )
+ const [insertSql, insertParams] = query.mock.calls[0]
+ expect(String(insertSql)).toMatch(/image_input/)
+ // Stored as canonical JSON text for the jsonb column.
+ expect(insertParams[5]).toBe(JSON.stringify(CURATED_SUPPORTED))
+ expect(created.image_input).toEqual(CURATED_SUPPORTED)
+ })
+
+ it('stores NULL when no capability is supplied (unknown is the absence of evidence)', async () => {
+ const query = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [ROW], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ const created = await createAllowedModel(
+ createLlmAllowedModelSchema.parse({
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ image_input: { state: 'unknown' },
+ }),
+ 'admin-1',
+ fakeDb(query)
+ )
+ expect(query.mock.calls[0][1][5]).toBeNull()
+ expect(created.image_input).toEqual({ state: 'unknown' })
+ })
})
describe('updateAllowedModel', () => {
@@ -171,6 +344,76 @@ describe('llmAllowedModels service', () => {
expect(String(sql)).toMatch(/updated_at = NOW\(\)/)
expect(params).toEqual(['Haiku', 'id'])
})
+
+ it('invalidates evidence when the (provider, model) pair is renamed', async () => {
+ const query = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [{ ...ROW, image_input: CURATED_SUPPORTED }], rowCount: 1 })
+ .mockResolvedValueOnce({
+ rows: [{ ...ROW, model: 'glm-5.2', image_input: null }],
+ rowCount: 1,
+ })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ await updateAllowedModel('id', { model: 'glm-5.2' }, 'admin-2', fakeDb(query))
+ const [sql, params] = query.mock.calls[1]
+ // Old evidence belonged to the OLD model: it must not carry over.
+ expect(String(sql)).toMatch(/image_input = NULL/)
+ expect(String(sql)).not.toMatch(/image_input = \$/)
+ expect(params).toEqual(['glm-5.2', 'id'])
+ })
+
+ it('keeps new evidence supplied in the same rename operation', async () => {
+ const query = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [{ ...ROW, image_input: CURATED_SUPPORTED }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [ROW], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ const fresh = {
+ state: 'unsupported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/llm/glm-5.3',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ }
+ await updateAllowedModel(
+ 'id',
+ updateLlmAllowedModelSchema.parse({ model: 'glm-5.3', image_input: fresh }),
+ 'admin-2',
+ fakeDb(query)
+ )
+ const [sql, params] = query.mock.calls[1]
+ expect(String(sql)).toMatch(/image_input = \$2/)
+ expect(String(sql)).not.toMatch(/image_input = NULL/)
+ expect(params).toEqual(['glm-5.3', JSON.stringify(fresh), 'id'])
+ })
+
+ it('clears evidence on an explicit null and never touches it on unrelated edits', async () => {
+ const clear = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [{ ...ROW, image_input: CURATED_SUPPORTED }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [{ ...ROW, image_input: null }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ await updateAllowedModel(
+ 'id',
+ updateLlmAllowedModelSchema.parse({ image_input: null }),
+ 'admin-2',
+ fakeDb(clear)
+ )
+ expect(clear.mock.calls[1][1]).toEqual([null, 'id'])
+ expect(String(clear.mock.calls[1][0])).toMatch(/image_input = \$1/)
+
+ const unrelated = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [{ ...ROW, image_input: CURATED_SUPPORTED }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [{ ...ROW, enabled: false }], rowCount: 1 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ await updateAllowedModel('id', { enabled: false }, 'admin-2', fakeDb(unrelated))
+ // Enabling/disabling is not a capability edit: evidence is frozen, so a
+ // published row keeps the exact metadata the ConfigMap already carries.
+ const setClause = String(unrelated.mock.calls[1][0]).split('WHERE')[0]
+ expect(setClause).not.toMatch(/image_input/)
+ })
})
describe('deleteAllowedModel', () => {
@@ -310,6 +553,34 @@ describe('llmAllowedModels service', () => {
expect(row.last_seen_at).toBeNull()
expect(row.stale).toBe(false)
})
+
+ it('normalizes legacy/malformed capability metadata to unknown and echoes curated evidence', async () => {
+ const query = vi.fn().mockResolvedValue({
+ rows: [
+ { ...ROW, image_input: null },
+ { ...ROW, id: '2', image_input: { state: 'bogus' } },
+ { ...ROW, id: '3', image_input: CURATED_SUPPORTED },
+ {
+ ...ROW,
+ id: '4',
+ image_input: {
+ state: 'supported',
+ evidence: {
+ ...CURATED_SUPPORTED.evidence,
+ reference: 'https://catalog.internal./docs',
+ },
+ },
+ },
+ ],
+ rowCount: 4,
+ })
+ const rows = await listAllowedModels(fakeDb(query))
+ expect(String(query.mock.calls[0][0])).toMatch(/image_input/)
+ expect(rows[0].image_input).toEqual({ state: 'unknown' })
+ expect(rows[1].image_input).toEqual({ state: 'unknown' })
+ expect(rows[2].image_input).toEqual(CURATED_SUPPORTED)
+ expect(rows[3].image_input).toEqual({ state: 'unknown' })
+ })
})
describe('listEnabledGroupedByProvider', () => {
@@ -364,5 +635,47 @@ describe('llmAllowedModels service', () => {
expect(String(sql)).not.toMatch(/AND NOT stale\b/)
expect(grouped.openai).toEqual([{ model: 'gpt-legacy' }])
})
+
+ it('projects stored capability metadata and omits it when absent (#654)', async () => {
+ const query = vi.fn().mockResolvedValue({
+ rows: [
+ {
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ vendor: 'Zhipu',
+ display_name: null,
+ context_window_tokens: null,
+ image_input: CURATED_SUPPORTED,
+ },
+ {
+ provider: 'zai',
+ model: 'glm-5.3',
+ vendor: 'Zhipu',
+ display_name: null,
+ context_window_tokens: null,
+ image_input: null,
+ },
+ {
+ provider: 'zai',
+ model: 'glm-legacy',
+ vendor: null,
+ display_name: null,
+ context_window_tokens: null,
+ },
+ ],
+ rowCount: 3,
+ })
+ const grouped = await listEnabledGroupedByProvider(fakeDb(query))
+ expect(String(query.mock.calls[0][0])).toMatch(/image_input/)
+ expect(grouped.zai[0]).toEqual({
+ model: 'glm-5.3-flash',
+ vendor: 'Zhipu',
+ imageInput: CURATED_SUPPORTED,
+ })
+ // Absent metadata stays absent: consumers normalize it to `unknown`, and
+ // the serialized entry keeps the pre-#654 shape for uncurated rows.
+ expect(grouped.zai[1]).toEqual({ model: 'glm-5.3', vendor: 'Zhipu' })
+ expect(grouped.zai[2]).toEqual({ model: 'glm-legacy' })
+ })
})
})
diff --git a/control-api/test/services.llmAllowedModelsConfigMap.test.ts b/control-api/test/services.llmAllowedModelsConfigMap.test.ts
index 849438119..e59c94a53 100644
--- a/control-api/test/services.llmAllowedModelsConfigMap.test.ts
+++ b/control-api/test/services.llmAllowedModelsConfigMap.test.ts
@@ -118,6 +118,45 @@ describe('buildConfigMapData', () => {
expect(source).toContain("NOT (provider = 'codex-subscription' AND stale)")
expect(CONTENT_HASH_ANNOTATION).toBe('clerum.io/content-hash')
})
+
+ it('#654 moves the content hash when a capability is published, and only then', async () => {
+ const { listEnabledGroupedByProvider } = await import('../src/services/llmAllowedModels.js')
+ const curated = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ }
+ const row = (image_input: unknown) => [
+ {
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ vendor: 'Zhipu',
+ display_name: null,
+ context_window_tokens: null,
+ image_input,
+ },
+ ]
+
+ const without = buildConfigMapData(await listEnabledGroupedByProvider(fakeDb(row(null))))
+ const absent = buildConfigMapData(
+ await listEnabledGroupedByProvider(fakeDb([{ ...row(null)[0], image_input: undefined }]))
+ )
+ const withCapability = buildConfigMapData(
+ await listEnabledGroupedByProvider(fakeDb(row(curated)))
+ )
+
+ // NULL and absent project identically: an uncurated allowlist keeps the
+ // pre-#654 bytes, so the host is not woken by a migration.
+ expect(absent.contentHash).toBe(without.contentHash)
+ expect(absent.data.zai).not.toMatch(/imageInput/)
+ // A published capability DOES change the materialized data + hash: the host
+ // must observe a capability change through the ConfigMap.
+ expect(withCapability.contentHash).not.toBe(without.contentHash)
+ expect(JSON.parse(withCapability.data.zai)[0].imageInput).toEqual(curated)
+ })
})
describe('LlmAllowedModelsConfigMapWriter', () => {
diff --git a/control-api/test/services.llmCatalogSync.guard.test.ts b/control-api/test/services.llmCatalogSync.guard.test.ts
index cb458a477..51777a3cf 100644
--- a/control-api/test/services.llmCatalogSync.guard.test.ts
+++ b/control-api/test/services.llmCatalogSync.guard.test.ts
@@ -30,7 +30,11 @@ describe('§4.5 sanity guard', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'vendored'), minPlausibleLiveTotal: 1 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'vendored'),
+ minPlausibleLiveTotal: 1,
+ },
db.connector
)
@@ -51,7 +55,11 @@ describe('§4.5 sanity guard', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1,
+ },
db.connector
)
@@ -71,7 +79,12 @@ describe('§4.5 sanity guard', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1, providerMinLive: 3 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1,
+ providerMinLive: 3,
+ },
db.connector
)
@@ -89,7 +102,11 @@ describe('§4.5 sanity guard', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 9999 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 9999,
+ },
db.connector
)
@@ -109,7 +126,11 @@ describe('§4.5 sanity guard', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5', 'claude-sonnet-5'] })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1,
+ },
db.connector
)
@@ -140,7 +161,12 @@ describe('§4.5 sanity guard', () => {
})
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1, providerMinLive: 0 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1,
+ providerMinLive: 0,
+ },
db.connector
)
diff --git a/control-api/test/services.llmCatalogSync.invariants.test.ts b/control-api/test/services.llmCatalogSync.invariants.test.ts
index 8d805ebfd..cd515c443 100644
--- a/control-api/test/services.llmCatalogSync.invariants.test.ts
+++ b/control-api/test/services.llmCatalogSync.invariants.test.ts
@@ -11,7 +11,7 @@ import { listEnabledGroupedByProvider } from '../src/services/llmAllowedModels.j
import { buildConfigMapData } from '../src/services/llmAllowedModelsConfigMap.js'
import { syncDiscoveredModels } from '../src/services/llmCatalogSync.js'
import { makeFakeDb } from './helpers/llmCatalogSyncFakeDb.js'
-import { loadStub, trimSnapshot } from './helpers/modelsDevFixtures.js'
+import { loadStub, trimSnapshot, withModalities } from './helpers/modelsDevFixtures.js'
vi.mock('../src/observability/logger.js', () => ({
rootLogger: { child: () => ({ info() {}, warn() {}, error() {}, debug() {} }) },
@@ -34,7 +34,7 @@ describe('catalog sync — load-bearing invariants (Fase 4)', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
+ { materializer: db.materializer, loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
db.connector
)
@@ -55,7 +55,7 @@ describe('catalog sync — load-bearing invariants (Fase 4)', () => {
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
+ { materializer: db.materializer, loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
db.connector
)
@@ -94,7 +94,7 @@ describe('catalog sync — load-bearing invariants (Fase 4)', () => {
])
const catalog = trimSnapshot({ anthropic: ['claude-opus-4-5'] })
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
+ { materializer: db.materializer, loadCatalog: loadStub(catalog, 'live'), ...LOW_FLOOR },
db.connector
)
expect(db.get('codex-subscription', 'gpt-5')?.stale).toBe(false)
@@ -102,4 +102,178 @@ describe('catalog sync — load-bearing invariants (Fase 4)', () => {
db.rows.some(row => row.provider === 'codex-subscription' && row.model !== 'gpt-5')
).toBe(false)
})
+
+ it('#654 derives image_input from modalities without clobbering curated or newer discovery evidence', async () => {
+ const CAPTURED_AT = '2026-08-19T16:16:10.000Z'
+ const TTL_MS = 30 * 24 * 60 * 60 * 1000
+ const curated = {
+ state: 'supported' as const,
+ evidence: {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+ }
+ const oldDiscovery = {
+ state: 'unknown' as const,
+ evidence: {
+ source: 'discovery' as const,
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-07-01T00:00:00.000Z',
+ },
+ }
+ // Captured AFTER this run's catalog: a later observation must never be
+ // regressed by an older one (a vendored fallback after a live sync).
+ const newerDiscovery = {
+ state: 'supported' as const,
+ evidence: {
+ source: 'discovery' as const,
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-09-01T00:00:00.000Z',
+ validUntil: '2026-10-01T00:00:00.000Z',
+ },
+ }
+ const db = makeFakeDb([
+ // Enabled + curated: published, must stay byte-identical.
+ {
+ provider: 'claude',
+ model: 'claude-opus-4-5',
+ source: 'discovery',
+ enabled: true,
+ image_input: curated,
+ },
+ // Disabled + curated: an operator decision that discovery must not undo.
+ {
+ provider: 'claude',
+ model: 'claude-sonnet-5',
+ source: 'discovery',
+ enabled: false,
+ image_input: curated,
+ },
+ // Disabled + older discovery provenance: refreshed from this catalog.
+ {
+ provider: 'claude',
+ model: 'claude-haiku-4-5-20251001',
+ source: 'discovery',
+ enabled: false,
+ image_input: oldDiscovery,
+ },
+ // ENABLED + older discovery provenance: also refreshed. The freeze the
+ // other serialized columns obey would expire this row's evidence one TTL
+ // after its only stamp, with no way back short of manual curation.
+ {
+ provider: 'claude',
+ model: 'claude-opus-4-6',
+ source: 'discovery',
+ enabled: true,
+ image_input: oldDiscovery,
+ },
+ // ENABLED + NEWER discovery provenance: untouched (monotonic guard).
+ {
+ provider: 'claude',
+ model: 'claude-sonnet-4-5',
+ source: 'discovery',
+ enabled: true,
+ image_input: newerDiscovery,
+ },
+ // MANUAL with no evidence: gets `image_input` and NOTHING else (#654).
+ // Seeded `stale: true` with null metadata so that every other column the
+ // discovery branch would have written is observable if it leaks here.
+ {
+ provider: 'claude',
+ model: 'claude-fable-5-1',
+ source: 'manual',
+ enabled: true,
+ stale: true,
+ display_name: null,
+ context_window_tokens: null,
+ image_input: null,
+ },
+ ])
+ const catalog = withModalities(
+ trimSnapshot({
+ anthropic: [
+ 'claude-opus-4-5',
+ 'claude-sonnet-5',
+ 'claude-haiku-4-5-20251001',
+ 'claude-opus-4-6',
+ 'claude-sonnet-4-5',
+ 'claude-fable-5-1',
+ // Absent from the DB → this run INSERTs it (disabled discovery row).
+ 'claude-opus-4-7',
+ ],
+ }),
+ {
+ 'claude-haiku-4-5-20251001': ['text', 'image'],
+ 'claude-opus-4-6': ['text'],
+ 'claude-sonnet-4-5': ['text', 'image'],
+ 'claude-fable-5-1': ['text', 'image'],
+ 'claude-opus-4-7': ['text', 'image'],
+ }
+ )
+
+ const result = await syncDiscoveredModels(
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live', CAPTURED_AT),
+ imageEvidenceTtlMs: TTL_MS,
+ ...LOW_FLOOR,
+ },
+ db.connector
+ )
+
+ const discovered = (state: 'supported' | 'unsupported') => ({
+ state,
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: CAPTURED_AT,
+ validUntil: new Date(Date.parse(CAPTURED_AT) + TTL_MS).toISOString(),
+ },
+ })
+
+ // Curated evidence is untouchable, enabled or not.
+ expect(db.get('claude', 'claude-opus-4-5')!.image_input).toEqual(curated)
+ expect(db.get('claude', 'claude-sonnet-5')!.image_input).toEqual(curated)
+ // Older discovery evidence is replaced by this catalog's verdict — and the
+ // enabled row is replaced too, because a frozen one would silently expire.
+ expect(db.get('claude', 'claude-haiku-4-5-20251001')!.image_input).toEqual(
+ discovered('supported')
+ )
+ expect(db.get('claude', 'claude-opus-4-6')!.image_input).toEqual(discovered('unsupported'))
+ // A NEWER capture is never regressed by this older one.
+ expect(db.get('claude', 'claude-sonnet-4-5')!.image_input).toEqual(newerDiscovery)
+ // A freshly inserted row is born disabled, and carries the catalog's verdict.
+ const inserted = db.get('claude', 'claude-opus-4-7')!
+ expect(inserted.enabled).toBe(false)
+ expect(inserted.image_input).toEqual(discovered('supported'))
+ // A manual row receives the catalog's verdict and keeps everything an
+ // operator authored. `stale`, `display_name` and `context_window_tokens`
+ // are the tells: the discovery branch writes all three, so if the manual
+ // statement ever widened, these would flip.
+ const manual = db.get('claude', 'claude-fable-5-1')!
+ expect(manual.image_input).toEqual(discovered('supported'))
+ expect(manual.source).toBe('manual')
+ expect(manual.enabled).toBe(true)
+ expect(manual.stale).toBe(true)
+ expect(manual.display_name).toBeNull()
+ expect(manual.context_window_tokens).toBeNull()
+ // Witness for every "unchanged" above: the run really did visit each row.
+ expect(db.connector.connect).toHaveBeenCalled()
+ for (const model of ['claude-opus-4-5', 'claude-sonnet-5', 'claude-sonnet-4-5']) {
+ const id = db.get('claude', model)!.id
+ expect(
+ db.calls.some(call => /SET last_seen_at/.test(call.sql) && call.params[0] === id)
+ ).toBe(true)
+ }
+ expect(
+ db.calls.some(call => /t\.source = 'manual'/.test(call.sql) && call.params[0] === manual.id)
+ ).toBe(true)
+ // Two enabled rows changed evidence (claude-opus-4-6 on the discovery branch
+ // and the manual claude-fable-5-1); the other enabled rows are curated or
+ // newer → the ConfigMap is republished once, after COMMIT.
+ expect(result.enabledImageInputChanged).toBe(2)
+ expect(result.materialized).toBe(true)
+ expect(db.materializer.materialize).toHaveBeenCalledTimes(1)
+ })
})
diff --git a/control-api/test/services.llmCatalogSync.properties.test.ts b/control-api/test/services.llmCatalogSync.properties.test.ts
index d5c0d35c1..9c5da32e2 100644
--- a/control-api/test/services.llmCatalogSync.properties.test.ts
+++ b/control-api/test/services.llmCatalogSync.properties.test.ts
@@ -26,7 +26,7 @@ import { VENDORED_MODELS_DEV_SNAPSHOT } from '../src/data/modelsDevSnapshot.js'
import { syncDiscoveredModels } from '../src/services/llmCatalogSync.js'
import { PROVIDER_KEY_MAP, mapCatalogToProviders } from '../src/services/modelsDevClient.js'
import { type FakeDb, type SeedRow, makeFakeDb } from './helpers/llmCatalogSyncFakeDb.js'
-import { loadStub, trimSnapshot } from './helpers/modelsDevFixtures.js'
+import { loadStub, trimSnapshot, withModalities } from './helpers/modelsDevFixtures.js'
vi.mock('../src/observability/logger.js', () => ({
rootLogger: { child: () => ({ info() {}, warn() {}, error() {}, debug() {} }) },
@@ -179,14 +179,22 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
const db = makeFakeDb(seed)
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LIVE_LOW_FLOOR },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ ...LIVE_LOW_FLOOR,
+ },
db.connector
)
const staleAfter1 = staleSet(db)
const enabledAfter1 = enabledSet(db)
const res2 = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LIVE_LOW_FLOOR },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ ...LIVE_LOW_FLOOR,
+ },
db.connector
)
@@ -207,7 +215,11 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
const db = makeFakeDb(seed)
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LIVE_LOW_FLOOR },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ ...LIVE_LOW_FLOOR,
+ },
db.connector
)
@@ -220,7 +232,11 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
}
const res2 = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LIVE_LOW_FLOOR },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ ...LIVE_LOW_FLOOR,
+ },
db.connector
)
// Re-run must not re-stale a healed row.
@@ -244,7 +260,11 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
const enabledBefore = new Set(seed.filter(r => r.enabled).map(rowKey))
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), ...LIVE_LOW_FLOOR },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ ...LIVE_LOW_FLOOR,
+ },
db.connector
)
@@ -274,7 +294,11 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
const res = await syncDiscoveredModels(
// Impossibly high global floor → every live total is "implausible".
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1_000_000 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1_000_000,
+ },
db.connector
)
@@ -306,7 +330,12 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
const staleBeforeByKey = new Map(seed.map(r => [rowKey(r), r.stale ?? false]))
await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1, providerMinLive: 0 },
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live'),
+ minPlausibleLiveTotal: 1,
+ providerMinLive: 0,
+ },
db.connector
)
@@ -322,4 +351,131 @@ describe('catalog sync — property-based reconciliation invariants (R1-M4)', ()
{ numRuns: NUM_RUNS }
)
})
+
+ it('P5 image_input evidence is monotonic in checkedAt and never overwrites curated', async () => {
+ const CAPTURED_AT = '2026-08-19T16:16:10.000Z'
+ const TTL_MS = 30 * 24 * 60 * 60 * 1000
+ const KEY = 'anthropic'
+ const IDS = Object.keys(VENDORED_MODELS_DEV_SNAPSHOT[KEY]!.models).slice(0, 6)
+ const PROVIDER_ID = KEY_TO_ID[KEY]!
+
+ /** The four evidence shapes a row can already carry when a sync arrives. */
+ type EvidenceKind = 'none' | 'curated' | 'discovery-older' | 'discovery-newer'
+ const evidenceFor = (kind: EvidenceKind, offsetMs: number) => {
+ if (kind === 'none') return null
+ if (kind === 'curated') {
+ return {
+ state: 'supported' as const,
+ evidence: {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: new Date(Date.parse(CAPTURED_AT) - offsetMs).toISOString(),
+ },
+ }
+ }
+ const sign = kind === 'discovery-older' ? -1 : 1
+ const checkedAt = new Date(Date.parse(CAPTURED_AT) + sign * offsetMs).toISOString()
+ return {
+ state: 'unsupported' as const,
+ evidence: {
+ source: 'discovery' as const,
+ reference: 'https://models.dev/api.json',
+ checkedAt,
+ validUntil: new Date(Date.parse(checkedAt) + TTL_MS).toISOString(),
+ },
+ }
+ }
+
+ const rowArb = fc.record({
+ source: fc.constantFrom('discovery', 'manual'),
+ enabled: fc.boolean(),
+ kind: fc.constantFrom<EvidenceKind>('none', 'curated', 'discovery-older', 'discovery-newer'),
+ // Strictly positive so `discovery-older`/`-newer` are never AT the capture
+ // instant, where `<=` makes the outcome a boundary case, not a class.
+ offsetMs: fc.integer({ min: 1_000, max: 90 * 24 * 60 * 60 * 1000 }),
+ supportsImages: fc.boolean(),
+ })
+
+ await fc.assert(
+ fc.asyncProperty(
+ fc.array(rowArb, { minLength: IDS.length, maxLength: IDS.length }),
+ async specs => {
+ const seed: SeedRow[] = IDS.map((model, i) => ({
+ provider: PROVIDER_ID,
+ model,
+ source: specs[i]!.source,
+ enabled: specs[i]!.enabled,
+ // Seeded stale so the flag DISCRIMINATES: the discovery branch
+ // clears it on every row it touches, so a manual row still stale
+ // after the run proves the manual statement did not write it.
+ stale: true,
+ image_input: evidenceFor(specs[i]!.kind, specs[i]!.offsetMs),
+ }))
+ const db = makeFakeDb(seed)
+ const catalog = withModalities(
+ trimSnapshot({ [KEY]: IDS }),
+ Object.fromEntries(
+ IDS.map((id, i) => [id, specs[i]!.supportsImages ? ['text', 'image'] : ['text']])
+ )
+ )
+
+ await syncDiscoveredModels(
+ {
+ materializer: db.materializer,
+ loadCatalog: loadStub(catalog, 'live', CAPTURED_AT),
+ imageEvidenceTtlMs: TTL_MS,
+ ...LIVE_LOW_FLOOR,
+ },
+ db.connector
+ )
+
+ // Witness the run was not vacuous: every seeded row is still there.
+ expect(db.rows.length).toBeGreaterThanOrEqual(IDS.length)
+
+ for (const [i, model] of IDS.entries()) {
+ const spec = specs[i]!
+ const before = evidenceFor(spec.kind, spec.offsetMs)
+ const after = db.get(PROVIDER_ID, model)!.image_input
+ const derived = {
+ state: spec.supportsImages ? 'supported' : 'unsupported',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: CAPTURED_AT,
+ validUntil: new Date(Date.parse(CAPTURED_AT) + TTL_MS).toISOString(),
+ },
+ }
+ // The guard is the SAME on both branches (#654), so `source` drops
+ // out of this rule entirely: what decides is the evidence already
+ // on the row, never who owns the row or whether it is enabled.
+ //
+ // Curated evidence outranks discovery whatever its age.
+ if (spec.kind === 'curated') expect(after).toEqual(before)
+ // A capture newer than this run's is never regressed.
+ else if (spec.kind === 'discovery-newer') expect(after).toEqual(before)
+ // Everything else takes the catalog's verdict — manual or not,
+ // enabled or not.
+ else expect(after).toEqual(derived)
+
+ // …but a manual row keeps every column an operator authored. The
+ // seed leaves these null/false, so a leak from the discovery
+ // branch (which writes all three) is observable.
+ const row = db.get(PROVIDER_ID, model)!
+ if (spec.source === 'manual') {
+ expect(row.source).toBe('manual')
+ expect(row.stale).toBe(true)
+ expect(row.display_name).toBeNull()
+ expect(row.context_window_tokens).toBeNull()
+ } else {
+ // The discriminator's other half: the discovery branch DOES clear
+ // `stale`, so `stale === true` above is a choice, not an untouched
+ // row in a run that wrote nothing.
+ expect(row.stale).toBe(false)
+ }
+ }
+ }
+ ),
+ { numRuns: NUM_RUNS }
+ )
+ })
})
diff --git a/control-api/test/services.llmCatalogSync.realPostgres.integration.test.ts b/control-api/test/services.llmCatalogSync.realPostgres.integration.test.ts
new file mode 100644
index 000000000..bb3998d82
--- /dev/null
+++ b/control-api/test/services.llmCatalogSync.realPostgres.integration.test.ts
@@ -0,0 +1,306 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { randomBytes } from 'node:crypto'
+import { Pool } from 'pg'
+import type { ImageInputCapability } from '@clerum/llm-providers'
+import { initDb } from '../src/db.js'
+import { type CatalogSyncResult, syncDiscoveredModels } from '../src/services/llmCatalogSync.js'
+import { loadStub, trimSnapshot, withModalities } from './helpers/modelsDevFixtures.js'
+import './realPostgres.requirement.ts'
+
+// R1-M2: run `syncDiscoveredModels` against a REAL PostgreSQL. The in-memory
+// fake used by services.llmCatalogSync.invariants.test.ts models the statement
+// semantics; it cannot prove the parts only Postgres decides:
+// - the `UPDATE ... FROM llm_allowed_models AS prev ... RETURNING
+// (t.image_input IS DISTINCT FROM prev.image_input)` self-join, which must
+// compare the NEW target row with the PRE-UPDATE row, so the returned
+// enabledImageInputChanged count (and the ConfigMap republish) is exact;
+// - the `(checkedAt)::timestamptz <= $capturedAt::timestamptz` monotonic
+// guard, which must compare instants, not strings.
+// Skipped without CONTROL_API_REAL_PG_ADMIN_URL, like every sibling suite.
+
+const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL
+const describeRealPostgres = adminUrl ? describe : describe.skip
+
+function databaseUrl(baseUrl: string, database: string): string {
+ const url = new URL(baseUrl)
+ url.pathname = `/${database}`
+ return url.toString()
+}
+
+function quoteIdent(value: string): string {
+ return `"${value.replace(/"/g, '""')}"`
+}
+
+const CAPTURED_AT = '2026-08-19T16:16:10.000Z'
+const TTL_MS = 30 * 24 * 60 * 60 * 1000
+const LOW_FLOOR = { minPlausibleLiveTotal: 1 }
+
+const curated: ImageInputCapability = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00.000Z',
+ },
+}
+const oldDiscovery: ImageInputCapability = {
+ state: 'unknown',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-07-01T00:00:00.000Z',
+ },
+}
+// Captured AFTER this run's catalog. Spelled without milliseconds (CAPTURED_AT
+// carries `.000Z`) so the real `::timestamptz` cast parses both spellings.
+const newerDiscovery: ImageInputCapability = {
+ state: 'supported',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-09-01T00:00:00Z',
+ validUntil: '2026-10-01T00:00:00Z',
+ },
+}
+
+function discovered(state: 'supported' | 'unsupported') {
+ return {
+ state,
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: CAPTURED_AT,
+ validUntil: new Date(Date.parse(CAPTURED_AT) + TTL_MS).toISOString(),
+ },
+ }
+}
+
+interface SeedRow {
+ model: string
+ source: 'discovery' | 'manual'
+ enabled: boolean
+ stale?: boolean
+ display_name?: string | null
+ context_window_tokens?: number | null
+ image_input: ImageInputCapability | null
+}
+
+// Same seed as the #654 invariant in services.llmCatalogSync.invariants.test.ts.
+const SEED: SeedRow[] = [
+ // Enabled + curated: published, must stay byte-identical.
+ { model: 'claude-opus-4-5', source: 'discovery', enabled: true, image_input: curated },
+ // Disabled + curated: an operator decision discovery must not undo.
+ { model: 'claude-sonnet-5', source: 'discovery', enabled: false, image_input: curated },
+ // Disabled + older discovery provenance: refreshed.
+ {
+ model: 'claude-haiku-4-5-20251001',
+ source: 'discovery',
+ enabled: false,
+ image_input: oldDiscovery,
+ },
+ // ENABLED + older discovery provenance: refreshed → counts as a change.
+ { model: 'claude-opus-4-6', source: 'discovery', enabled: true, image_input: oldDiscovery },
+ // ENABLED + NEWER discovery provenance: untouched (monotonic guard).
+ { model: 'claude-sonnet-4-5', source: 'discovery', enabled: true, image_input: newerDiscovery },
+ // MANUAL, enabled, no evidence: gets image_input and NOTHING else → counts
+ // as a change. Seeded stale with null metadata so any leak of the discovery
+ // branch's other writes is observable.
+ {
+ model: 'claude-fable-5-1',
+ source: 'manual',
+ enabled: true,
+ stale: true,
+ display_name: null,
+ context_window_tokens: null,
+ image_input: null,
+ },
+]
+
+const CATALOG = withModalities(
+ trimSnapshot({
+ anthropic: [
+ 'claude-opus-4-5',
+ 'claude-sonnet-5',
+ 'claude-haiku-4-5-20251001',
+ 'claude-opus-4-6',
+ 'claude-sonnet-4-5',
+ 'claude-fable-5-1',
+ // Absent from the DB → the first run INSERTs it as a disabled row.
+ 'claude-opus-4-7',
+ ],
+ }),
+ {
+ 'claude-haiku-4-5-20251001': ['text', 'image'],
+ 'claude-opus-4-6': ['text'],
+ 'claude-sonnet-4-5': ['text', 'image'],
+ 'claude-fable-5-1': ['text', 'image'],
+ 'claude-opus-4-7': ['text', 'image'],
+ }
+)
+
+type DbRow = Record<string, unknown> & {
+ model: string
+ enabled: boolean
+ source: string
+ image_input: ImageInputCapability | null
+}
+
+describeRealPostgres('syncDiscoveredModels on real PostgreSQL (#654 image_input)', () => {
+ const database = `control_api_catalog_sync_${randomBytes(6).toString('hex')}`
+ let adminPool: Pool
+ let dbPool: Pool
+ const materializer = { materialize: vi.fn(async () => {}) }
+ let manualBefore: DbRow
+ let firstRun: CatalogSyncResult
+
+ async function readRows(): Promise<Map<string, DbRow>> {
+ const { rows } = await dbPool.query<DbRow>(
+ `SELECT * FROM llm_allowed_models WHERE provider = 'claude' ORDER BY model`
+ )
+ return new Map(rows.map(row => [row.model, row]))
+ }
+
+ async function countRuns(): Promise<number> {
+ const { rows } = await dbPool.query<{ n: string }>(
+ 'SELECT count(*)::text AS n FROM llm_catalog_sync_runs'
+ )
+ return Number(rows[0].n)
+ }
+
+ function runSync(capturedAt: string, source: 'live' | 'vendored' = 'live') {
+ return syncDiscoveredModels(
+ {
+ materializer,
+ loadCatalog: loadStub(CATALOG, source, capturedAt),
+ imageEvidenceTtlMs: TTL_MS,
+ ...LOW_FLOOR,
+ },
+ dbPool
+ )
+ }
+
+ beforeAll(async () => {
+ adminPool = new Pool({ connectionString: adminUrl })
+ await adminPool.query(`CREATE DATABASE ${quoteIdent(database)}`)
+ dbPool = new Pool({ connectionString: databaseUrl(adminUrl!, database) })
+ await initDb({ connect: () => dbPool.connect() })
+
+ // initDb seeds the static allowlist as `source='manual'` rows. Start from
+ // an empty table so the seed below is the whole universe the sync sees.
+ await dbPool.query('DELETE FROM llm_allowed_models')
+ for (const row of SEED) {
+ await dbPool.query(
+ `INSERT INTO llm_allowed_models
+ (provider, model, enabled, source, stale, display_name,
+ context_window_tokens, image_input)
+ VALUES ('claude', $1, $2, $3, $4, $5, $6, $7::jsonb)`,
+ [
+ row.model,
+ row.enabled,
+ row.source,
+ row.stale ?? false,
+ row.display_name ?? null,
+ row.context_window_tokens ?? null,
+ row.image_input === null ? null : JSON.stringify(row.image_input),
+ ]
+ )
+ }
+ const seeded = await readRows()
+ expect(seeded.size).toBe(SEED.length)
+ manualBefore = seeded.get('claude-fable-5-1')!
+ })
+
+ afterAll(async () => {
+ await dbPool?.end()
+ if (!adminPool) return
+ await adminPool.query(
+ `SELECT pg_terminate_backend(pid)
+ FROM pg_stat_activity
+ WHERE datname = $1
+ AND pid <> pg_backend_pid()`,
+ [database]
+ )
+ await adminPool.query(`DROP DATABASE IF EXISTS ${quoteIdent(database)}`)
+ await adminPool.end()
+ })
+
+ it('counts exactly the enabled rows whose image_input changed and republishes once', async () => {
+ firstRun = await runSync(CAPTURED_AT)
+
+ // claude-opus-4-6 (discovery) and claude-fable-5-1 (manual). The other
+ // enabled rows are curated or newer, so the self-join must see them as
+ // unchanged; the disabled rows that did change must not be counted.
+ expect(firstRun.enabledImageInputChanged).toBe(2)
+ expect(firstRun.materialized).toBe(true)
+ expect(firstRun.added).toBe(1)
+ expect(materializer.materialize).toHaveBeenCalledTimes(1)
+
+ const rows = await readRows()
+ expect(rows.get('claude-opus-4-6')!.image_input).toEqual(discovered('unsupported'))
+ expect(rows.get('claude-haiku-4-5-20251001')!.image_input).toEqual(discovered('supported'))
+ const inserted = rows.get('claude-opus-4-7')!
+ expect(inserted.enabled).toBe(false)
+ expect(inserted.source).toBe('discovery')
+ expect(inserted.image_input).toEqual(discovered('supported'))
+ })
+
+ it('an immediate re-run reports no change and does not republish', async () => {
+ const runsBefore = await countRuns()
+ const rerun = await runSync(CAPTURED_AT)
+
+ // Liveness witness: this run really happened and really visited the rows.
+ // It persisted its own summary row, and refreshed the discovery rows
+ // (`<=` rewrites evidence stamped with the same capture).
+ expect(await countRuns()).toBe(runsBefore + 1)
+ expect(rerun.ranAt).not.toBe(firstRun.ranAt)
+ expect(rerun.updated).toBe(SEED.filter(r => r.source === 'discovery').length + 1)
+
+ expect(rerun.enabledImageInputChanged).toBe(0)
+ expect(rerun.materialized).toBe(false)
+ expect(materializer.materialize).toHaveBeenCalledTimes(1)
+ const rows = await readRows()
+ expect(rows.get('claude-opus-4-6')!.image_input).toEqual(discovered('unsupported'))
+ expect(rows.get('claude-fable-5-1')!.image_input).toEqual(discovered('supported'))
+ })
+
+ it('never regresses stored discovery evidence with a newer checkedAt', async () => {
+ const rows = await readRows()
+ expect(rows.get('claude-sonnet-4-5')!.image_input).toEqual(newerDiscovery)
+
+ // An OLDER capture (a vendored fallback after the live run) must not
+ // overwrite anything this live run stamped either.
+ const olderRun = await runSync('2026-08-01T00:00:00Z', 'vendored')
+ expect(olderRun.updated).toBeGreaterThan(0)
+ expect(olderRun.enabledImageInputChanged).toBe(0)
+ expect(materializer.materialize).toHaveBeenCalledTimes(1)
+ const after = await readRows()
+ expect(after.get('claude-sonnet-4-5')!.image_input).toEqual(newerDiscovery)
+ expect(after.get('claude-opus-4-6')!.image_input).toEqual(discovered('unsupported'))
+ expect(after.get('claude-fable-5-1')!.image_input).toEqual(discovered('supported'))
+ })
+
+ it('writes only image_input on a manual row', async () => {
+ const manual = (await readRows()).get('claude-fable-5-1')!
+ expect(manual.image_input).toEqual(discovered('supported'))
+ expect(manualBefore.image_input).toBeNull()
+
+ // Every other column — including stale, last_seen_at, discovered_at,
+ // display_name and context_window_tokens, which the discovery branch
+ // would write — is exactly what the seed stored.
+ const { image_input: _afterImage, ...afterRest } = manual
+ const { image_input: _beforeImage, ...beforeRest } = manualBefore
+ expect(afterRest).toEqual(beforeRest)
+ expect(afterRest.source).toBe('manual')
+ expect(afterRest.stale).toBe(true)
+ expect(afterRest.last_seen_at).toBeNull()
+ })
+
+ it('leaves curated evidence untouched, enabled or not', async () => {
+ const rows = await readRows()
+ expect(rows.get('claude-opus-4-5')!.image_input).toEqual(curated)
+ expect(rows.get('claude-sonnet-5')!.image_input).toEqual(curated)
+ // Witness: the sync did visit both rows (last_seen_at is only set by it).
+ expect(rows.get('claude-opus-4-5')!.last_seen_at).toBeInstanceOf(Date)
+ expect(rows.get('claude-sonnet-5')!.last_seen_at).toBeInstanceOf(Date)
+ })
+})
diff --git a/control-api/test/services.llmCatalogSync.test.ts b/control-api/test/services.llmCatalogSync.test.ts
index b432a536e..2aba5c23f 100644
--- a/control-api/test/services.llmCatalogSync.test.ts
+++ b/control-api/test/services.llmCatalogSync.test.ts
@@ -1,16 +1,32 @@
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { registry } from '../src/observability/metrics.js'
import { syncDiscoveredModels } from '../src/services/llmCatalogSync.js'
import type { RawModelsDevCatalog } from '../src/services/modelsDevClient.js'
type Row = Record<string, unknown>
+/**
+ * The sync REQUIRES a ConfigMap materializer (#654) — it can change what runtime
+ * is served. Most tests here assert SQL shape on rows the run never publishes,
+ * so this spy stays uncalled; the publication tests assert on it directly.
+ */
+const materializer = { materialize: vi.fn(async () => {}) }
+
+beforeEach(() => {
+ materializer.materialize.mockReset()
+})
+
/**
* A fake transactional client that routes queries by SQL shape. `existing` maps
* provider → the rows the per-provider SELECT should return (id/model/source).
* It records the INSERT/UPDATE/stale calls so tests can assert branch behavior.
*/
function makeConnector(
- existing: Record<string, Array<{ id: string; model: string; source: string }>>
+ existing: Record<string, Array<{ id: string; model: string; source: string }>>,
+ // What the discovery UPDATE's RETURNING clause reports. The default says the
+ // touched row is disabled, which is what every SQL-shape test below wants: a
+ // disabled row can never force a ConfigMap write.
+ updateReturning: Row = { enabled: false, image_input_changed: false }
) {
const calls: Array<{ sql: string; params: unknown[] }> = []
const query = vi.fn(async (sql: string, params: unknown[] = []) => {
@@ -24,7 +40,13 @@ function makeConnector(
return { rows: [], rowCount: 1 }
}
if (/UPDATE llm_allowed_models[\s\S]*SET last_seen_at/.test(sql)) {
- return { rows: [], rowCount: 1 }
+ return { rows: [updateReturning], rowCount: 1 }
+ }
+ // The manual-row statement reports through the SAME RETURNING contract, so
+ // it answers with the same row: a test that flips `updateReturning` to an
+ // enabled row must be able to drive publication from either branch.
+ if (/UPDATE llm_allowed_models[\s\S]*t\.source = 'manual'/.test(sql)) {
+ return { rows: [updateReturning], rowCount: 1 }
}
if (/UPDATE llm_allowed_models[\s\S]*SET stale = true/.test(sql)) {
// Report a stale transition for the vanished-row test (claude provider).
@@ -42,25 +64,77 @@ function makeConnector(
}
function catalogWith(
- models: Record<string, { id: string; name?: string; limit?: { context?: number } }>
+ models: Record<
+ string,
+ {
+ id: string
+ name?: string
+ limit?: { context?: number }
+ modalities?: { input?: unknown }
+ }
+ >
): RawModelsDevCatalog {
return { anthropic: { name: 'Anthropic', models } }
}
-function loadStub(catalog: RawModelsDevCatalog, source: 'live' | 'vendored' = 'vendored') {
- return async () => ({ source, fetchedAt: '2026-07-13T00:00:00.000Z', catalog })
+function loadStub(
+ catalog: RawModelsDevCatalog,
+ source: 'live' | 'vendored' = 'vendored',
+ // `fetchedAt` is the run's acquisition time; `capturedAt` is when the DATA was
+ // captured (a vendored snapshot's baked date). Kept distinct on purpose.
+ capturedAt = '2026-07-10T00:00:00.000Z'
+) {
+ return async () => ({
+ source,
+ fetchedAt: '2026-07-13T00:00:00.000Z',
+ capturedAt,
+ catalog,
+ })
}
const CALL_FOR = (calls: Array<{ sql: string; params: unknown[] }>, re: RegExp) =>
calls.filter(c => re.test(c.sql))
+/**
+ * Current value of `clerum_llm_allowlist_configmap_write_failures_total{phase}`.
+ * Read from the real registry rather than a spy: the point of the assertion is
+ * that the operator-visible counter moved.
+ */
+async function configMapWriteFailures(phase: string): Promise<number> {
+ const metric = registry.getSingleMetric('clerum_llm_allowlist_configmap_write_failures_total')
+ const collected = (await metric?.get()) as
+ | { values: Array<{ labels: Record<string, unknown>; value: number }> }
+ | undefined
+ return collected?.values.find(v => v.labels.phase === phase)?.value ?? 0
+}
+
+/**
+ * The exact provenance payload discovery persists for a model the catalog says
+ * nothing about. A KNOWN state additionally carries `validUntil` — the shared
+ * contract refuses a discovery claim without an expiry — and is asserted as a
+ * parsed object below, since only key ORDER would differ here.
+ */
+function discoveryProvenance(capturedAt: string): string {
+ return JSON.stringify({
+ state: 'unknown',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: capturedAt,
+ },
+ })
+}
+
describe('syncDiscoveredModels — source-guarded reconciliation', () => {
it('INSERTs a new discovered model as disabled discovery (enabled=false, ON CONFLICT DO NOTHING)', async () => {
const { connector, calls } = makeConnector({}) // no existing rows anywhere
const catalog = catalogWith({
'claude-opus-4-5': { id: 'claude-opus-4-5', name: 'Opus', limit: { context: 200000 } },
})
- const res = await syncDiscoveredModels({ loadCatalog: loadStub(catalog) }, connector)
+ const res = await syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog) },
+ connector
+ )
const inserts = CALL_FOR(calls, /INSERT INTO llm_allowed_models/)
expect(inserts).toHaveLength(1)
@@ -68,26 +142,149 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
expect(inserts[0].sql).toMatch(/'discovery'/)
expect(inserts[0].sql).toMatch(/false/)
expect(inserts[0].sql).toMatch(/ON CONFLICT \(provider, model\) DO NOTHING/)
- // params: provider, model, ctx, display
- expect(inserts[0].params).toEqual(['claude', 'claude-opus-4-5', 200000, 'Opus'])
+ // params: provider, model, ctx, display, image_input
+ expect(inserts[0].params).toEqual([
+ 'claude',
+ 'claude-opus-4-5',
+ 200000,
+ 'Opus',
+ discoveryProvenance('2026-07-10T00:00:00.000Z'),
+ ])
expect(res.added).toBe(1)
expect(res.updated).toBe(0)
})
- it('NEVER touches a colliding source=manual row (invisible to discovery)', async () => {
+ it('#654 stamps discovery provenance with the SOURCE capture time, never `fetchedAt`', async () => {
+ const { connector, calls } = makeConnector({})
+ const catalog = catalogWith({
+ // Says nothing about modalities …
+ 'claude-opus-4-5': { id: 'claude-opus-4-5' },
+ // … and one that does, so the KNOWN-state payload is covered too.
+ 'claude-sonnet-4-5': {
+ id: 'claude-sonnet-4-5',
+ modalities: { input: ['text', 'image'] },
+ },
+ })
+ // The stub's fetchedAt (acquisition) deliberately differs from capturedAt.
+ await syncDiscoveredModels(
+ {
+ materializer,
+ loadCatalog: loadStub(catalog, 'vendored', '2026-08-19T16:16:10.000Z'),
+ imageEvidenceTtlMs: 30 * 24 * 60 * 60 * 1000,
+ },
+ connector
+ )
+
+ const inserts = CALL_FOR(calls, /INSERT INTO llm_allowed_models/)
+ const byModel = new Map(inserts.map(c => [String(c.params[1]), c]))
+ const opus = byModel.get('claude-opus-4-5')!
+ const persisted = JSON.parse(String(opus.params[4]))
+ expect(persisted).toEqual({
+ state: 'unknown',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-08-19T16:16:10.000Z',
+ },
+ })
+ // Reloading a stale snapshot must not manufacture freshness.
+ expect(String(opus.params[4])).not.toContain('2026-07-13T00:00:00.000Z')
+ // An entry the catalog said nothing about stays unknown — and, being
+ // unknown, carries no expiry to state.
+ expect(persisted.evidence.validUntil).toBeUndefined()
+
+ // A KNOWN state must carry an expiry, and it is derived from the CAPTURE
+ // time: a vendored snapshot may only claim support for as long as it is
+ // fresh (capturedAt + 30d, NOT fetchedAt + 30d).
+ const sonnet = JSON.parse(String(byModel.get('claude-sonnet-4-5')!.params[4]))
+ expect(sonnet).toEqual({
+ state: 'supported',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-08-19T16:16:10.000Z',
+ validUntil: '2026-09-18T16:16:10.000Z',
+ },
+ })
+ })
+
+ it('throws when the shared contract rejects the discovery evidence it built', async () => {
+ const { connector, calls } = makeConnector({})
+ const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
+ // `checkedAt` must be a real date, so the shared parser refuses the payload
+ // this capture stamp produces. Storing NULL instead would hide a programming
+ // error behind a row that merely looks unexamined.
+ await expect(
+ syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog, 'live', 'not-a-timestamp') },
+ connector
+ )
+ ).rejects.toThrow(/discoveryImageInput: shared contract rejected/)
+
+ // Witness the run actually started (so the throw is the contract's, not a
+ // connector that never opened) and that nothing was written after it.
+ expect(CALL_FOR(calls, /^BEGIN$/)).toHaveLength(1)
+ expect(CALL_FOR(calls, /INSERT INTO llm_allowed_models/)).toHaveLength(0)
+ })
+
+ it('touches ONLY image_input on a colliding source=manual row, through the same guard', async () => {
const { connector, calls } = makeConnector({
claude: [{ id: 'm1', model: 'claude-opus-4-5', source: 'manual' }],
})
const catalog = catalogWith({
- 'claude-opus-4-5': { id: 'claude-opus-4-5', name: 'Opus' },
+ 'claude-opus-4-5': { id: 'claude-opus-4-5', name: 'Opus', modalities: { input: ['text'] } },
})
- const res = await syncDiscoveredModels({ loadCatalog: loadStub(catalog) }, connector)
+ const res = await syncDiscoveredModels(
+ {
+ materializer,
+ loadCatalog: loadStub(catalog, 'live', '2026-08-19T16:16:10.000Z'),
+ imageEvidenceTtlMs: 30 * 24 * 60 * 60 * 1000,
+ },
+ connector
+ )
- // No INSERT and no last_seen UPDATE for the manual-shadowed model.
+ // The row is still invisible to everything an operator authored.
expect(CALL_FOR(calls, /INSERT INTO llm_allowed_models/)).toHaveLength(0)
expect(CALL_FOR(calls, /SET last_seen_at/)).toHaveLength(0)
expect(res.added).toBe(0)
expect(res.updated).toBe(0)
+
+ // …except `image_input`, written by exactly one statement (#654). This is
+ // the liveness witness for the four negative assertions above: without it
+ // they would also hold for a sync that never reached this row at all.
+ const manual = CALL_FOR(calls, /t\.source = 'manual'/)
+ expect(manual).toHaveLength(1)
+ const sql = manual[0]!.sql
+ expect(sql).toMatch(/SET image_input = CASE/)
+ // Same guard as the discovery branch: NULL, or discovery evidence not newer.
+ expect(sql).toMatch(/WHEN t\.image_input IS NULL THEN \$2::jsonb/)
+ expect(sql).toMatch(
+ /\(t\.image_input->'evidence'->>'checkedAt'\)::timestamptz <= \$3::timestamptz/
+ )
+ expect(sql).toMatch(
+ /RETURNING t\.enabled, \(t\.image_input IS DISTINCT FROM prev\.image_input\)/
+ )
+ // Nothing else is ASSIGNED — asserted on the assignment TARGETS, not on a
+ // substring search. `source` and `enabled` legitimately appear elsewhere in
+ // this statement (the WHERE, the RETURNING, and the guard's
+ // `evidence->>'source'`), so a substring search could not tell "never
+ // written" from "mentioned" and would fail on a correct statement.
+ const setClause = sql.slice(sql.indexOf('SET '), sql.indexOf('FROM llm_allowed_models AS prev'))
+ const assigned = [...setClause.matchAll(/(?:SET|,)\s+([a-z_]+)\s*=/g)].map(m => m[1])
+ expect(assigned).toEqual(['image_input'])
+ expect(manual[0]!.params).toEqual([
+ 'm1',
+ JSON.stringify({
+ state: 'unsupported',
+ evidence: {
+ source: 'discovery',
+ reference: 'https://models.dev/api.json',
+ checkedAt: '2026-08-19T16:16:10.000Z',
+ validUntil: '2026-09-18T16:16:10.000Z',
+ },
+ }),
+ '2026-08-19T16:16:10.000Z',
+ ])
})
it('NULL-FILLs a present discovery row (COALESCE) and never overwrites enabled', async () => {
@@ -97,25 +294,128 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
const catalog = catalogWith({
'claude-opus-4-5': { id: 'claude-opus-4-5', name: 'Opus', limit: { context: 200000 } },
})
- const res = await syncDiscoveredModels({ loadCatalog: loadStub(catalog) }, connector)
+ const res = await syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog) },
+ connector
+ )
const updates = CALL_FOR(calls, /SET last_seen_at/)
expect(updates).toHaveLength(1)
const sql = updates[0].sql
- expect(sql).toMatch(/COALESCE\(context_window_tokens/)
- expect(sql).toMatch(/COALESCE\(display_name/)
+ expect(sql).toMatch(/COALESCE\(t\.context_window_tokens/)
+ expect(sql).toMatch(/COALESCE\(t\.display_name/)
expect(sql).toMatch(/stale = false/)
// The serialized columns are CASE-guarded to disabled rows only, so an
// ENABLED discovery row (already in the CM) is never mutated → no CM drift.
- expect(sql).toMatch(/CASE\s+WHEN enabled THEN context_window_tokens/)
- expect(sql).toMatch(/CASE\s+WHEN enabled THEN display_name/)
+ expect(sql).toMatch(/CASE\s+WHEN t\.enabled THEN t\.context_window_tokens/)
+ expect(sql).toMatch(/CASE\s+WHEN t\.enabled THEN t\.display_name/)
// `enabled` is never assigned in the SET clause.
expect(/enabled\s*=/.test(sql)).toBe(false)
- expect(updates[0].params).toEqual(['d1', 200000, 'Opus'])
+ expect(updates[0].params).toEqual([
+ 'd1',
+ 200000,
+ 'Opus',
+ discoveryProvenance('2026-07-10T00:00:00.000Z'),
+ '2026-07-10T00:00:00.000Z',
+ ])
expect(res.updated).toBe(1)
expect(res.added).toBe(0)
})
+ it('refreshes image_input on enabled rows only when NULL or older discovery evidence', async () => {
+ const { connector, calls } = makeConnector({
+ claude: [{ id: 'd1', model: 'claude-opus-4-5', source: 'discovery' }],
+ })
+ const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
+ await syncDiscoveredModels({ materializer, loadCatalog: loadStub(catalog) }, connector)
+
+ const sql = CALL_FOR(calls, /SET last_seen_at/)[0].sql
+ // A row with no evidence gets the provenance …
+ expect(sql).toMatch(/WHEN t\.image_input IS NULL THEN \$4::jsonb/)
+ // … a discovery-sourced one is refreshed only by a capture at least as
+ // recent as the one already recorded (compared as timestamptz, because
+ // `…Z` and `….000Z` are the same instant but different strings) …
+ expect(sql).toMatch(
+ /t\.image_input->'evidence'->>'source' = 'discovery'[\s\S]*\(t\.image_input->'evidence'->>'checkedAt'\)::timestamptz <= \$5::timestamptz/
+ )
+ // … and anything else (operator-curated, or a newer capture) is untouched.
+ expect(sql).toMatch(/ELSE t\.image_input/)
+ // The run reports whether it actually changed an ENABLED row's evidence —
+ // the only change that can make the served ConfigMap wrong.
+ expect(sql).toMatch(
+ /RETURNING t\.enabled, \(t\.image_input IS DISTINCT FROM prev\.image_input\)/
+ )
+ // image_input deliberately does NOT take the enabled-row freeze. Witness
+ // that the freeze exists in this very statement for the other columns, so
+ // its absence here is a choice and not a missing clause.
+ expect(sql).toMatch(/WHEN t\.enabled THEN t\.context_window_tokens/)
+ expect(/WHEN t\.enabled THEN t\.image_input/.test(sql)).toBe(false)
+ })
+
+ it('materializes the ConfigMap after COMMIT when an enabled row changed image_input', async () => {
+ const { connector, calls, query } = makeConnector(
+ { claude: [{ id: 'd1', model: 'claude-opus-4-5', source: 'discovery' }] },
+ { enabled: true, image_input_changed: true }
+ )
+ const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
+ const res = await syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog) },
+ connector
+ )
+
+ expect(materializer.materialize).toHaveBeenCalledTimes(1)
+ // AFTER commit, never inside the transaction: a ConfigMap write held open
+ // would keep the advisory lock for the length of a call to the cluster.
+ const commitCall = query.mock.calls.findIndex(c => /^COMMIT$/.test(String(c[0])))
+ expect(commitCall).toBeGreaterThanOrEqual(0)
+ expect(materializer.materialize.mock.invocationCallOrder[0]).toBeGreaterThan(
+ query.mock.invocationCallOrder[commitCall]
+ )
+ expect(res.enabledImageInputChanged).toBe(1)
+ expect(res.materialized).toBe(true)
+ expect(CALL_FOR(calls, /SET last_seen_at/)).toHaveLength(1)
+ })
+
+ it('does not materialize when only disabled rows changed', async () => {
+ const { connector, calls } = makeConnector(
+ { claude: [{ id: 'd1', model: 'claude-opus-4-5', source: 'discovery' }] },
+ { enabled: false, image_input_changed: true }
+ )
+ const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
+ const res = await syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog) },
+ connector
+ )
+
+ expect(materializer.materialize).not.toHaveBeenCalled()
+ // Witness: the write the assertion above denies publishing DID happen — a
+ // disabled row is not in the ConfigMap, so changing it publishes nothing.
+ expect(CALL_FOR(calls, /SET last_seen_at/)).toHaveLength(1)
+ expect(res.updated).toBe(1)
+ expect(res.enabledImageInputChanged).toBe(0)
+ expect(res.materialized).toBe(false)
+ })
+
+ it('reports and rethrows a ConfigMap write failure after the transaction committed', async () => {
+ const { connector, calls } = makeConnector(
+ { claude: [{ id: 'd1', model: 'claude-opus-4-5', source: 'discovery' }] },
+ { enabled: true, image_input_changed: true }
+ )
+ const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
+ const before = await configMapWriteFailures('sync')
+ materializer.materialize.mockRejectedValueOnce(new Error('apiserver unreachable'))
+
+ await expect(
+ syncDiscoveredModels({ materializer, loadCatalog: loadStub(catalog) }, connector)
+ ).rejects.toThrow('apiserver unreachable')
+
+ // The rows are durable: the failure happened after COMMIT, and nothing rolls
+ // back (that COMMIT is also the witness that the run reached the publish).
+ expect(CALL_FOR(calls, /^COMMIT$/)).toHaveLength(1)
+ expect(CALL_FOR(calls, /^ROLLBACK$/)).toHaveLength(0)
+ expect(await configMapWriteFailures('sync')).toBe(before + 1)
+ })
+
it('flags vanished discovery rows stale from a LIVE catalog (never delete, never disable)', async () => {
const { connector, calls } = makeConnector({
// A discovery row exists but the catalog no longer lists it.
@@ -126,7 +426,7 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
// plausibility floor. The tiny 1-model catalog would otherwise trip the
// global floor (default 100), so lower it here to exercise stale-marking.
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1 },
+ { materializer, loadCatalog: loadStub(catalog, 'live'), minPlausibleLiveTotal: 1 },
connector
)
@@ -150,7 +450,7 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
})
const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
const res = await syncDiscoveredModels(
- { loadCatalog: loadStub(catalog, 'vendored') },
+ { materializer, loadCatalog: loadStub(catalog, 'vendored') },
connector
)
@@ -164,7 +464,10 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
it('runs inside a transaction, takes the advisory lock, persists a run row, and returns the source', async () => {
const { connector, calls, release } = makeConnector({})
const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
- const res = await syncDiscoveredModels({ loadCatalog: loadStub(catalog, 'live') }, connector)
+ const res = await syncDiscoveredModels(
+ { materializer, loadCatalog: loadStub(catalog, 'live') },
+ connector
+ )
expect(CALL_FOR(calls, /^BEGIN$/)).toHaveLength(1)
expect(CALL_FOR(calls, /pg_advisory_xact_lock/)).toHaveLength(1)
@@ -191,7 +494,7 @@ describe('syncDiscoveredModels — source-guarded reconciliation', () => {
})
const catalog = catalogWith({ 'claude-opus-4-5': { id: 'claude-opus-4-5' } })
await expect(
- syncDiscoveredModels({ loadCatalog: loadStub(catalog) }, connector)
+ syncDiscoveredModels({ materializer, loadCatalog: loadStub(catalog) }, connector)
).rejects.toThrow('boom')
expect(query).toHaveBeenCalledWith('ROLLBACK')
expect(release).toHaveBeenCalledTimes(1)
diff --git a/control-api/test/services.llmCatalogSyncCron.test.ts b/control-api/test/services.llmCatalogSyncCron.test.ts
index 8d4169d9f..6a9f08a47 100644
--- a/control-api/test/services.llmCatalogSyncCron.test.ts
+++ b/control-api/test/services.llmCatalogSyncCron.test.ts
@@ -7,6 +7,8 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { CatalogSyncResult } from '../src/services/llmCatalogSync.js'
import {
+ LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS,
+ type LlmCatalogSyncCronDeps,
runLlmCatalogSyncTick,
startLlmCatalogSyncCron,
stopLlmCatalogSyncCron,
@@ -23,6 +25,8 @@ const OK: CatalogSyncResult = {
added: 0,
updated: 0,
staled: 0,
+ enabledImageInputChanged: 0,
+ materialized: false,
}
/**
@@ -186,41 +190,136 @@ describe('runLlmCatalogSyncTick', () => {
})
describe('startLlmCatalogSyncCron', () => {
- it('unref()s the interval so it never holds the process open', () => {
- const unref = vi.fn()
- const spy = vi
+ // Interval far above the first-run jitter, so advancing past the jitter can
+ // never also reach the first interval tick, whatever Math.random returns.
+ const INTERVAL_MS = 60_000
+
+ it('unref()s both the first-run timeout and the interval so neither holds the process open', () => {
+ const timeoutUnref = vi.fn()
+ const intervalUnref = vi.fn()
+ let firstRun: (() => void) | undefined
+ const timeoutSpy = vi.spyOn(global, 'setTimeout').mockImplementation(((fn: () => void) => {
+ firstRun = fn
+ return { unref: timeoutUnref } as unknown as ReturnType<typeof setTimeout>
+ }) as unknown as typeof setTimeout)
+ const intervalSpy = vi
.spyOn(global, 'setInterval')
- .mockReturnValue({ unref } as unknown as ReturnType<typeof setInterval>)
+ .mockReturnValue({ unref: intervalUnref } as unknown as ReturnType<typeof setInterval>)
startLlmCatalogSyncCron(
{ connector: makeLockPool({ held: false }, []), sync: async () => OK },
- 1000
+ INTERVAL_MS
)
- expect(unref).toHaveBeenCalledTimes(1)
- spy.mockRestore()
+ expect(timeoutSpy).toHaveBeenCalledTimes(1)
+ expect(timeoutUnref).toHaveBeenCalledTimes(1)
+ // The interval is armed by the first run, not by start().
+ expect(intervalSpy).not.toHaveBeenCalled()
+ expect(firstRun).toBeTypeOf('function')
+
+ firstRun?.()
+ expect(intervalSpy).toHaveBeenCalledTimes(1)
+ expect(intervalSpy.mock.calls[0]?.[1]).toBe(INTERVAL_MS)
+ expect(intervalUnref).toHaveBeenCalledTimes(1)
})
- it('fires the tick on the interval and stops firing after stop', async () => {
+ it('schedules the first run inside the jitter window, not one interval later', () => {
+ const timeoutSpy = vi.spyOn(global, 'setTimeout')
+ startLlmCatalogSyncCron(
+ { connector: makeLockPool({ held: false }, []), sync: async () => OK },
+ INTERVAL_MS
+ )
+ expect(timeoutSpy).toHaveBeenCalledTimes(1)
+ const delay = timeoutSpy.mock.calls[0]?.[1]
+ expect(delay).toBeGreaterThanOrEqual(0)
+ expect(delay).toBeLessThan(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS)
+ })
+
+ it('runs one tick shortly after start, then keeps ticking on the interval', async () => {
vi.useFakeTimers()
const calls: string[] = []
const connector = makeLockPool({ held: false }, calls)
const sync = vi.fn(async () => OK)
- startLlmCatalogSyncCron({ connector, sync }, 1000)
- await vi.advanceTimersByTimeAsync(1000)
+ startLlmCatalogSyncCron({ connector, sync }, INTERVAL_MS)
+ // start() does not run the tick synchronously — boot never waits on it.
+ expect(sync).not.toHaveBeenCalled()
+ expect(connector.connect).not.toHaveBeenCalled()
+
+ await vi.advanceTimersByTimeAsync(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS)
+ // One full lock-guarded tick, long before the first interval would elapse.
expect(sync).toHaveBeenCalledTimes(1)
+ expect(calls).toEqual(['acquire:ok', 'unlock', 'release'])
+
+ // Witness that the interval still runs after the first tick.
+ await vi.advanceTimersByTimeAsync(INTERVAL_MS)
+ expect(sync).toHaveBeenCalledTimes(2)
+ expect(calls).toEqual(['acquire:ok', 'unlock', 'release', 'acquire:ok', 'unlock', 'release'])
+ })
+
+ it('fires the first run and the interval, and stops firing after stop', async () => {
+ vi.useFakeTimers()
+ const calls: string[] = []
+ const connector = makeLockPool({ held: false }, calls)
+ const sync = vi.fn(async () => OK)
+
+ startLlmCatalogSyncCron({ connector, sync }, INTERVAL_MS)
+ await vi.advanceTimersByTimeAsync(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS + INTERVAL_MS)
+ expect(sync).toHaveBeenCalledTimes(2) // first run + one interval tick
+
+ stopLlmCatalogSyncCron()
+ await vi.advanceTimersByTimeAsync(5 * INTERVAL_MS)
+ expect(sync).toHaveBeenCalledTimes(2) // no further ticks after stop
+ })
+
+ it('stop before the first run cancels it; a later start still runs', async () => {
+ vi.useFakeTimers()
+ const connector = makeLockPool({ held: false }, [])
+ const sync = vi.fn(async () => OK)
+ startLlmCatalogSyncCron({ connector, sync }, INTERVAL_MS)
stopLlmCatalogSyncCron()
- await vi.advanceTimersByTimeAsync(5000)
- expect(sync).toHaveBeenCalledTimes(1) // no further ticks after stop
+ await vi.advanceTimersByTimeAsync(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS + 2 * INTERVAL_MS)
+ expect(sync).not.toHaveBeenCalled()
+ expect(connector.connect).not.toHaveBeenCalled()
+
+ // Witness: the same clock and deps DO tick once started again, so the zero
+ // above is the cancelled first run, not a timer that could never fire.
+ startLlmCatalogSyncCron({ connector, sync }, INTERVAL_MS)
+ await vi.advanceTimersByTimeAsync(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS)
+ expect(sync).toHaveBeenCalledTimes(1)
+ expect(connector.connect).toHaveBeenCalledTimes(1)
+ })
+
+ it('is idempotent — a second start creates no second first run and no second interval', async () => {
+ vi.useFakeTimers()
+ const timeoutSpy = vi.spyOn(global, 'setTimeout')
+ const intervalSpy = vi.spyOn(global, 'setInterval')
+ const sync = vi.fn(async () => OK)
+ const deps = { connector: makeLockPool({ held: false }, []), sync }
+
+ startLlmCatalogSyncCron(deps, INTERVAL_MS)
+ startLlmCatalogSyncCron(deps, INTERVAL_MS) // while the first run is pending
+ expect(timeoutSpy).toHaveBeenCalledTimes(1)
+
+ await vi.advanceTimersByTimeAsync(LLM_CATALOG_SYNC_FIRST_RUN_JITTER_MS)
+ expect(sync).toHaveBeenCalledTimes(1)
+ expect(intervalSpy).toHaveBeenCalledTimes(1)
+
+ startLlmCatalogSyncCron(deps, INTERVAL_MS) // after the interval is armed
+ await vi.advanceTimersByTimeAsync(INTERVAL_MS)
+ expect(timeoutSpy).toHaveBeenCalledTimes(1)
+ expect(intervalSpy).toHaveBeenCalledTimes(1)
+ expect(sync).toHaveBeenCalledTimes(2) // one first run + one interval tick
})
- it('is idempotent — a second start does not create a second interval', () => {
- const spy = vi.spyOn(global, 'setInterval')
- const deps = { connector: makeLockPool({ held: false }, []), sync: async () => OK }
- startLlmCatalogSyncCron(deps, 1000)
- startLlmCatalogSyncCron(deps, 1000)
- expect(spy).toHaveBeenCalledTimes(1)
+ it('requires an injected sync (compile-time)', () => {
+ // #654: the sync now needs a ConfigMap materializer and the cron has no
+ // gateway, so a default here could only be a call the sync would reject.
+ // The guarantee is the TYPE, not a runtime branch — hence no assertion on
+ // behaviour, only that omitting `sync` fails to compile.
+ // @ts-expect-error `sync` is required
+ const missingSync: LlmCatalogSyncCronDeps = { connector: makeLockPool({ held: false }, []) }
+ expect(missingSync.connector).toBeDefined()
})
})
diff --git a/control-api/test/services.modelsDevClient.test.ts b/control-api/test/services.modelsDevClient.test.ts
index 1bebe9f4b..3fdc0899c 100644
--- a/control-api/test/services.modelsDevClient.test.ts
+++ b/control-api/test/services.modelsDevClient.test.ts
@@ -1,9 +1,11 @@
import { describe, expect, it, vi } from 'vitest'
import { PROVIDER_IDS } from '@clerum/llm-providers'
+import { VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT } from '../src/data/modelsDevSnapshot.js'
import {
MODELS_DEV_API_URL,
PROVIDER_KEY_MAP,
type RawModelsDevCatalog,
+ imageInputStateFromModalities,
loadModelsDevCatalog,
mapCatalogToProviders,
} from '../src/services/modelsDevClient.js'
@@ -18,8 +20,13 @@ const FIXTURE: RawModelsDevCatalog = {
id: 'claude-opus-4-5',
name: 'Claude Opus 4.5',
limit: { context: 200000 },
+ modalities: { input: ['text', 'image'] },
+ },
+ 'claude-haiku-4-5': {
+ id: 'claude-haiku-4-5',
+ name: 'Claude Haiku 4.5',
+ modalities: { input: ['text'] },
},
- 'claude-haiku-4-5': { id: 'claude-haiku-4-5', name: 'Claude Haiku 4.5' },
},
},
google: {
@@ -69,11 +76,16 @@ describe('modelsDevClient — mapCatalogToProviders', () => {
const byProvider = mapCatalogToProviders(FIXTURE)
const claude = byProvider.claude
expect(claude).toEqual([
- { model_id: 'claude-haiku-4-5', display_name: 'Claude Haiku 4.5' },
+ {
+ model_id: 'claude-haiku-4-5',
+ display_name: 'Claude Haiku 4.5',
+ image_input_state: 'unsupported',
+ },
{
model_id: 'claude-opus-4-5',
display_name: 'Claude Opus 4.5',
context_window_tokens: 200000,
+ image_input_state: 'supported',
},
])
// vendor is never derived from models.dev (no reliable per-model field).
@@ -87,6 +99,8 @@ describe('modelsDevClient — mapCatalogToProviders', () => {
model_id: 'gemini-3.1-flash',
display_name: 'Gemini 3.1 Flash',
context_window_tokens: 1000000,
+ // No `modalities` in the fixture — the catalog said nothing, so neither do we.
+ image_input_state: 'unknown',
},
])
})
@@ -117,7 +131,7 @@ describe('modelsDevClient — mapCatalogToProviders', () => {
}
const claude = mapCatalogToProviders(catalog).claude
// Only the well-formed id survives; the three malformed ones are dropped.
- expect(claude).toEqual([{ model_id: 'good', display_name: 'ok' }])
+ expect(claude).toEqual([{ model_id: 'good', display_name: 'ok', image_input_state: 'unknown' }])
})
it('CLAMPs an over-long display_name to 400 chars (keeps the model)', () => {
@@ -136,7 +150,69 @@ describe('modelsDevClient — mapCatalogToProviders', () => {
const catalog: RawModelsDevCatalog = {
anthropic: { name: 'Anthropic', models: { [id400]: { id: id400 } } },
}
- expect(mapCatalogToProviders(catalog).claude).toEqual([{ model_id: id400 }])
+ expect(mapCatalogToProviders(catalog).claude).toEqual([
+ { model_id: id400, image_input_state: 'unknown' },
+ ])
+ })
+
+ it('carries image_input_state per discovered model', () => {
+ const catalog: RawModelsDevCatalog = {
+ anthropic: {
+ name: 'Anthropic',
+ models: {
+ 'sees-images': { id: 'sees-images', modalities: { input: ['text', 'image'] } },
+ 'text-only': { id: 'text-only', modalities: { input: ['text'] } },
+ 'no-modalities': { id: 'no-modalities' },
+ },
+ },
+ }
+ const claude = mapCatalogToProviders(catalog).claude
+ // Witness: all three entries survived the mapping, so the states below are
+ // read off real rows and not off an empty list.
+ expect(claude.map(m => m.model_id)).toEqual(['no-modalities', 'sees-images', 'text-only'])
+ expect(claude.map(m => m.image_input_state)).toEqual(['unknown', 'supported', 'unsupported'])
+ })
+})
+
+describe('modelsDevClient — imageInputStateFromModalities', () => {
+ it('returns supported when modalities.input includes "image"', () => {
+ expect(imageInputStateFromModalities({ modalities: { input: ['text', 'image'] } })).toBe(
+ 'supported'
+ )
+ expect(imageInputStateFromModalities({ modalities: { input: ['image'] } })).toBe('supported')
+ })
+
+ it('returns unsupported for a non-empty string array without "image"', () => {
+ expect(imageInputStateFromModalities({ modalities: { input: ['text'] } })).toBe('unsupported')
+ expect(imageInputStateFromModalities({ modalities: { input: ['text', 'audio'] } })).toBe(
+ 'unsupported'
+ )
+ // The token is matched exactly: models.dev writes it lowercase.
+ expect(imageInputStateFromModalities({ modalities: { input: ['text', 'Image'] } })).toBe(
+ 'unsupported'
+ )
+ })
+
+ it('returns unknown when modalities is absent', () => {
+ expect(imageInputStateFromModalities({})).toBe('unknown')
+ expect(imageInputStateFromModalities({ id: 'm-1', name: 'M1' })).toBe('unknown')
+ })
+
+ it('returns unknown when modalities.input is absent, not an array, or empty', () => {
+ expect(imageInputStateFromModalities({ modalities: {} })).toBe('unknown')
+ expect(imageInputStateFromModalities({ modalities: { input: 'image' } })).toBe('unknown')
+ expect(imageInputStateFromModalities({ modalities: { input: null } })).toBe('unknown')
+ expect(imageInputStateFromModalities({ modalities: { input: {} } })).toBe('unknown')
+ expect(imageInputStateFromModalities({ modalities: { input: [] } })).toBe('unknown')
+ })
+
+ it('returns unknown when any element is not a string', () => {
+ expect(imageInputStateFromModalities({ modalities: { input: ['text', 1] } })).toBe('unknown')
+ // Load-bearing: the array DOES contain 'image', and the answer is still
+ // unknown — a malformed list is not evidence of anything.
+ expect(imageInputStateFromModalities({ modalities: { input: ['image', null] } })).toBe(
+ 'unknown'
+ )
})
})
@@ -159,16 +235,37 @@ describe('modelsDevClient — loadModelsDevCatalog', () => {
expect.objectContaining({ redirect: 'error' })
)
expect(typeof res.fetchedAt).toBe('string')
+ // Live data IS the observation: acquisition and capture coincide.
+ expect(res.capturedAt).toBe(res.fetchedAt)
})
it('falls back to the vendored snapshot when the fetch throws (network error)', async () => {
const fetchImpl = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'))
- const res = await loadModelsDevCatalog({ fetchImpl: fetchImpl as unknown as typeof fetch })
+ const res = await loadModelsDevCatalog({
+ fetchImpl: fetchImpl as unknown as typeof fetch,
+ // A vendored fallback loaded today is NOT a fresh observation: the capture
+ // stamp stays the snapshot's baked date.
+ now: () => new Date('2026-09-16T12:00:00.000Z'),
+ })
expect(res.source).toBe('vendored')
+ expect(res.fetchedAt).toBe('2026-09-16T12:00:00.000Z')
+ expect(res.capturedAt).toBe(VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT)
+ expect(res.capturedAt).not.toBe(res.fetchedAt)
// The vendored snapshot must carry our mapped providers so the sync has data.
const byProvider = mapCatalogToProviders(res.catalog)
expect(byProvider.claude.length).toBeGreaterThan(0)
expect(byProvider.openai.length).toBeGreaterThan(0)
+ // #654: it must also carry `modalities.input`. The offline path is the one
+ // taken when there is NO network — exactly where an operator cannot go look
+ // the answer up — so a snapshot regenerated without modalities would report
+ // every model's image capability as `unknown` and make the feature inert
+ // precisely where it is least recoverable. Both verdicts are asserted: a
+ // snapshot that only ever answers `supported` would be just as wrong.
+ const states = Object.values(byProvider)
+ .flat()
+ .map(m => m.image_input_state)
+ expect(states.filter(s => s === 'supported').length).toBeGreaterThan(0)
+ expect(states.filter(s => s === 'unsupported').length).toBeGreaterThan(0)
})
it('falls back to vendored on a non-2xx response', async () => {
diff --git a/deploy/base/control-plane/configmaps.yaml b/deploy/base/control-plane/configmaps.yaml
index 1cebd5367..0824c9179 100644
--- a/deploy/base/control-plane/configmaps.yaml
+++ b/deploy/base/control-plane/configmaps.yaml
@@ -96,7 +96,9 @@ data:
CONTROL_API_ALLOWED_IMAGE_PREFIXES: "ghcr.io/evenfire-ai/,mongodb/,mcr.microsoft.com/,clerum/"
CONTROL_API_ENFORCE_IMAGE_ALLOWLIST: "false"
# LLM catalog discovery sync cron (spec 09 Fase 4). Non-destructive; code
- # default off. Interval + plausibility floors keep their code defaults.
+ # default off. Enabled here: the first sync runs a few seconds after
+ # control-api starts (fills image_input evidence), then every interval.
+ # Interval + plausibility floors keep their code defaults.
LLM_CATALOG_SYNC_CRON_ENABLED: "true"
---
apiVersion: v1
diff --git a/deploy/images.json b/deploy/images.json
index 390247fd0..d94202a8c 100644
--- a/deploy/images.json
+++ b/deploy/images.json
@@ -323,6 +323,13 @@
"published": true,
"deployed_to_minikube": true
},
+ {
+ "name": "image-capabilities-mcp-host",
+ "path": "tests/e2e/fixtures/image-capabilities",
+ "rooted": true,
+ "published": false,
+ "deployed_to_minikube": false
+ },
{
"name": "codex-approved-tools-control-api-e2e",
"path": "tests/e2e/fixtures/codex-subscription/approved-tools-oauth",
diff --git a/desktop-app/src/__tests__/appService.hostModels.test.ts b/desktop-app/src/__tests__/appService.hostModels.test.ts
index 9451496fa..6722e724b 100644
--- a/desktop-app/src/__tests__/appService.hostModels.test.ts
+++ b/desktop-app/src/__tests__/appService.hostModels.test.ts
@@ -115,31 +115,41 @@ describe('AppService.getHostModels', () => {
})
describe('AppService.setHostModel', () => {
- it('issues a host:model:write token and forwards the selection', async () => {
- const { service, issueRpcTokenForHostRefs, rpcClient } = modelService()
- rpcClient.setHostModel.mockResolvedValue({
- effective: 'next-task',
- provider: 'claude',
- model: 'claude-haiku-4-5',
- })
-
- const result = await service.setHostModel('chatllm', 'chat-1', 'claude-haiku-4-5')
-
- expect(result.effective).toBe('next-task')
- // The write path is gated by the dedicated write scope (§8.2) and (issue
- // #791) additionally requests host:wake:write so a model swap can wake a
- // suspended stateless Host.
- expect(issueRpcTokenForHostRefs).toHaveBeenCalledWith(
- ['host:model:write', 'host:wake:write'],
- ['chatllm']
- )
- expect(rpcClient.setHostModel).toHaveBeenCalledWith(
- 'rpc-token',
- 'chatllm',
- 'chat-1',
- 'claude-haiku-4-5'
- )
- })
+ it.each([undefined, 7])(
+ 'forwards the selection and its optional revision %s under the existing scope',
+ async revision => {
+ const { service, issueRpcTokenForHostRefs, rpcClient } = modelService()
+ rpcClient.setHostModel.mockResolvedValue({
+ effective: 'next-task',
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ })
+
+ const result = await service.setHostModel(
+ 'chatllm',
+ 'chat-1',
+ 'claude-haiku-4-5',
+ undefined,
+ revision
+ )
+
+ expect(result.effective).toBe('next-task')
+ // The write path is gated by the dedicated write scope (§8.2) and (issue
+ // #791) additionally requests host:wake:write so a model swap can wake a
+ // suspended stateless Host.
+ expect(issueRpcTokenForHostRefs).toHaveBeenCalledWith(
+ ['host:model:write', 'host:wake:write'],
+ ['chatllm']
+ )
+ expect(rpcClient.setHostModel).toHaveBeenCalledWith(
+ 'rpc-token',
+ 'chatllm',
+ 'chat-1',
+ 'claude-haiku-4-5',
+ revision
+ )
+ }
+ )
it('propagates a model_not_allowed rejection unchanged (no swallow)', async () => {
const { service, rpcClient } = modelService()
diff --git a/desktop-app/src/__tests__/appService.rpc.test.ts b/desktop-app/src/__tests__/appService.rpc.test.ts
index 56d4fed1c..4ce47ec1b 100644
--- a/desktop-app/src/__tests__/appService.rpc.test.ts
+++ b/desktop-app/src/__tests__/appService.rpc.test.ts
@@ -44,6 +44,9 @@ describe('AppService.invokeHostMessage', () => {
{
content: 'What workflow recipes can I trigger and what inputs do they require?',
channelType: 'slack',
+ model: 'vision-model',
+ modelSelectionRevision: 7,
+ imageModel: { provider: 'untrusted', model: 'untrusted' },
channelId: 'attacker-channel',
hostRef: 'attacker-host',
sender: 'attacker-controlled-user',
@@ -64,6 +67,8 @@ describe('AppService.invokeHostMessage', () => {
expect(forwarded).toEqual({
content: 'What workflow recipes can I trigger and what inputs do they require?',
channelType: 'rpc',
+ model: 'vision-model',
+ modelSelectionRevision: 7,
channelId: 'chatllm',
hostRef: 'chatllm',
sender: '00000000-0000-4000-8000-000000000001',
@@ -74,6 +79,42 @@ describe('AppService.invokeHostMessage', () => {
expect(service.rpcClient.invokeHostMessage.mock.calls[0][3]).toEqual({ async: true })
})
+ it('rejects malformed attachments before issuing an RPC token', async () => {
+ const service = new AppService() as any
+ service.sessionToken = 'test-token-session'
+ service.me = {
+ id: '00000000-0000-4000-8000-000000000001',
+ email: '[email protected]',
+ name: 'Test User',
+ picture: null,
+ teamId: '00000000-0000-4000-8000-0000000000aa',
+ teamName: 'Test Team',
+ role: 'member',
+ }
+ service.rpcTokenManager = {
+ getOrIssue: vi.fn().mockResolvedValue({ token: 'test-token-rpc' }),
+ clear: vi.fn(),
+ }
+ service.rpcClient = {
+ invokeHostMessage: vi.fn().mockResolvedValue({ success: true, response: 'ok' }),
+ }
+ const issueToken = vi.spyOn(service, 'issueRpcTokenForHostRefs')
+
+ await expect(
+ service.invokeHostMessage('chatllm', { content: 'hello', attachments: {} }, ['chatllm'])
+ ).rejects.toThrow('Image attachments must be a list.')
+ expect(issueToken).not.toHaveBeenCalled()
+ expect(service.rpcTokenManager.getOrIssue).not.toHaveBeenCalled()
+ expect(service.rpcClient.invokeHostMessage).not.toHaveBeenCalled()
+
+ // Positive control: the same call with a well-formed list issues the token
+ // and reaches the Host, so the checks above are not vacuous.
+ await service.invokeHostMessage('chatllm', { content: 'hello', attachments: [] }, ['chatllm'])
+ expect(issueToken).toHaveBeenCalledTimes(1)
+ expect(service.rpcTokenManager.getOrIssue).toHaveBeenCalled()
+ expect(service.rpcClient.invokeHostMessage).toHaveBeenCalledTimes(1)
+ })
+
it('switches to a matching directory team before issuing RPC tokens for teamless sessions', async () => {
const service = new AppService() as any
service.desktopGfsUploadStatePath = vi
diff --git a/desktop-app/src/__tests__/devIsolation.test.ts b/desktop-app/src/__tests__/devIsolation.test.ts
new file mode 100644
index 000000000..25500d548
--- /dev/null
+++ b/desktop-app/src/__tests__/devIsolation.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import {
+ admitIsolationBaseDir,
+ devIsolationRuntimePolicy,
+ publicDevIsolationRecord,
+ resolveDevIsolation,
+ verifyDevIsolationRuntime,
+} from '../devIsolation'
+
+const env = {
+ EVENFIRE_DEV_ISOLATION: '1',
+ EVENFIRE_DEV_ISOLATION_RUN_DIR: '/tmp/isolated-run',
+ EVENFIRE_DEV_ISOLATION_TARGET: 'minikube-30488',
+ EVENFIRE_DEV_ISOLATION_PR: '660',
+ EVENFIRE_DEV_ISOLATION_REST_URL: 'http://127.0.0.1:30579',
+ EVENFIRE_DEV_ISOLATION_RPC_URL: 'http://127.0.0.1:30582',
+ EVENFIRE_DEV_ISOLATION_APP_PATH: '/repo/desktop-app/dist',
+ EXTERNAL_REST_API_BASE_URL: 'http://127.0.0.1:30579',
+ RPC_PROXY_BASE_URL: 'http://127.0.0.1:30582',
+ CLERUM_DESKTOP_CONFIG_PATH: '/tmp/isolated-run/runtime-config.json',
+}
+const argv = [
+ 'electron',
+ '--user-data-dir=/tmp/isolated-run/user-data',
+ '/repo/desktop-app/dist/main.js',
+]
+
+describe('explicit development instance isolation', () => {
+ it('leaves normal packaged and development launches unchanged', () => {
+ expect(resolveDevIsolation({}, [], false)).toEqual({ mode: 'normal' })
+ expect(resolveDevIsolation({}, [], true)).toEqual({ mode: 'normal' })
+ expect(devIsolationRuntimePolicy(null)).toMatchObject({
+ registerOsProtocols: true,
+ acceptDeepLinks: true,
+ pinWindowTitle: false,
+ })
+ })
+ it('refuses an opt-in in a packaged application', () => {
+ expect(resolveDevIsolation(env, argv, true)).toMatchObject({
+ mode: 'refused',
+ code: 'DEV_ISOLATION_PACKAGED',
+ })
+ })
+ it('requires the explicit directory before single-instance/protocol setup', () => {
+ expect(resolveDevIsolation(env, [])).toMatchObject({ mode: 'refused' })
+ expect(resolveDevIsolation(env, ['--user-data-dir=/tmp/another-run'])).toMatchObject({
+ mode: 'refused',
+ })
+ })
+ it.each(['CLERUM_DESKTOP_CONFIG_PATH', 'EXTERNAL_REST_API_BASE_URL', 'RPC_PROXY_BASE_URL'])(
+ 'refuses missing or divergent %s',
+ key => {
+ expect(resolveDevIsolation({ ...env, [key]: '' }, argv)).toMatchObject({ mode: 'refused' })
+ expect(resolveDevIsolation({ ...env, [key]: 'http://127.0.0.1:33333' }, argv)).toMatchObject({
+ mode: 'refused',
+ })
+ }
+ )
+ it.each([
+ 'https://example.com:443',
+ 'http://user:[email protected]:30579',
+ 'http://127.0.0.1:30579/?private=value',
+ ])('refuses unsafe endpoint %s', value => {
+ expect(
+ resolveDevIsolation(
+ { ...env, EVENFIRE_DEV_ISOLATION_REST_URL: value, EXTERNAL_REST_API_BASE_URL: value },
+ argv
+ )
+ ).toMatchObject({ mode: 'refused' })
+ })
+ it('isolates OS routing and verifies effective identity before exposing metadata', () => {
+ const result = resolveDevIsolation(env, argv)
+ expect(result.mode).toBe('isolated')
+ if (result.mode !== 'isolated') throw new Error('expected isolated plan')
+ const { plan } = result
+ expect(devIsolationRuntimePolicy(plan)).toMatchObject({
+ registerOsProtocols: false,
+ acceptDeepLinks: false,
+ pinWindowTitle: true,
+ })
+ expect(plan.label).toContain('PR660')
+ const observed = {
+ pid: 123,
+ userDataDir: plan.userDataDir,
+ appPath: plan.appPath!,
+ restUrl: plan.restUrl,
+ rpcUrl: plan.rpcUrl,
+ configStoragePath: plan.configPath,
+ envKey: 'fixture-environment',
+ }
+ expect(verifyDevIsolationRuntime(plan, observed)).toEqual({ ok: true })
+ expect(publicDevIsolationRecord(plan, observed).pid).toBe(123)
+ for (const key of ['userDataDir', 'appPath', 'restUrl', 'rpcUrl', 'configStoragePath']) {
+ const wrong = { ...observed, [key]: 'foreign-value' }
+ expect(verifyDevIsolationRuntime(plan, wrong).ok).toBe(false)
+ expect(() => publicDevIsolationRecord(plan, wrong)).toThrow('before runtime verification')
+ }
+ })
+ it('rejects application data inside the checkout', () => {
+ expect(
+ admitIsolationBaseDir({
+ requested: '/repo/private-run',
+ repoRoot: '/repo',
+ platform: 'darwin',
+ homedir: '/home/user',
+ env: {},
+ })
+ ).toMatchObject({ ok: false })
+ })
+})
diff --git a/desktop-app/src/__tests__/imageInputDecision.test.ts b/desktop-app/src/__tests__/imageInputDecision.test.ts
new file mode 100644
index 000000000..5f35ca675
--- /dev/null
+++ b/desktop-app/src/__tests__/imageInputDecision.test.ts
@@ -0,0 +1,303 @@
+import { describe, expect, it } from 'vitest'
+import fc from 'fast-check'
+import {
+ IMAGE_INPUT_LOCAL_REASON,
+ type ImageInputDecision,
+ canSendImagesWith,
+ imageInputBlockMessage,
+ normalizeImageInputDecision,
+ resolveImageInputDecision,
+ resolveModelImageInput,
+} from '../imageInputDecision'
+
+// The Host-side producer of the decisions this module validates. Loaded by
+// relative path from the test only, so the fixtures are the producer's real
+// output rather than hand-written copies of it.
+const producer = require('../../../packages/llm-providers/imageInput.cjs') as {
+ resolveImageInputCapability: (
+ value: unknown,
+ options: { now?: number; transportSupported?: boolean }
+ ) => ImageInputDecision
+}
+
+describe('imageInputDecision — wire normalization', () => {
+ it('treats a missing decision as unknown (legacy host, absent metadata)', () => {
+ expect(normalizeImageInputDecision(undefined)).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ expect(normalizeImageInputDecision(null)).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ })
+
+ it('normalizes malformed payloads to unknown instead of unsupported', () => {
+ expect(normalizeImageInputDecision('supported')).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ expect(normalizeImageInputDecision({ state: 'maybe' })).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ expect(normalizeImageInputDecision({ state: 'supported', validUntil: 'not-a-date' })).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ })
+
+ it('preserves the host reason and state verbatim', () => {
+ expect(
+ normalizeImageInputDecision({ state: 'unsupported', reason: 'provider_text_only' })
+ ).toEqual({ state: 'unsupported', reason: 'provider_text_only' })
+ expect(normalizeImageInputDecision({ state: 'supported', reason: 'curated_2026_09' })).toEqual({
+ state: 'supported',
+ reason: 'curated_2026_09',
+ })
+ })
+})
+
+describe('imageInputDecision — freshness', () => {
+ const now = Date.parse('2026-09-16T10:00:00.000Z')
+
+ it('keeps a supported decision whose evidence is still valid', () => {
+ const decision = resolveImageInputDecision(
+ { state: 'supported', reason: 'curated', validUntil: '2026-09-17T00:00:00.000Z' },
+ now
+ )
+ expect(decision.state).toBe('supported')
+ expect(canSendImagesWith(decision)).toBe(true)
+ })
+
+ it('downgrades expired evidence to unknown at read time (no catalog change needed)', () => {
+ const decision = resolveImageInputDecision(
+ { state: 'supported', reason: 'curated', validUntil: '2026-09-15T00:00:00.000Z' },
+ now
+ )
+ expect(decision).toEqual({
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.evidenceExpired,
+ validUntil: '2026-09-15T00:00:00.000Z',
+ })
+ expect(canSendImagesWith(decision)).toBe(false)
+ })
+
+ it('treats an expired denial as stale evidence (unknown, not a lasting denial)', () => {
+ const decision = resolveImageInputDecision(
+ { state: 'unsupported', reason: 'text_only', validUntil: '2026-09-01T00:00:00.000Z' },
+ now
+ )
+ expect(decision).toEqual({
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.evidenceExpired,
+ validUntil: '2026-09-01T00:00:00.000Z',
+ })
+ expect(canSendImagesWith(decision)).toBe(false)
+ })
+})
+
+describe('imageInputDecision — effective model resolution', () => {
+ const models = [
+ { name: 'glm-5.3', imageInput: { state: 'unsupported', reason: 'text_only' } },
+ { name: 'glm-5.3-flash', imageInput: { state: 'supported', reason: 'curated' } },
+ { name: 'legacy-model' },
+ ]
+
+ it('resolves the capability of the model that will be requested', () => {
+ expect(resolveModelImageInput(models, 'glm-5.3-flash').state).toBe('supported')
+ expect(resolveModelImageInput(models, 'glm-5.3').state).toBe('unsupported')
+ expect(resolveModelImageInput(models, 'legacy-model')).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ })
+
+ it('never falls back to another model or provider', () => {
+ expect(resolveModelImageInput(models, 'not-in-catalog')).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ expect(resolveModelImageInput(models, '')).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ expect(resolveModelImageInput(null, 'glm-5.3-flash')).toEqual({
+ state: 'unknown',
+ reason: 'model_unknown',
+ })
+ })
+})
+
+describe('imageInputDecision — user copy', () => {
+ it.each([
+ ['model_unsupported', 'unsupported', /not supported by model "glm-5\.3"/],
+ ['model_unknown', 'unknown', /not verified for model "glm-5\.3"/],
+ ['evidence_expired', 'unknown', /evidence for model "glm-5\.3" has expired/],
+ ['evidence_not_yet_valid', 'unknown', /dated in the future/],
+ ['transport_unsupported', 'unsupported', /provider transport/],
+ ] as const)('explains the %s reason with its own message', (reason, state, expected) => {
+ expect(imageInputBlockMessage('glm-5.3', { state, reason })).toMatch(expected)
+ })
+
+ it('treats a reason it does not know as unverified', () => {
+ expect(
+ imageInputBlockMessage('glm-5.3', { state: 'unsupported', reason: 'text_only' })
+ ).toMatch(/not verified for model "glm-5\.3"/)
+ })
+
+ it('returns no message when images are allowed', () => {
+ expect(imageInputBlockMessage('glm-5.3-flash', { state: 'supported', reason: 'curated' })).toBe(
+ null
+ )
+ })
+})
+
+const PRODUCER_T0 = Date.parse('2026-09-01T00:00:00.000Z')
+const isoAt = (ms: number) => new Date(ms).toISOString()
+
+/** A decision exactly as the Host producer emits it for curated evidence. */
+function producedDecision(state: 'supported' | 'unsupported'): ImageInputDecision {
+ return producer.resolveImageInputCapability(
+ {
+ state,
+ evidence: {
+ source: 'curated',
+ reference: 'evidence:glm-5.3-flash',
+ checkedAt: isoAt(PRODUCER_T0),
+ validUntil: isoAt(PRODUCER_T0 + 60_000),
+ },
+ },
+ { now: PRODUCER_T0 + 1_000, transportSupported: true }
+ )
+}
+
+describe('imageInputDecision — evidence produced by the Host', () => {
+ const now = PRODUCER_T0 + 1_000
+
+ it.each([
+ ['supported', 'supported'],
+ ['unsupported', 'model_unsupported'],
+ ] as const)('round-trips valid %s evidence unchanged', (state, reason) => {
+ const produced = producedDecision(state)
+ // Witness: the fixture really carries evidence and the shared bound.
+ expect(produced).toMatchObject({ state, reason, validUntil: isoAt(PRODUCER_T0 + 60_000) })
+ expect(produced.evidence?.validUntil).toBe(produced.validUntil)
+
+ expect(normalizeImageInputDecision(produced)).toEqual(produced)
+ expect(resolveImageInputDecision(produced, now)).toEqual(produced)
+ })
+
+ it('rejects evidence whose validUntil differs from the decision bound', () => {
+ const produced = producedDecision('supported')
+ expect(resolveImageInputDecision(produced, now).state).toBe('supported')
+
+ const mismatched = {
+ ...produced,
+ evidence: { ...produced.evidence, validUntil: isoAt(PRODUCER_T0 + 999_999) },
+ }
+ expect(normalizeImageInputDecision(mismatched)).toEqual({
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.modelUnknown,
+ })
+ })
+
+ it('rejects expiring evidence when the top-level validUntil is missing', () => {
+ const { validUntil, ...withoutBound } = producedDecision('supported')
+ // Witness: the bound existed and only the top-level copy was dropped.
+ expect(validUntil).toBe(isoAt(PRODUCER_T0 + 60_000))
+ expect(withoutBound.evidence?.validUntil).toBe(validUntil)
+
+ expect(normalizeImageInputDecision(withoutBound)).toEqual({
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.modelUnknown,
+ })
+ })
+
+ it.each([
+ ['checkedAt', { checkedAt: 'not-a-date' }],
+ ['source', { source: 'manual' }],
+ ] as const)('rejects evidence with an invalid %s', (_field, patch) => {
+ const produced = producedDecision('supported')
+ expect(normalizeImageInputDecision(produced).state).toBe('supported')
+
+ const invalid = { ...produced, evidence: { ...produced.evidence, ...patch } }
+ expect(normalizeImageInputDecision(invalid)).toEqual({
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.modelUnknown,
+ })
+ })
+})
+
+describe('imageInputDecision — parity with the Host producer', () => {
+ it('never authorizes what the producer would not, emits only producer reasons, and is idempotent', () => {
+ const producerReasons = new Set<string>()
+ const desktopReasons = new Set<string>()
+ const seen = { supported: 0, expired: 0 }
+
+ fc.assert(
+ fc.property(
+ fc.constantFrom('supported', 'unsupported', 'unknown'),
+ fc.constantFrom('curated', 'discovery'),
+ fc.constantFrom('evidence:glm-5.3', 'evidence:catalog/glm-5.3-flash'),
+ fc.integer({ min: 1, max: 10_000 }),
+ fc.option(fc.integer({ min: 1, max: 10_000 }), { nil: undefined }),
+ fc.integer({ min: 0, max: 20_000 }),
+ fc.integer({ min: 0, max: 20_000 }),
+ fc.boolean(),
+ (
+ state,
+ source,
+ reference,
+ checkedOffset,
+ validOffset,
+ hostOffset,
+ desktopDelay,
+ transportSupported
+ ) => {
+ const checkedAt = PRODUCER_T0 + checkedOffset
+ const capability = {
+ state,
+ evidence: {
+ source,
+ reference,
+ checkedAt: isoAt(checkedAt),
+ ...(validOffset === undefined ? {} : { validUntil: isoAt(checkedAt + validOffset) }),
+ },
+ }
+ const hostNow = PRODUCER_T0 + hostOffset
+ // The desktop evaluates the Host's decision at or after the Host made it.
+ const desktopNow = hostNow + desktopDelay
+
+ const hostDecision = producer.resolveImageInputCapability(capability, {
+ now: hostNow,
+ transportSupported,
+ })
+ const desktopView = resolveImageInputDecision(hostDecision, desktopNow)
+ const producerAtDesktopClock = producer.resolveImageInputCapability(capability, {
+ now: desktopNow,
+ transportSupported,
+ })
+
+ producerReasons.add(hostDecision.reason)
+ producerReasons.add(producerAtDesktopClock.reason)
+ desktopReasons.add(desktopView.reason)
+
+ if (desktopView.state === 'supported') {
+ seen.supported += 1
+ expect(producerAtDesktopClock.state).toBe('supported')
+ }
+ if (desktopView.reason === IMAGE_INPUT_LOCAL_REASON.evidenceExpired) seen.expired += 1
+ expect(resolveImageInputDecision(desktopView, desktopNow)).toEqual(desktopView)
+ }
+ ),
+ { numRuns: 3000 }
+ )
+
+ // Witnesses: both the authorizing and the expiring branches were exercised.
+ expect(seen.supported).toBeGreaterThan(0)
+ expect(seen.expired).toBeGreaterThan(0)
+ expect(desktopReasons.size).toBeGreaterThan(1)
+ for (const reason of desktopReasons) expect(producerReasons).toContain(reason)
+ })
+})
diff --git a/desktop-app/src/__tests__/ipc.hostModelSelection.test.ts b/desktop-app/src/__tests__/ipc.hostModelSelection.test.ts
new file mode 100644
index 000000000..2931dbcb6
--- /dev/null
+++ b/desktop-app/src/__tests__/ipc.hostModelSelection.test.ts
@@ -0,0 +1,117 @@
+/**
+ * Issue #654 L1/L2 — the IPC boundary refuses an invalid model-selection
+ * revision instead of dropping it. Dropping it would turn a conditional
+ * (compare-and-set) write into an unconditional one.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import type { AppService } from '../appService.js'
+
+type Handler = (event: unknown, payload: unknown) => Promise<unknown>
+
+const electron = vi.hoisted(() => ({ handlers: new Map<string, Handler>() }))
+
+vi.mock('electron', () => ({
+ BrowserWindow: { fromWebContents: vi.fn(), getAllWindows: vi.fn(() => []) },
+ Notification: vi.fn(),
+ app: { on: vi.fn(), getPath: vi.fn(), getVersion: vi.fn() },
+ clipboard: { writeText: vi.fn() },
+ dialog: { showSaveDialog: vi.fn() },
+ ipcMain: {
+ handle: vi.fn((channel: string, handler: Handler) => {
+ electron.handlers.set(channel, handler)
+ }),
+ on: vi.fn(),
+ removeHandler: vi.fn(),
+ },
+}))
+// ipc.ts only uses AppService as a type at registration; the real module would
+// pull in the whole main-process graph.
+vi.mock('../appService.js', () => ({ AppService: class {} }))
+
+const service = {
+ setHostModel: vi.fn(async () => ({ effective: 'next-task' })),
+ invokeHostMessage: vi.fn(async () => ({ taskId: 'task-1' })),
+}
+const trusted = { senderFrame: { url: 'file:///app/index.html' } }
+
+function handler(channel: string): Handler {
+ const registered = electron.handlers.get(channel)
+ if (!registered) throw new Error(`no IPC handler registered for ${channel}`)
+ return registered
+}
+
+beforeAll(async () => {
+ const { registerIpcHandlers } = await import('../ipc.js')
+ registerIpcHandlers(service as unknown as AppService)
+})
+
+afterEach(() => {
+ service.setHostModel.mockClear()
+ service.invokeHostMessage.mockClear()
+})
+
+describe('rpc:setHostModel expectedRevision', () => {
+ const base = { hostRef: 'agent-x', chatId: 'chat-1', model: 'glm-5.3-flash' }
+
+ it('forwards a valid revision as the CAS base', async () => {
+ await handler('rpc:setHostModel')(trusted, { ...base, expectedRevision: 4 })
+ expect(service.setHostModel).toHaveBeenCalledWith(
+ 'agent-x',
+ 'chat-1',
+ 'glm-5.3-flash',
+ undefined,
+ 4
+ )
+ })
+
+ it('forwards an absent revision as absent (hosts without CAS)', async () => {
+ await handler('rpc:setHostModel')(trusted, base)
+ expect(service.setHostModel).toHaveBeenCalledWith(
+ 'agent-x',
+ 'chat-1',
+ 'glm-5.3-flash',
+ undefined,
+ undefined
+ )
+ })
+
+ it.each([1.5, -1, Number.NaN, '3', null])(
+ 'rejects %s instead of dropping the CAS base',
+ async expectedRevision => {
+ await expect(
+ handler('rpc:setHostModel')(trusted, { ...base, expectedRevision })
+ ).rejects.toThrow('expectedRevision must be a non-negative integer')
+ expect(service.setHostModel).toHaveBeenCalledTimes(0)
+ }
+ )
+})
+
+describe('rpc:invokeHostMessage model fields', () => {
+ const send = (payload: Record<string, unknown>) =>
+ handler('rpc:invokeHostMessage')(trusted, {
+ hostRef: 'agent-x',
+ payload: { content: 'hi', ...payload },
+ })
+
+ it('forwards a valid model and revision', async () => {
+ await send({ model: 'glm-5.3-flash', modelSelectionRevision: 3 })
+ expect(service.invokeHostMessage).toHaveBeenCalledWith(
+ 'agent-x',
+ expect.objectContaining({ model: 'glm-5.3-flash', modelSelectionRevision: 3 }),
+ undefined,
+ undefined
+ )
+ })
+
+ it.each([
+ [{ modelSelectionRevision: '3' }, 'modelSelectionRevision'],
+ [{ modelSelectionRevision: -1 }, 'modelSelectionRevision'],
+ [{ modelSelectionRevision: 2.5 }, 'modelSelectionRevision'],
+ [{ model: '' }, 'model'],
+ [{ model: ' ' }, 'model'],
+ [{ model: 7 }, 'model'],
+ ])('rejects %o', async (fields, field) => {
+ await expect(send(fields)).rejects.toThrow(`Invalid host message request: ${field}`)
+ expect(service.invokeHostMessage).toHaveBeenCalledTimes(0)
+ })
+})
diff --git a/desktop-app/src/appService.ts b/desktop-app/src/appService.ts
index 86865d45a..59745276f 100644
--- a/desktop-app/src/appService.ts
+++ b/desktop-app/src/appService.ts
@@ -3322,6 +3322,10 @@ export class AppService {
if (!targetHostRef) {
throw new Error('hostRef is required')
}
+ // A malformed request is rejected before any token is issued for it.
+ if (request.attachments != null && !Array.isArray(request.attachments)) {
+ throw new Error('Image attachments must be a list.')
+ }
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
@@ -3350,6 +3354,9 @@ export class AppService {
// as its own allow-list (routes/rpc.ts `forwardedBody`), so `model` must be
// forwarded there too — it does not pass the body through unchanged.
...(typeof request.model === 'string' && request.model ? { model: request.model } : {}),
+ ...(request.modelSelectionRevision === undefined
+ ? {}
+ : { modelSelectionRevision: request.modelSelectionRevision }),
}
try {
return await this.rpcClient.invokeHostMessage(
@@ -4398,7 +4405,8 @@ export class AppService {
hostRef: string,
chatId: string,
model: string,
- hostRefs?: string[]
+ hostRefs?: string[],
+ expectedRevision?: number
): Promise<SetHostModelResult> {
const targetHostRef = String(hostRef || '').trim()
const targetModel = String(model || '').trim()
@@ -4407,7 +4415,13 @@ export class AppService {
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_MODEL_SCOPES, effectiveHostRefs)
- return this.rpcClient.setHostModel(rpc.token, targetHostRef, chatId, targetModel)
+ return this.rpcClient.setHostModel(
+ rpc.token,
+ targetHostRef,
+ chatId,
+ targetModel,
+ expectedRevision
+ )
}
/**
diff --git a/desktop-app/src/devIsolation.ts b/desktop-app/src/devIsolation.ts
new file mode 100644
index 000000000..75f0b8b3a
--- /dev/null
+++ b/desktop-app/src/devIsolation.ts
@@ -0,0 +1,604 @@
+/**
+ * Desktop dev-isolation contract.
+ *
+ * Several checkouts must be able to run the desktop app side by side on one
+ * machine. Without this module they cannot, because three pieces of state are
+ * machine-wide:
+ *
+ * - the OS protocol handler. `registerCustomProtocols()` makes the *running*
+ * bundle the default handler for `evenfire:`/`clerum:`, so whoever launches
+ * last steals the deep links of everyone else — and a computer-use agent
+ * that resolves the app by name lands on an arbitrary instance.
+ * - the application name (`Evenfire`), which is exactly what a computer-use
+ * agent has to disambiguate between.
+ * - the user-data directory, which holds the Chromium profile, the stored
+ * runtime-config profiles and the session material.
+ *
+ * This module is the pure contract for the explicit, opt-in isolation mode that
+ * removes that sharing. It owns:
+ *
+ * - the opt-in itself (`--evenfire-dev-isolation` or
+ * `EVENFIRE_DEV_ISOLATION=1`), so that a normal launch can never drift into
+ * isolated behaviour and an isolated launch can never silently fall back to
+ * the shared profile;
+ * - validation of what the launcher declared: an absolute per-run directory, a
+ * template of paths under it, loopback endpoints with explicit ports and no
+ * embedded credentials, and a safe target slug;
+ * - the derived visible identity (`PR660 · Minikube30488` plus an ASCII app
+ * name) used for the process title, `app.setName` and the window title;
+ * - the runtime policy that states, in one place, that an isolated run must
+ * not register OS protocols and must not process deep links;
+ * - verification of the *effective* runtime (real userData, app path,
+ * endpoints, config storage path) against the declaration, so a divergence
+ * aborts instead of quietly reading a shared profile.
+ *
+ * The module performs no I/O, imports nothing from Electron, and never reads a
+ * profile, a keychain entry, an environment dump or a secret: the caller passes
+ * in what it observed. That keeps every security-relevant invariant testable
+ * without launching a GUI.
+ *
+ * Nothing here changes the normal startup path. With no opt-in the only result
+ * is `{ mode: 'normal' }`, and callers keep today's behaviour unchanged.
+ */
+import path from 'node:path'
+
+/** Opt-in flag accepted on the command line. */
+export const DEV_ISOLATION_FLAG = '--evenfire-dev-isolation'
+/** Opt-in environment variable; `1`/`true` enable, `0`/`false`/unset do not. */
+export const DEV_ISOLATION_ENABLE_ENV = 'EVENFIRE_DEV_ISOLATION'
+
+/**
+ * Payload the launcher declares. Only the run directory, the two endpoints, the
+ * target slug and (optionally) the PR number and expected app path are needed;
+ * every other value is derived here so the launcher and the app cannot disagree
+ * about names or paths.
+ */
+export const DEV_ISOLATION_ENV = {
+ runDir: 'EVENFIRE_DEV_ISOLATION_RUN_DIR',
+ restUrl: 'EVENFIRE_DEV_ISOLATION_REST_URL',
+ rpcUrl: 'EVENFIRE_DEV_ISOLATION_RPC_URL',
+ target: 'EVENFIRE_DEV_ISOLATION_TARGET',
+ pr: 'EVENFIRE_DEV_ISOLATION_PR',
+ appPath: 'EVENFIRE_DEV_ISOLATION_APP_PATH',
+} as const
+
+export const DEV_ISOLATION_USER_DATA_DIR_NAME = 'user-data'
+export const DEV_ISOLATION_CONFIG_FILE_NAME = 'runtime-config.json'
+export const DEV_ISOLATION_RECORD_FILE_NAME = 'run.json'
+export const DEV_ISOLATION_PID_FILE_NAME = 'run.pid'
+/** Prefix of the shared default app name; an isolated name must extend it. */
+export const DEV_ISOLATION_APP_NAME_PREFIX = 'Evenfire'
+
+const ENABLED_VALUES = new Set(['1', 'true'])
+const DISABLED_VALUES = new Set(['0', 'false'])
+const TARGET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+const PR_PATTERN = /^[0-9]{1,6}$/
+// The visible label may contain the middle dot the operator reads; the app name
+// stays plain ASCII because it becomes a process and application name.
+const LABEL_PATTERN = /^[\x20-\x7e\u00b7]{1,80}$/
+const APP_NAME_PATTERN = /^[\x20-\x7e]{1,64}$/
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
+export type DevIsolationEnablement = 'disabled' | 'enabled' | 'invalid'
+
+/**
+ * Read the opt-in. An unrecognized value is `invalid` rather than `disabled`:
+ * a typo must refuse the launch instead of quietly starting the shared-profile
+ * app the operator was trying to avoid.
+ */
+export function readDevIsolationEnablement(
+ env: NodeJS.ProcessEnv,
+ argv: readonly string[]
+): DevIsolationEnablement {
+ const raw = String(env[DEV_ISOLATION_ENABLE_ENV] ?? '')
+ .trim()
+ .toLowerCase()
+ const flagged = argv.includes(DEV_ISOLATION_FLAG)
+ if (ENABLED_VALUES.has(raw) || flagged) return 'enabled'
+ if (raw === '' || DISABLED_VALUES.has(raw)) return 'disabled'
+ return 'invalid'
+}
+
+export type DevIsolationPaths = {
+ runDir: string
+ userDataDir: string
+ configPath: string
+ recordPath: string
+ pidPath: string
+}
+
+/** Template of the per-run paths, derived from the run directory alone. */
+export function devIsolationPaths(runDir: string): DevIsolationPaths {
+ const root = path.resolve(runDir)
+ return {
+ runDir: root,
+ userDataDir: path.join(root, DEV_ISOLATION_USER_DATA_DIR_NAME),
+ configPath: path.join(root, DEV_ISOLATION_CONFIG_FILE_NAME),
+ recordPath: path.join(root, DEV_ISOLATION_RECORD_FILE_NAME),
+ pidPath: path.join(root, DEV_ISOLATION_PID_FILE_NAME),
+ }
+}
+
+export type DevIsolationIdentity = {
+ target: string
+ pr: string | null
+ /** Visible, non-ASCII-safe label, e.g. `PR660 · Minikube30488`. */
+ label: string
+ /** Process and application name, e.g. `Evenfire PR660 Minikube30488`. */
+ appName: string
+}
+
+function titleCaseToken(value: string): string {
+ return value
+ .split(/[^A-Za-z0-9]+/)
+ .filter(Boolean)
+ .map(token => token.charAt(0).toUpperCase() + token.slice(1).toLowerCase())
+ .join('')
+}
+
+/**
+ * Derive the unique visible identity from the target slug and the optional PR
+ * number. Deterministic: the launcher and the app compute the same value from
+ * the same inputs, so a drifted name is a detectable divergence, not a silent
+ * difference.
+ */
+export function deriveDevIsolationIdentity(input: {
+ target: string
+ pr?: string | null
+}): DevIsolationIdentity {
+ const target = String(input.target ?? '').trim()
+ const pr = typeof input.pr === 'string' && input.pr.trim() ? input.pr.trim() : null
+ const targetLabel = titleCaseToken(target) || 'Target'
+ const prLabel = pr ? `PR${pr}` : ''
+ const label = prLabel ? `${prLabel} \u00b7 ${targetLabel}` : targetLabel
+ const appName = `${DEV_ISOLATION_APP_NAME_PREFIX} ${[prLabel, targetLabel]
+ .filter(Boolean)
+ .join(' ')}`
+ return { target, pr, label, appName }
+}
+
+/**
+ * A loopback endpoint with an explicit port and no embedded credentials. This
+ * is deliberately strict: an isolated run must not be pointable at a shared or
+ * remote deployment by a mistyped or hostile input, and a URL that carries a
+ * user/password must never reach the public run record.
+ */
+export function isLoopbackEndpointUrl(value: string): boolean {
+ const raw = String(value ?? '').trim()
+ if (!raw) return false
+ let url: URL
+ try {
+ url = new URL(raw)
+ } catch {
+ return false
+ }
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return false
+ if (url.username || url.password) return false
+ if (!LOOPBACK_HOSTS.has(url.hostname)) return false
+ if (!url.port) return false
+ const port = Number(url.port)
+ if (!Number.isInteger(port) || port < 1 || port > 65535) return false
+ if (url.pathname !== '/' || url.search || url.hash) return false
+ return true
+}
+
+/** Strict containment: a path equal to `parent` is not "inside" it. */
+export function isPathInside(parent: string, child: string): boolean {
+ const from = path.resolve(parent)
+ const to = path.resolve(child)
+ if (from === to) return false
+ const prefix = from.endsWith(path.sep) ? from : `${from}${path.sep}`
+ return to.startsWith(prefix)
+}
+
+export type DevIsolationPlan = DevIsolationPaths & {
+ restUrl: string
+ rpcUrl: string
+ appPath: string | null
+ identity: DevIsolationIdentity
+ label: string
+ appName: string
+}
+
+export type DevIsolationRefusal = { code: string; message: string }
+export type DevIsolationPlanResult =
+ | { ok: true; plan: DevIsolationPlan }
+ | ({ ok: false } & DevIsolationRefusal)
+
+/**
+ * Validate the launcher's declaration and build the plan. Every failure is a
+ * refusal, never a fallback: the caller aborts.
+ */
+export function buildDevIsolationPlan(env: NodeJS.ProcessEnv): DevIsolationPlanResult {
+ const rawRunDir = String(env[DEV_ISOLATION_ENV.runDir] ?? '').trim()
+ if (!rawRunDir) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_RUN_DIR_REQUIRED',
+ message: `${DEV_ISOLATION_ENV.runDir} is required`,
+ }
+ }
+ if (!path.isAbsolute(rawRunDir)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_RUN_DIR_NOT_ABSOLUTE',
+ message: `${DEV_ISOLATION_ENV.runDir} must be an absolute path`,
+ }
+ }
+
+ const rawTarget = String(env[DEV_ISOLATION_ENV.target] ?? '').trim()
+ if (!TARGET_PATTERN.test(rawTarget)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_TARGET_INVALID',
+ message: `${DEV_ISOLATION_ENV.target} must match ${TARGET_PATTERN.source}`,
+ }
+ }
+
+ const rawPr = String(env[DEV_ISOLATION_ENV.pr] ?? '').trim()
+ if (rawPr && !PR_PATTERN.test(rawPr)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_PR_INVALID',
+ message: `${DEV_ISOLATION_ENV.pr} must be digits only`,
+ }
+ }
+
+ const rawRestUrl = String(env[DEV_ISOLATION_ENV.restUrl] ?? '').trim()
+ if (!isLoopbackEndpointUrl(rawRestUrl)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_REST_URL_INVALID',
+ message: `${DEV_ISOLATION_ENV.restUrl} must be an http(s) loopback URL with an explicit port and no credentials`,
+ }
+ }
+ const rawRpcUrl = String(env[DEV_ISOLATION_ENV.rpcUrl] ?? '').trim()
+ if (!isLoopbackEndpointUrl(rawRpcUrl)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_RPC_URL_INVALID',
+ message: `${DEV_ISOLATION_ENV.rpcUrl} must be an http(s) loopback URL with an explicit port and no credentials`,
+ }
+ }
+
+ const rawAppPath = String(env[DEV_ISOLATION_ENV.appPath] ?? '').trim()
+ if (rawAppPath && !path.isAbsolute(rawAppPath)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_APP_PATH_NOT_ABSOLUTE',
+ message: `${DEV_ISOLATION_ENV.appPath} must be an absolute path when set`,
+ }
+ }
+
+ const identity = deriveDevIsolationIdentity({ target: rawTarget, pr: rawPr || null })
+ if (!LABEL_PATTERN.test(identity.label)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_LABEL_INVALID',
+ message: 'derived isolation label must be 1-80 printable characters',
+ }
+ }
+ if (!APP_NAME_PATTERN.test(identity.appName)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_APP_NAME_INVALID',
+ message: 'derived isolation app name must be 1-64 printable ASCII characters',
+ }
+ }
+ if (identity.appName === DEV_ISOLATION_APP_NAME_PREFIX) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_APP_NAME_NOT_UNIQUE',
+ message: `an isolated app name must extend ${DEV_ISOLATION_APP_NAME_PREFIX}, not collide with it`,
+ }
+ }
+
+ const paths = devIsolationPaths(rawRunDir)
+ return {
+ ok: true,
+ plan: {
+ ...paths,
+ restUrl: rawRestUrl,
+ rpcUrl: rawRpcUrl,
+ appPath: rawAppPath || null,
+ identity,
+ label: identity.label,
+ appName: identity.appName,
+ },
+ }
+}
+
+export type DevIsolationDecision =
+ | { mode: 'normal' }
+ | { mode: 'isolated'; plan: DevIsolationPlan }
+ | ({ mode: 'refused' } & DevIsolationRefusal)
+
+/**
+ * Total decision for the main process: normal, isolated, or refused. Refused is
+ * a distinct outcome on purpose — an isolation request that cannot be honoured
+ * must never continue as a shared-profile launch.
+ */
+export function resolveDevIsolation(
+ env: NodeJS.ProcessEnv,
+ argv: readonly string[],
+ isPackaged = false
+): DevIsolationDecision {
+ const enablement = readDevIsolationEnablement(env, argv)
+ if (enablement === 'disabled') return { mode: 'normal' }
+ if (enablement === 'invalid') {
+ return {
+ mode: 'refused',
+ code: 'DEV_ISOLATION_ENABLE_INVALID',
+ message: `${DEV_ISOLATION_ENABLE_ENV} must be 1/true/0/false or unset, or ${DEV_ISOLATION_FLAG} must be passed`,
+ }
+ }
+ if (isPackaged) {
+ return {
+ mode: 'refused',
+ code: 'DEV_ISOLATION_PACKAGED',
+ message: 'Isolation is development-only',
+ }
+ }
+ const plan = buildDevIsolationPlan(env)
+ if (!plan.ok) return { mode: 'refused', code: plan.code, message: plan.message }
+ const inline = argv.find(argument => argument.startsWith('--user-data-dir='))
+ const index = argv.indexOf('--user-data-dir')
+ const userData = inline?.slice('--user-data-dir='.length) ?? (index >= 0 ? argv[index + 1] : '')
+ if (
+ !userData ||
+ !path.isAbsolute(userData) ||
+ path.resolve(userData) !== plan.plan.userDataDir ||
+ env.CLERUM_DESKTOP_CONFIG_PATH !== plan.plan.configPath ||
+ env.EXTERNAL_REST_API_BASE_URL !== plan.plan.restUrl ||
+ env.RPC_PROXY_BASE_URL !== plan.plan.rpcUrl
+ ) {
+ return {
+ mode: 'refused',
+ code: 'DEV_ISOLATION_LAUNCH_MISMATCH',
+ message:
+ 'Explicit user data, config path and effective endpoints must match the isolation plan',
+ }
+ }
+ return { mode: 'isolated', plan: plan.plan }
+}
+
+export type DevIsolationRuntimePolicy = {
+ isolate: boolean
+ /** Isolated runs leave the machine-wide protocol handler untouched. */
+ registerOsProtocols: boolean
+ /** Isolated runs never route deep links, including another session's. */
+ acceptDeepLinks: boolean
+ /** Isolated runs keep their label as the window title. */
+ pinWindowTitle: boolean
+ /** Unique process/application name, or null to keep the shipped name. */
+ appName: string | null
+ /** Visible window title, or null to keep the derived production title. */
+ windowTitle: string | null
+}
+
+/**
+ * The single place that decides what an isolated run may do with machine-wide
+ * state. With no plan every field is the production value, so the normal path
+ * stays unchanged.
+ */
+export function devIsolationRuntimePolicy(
+ plan: DevIsolationPlan | null
+): DevIsolationRuntimePolicy {
+ if (!plan) {
+ return {
+ isolate: false,
+ registerOsProtocols: true,
+ acceptDeepLinks: true,
+ pinWindowTitle: false,
+ appName: null,
+ windowTitle: null,
+ }
+ }
+ return {
+ isolate: true,
+ registerOsProtocols: false,
+ acceptDeepLinks: false,
+ pinWindowTitle: true,
+ appName: plan.appName,
+ windowTitle: plan.label,
+ }
+}
+
+export type DevIsolationObservation = {
+ pid: number
+ /** Real (`realpath`) userData directory Electron resolved. */
+ userDataDir: string
+ /** Real app path the process is running from. */
+ appPath: string
+ /** Effective endpoints after config hydration. */
+ restUrl: string
+ rpcUrl: string
+ /** Effective runtime-config storage path after hydration. */
+ configStoragePath: string
+ /** Derived environment key of the hydrated runtime. */
+ envKey: string
+}
+
+export type DevIsolationMismatch = {
+ field: 'userDataDir' | 'appPath' | 'restUrl' | 'rpcUrl' | 'configStoragePath'
+ expected: string
+ actual: string
+}
+
+export type DevIsolationVerdict = { ok: true } | { ok: false; mismatches: DevIsolationMismatch[] }
+
+function samePath(left: string, right: string): boolean {
+ return path.resolve(left) === path.resolve(right)
+}
+
+/**
+ * Compare what the app actually resolved against what the launcher declared.
+ *
+ * The config storage path is compared exactly, not by containment: it is the
+ * proof that the runtime-config layer pointed at the isolated file instead of
+ * the developer's shared `runtime-configs` directory. Callers pass `realpath`
+ * results for the paths, so a symlinked parent cannot fake a match.
+ */
+export function verifyDevIsolationRuntime(
+ plan: DevIsolationPlan,
+ observed: DevIsolationObservation
+): DevIsolationVerdict {
+ const mismatches: DevIsolationMismatch[] = []
+ if (!samePath(plan.userDataDir, observed.userDataDir)) {
+ mismatches.push({
+ field: 'userDataDir',
+ expected: plan.userDataDir,
+ actual: observed.userDataDir,
+ })
+ }
+ if (plan.appPath && !samePath(plan.appPath, observed.appPath)) {
+ mismatches.push({ field: 'appPath', expected: plan.appPath, actual: observed.appPath })
+ }
+ if (plan.restUrl !== observed.restUrl) {
+ mismatches.push({ field: 'restUrl', expected: plan.restUrl, actual: observed.restUrl })
+ }
+ if (plan.rpcUrl !== observed.rpcUrl) {
+ mismatches.push({ field: 'rpcUrl', expected: plan.rpcUrl, actual: observed.rpcUrl })
+ }
+ if (!samePath(plan.configPath, observed.configStoragePath)) {
+ mismatches.push({
+ field: 'configStoragePath',
+ expected: plan.configPath,
+ actual: observed.configStoragePath,
+ })
+ }
+ return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches }
+}
+
+/** Keys a public run record may contain. Nothing else is ever serialized. */
+export const DEV_ISOLATION_RECORD_FIELDS = [
+ 'kind',
+ 'pid',
+ 'label',
+ 'appName',
+ 'target',
+ 'envKey',
+ 'runDir',
+ 'userDataDir',
+ 'configPath',
+ 'configStoragePath',
+ 'appPath',
+ 'restUrl',
+ 'rpcUrl',
+] as const
+
+/**
+ * Public metadata for one isolated run: the identity, the pid and the paths and
+ * endpoints the operator asked to see. Built from an allow-list so a caller
+ * cannot leak an environment dump, a token or a credential into the record, and
+ * so the record is byte-identical between the launcher and the app.
+ */
+export function publicDevIsolationRecord(
+ plan: DevIsolationPlan,
+ observed: DevIsolationObservation
+): Record<string, string | number> {
+ if (!verifyDevIsolationRuntime(plan, observed).ok) {
+ throw new Error('Isolation metadata is unavailable before runtime verification')
+ }
+ return {
+ kind: 'evenfire-dev-isolation',
+ pid: observed.pid,
+ label: plan.label,
+ appName: plan.appName,
+ target: plan.identity.target,
+ envKey: observed.envKey,
+ runDir: plan.runDir,
+ userDataDir: observed.userDataDir,
+ configPath: plan.configPath,
+ configStoragePath: observed.configStoragePath,
+ appPath: observed.appPath,
+ restUrl: observed.restUrl,
+ rpcUrl: observed.rpcUrl,
+ }
+}
+
+function singleLineValue(value: string | number | undefined): string {
+ const raw = typeof value === 'number' ? String(value) : String(value ?? '')
+ return raw
+ .replace(/[\u0000-\u001f\u007f]/g, '?')
+ .replace(/\s+/g, ' ')
+ .trim()
+}
+
+/** One log line, deterministic order, never multi-line. */
+export function formatDevIsolationLogLine(record: Record<string, string | number>): string {
+ const fields = Object.keys(record)
+ .sort()
+ .map(key => `${key}=${singleLineValue(record[key])}`)
+ return `[Desktop][dev-isolation] ${fields.join(' ')}`
+}
+
+export type IsolationBaseDirDecision =
+ | { ok: true; baseDir: string }
+ | ({ ok: false } & DevIsolationRefusal)
+
+/** Platform default parent directory for per-run directories. */
+export function defaultIsolationBaseDir(input: {
+ platform: NodeJS.Platform
+ homedir: string
+ env: NodeJS.ProcessEnv
+}): string {
+ if (input.platform === 'darwin') {
+ return path.join(
+ input.homedir,
+ 'Library',
+ 'Application Support',
+ `${DEV_ISOLATION_APP_NAME_PREFIX} Dev Isolation`
+ )
+ }
+ if (input.platform === 'win32') {
+ const localAppData = String(input.env.LOCALAPPDATA ?? '').trim()
+ return path.join(
+ localAppData || path.join(input.homedir, 'AppData', 'Local'),
+ `${DEV_ISOLATION_APP_NAME_PREFIX} Dev Isolation`
+ )
+ }
+ const stateHome = String(input.env.XDG_STATE_HOME ?? '').trim()
+ return path.join(
+ stateHome || path.join(input.homedir, '.local', 'state'),
+ 'evenfire-dev-isolation'
+ )
+}
+
+/**
+ * Admit the parent directory of the per-run directories. A requested directory
+ * must be absolute and outside the repository: run state holds credentials-side
+ * material (the Chromium profile), and it must never land in the worktree where
+ * it could be committed or copied into notes.
+ */
+export function admitIsolationBaseDir(input: {
+ requested?: string
+ repoRoot: string
+ platform: NodeJS.Platform
+ homedir: string
+ env: NodeJS.ProcessEnv
+}): IsolationBaseDirDecision {
+ const requested = String(input.requested ?? '').trim()
+ if (requested && !path.isAbsolute(requested)) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_BASE_DIR_NOT_ABSOLUTE',
+ message: 'the isolation base directory must be an absolute path',
+ }
+ }
+ const baseDir = requested
+ ? path.resolve(requested)
+ : defaultIsolationBaseDir({
+ platform: input.platform,
+ homedir: input.homedir,
+ env: input.env,
+ })
+ if (isPathInside(input.repoRoot, baseDir) || path.resolve(input.repoRoot) === baseDir) {
+ return {
+ ok: false,
+ code: 'DEV_ISOLATION_BASE_DIR_INSIDE_REPO',
+ message: 'the isolation base directory must be outside the repository',
+ }
+ }
+ return { ok: true, baseDir }
+}
diff --git a/desktop-app/src/imageInputDecision.ts b/desktop-app/src/imageInputDecision.ts
new file mode 100644
index 000000000..c65be4748
--- /dev/null
+++ b/desktop-app/src/imageInputDecision.ts
@@ -0,0 +1,205 @@
+/**
+ * Image-input capability for ONE model, shared by the Desktop main process (wire
+ * validation) and the renderer (composer/model-selector guards). Runtime-safe
+ * module: the renderer imports it directly, the same way it imports
+ * `chatMessageMerge`.
+ *
+ * Scope: this module only VALIDATES the decision the host projected. It never
+ * recomputes model or transport capability, and there is deliberately no
+ * provider-based fallback — capability comes from the host, never from the
+ * provider id, the model name, or OpenAI compatibility.
+ *
+ * `state` is the only authorization-relevant field. Images may be attached only
+ * when the host projected `supported` with evidence that has not expired.
+ * Anything missing, malformed or expired normalizes to `unknown`: the model
+ * stays selectable for text and image attachments are blocked with an explicit
+ * reason. Host-provided reasons are preserved verbatim; the local normalization
+ * reasons are `model_unknown` and `evidence_expired`.
+ */
+
+export type ImageInputState = 'supported' | 'unsupported' | 'unknown'
+
+export interface ImageInputDecision {
+ state: ImageInputState
+ /** Stable, machine-readable reason token (never user copy). */
+ reason: string
+ /** ISO timestamp after which the evidence must be re-evaluated as unknown. */
+ validUntil?: string
+ evidence?: {
+ source: 'curated' | 'discovery'
+ reference: string
+ checkedAt: string
+ validUntil?: string
+ }
+}
+
+/** Local normalization reasons. Host-provided reasons are preserved as-is. */
+export const IMAGE_INPUT_LOCAL_REASON = {
+ /** No decision projected, malformed decision, or model absent from the catalog. */
+ modelUnknown: 'model_unknown',
+ /** Evidence existed but its `validUntil` already passed. */
+ evidenceExpired: 'evidence_expired',
+} as const
+
+const IMAGE_INPUT_STATES: readonly ImageInputState[] = ['supported', 'unsupported', 'unknown']
+
+function modelUnknown(): ImageInputDecision {
+ return { state: 'unknown', reason: IMAGE_INPUT_LOCAL_REASON.modelUnknown }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Normalizes an untrusted wire value into a decision. Missing or malformed input
+ * becomes `unknown` (never `unsupported`, so the UI can tell "not verified" from
+ * "known to be text-only"). A malformed `validUntil` is treated as malformed
+ * evidence rather than silently dropped: dropping it would turn an expiring
+ * approval into a permanent one.
+ */
+export function normalizeImageInputDecision(raw: unknown): ImageInputDecision {
+ if (!isPlainObject(raw)) return modelUnknown()
+
+ const state = raw.state
+ if (typeof state !== 'string' || !IMAGE_INPUT_STATES.includes(state as ImageInputState)) {
+ return modelUnknown()
+ }
+
+ if (typeof raw.reason !== 'string' || !/^[a-z][a-z0-9_]{0,127}$/.test(raw.reason))
+ return modelUnknown()
+ const decision: ImageInputDecision = {
+ state: state as ImageInputState,
+ reason: raw.reason,
+ }
+
+ if (raw.validUntil !== undefined) {
+ if (typeof raw.validUntil !== 'string' || Number.isNaN(Date.parse(raw.validUntil))) {
+ return modelUnknown()
+ }
+ decision.validUntil = raw.validUntil
+ }
+
+ if (raw.evidence !== undefined) {
+ const evidence = raw.evidence
+ if (
+ !isPlainObject(evidence) ||
+ !['curated', 'discovery'].includes(String(evidence.source)) ||
+ typeof evidence.reference !== 'string' ||
+ !evidence.reference.trim() ||
+ evidence.reference.length > 1024 ||
+ typeof evidence.checkedAt !== 'string' ||
+ !Number.isFinite(Date.parse(evidence.checkedAt)) ||
+ (evidence.validUntil !== undefined &&
+ (typeof evidence.validUntil !== 'string' ||
+ !Number.isFinite(Date.parse(evidence.validUntil))))
+ ) {
+ return modelUnknown()
+ }
+ decision.evidence = {
+ source: evidence.source as 'curated' | 'discovery',
+ reference: evidence.reference,
+ checkedAt: evidence.checkedAt,
+ ...(evidence.validUntil === undefined ? {} : { validUntil: evidence.validUntil as string }),
+ }
+ // The host emits the same bound in both fields. Never turn a mismatched
+ // expiring decision into a permanent approval by dropping its bound.
+ if (decision.evidence.validUntil && decision.evidence.validUntil !== decision.validUntil)
+ return modelUnknown()
+ }
+
+ return decision
+}
+
+/** True when the decision still authorizes images at `nowMs`. */
+export function isImageInputDecisionValid(
+ decision: ImageInputDecision,
+ nowMs: number = Date.now()
+): boolean {
+ if (!decision.validUntil) return true
+ const expiresAt = Date.parse(decision.validUntil)
+ if (Number.isNaN(expiresAt)) return false
+ return expiresAt > nowMs
+}
+
+/**
+ * Normalizes AND re-evaluates freshness. This is the function every guard uses:
+ * an expired approval reads as `unknown` with `evidence_expired` at each
+ * attempt, without waiting for a ConfigMap/catalog change.
+ */
+export function resolveImageInputDecision(
+ raw: unknown,
+ nowMs: number = Date.now()
+): ImageInputDecision {
+ const decision = normalizeImageInputDecision(raw)
+ if (decision.state === 'unknown') return decision
+ if (decision.state === 'unsupported' && decision.reason === 'transport_unsupported')
+ return decision
+ if (!isImageInputDecisionValid(decision, nowMs)) {
+ return {
+ state: 'unknown',
+ reason: IMAGE_INPUT_LOCAL_REASON.evidenceExpired,
+ validUntil: decision.validUntil,
+ ...(decision.evidence ? { evidence: decision.evidence } : {}),
+ }
+ }
+ return decision
+}
+
+/** Minimal model-option shape needed to resolve the effective capability. */
+export interface ImageInputModelOption {
+ name: string
+ imageInput?: unknown
+}
+
+/**
+ * Resolves the capability of the model that will actually be requested. The
+ * caller must pass the effective model (confirmed selection, pending intent, or
+ * host default) — never a provider id and never `servedBy`.
+ */
+export function resolveModelImageInput(
+ models: readonly ImageInputModelOption[] | null | undefined,
+ effectiveModel: string | null | undefined,
+ nowMs: number = Date.now()
+): ImageInputDecision {
+ const wanted = typeof effectiveModel === 'string' ? effectiveModel.trim() : ''
+ if (!wanted) return modelUnknown()
+ const option = (models ?? []).find(model => model?.name === wanted)
+ if (!option) return modelUnknown()
+ return resolveImageInputDecision(option.imageInput, nowMs)
+}
+
+/** Only `supported` authorizes attaching images. */
+export function canSendImagesWith(decision: ImageInputDecision): boolean {
+ return decision.state === 'supported'
+}
+
+/**
+ * User-facing explanation for a blocking decision; `null` when images are
+ * allowed. Kept here so the composer, the paste/drop handlers and the send-time
+ * guard show identical copy.
+ */
+export function imageInputBlockMessage(
+ effectiveModel: string | null | undefined,
+ decision: ImageInputDecision
+): string | null {
+ if (canSendImagesWith(decision)) return null
+ const label =
+ typeof effectiveModel === 'string' && effectiveModel.trim()
+ ? effectiveModel
+ : 'the selected model'
+ switch (decision.reason) {
+ case 'model_unsupported':
+ return `Image attachments are not supported by model "${label}". Switch to a model with image input support before attaching images.`
+ case 'evidence_expired':
+ return `The image-input evidence for model "${label}" has expired. Ask an operator to refresh it before attaching images.`
+ case 'evidence_not_yet_valid':
+ return `The image-input evidence for model "${label}" is dated in the future and cannot be used yet. Ask an operator to correct it.`
+ case 'transport_unsupported':
+ // The provider is fixed per Host, so switching models would not help.
+ return "Image attachments are not available for this agent's provider transport yet."
+ default:
+ // A reason the Desktop does not know is, by fail-closed design, unverified.
+ return `Image input is not verified for model "${label}" yet. Ask an operator to curate its image-input evidence, or switch to a verified model.`
+ }
+}
diff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.ts
index cf07a5768..605bfca3b 100644
--- a/desktop-app/src/ipc.ts
+++ b/desktop-app/src/ipc.ts
@@ -147,6 +147,11 @@ async function writeUniqueDownload(
throw new Error('Could not create a unique artifact download filename')
}
+/** A model-selection revision (issue #654 CAS base): a non-negative integer. */
+function isSelectionRevision(value: unknown): value is number {
+ return Number.isSafeInteger(value) && (value as number) >= 0
+}
+
function parseHostMessageRequest(raw: unknown): HostMessageRequest {
const parsed = raw as HostMessageRequest
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -155,6 +160,15 @@ function parseHostMessageRequest(raw: unknown): HostMessageRequest {
if (typeof parsed.content !== 'string' || !parsed.content.trim()) {
throw new Error('Invalid host message request')
}
+ if (parsed.model !== undefined && (typeof parsed.model !== 'string' || !parsed.model.trim())) {
+ throw new Error('Invalid host message request: model')
+ }
+ if (
+ parsed.modelSelectionRevision !== undefined &&
+ !isSelectionRevision(parsed.modelSelectionRevision)
+ ) {
+ throw new Error('Invalid host message request: modelSelectionRevision')
+ }
return parsed
}
@@ -1296,7 +1310,13 @@ export function registerIpcHandlers(service: AppService): void {
'rpc:setHostModel',
async (
event,
- payload: { hostRef: string; chatId: string; model: string; hostRefs?: string[] }
+ payload: {
+ hostRef: string
+ chatId: string
+ model: string
+ hostRefs?: string[]
+ expectedRevision?: number
+ }
) => {
assertTrustedSender(event)
const hostRef = sanitizeString(payload?.hostRef)
@@ -1305,7 +1325,15 @@ export function registerIpcHandlers(service: AppService): void {
if (!hostRef || !chatId || !model) {
throw new Error('hostRef, chatId, and model are required')
}
- return service.setHostModel(hostRef, chatId, model, payload?.hostRefs)
+ // Optional CAS precondition (issue #654). Absent on hosts that do not
+ // project `modelSelectionRevision`; the request then omits it entirely.
+ // A present but invalid revision is refused: dropping it would turn a
+ // conditional write into an unconditional one.
+ const expectedRevision = payload?.expectedRevision
+ if (expectedRevision !== undefined && !isSelectionRevision(expectedRevision)) {
+ throw new Error('expectedRevision must be a non-negative integer')
+ }
+ return service.setHostModel(hostRef, chatId, model, payload?.hostRefs, expectedRevision)
}
)
diff --git a/desktop-app/src/main.ts b/desktop-app/src/main.ts
index fc6034a08..1aa758df3 100644
--- a/desktop-app/src/main.ts
+++ b/desktop-app/src/main.ts
@@ -1,9 +1,23 @@
import { BrowserWindow, app, ipcMain, nativeTheme, powerMonitor } from 'electron'
+import fs from 'node:fs'
import path from 'node:path'
import { AppService } from './appService.js'
import { routeClerumOauthCompleted } from './clerumDeepLink.js'
-import { config } from './config.js'
+import {
+ config,
+ getActiveEnvKey,
+ getDesktopRuntimeConfigState,
+ hydrateDesktopRuntimeConfig,
+} from './config.js'
import { installDesktopTextContextMenus } from './desktopTextContextMenu.js'
+import {
+ type DevIsolationPlan,
+ devIsolationRuntimePolicy,
+ formatDevIsolationLogLine,
+ publicDevIsolationRecord,
+ resolveDevIsolation,
+ verifyDevIsolationRuntime,
+} from './devIsolation.js'
import { createEvenfireDeepLinkRouter } from './evenfireDeepLinkRouter.js'
import { assertTrustedSender, registerIpcHandlers } from './ipc.js'
import { createMainWindowCoordinator, createRetryableInitializer } from './mainWindowCoordinator.js'
@@ -25,8 +39,23 @@ import { installAdaptiveSystemIcon, resolveSystemIconPath } from './systemIcon.j
const EVENFIRE_APP_NAME = 'Evenfire'
const EVENFIRE_APP_ID = 'ai.evenfire.desktop'
-process.title = EVENFIRE_APP_NAME
-app.setName(EVENFIRE_APP_NAME)
+/**
+ * Dev isolation is opt-in and fail-closed. A launch that asked for an isolated
+ * instance must never continue into the shared user profile or the machine-wide
+ * OS protocol handler, so an unhonourable request aborts here — before
+ * `registerCustomProtocols()` can touch the default handler.
+ */
+const devIsolation = resolveDevIsolation(process.env, process.argv, app.isPackaged)
+if (devIsolation.mode === 'refused') {
+ console.error(`[Desktop] Dev isolation refused: ${devIsolation.code}: ${devIsolation.message}`)
+ process.exit(1)
+}
+const devIsolationPlan: DevIsolationPlan | null =
+ devIsolation.mode === 'isolated' ? devIsolation.plan : null
+const devIsolationPolicy = devIsolationRuntimePolicy(devIsolationPlan)
+
+process.title = devIsolationPolicy.appName ?? EVENFIRE_APP_NAME
+app.setName(devIsolationPolicy.appName ?? EVENFIRE_APP_NAME)
app.setAppUserModelId(EVENFIRE_APP_ID)
// Prevent crash on EPIPE when stdout/stderr pipe is broken (e.g., parent terminal closed)
@@ -327,29 +356,87 @@ function handleClerumUrl(rawUrl: string): void {
focusMainWindow()
}
-registerCustomProtocols()
+// An isolated run leaves the machine-wide default handler exactly as it is: the
+// normal app keeps owning `evenfire:`/`clerum:` deep links.
+if (devIsolationPolicy.registerOsProtocols) {
+ registerCustomProtocols()
+}
const gotSingleInstanceLock = app.requestSingleInstanceLock()
if (!gotSingleInstanceLock) {
app.quit()
} else {
app.on('second-instance', (_event, argv) => {
- const protocolUrls = collectInitialProtocolUrls(argv)
- protocolUrls.evenfireUrls.forEach(evenfireDeepLinkRouter.handle)
- protocolUrls.clerumUrls.forEach(handleClerumUrl)
+ // An isolated instance never routes deep links: a URL delivered here belongs
+ // to the session that owns the OS handler, not to this one. A relaunch still
+ // brings this instance's window forward.
+ if (devIsolationPolicy.acceptDeepLinks) {
+ const protocolUrls = collectInitialProtocolUrls(argv)
+ protocolUrls.evenfireUrls.forEach(evenfireDeepLinkRouter.handle)
+ protocolUrls.clerumUrls.forEach(handleClerumUrl)
+ }
requestMainWindow()
})
}
-app.on('open-url', (event, rawUrl) => {
- event.preventDefault()
- const lowerUrl = rawUrl.toLowerCase()
- if (lowerUrl.startsWith(`${DESKTOP_SETUP_PROTOCOL}:`)) {
- evenfireDeepLinkRouter.handle(rawUrl)
- } else if (lowerUrl.startsWith(`${CLERUM_PROTOCOL}:`)) {
- handleClerumUrl(rawUrl)
+if (devIsolationPolicy.acceptDeepLinks) {
+ app.on('open-url', (event, rawUrl) => {
+ event.preventDefault()
+ const lowerUrl = rawUrl.toLowerCase()
+ if (lowerUrl.startsWith(`${DESKTOP_SETUP_PROTOCOL}:`)) {
+ evenfireDeepLinkRouter.handle(rawUrl)
+ } else if (lowerUrl.startsWith(`${CLERUM_PROTOCOL}:`)) {
+ handleClerumUrl(rawUrl)
+ }
+ })
+}
+
+/**
+ * Verify the effective runtime against the launcher's declaration and log the
+ * public metadata for this run. Returns false when the process must abort:
+ * continuing would use a profile the operator did not ask for.
+ *
+ * Paths are compared after `realpath`, so a symlinked parent cannot fake a
+ * match, and the config storage path is compared exactly — it is the proof that
+ * the runtime-config layer pointed at the isolated file rather than the shared
+ * `runtime-configs` directory.
+ */
+function verifyDevIsolationBeforeServices(plan: DevIsolationPlan): boolean {
+ hydrateDesktopRuntimeConfig()
+ const runtimeState = getDesktopRuntimeConfigState()
+ const realPath = (value: string): string => {
+ try {
+ return fs.realpathSync.native(value)
+ } catch {
+ return path.resolve(value)
+ }
}
-})
+ const observed = {
+ pid: process.pid,
+ userDataDir: realPath(app.getPath('userData')),
+ appPath: realPath(app.getAppPath()),
+ restUrl: config.externalRestApiBaseUrl,
+ rpcUrl: config.rpcProxyBaseUrl,
+ configStoragePath: runtimeState.storagePath,
+ envKey: getActiveEnvKey(),
+ }
+ const expected: DevIsolationPlan = {
+ ...plan,
+ userDataDir: realPath(plan.userDataDir),
+ appPath: plan.appPath ? realPath(plan.appPath) : null,
+ }
+ const verdict = verifyDevIsolationRuntime(expected, observed)
+ if (verdict.ok) {
+ console.log(formatDevIsolationLogLine(publicDevIsolationRecord(expected, observed)))
+ return true
+ }
+ const detail = verdict.mismatches.map(mismatch => mismatch.field).join(', ')
+ console.error(
+ `[Desktop] Dev isolation refused: the effective runtime diverges from the launcher: ${detail}`
+ )
+ app.exit(1)
+ return false
+}
async function createWindow(): Promise<void> {
try {
@@ -368,9 +455,10 @@ async function createWindow(): Promise<void> {
show: false,
frame: false,
title:
- config.appName === EVENFIRE_APP_NAME
+ devIsolationPolicy.windowTitle ??
+ (config.appName === EVENFIRE_APP_NAME
? EVENFIRE_APP_NAME
- : `${EVENFIRE_APP_NAME} — ${config.appName}`,
+ : `${EVENFIRE_APP_NAME} — ${config.appName}`),
icon: resolveSystemIconPath(systemIconAssetsDirectory(), nativeTheme.shouldUseDarkColors),
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
@@ -380,6 +468,14 @@ async function createWindow(): Promise<void> {
},
})
mainWindow = window
+ if (devIsolationPolicy.pinWindowTitle) {
+ // Keep the isolated identity in the window title after the renderer updates
+ // document.title: window/app automation resolves this instance by it.
+ window.webContents.on('page-title-updated', event => {
+ event.preventDefault()
+ window.setTitle(devIsolationPolicy.windowTitle ?? window.getTitle())
+ })
+ }
wireHostDesktopShortcutRouting(window)
mainWindowRendererReady = false
window.on('closed', () => {
@@ -439,6 +535,10 @@ if (gotSingleInstanceLock) {
app
.whenReady()
.then(async () => {
+ // Before any service initializes: an isolated run that cannot prove its
+ // own userData, app path, endpoints and config storage is the declared
+ // isolated ones aborts instead of reading a shared profile.
+ if (devIsolationPlan && !verifyDevIsolationBeforeServices(devIsolationPlan)) return
installDesktopTextContextMenus()
wireAdaptiveSystemIcon()
// Must precede registerIpcHandlers: the SDK IPC handlers resolve the
@@ -456,10 +556,14 @@ if (gotSingleInstanceLock) {
// Collect startup argv once. The renderer-ready handshake drains queued
// Evenfire URLs after its listeners are installed; rescanning argv would
// dispatch setup links twice on Windows/Linux.
- const initialProtocolUrls = collectInitialProtocolUrls(process.argv)
+ // An isolated run collects nothing: its argv cannot contain a deep link
+ // that belongs to this session.
+ const initialProtocolUrls = devIsolationPolicy.acceptDeepLinks
+ ? collectInitialProtocolUrls(process.argv)
+ : { evenfireUrls: [], clerumUrls: [] }
initialProtocolUrls.evenfireUrls.forEach(evenfireDeepLinkRouter.enqueuePending)
await mainWindowCoordinator.ensureWindow()
- if (process.platform !== 'darwin') {
+ if (devIsolationPolicy.acceptDeepLinks && process.platform !== 'darwin') {
initialProtocolUrls.clerumUrls.forEach(handleClerumUrl)
}
})
diff --git a/desktop-app/src/preload.ts b/desktop-app/src/preload.ts
index d57e13944..b28d89d11 100644
--- a/desktop-app/src/preload.ts
+++ b/desktop-app/src/preload.ts
@@ -455,8 +455,20 @@ const clerum = Object.freeze({
ipcRenderer.invoke('rpc:getContextBreakdown', { hostRef, agent, chatId, hostRefs }),
getHostModels: (hostRef: string, chatId: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:getHostModels', { hostRef, chatId, hostRefs }),
- setHostModel: (hostRef: string, chatId: string, model: string, hostRefs?: string[]) =>
- ipcRenderer.invoke('rpc:setHostModel', { hostRef, chatId, model, hostRefs }),
+ setHostModel: (
+ hostRef: string,
+ chatId: string,
+ model: string,
+ hostRefs?: string[],
+ expectedRevision?: number
+ ) =>
+ ipcRenderer.invoke('rpc:setHostModel', {
+ hostRef,
+ chatId,
+ model,
+ hostRefs,
+ expectedRevision,
+ }),
// Spec 15 Fase B — explicit user rename. No `hostRefs` fleet arg: the main
// process scopes the write token to this single host.
renameSession: (hostRef: string, agent: string, chatId: string, title: string) =>
diff --git a/desktop-app/src/renderer.d.ts b/desktop-app/src/renderer.d.ts
index af75ee4d0..01ddbe096 100644
--- a/desktop-app/src/renderer.d.ts
+++ b/desktop-app/src/renderer.d.ts
@@ -574,7 +574,14 @@ declare global {
hostRef: string,
chatId: string,
model: string,
- hostRefs?: string[]
+ hostRefs?: string[],
+ /**
+ * Optional CAS precondition (issue #654). Only sent when the host
+ * projected `modelSelectionRevision`; a stale value is rejected with
+ * `model_selection_conflict` instead of silently overwriting a newer
+ * selection.
+ */
+ expectedRevision?: number
) => Promise<SetHostModelResult>
/**
* Spec 15 Fase B — explicit user rename, propagated to the server. Rejects
diff --git a/desktop-app/src/rpcProxyClient.ts b/desktop-app/src/rpcProxyClient.ts
index aa0fecff5..3f7a45e94 100644
--- a/desktop-app/src/rpcProxyClient.ts
+++ b/desktop-app/src/rpcProxyClient.ts
@@ -34,6 +34,8 @@ export type { SandboxUiApp } from './types.js'
* convention used by {@link RpcProxyClient.loadSessionMessages}.
*/
const MODEL_NOT_ALLOWED = 'model_not_allowed'
+/** CAS precondition failure on `POST …/hosts/:hostRef/model` (issue #654). */
+const MODEL_SELECTION_CONFLICT = 'model_selection_conflict'
function wireObject(value: unknown, label: string): Record<string, unknown> {
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
@@ -1142,7 +1144,8 @@ export class RpcProxyClient {
rpcToken: string,
hostRef: string,
chatId: string,
- model: string
+ model: string,
+ expectedRevision?: number
): Promise<SetHostModelResult> {
const response = await fetch(url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/model`), {
method: 'POST',
@@ -1150,7 +1153,12 @@ export class RpcProxyClient {
authorization: `Bearer ${rpcToken}`,
'content-type': 'application/json',
},
- body: JSON.stringify({ chatId, model }),
+ // `expectedRevision` is omitted unless the host projected a revision
+ // (issue #654 CAS), so an older host keeps receiving the exact body it
+ // accepts today.
+ body: JSON.stringify(
+ expectedRevision === undefined ? { chatId, model } : { chatId, model, expectedRevision }
+ ),
signal: withTimeout(),
})
if (!response.ok) {
@@ -1166,6 +1174,16 @@ export class RpcProxyClient {
if (errorCodeFromBody(body) === MODEL_NOT_ALLOWED) {
throw new ApiError(`Set host model rejected (${MODEL_NOT_ALLOWED})`, response.status, body)
}
+ // CAS precondition failed: another writer moved the session selection.
+ // Terminal (never a wake/piggyback case) and surfaced by token so the
+ // renderer can refetch instead of trusting the rejected optimistic state.
+ if (errorCodeFromBody(body) === MODEL_SELECTION_CONFLICT) {
+ throw new ApiError(
+ `Set host model conflicted (${MODEL_SELECTION_CONFLICT})`,
+ response.status,
+ body
+ )
+ }
throw new ApiError(
`Set host model failed (${response.status}): ${body}`,
response.status,
diff --git a/desktop-app/src/types.ts b/desktop-app/src/types.ts
index e4d83c1dd..42d99f7cf 100644
--- a/desktop-app/src/types.ts
+++ b/desktop-app/src/types.ts
@@ -1,3 +1,5 @@
+import type { ImageInputDecision } from './imageInputDecision'
+
export type Role = 'admin' | 'inviter' | 'member'
export type RpcScope =
| 'mcp:servers:list'
@@ -534,6 +536,8 @@ export type HostMessageRequest = {
* validates + persists this session selection before running the task.
*/
model?: string
+ /** CAS base captured with a visual message's explicit model choice. */
+ modelSelectionRevision?: number
[key: string]: unknown
}
@@ -562,6 +566,18 @@ export type HostMessageResponse = {
status?: 'completed' | 'waiting_approval' | 'pending' | 'cancelled' | 'failed' | 'processing'
response?: string
error?: TaskError | string
+ /**
+ * #654 — the model-selection revision the Host holds after this send.
+ * Present on a success when the request carried a `model`: the current
+ * revision, bumped only when that model differed from the session's effective
+ * model and was written (a send on the model the session already runs on,
+ * such as the Host default, reports it unchanged). Present on an
+ * `LLM_MODEL_SELECTION_CONFLICT` failure as the winning revision to retry on.
+ * Absent on an image send refused for its model (`LLM_IMAGE_INPUT_*`), which
+ * writes nothing. Its ABSENCE on a success after a piggyback means the Host
+ * ignored the selection.
+ */
+ modelSelectionRevision?: number
approval?: {
taskId: string
requestId: string
@@ -1089,6 +1105,13 @@ export interface HostModelOption {
name: string
displayName?: string
contextWindowTokens?: number
+ /**
+ * Image-input capability projected by the host for this model (issue #654).
+ * Optional and additive: a host that predates the projection omits it, which
+ * normalizes to `unknown` — text stays allowed and image attachments are
+ * blocked with an explicit reason. Never inferred from provider/model name.
+ */
+ imageInput?: ImageInputDecision
/** Last-known catalog row; hidden from new picks unless it is already selected. */
stale?: boolean
/** Operator-disabled catalog row; hidden from new picks unless it is already selected. */
@@ -1112,6 +1135,12 @@ export interface HostModelsResult {
sessionModelBlocked?: string
degraded: boolean
models: HostModelOption[]
+ /**
+ * Revision of the session selection this projection was read at (issue #654
+ * CAS). Optional: when the host does not project it, the renderer never sends
+ * `expectedRevision`, so selection writes stay backwards compatible.
+ */
+ modelSelectionRevision?: number
}
/**
@@ -1125,6 +1154,8 @@ export interface SetHostModelResult {
effective: 'next-task'
provider: string
model: string
+ /** Revision after this accepted write; feeds the next CAS attempt. */
+ modelSelectionRevision?: number
}
export interface ChatMessage {
diff --git a/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts b/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts
new file mode 100644
index 000000000..47582627a
--- /dev/null
+++ b/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts
@@ -0,0 +1,483 @@
+// desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts
+//
+// E2E_GUARDIAN_IPC_FLOW: Desktop chat, the model catalog and the agent list all
+// travel over Electron IPC, so this module has no renderer request to await. It
+// exists to read the OTHER end of the journey: the external provider boundary.
+//
+// Scope. This module owns three things and nothing else:
+//
+// 1. the environment contract of the fixture lane (the runner owns the values);
+// 2. a read-only, shell-free ledger read of the derived fixture that answers
+// the external provider origin;
+// 3. integrity checks that make that ledger usable as an oracle.
+//
+// It never mutates cluster state, never calls a product API, and never mocks an
+// IPC, RPC, database, host or renderer boundary. The read runs a fixed `cat` in
+// a fixed deployment through an argument vector (no shell), so no environment
+// value can ever become a shell token.
+//
+// Why the ledger is trustworthy evidence: the derived fixture answers exactly
+// one origin (the ZAI OpenAI chat-completions endpoint) and refuses every other
+// external origin, so a ledger row proves a real provider call happened, and
+// `imageSha256` is the digest of the exact PNG bytes that reached the wire.
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+
+/** The runner-owned opt-in that selects the derived-provider fixture lane. */
+export const IMAGE_CAPABILITIES_RUN_ID_PATTERN = /^image-capabilities-[a-f0-9]{12}$/
+
+/**
+ * The two model ids the derived fixture answers for. The fixture refuses every
+ * other model on the wire, so a mismatch here would produce a refused provider
+ * call instead of a usable oracle; the lane fails loud before that can happen.
+ */
+export const IMAGE_CAPABILITY_FIXTURE_MODELS = {
+ supported: 'glm-5.3-flash',
+ unsupported: 'glm-5.3',
+} as const
+
+/** Where the derived fixture publishes its provider-boundary ledger. */
+export const IMAGE_CAPABILITY_EVIDENCE = {
+ namespace: 'mcp-host',
+ deployment: 'chatllm',
+ path: '/tmp/image-capabilities-evidence.json',
+} as const
+
+/**
+ * Response kinds the fixture records. Declared here rather than imported from
+ * the fixture so the oracle stays independent of the producer: if the fixture
+ * changes what it emits, this lane must fail, not silently follow.
+ */
+export const FIXTURE_RESPONSE_KIND = {
+ tileColors: 'tile-colors',
+ textOnly: 'text-only',
+ rejected: 'rejected',
+} as const
+
+/** The fixture's text-only answer. It names no image and no color. */
+export const FIXTURE_TEXT_ONLY_CONTENT = 'IMAGE_FIXTURE_TEXT_OK'
+
+const SHA256_HEX = /^[a-f0-9]{64}$/
+const MINIKUBE_PROFILE_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1'])
+
+/** Bounded read: the command must never hang a verification run. */
+const KUBECTL_TIMEOUT_MS = 20_000
+const MAX_EVIDENCE_BYTES = 4 * 1024 * 1024
+
+export type ImageCapabilitiesMode = 'fixture' | 'real'
+
+/**
+ * Selects the lane from the environment alone.
+ *
+ * An unset run id means the caller is running the real-provider smoke journey.
+ * A malformed run id is never treated as "unset": that would silently downgrade
+ * a fixture run into a paid one.
+ */
+export function resolveImageCapabilitiesMode(
+ env: NodeJS.ProcessEnv = process.env
+): ImageCapabilitiesMode {
+ const runId = (env.IMAGE_CAPABILITIES_RUN_ID ?? '').trim()
+ if (!runId) return 'real'
+ if (!IMAGE_CAPABILITIES_RUN_ID_PATTERN.test(runId)) {
+ throw new Error(
+ `IMAGE_CAPABILITIES_RUN_ID="${runId}" is not a fixture run id: expected ` +
+ 'image-capabilities-<12 hex>. Unset it to run the real-provider smoke journey.'
+ )
+ }
+ return 'fixture'
+}
+
+function configured(value: string | undefined): string {
+ return (value ?? '').trim()
+}
+
+/** Every binding the fixture lane needs, after validation. */
+export interface ImageCapabilitiesFixtureEnv {
+ runId: string
+ profile: string
+ hostRef: string
+ externalRestApiBaseUrl: string
+ rpcProxyBaseUrl: string
+ supportedModel: string
+ unsupportedModel: string
+ unknownModel: string
+}
+
+function requireLoopbackTarget(label: string, rawUrl: string): URL {
+ let url: URL
+ try {
+ url = new URL(rawUrl)
+ } catch {
+ throw new Error(`${label} must be an absolute URL; received "${rawUrl}".`)
+ }
+ if (!LOOPBACK_HOSTS.has(url.hostname)) {
+ throw new Error(
+ `${label} targets a non-loopback host "${url.hostname}"; this lane runs only against the ` +
+ 'branch-owned local stack.'
+ )
+ }
+ return url
+}
+
+/**
+ * Resolves and validates the fixture lane's environment. Every problem is
+ * collected and reported together, because a half-configured run must fail at
+ * the gate rather than after an Electron launch.
+ *
+ * Deliberate strictness, each with a reason:
+ * - the run id selects the lane and is matched against the pod's own ledger;
+ * - the minikube profile must equal the real-PostgreSQL context, which is the
+ * binding the fixture container itself validates;
+ * - the host ref must be the deployment whose ledger is read, or the journey
+ * would talk to a different pod than the oracle;
+ * - both base URLs must be loopback, and the remote escape hatch is refused
+ * outright: this lane's oracle is a pod on this cluster;
+ * - the login identity is required instead of falling back to the shared
+ * defaults, so the journey can never run as a different user than the one
+ * the runner seeded;
+ * - the two wire models must be exactly the ids the fixture answers.
+ */
+export function requireImageCapabilitiesFixtureEnv(
+ env: NodeJS.ProcessEnv = process.env
+): ImageCapabilitiesFixtureEnv {
+ const problems: string[] = []
+
+ const runId = configured(env.IMAGE_CAPABILITIES_RUN_ID)
+ if (!IMAGE_CAPABILITIES_RUN_ID_PATTERN.test(runId)) {
+ problems.push(
+ `IMAGE_CAPABILITIES_RUN_ID must match image-capabilities-<12 hex> (received "${runId || '<unset>'}")`
+ )
+ }
+
+ const profile = configured(env.MINIKUBE_PROFILE)
+ const context = configured(env.CONTROL_API_REAL_PG_CONTEXT)
+ if (!MINIKUBE_PROFILE_PATTERN.test(profile)) {
+ problems.push(
+ `MINIKUBE_PROFILE must be a valid profile name (received "${profile || '<unset>'}")`
+ )
+ }
+ if (profile !== context) {
+ problems.push(
+ `MINIKUBE_PROFILE must equal CONTROL_API_REAL_PG_CONTEXT ` +
+ `(received "${profile || '<unset>'}" vs "${context || '<unset>'}")`
+ )
+ }
+
+ const hostRef = configured(env.E2E_HOST_REF)
+ if (hostRef !== IMAGE_CAPABILITY_EVIDENCE.deployment) {
+ problems.push(
+ `E2E_HOST_REF must be "${IMAGE_CAPABILITY_EVIDENCE.deployment}" so the journey and the ` +
+ `fixture ledger describe the same pod (received "${hostRef || '<unset>'}")`
+ )
+ }
+
+ if (configured(env.QA_RECORDER_ALLOW_REMOTE) === '1') {
+ problems.push('QA_RECORDER_ALLOW_REMOTE=1 is not available for this lane (loopback only)')
+ }
+
+ const externalRestApiBaseUrl = configured(env.EXTERNAL_REST_API_BASE_URL)
+ const rpcProxyBaseUrl = configured(env.RPC_PROXY_BASE_URL)
+ for (const [label, rawUrl] of [
+ ['EXTERNAL_REST_API_BASE_URL', externalRestApiBaseUrl],
+ ['RPC_PROXY_BASE_URL', rpcProxyBaseUrl],
+ ] as const) {
+ if (!rawUrl) {
+ problems.push(`${label} is required`)
+ continue
+ }
+ try {
+ requireLoopbackTarget(label, rawUrl)
+ } catch (error) {
+ problems.push((error as Error).message)
+ }
+ }
+
+ const email = configured(env.E2E_DEV_LOGIN_EMAIL)
+ if (!email) problems.push('E2E_DEV_LOGIN_EMAIL is required')
+
+ const desktopSecret = configured(env.E2E_DESKTOP_PASSWORD)
+ if (!desktopSecret) problems.push('E2E_DESKTOP_PASSWORD is required')
+
+ const supportedModel = configured(env.QA_RECORDER_IMAGE_MODEL_SUPPORTED)
+ const unsupportedModel = configured(env.QA_RECORDER_IMAGE_MODEL_UNSUPPORTED)
+ const unknownModel = configured(env.QA_RECORDER_IMAGE_MODEL_UNKNOWN)
+ if (supportedModel !== IMAGE_CAPABILITY_FIXTURE_MODELS.supported) {
+ problems.push(
+ `QA_RECORDER_IMAGE_MODEL_SUPPORTED must be the fixture's image model ` +
+ `"${IMAGE_CAPABILITY_FIXTURE_MODELS.supported}" (received "${supportedModel || '<unset>'}")`
+ )
+ }
+ if (unsupportedModel !== IMAGE_CAPABILITY_FIXTURE_MODELS.unsupported) {
+ problems.push(
+ `QA_RECORDER_IMAGE_MODEL_UNSUPPORTED must be the fixture's text model ` +
+ `"${IMAGE_CAPABILITY_FIXTURE_MODELS.unsupported}" (received "${unsupportedModel || '<unset>'}")`
+ )
+ }
+ if (!unknownModel) {
+ problems.push('QA_RECORDER_IMAGE_MODEL_UNKNOWN is required (the model with no image evidence)')
+ }
+ const modelIds = [supportedModel, unsupportedModel, unknownModel].filter(Boolean)
+ if (new Set(modelIds).size !== modelIds.length) {
+ problems.push('the three QA_RECORDER_IMAGE_MODEL_* ids must be distinct')
+ }
+
+ if (problems.length > 0) {
+ throw new Error(
+ 'image-capabilities fixture lane is not configured:\n' +
+ problems.map(problem => ` - ${problem}`).join('\n') +
+ '\nThe runner that starts this lane must export these exact bindings; this lane never ' +
+ 'reads .env.qa-recorder or the repository .env.'
+ )
+ }
+
+ return {
+ runId,
+ profile,
+ hostRef,
+ externalRestApiBaseUrl,
+ rpcProxyBaseUrl,
+ supportedModel,
+ unsupportedModel,
+ unknownModel,
+ }
+}
+
+/** One provider-boundary attempt, exactly as the derived fixture records it. */
+export interface FixtureProviderAttempt {
+ /** Model id, or null when the request was refused before its body was parsed. */
+ model: string | null
+ /** Digest of the exact PNG bytes that reached the wire, or null when none did. */
+ imageSha256: string | null
+ responseKind: string
+}
+
+export interface FixtureEvidenceCounters {
+ totalAttempts: number
+ imageAttempts: number
+ textAttempts: number
+ rejectedAttempts: number
+ tileColorResponses: number
+ textOnlyResponses: number
+ textModelImageRefusals: number
+ blockedEgress: number
+}
+
+export interface ImageCapabilityEvidenceSnapshot {
+ runId: string
+ profile: string
+ pid: number
+ counters: FixtureEvidenceCounters
+ attempts: FixtureProviderAttempt[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+const COUNTER_KEYS: readonly (keyof FixtureEvidenceCounters)[] = [
+ 'totalAttempts',
+ 'imageAttempts',
+ 'textAttempts',
+ 'rejectedAttempts',
+ 'tileColorResponses',
+ 'textOnlyResponses',
+ 'textModelImageRefusals',
+ 'blockedEgress',
+]
+
+function requireCounters(value: unknown, source: string): FixtureEvidenceCounters {
+ if (!isRecord(value)) throw new Error(`${source}: counters must be an object`)
+ const counters = {} as FixtureEvidenceCounters
+ for (const key of COUNTER_KEYS) {
+ const raw = value[key]
+ if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 0) {
+ throw new Error(
+ `${source}: counters.${key} must be a non-negative integer (received ${JSON.stringify(raw)})`
+ )
+ }
+ counters[key] = raw
+ }
+ return counters
+}
+
+const KNOWN_RESPONSE_KINDS: readonly string[] = Object.values(FIXTURE_RESPONSE_KIND)
+
+function requireAttemptRow(value: unknown, index: number, source: string): FixtureProviderAttempt {
+ if (!isRecord(value)) throw new Error(`${source}: attempts[${index}] must be an object`)
+
+ const model = value.model
+ if (model !== null && typeof model !== 'string') {
+ throw new Error(`${source}: attempts[${index}].model must be a string or null`)
+ }
+
+ const imageSha256 = value.imageSha256
+ if (imageSha256 !== null && !(typeof imageSha256 === 'string' && SHA256_HEX.test(imageSha256))) {
+ throw new Error(`${source}: attempts[${index}].imageSha256 must be a sha256 hex digest or null`)
+ }
+
+ const responseKind = value.responseKind
+ if (typeof responseKind !== 'string' || !KNOWN_RESPONSE_KINDS.includes(responseKind)) {
+ throw new Error(
+ `${source}: attempts[${index}].responseKind must be one of ${KNOWN_RESPONSE_KINDS.join(', ')} ` +
+ `(received ${JSON.stringify(responseKind)})`
+ )
+ }
+
+ return { model, imageSha256, responseKind }
+}
+
+/** Parses and validates the ledger; fixture fields this lane does not use are ignored. */
+function parseEvidenceSnapshot(
+ rawText: string,
+ source: string,
+ expected: { runId: string; profile: string }
+): ImageCapabilityEvidenceSnapshot {
+ let parsed: unknown
+ try {
+ parsed = JSON.parse(rawText)
+ } catch (error) {
+ throw new Error(`${source}: evidence is not valid JSON (${(error as Error).message})`)
+ }
+ if (!isRecord(parsed)) throw new Error(`${source}: evidence must be a JSON object`)
+
+ const runId = parsed.runId
+ if (typeof runId !== 'string' || !runId) {
+ throw new Error(`${source}: runId must be a non-empty string`)
+ }
+ if (runId !== expected.runId) {
+ throw new Error(
+ `${source}: the pod ledger belongs to run "${runId}" but this lane is configured for ` +
+ `"${expected.runId}"; refusing to use another run's evidence.`
+ )
+ }
+
+ const profile = parsed.profile
+ if (typeof profile !== 'string' || !profile) {
+ throw new Error(`${source}: profile must be a non-empty string`)
+ }
+ if (profile !== expected.profile) {
+ throw new Error(
+ `${source}: the pod ledger was written under profile "${profile}" but this lane runs ` +
+ `"${expected.profile}".`
+ )
+ }
+
+ const pid = parsed.pid
+ if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+ throw new Error(`${source}: pid must be a positive integer`)
+ }
+
+ const counters = requireCounters(parsed.counters, source)
+
+ const attemptsRaw = parsed.attempts
+ if (!Array.isArray(attemptsRaw)) {
+ throw new Error(
+ `${source}: attempts must be an array. The derived fixture publishes one row per ` +
+ 'provider-boundary attempt under "attempts".'
+ )
+ }
+ const attempts = attemptsRaw.map((row, index) => requireAttemptRow(row, index, source))
+
+ if (attempts.length !== counters.totalAttempts) {
+ throw new Error(
+ `${source}: attempts.length (${attempts.length}) must equal counters.totalAttempts ` +
+ `(${counters.totalAttempts}); the ledger is not internally consistent.`
+ )
+ }
+
+ return { runId, profile, pid, counters, attempts }
+}
+
+function describeExecFailure(error: unknown): string {
+ const stderr = isRecord(error) && typeof error.stderr === 'string' ? error.stderr.trim() : ''
+ const message = error instanceof Error ? error.message : String(error)
+ return stderr ? `${message}\n${stderr}` : message
+}
+
+/**
+ * Reads the derived fixture's provider-boundary ledger, read-only.
+ *
+ * The namespace, deployment and path are fixed constants, the context is the
+ * validated profile, and the call is bounded by a request timeout, so this can
+ * neither reach another cluster nor hang a verification run. Arguments are
+ * passed as a vector, never through a shell.
+ */
+export function readImageCapabilityEvidence(target: {
+ runId: string
+ profile: string
+}): ImageCapabilityEvidenceSnapshot {
+ const args = [
+ '--context',
+ target.profile,
+ '--request-timeout=20s',
+ '-n',
+ IMAGE_CAPABILITY_EVIDENCE.namespace,
+ 'exec',
+ `deploy/${IMAGE_CAPABILITY_EVIDENCE.deployment}`,
+ '--',
+ 'cat',
+ IMAGE_CAPABILITY_EVIDENCE.path,
+ ]
+ const command = `kubectl ${args.join(' ')}`
+
+ let stdout: string
+ try {
+ stdout = execFileSync('kubectl', args, {
+ encoding: 'utf8',
+ timeout: KUBECTL_TIMEOUT_MS,
+ maxBuffer: MAX_EVIDENCE_BYTES,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ } catch (error) {
+ throw new Error(
+ `[image-capabilities] read-only evidence read failed: ${command}\n${describeExecFailure(error)}`
+ )
+ }
+
+ return parseEvidenceSnapshot(stdout, command, target)
+}
+
+/**
+ * Returns the rows appended between two reads of the same fixture process.
+ *
+ * Both invariants matter: the ledger must only ever grow, and the process id
+ * must be unchanged. A pod restart between the two reads would otherwise let a
+ * stale row satisfy the oracle.
+ */
+export function appendedAttempts(
+ before: ImageCapabilityEvidenceSnapshot,
+ after: ImageCapabilityEvidenceSnapshot
+): FixtureProviderAttempt[] {
+ if (after.pid !== before.pid) {
+ throw new Error(
+ `[image-capabilities] the fixture process changed between reads (${before.pid} -> ` +
+ `${after.pid}); the ledger cannot be correlated across a restart.`
+ )
+ }
+ if (after.attempts.length < before.attempts.length) {
+ throw new Error(
+ `[image-capabilities] the ledger shrank between reads (${before.attempts.length} -> ` +
+ `${after.attempts.length}); it must only ever grow.`
+ )
+ }
+ for (const [index, row] of before.attempts.entries()) {
+ const current = after.attempts[index]
+ if (
+ !current ||
+ current.model !== row.model ||
+ current.imageSha256 !== row.imageSha256 ||
+ current.responseKind !== row.responseKind
+ ) {
+ throw new Error(
+ `[image-capabilities] ledger row ${index} changed between reads; the ledger must be append-only.`
+ )
+ }
+ }
+ return after.attempts.slice(before.attempts.length)
+}
+
+/** Lowercase sha256 of the exact bytes a caller handed to the composer. */
+export function sha256Hex(bytes: Buffer): string {
+ return createHash('sha256').update(bytes).digest('hex')
+}
diff --git a/desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts b/desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts
new file mode 100644
index 000000000..743fb4c0d
--- /dev/null
+++ b/desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts
@@ -0,0 +1,169 @@
+// desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts
+//
+// E2E_GUARDIAN_IPC_FLOW: fixture-only module. It renders deterministic PNG bytes
+// and matchers for the caller; it never drives the Electron app, so it has no
+// route or network transition to await. The journey in
+// qa-recorder-image-capabilities.spec.ts owns the IPC-flow oracle.
+//
+// Real PNG fixture for the Desktop image-capability recorder journey.
+//
+// The journey needs an image whose content the test knows exactly and the model
+// can only learn by reading the pixels. Nothing in the prompt or the filename
+// discloses the colors: the assertion is the ordered tile sequence, so a run
+// that never delivered the image cannot pass by guessing.
+//
+// The encoder is deliberately dependency-free (node:zlib + a local CRC32) so the
+// fixture cannot drift with a third-party image library, and the bytes are a
+// standards-compliant PNG that any viewer can open.
+import { crc32, deflateSync } from 'node:zlib'
+
+/** Twelve visually distinct, unambiguous, named colors. */
+export const IMAGE_FIXTURE_PALETTE = [
+ 'red',
+ 'blue',
+ 'green',
+ 'yellow',
+ 'orange',
+ 'purple',
+ 'magenta',
+ 'cyan',
+ 'brown',
+ 'pink',
+ 'gray',
+ 'lime',
+] as const
+
+type Rgb = readonly [number, number, number]
+
+/** Exact RGB values used to paint each named color. */
+export const IMAGE_FIXTURE_RGB: Record<(typeof IMAGE_FIXTURE_PALETTE)[number], Rgb> = {
+ red: [220, 30, 30],
+ blue: [30, 70, 220],
+ green: [30, 170, 60],
+ yellow: [245, 220, 25],
+ orange: [250, 140, 20],
+ purple: [135, 60, 200],
+ magenta: [230, 40, 190],
+ cyan: [30, 205, 220],
+ brown: [125, 80, 45],
+ pink: [250, 160, 200],
+ gray: [135, 135, 135],
+ lime: [175, 235, 35],
+}
+
+export const IMAGE_FIXTURE_COLUMNS = 2
+export const IMAGE_FIXTURE_ROWS = 3
+/** Tile dimensions chosen so each color block dominates its cell. */
+export const IMAGE_FIXTURE_TILE_WIDTH = 320
+export const IMAGE_FIXTURE_TILE_HEIGHT = 240
+
+export interface ImageFixture {
+ /** Standards-compliant PNG bytes for the two-by-three tile grid. */
+ png: Buffer
+ /**
+ * The tile colors in reading order (left to right, top to bottom). This is the
+ * ordered sequence the model must report back; it is never sent to the model.
+ */
+ orderedColors: string[]
+ /** Opaque file name that does not encode the colors. */
+ fileName: string
+}
+
+/** Deterministic PRNG so a failing run can be reproduced from its seed. */
+function mulberry32(seed: number): () => number {
+ let state = seed >>> 0
+ return () => {
+ state = (state + 0x6d2b79f5) >>> 0
+ let t = state
+ t = Math.imul(t ^ (t >>> 15), t | 1)
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+ }
+}
+
+function pngChunk(type: string, data: Buffer): Buffer {
+ const length = Buffer.alloc(4)
+ length.writeUInt32BE(data.length, 0)
+ const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data])
+ const crc = Buffer.alloc(4)
+ crc.writeUInt32BE(crc32(typeAndData), 0)
+ return Buffer.concat([length, typeAndData, crc])
+}
+
+export function encodePng(
+ width: number,
+ height: number,
+ pixelAt: (x: number, y: number) => Rgb
+): Buffer {
+ const bytesPerRow = width * 3
+ // One filter byte (0 = None) per scanline, then the RGB triples.
+ const raw = Buffer.alloc((bytesPerRow + 1) * height)
+ for (let y = 0; y < height; y += 1) {
+ const rowStart = y * (bytesPerRow + 1)
+ raw[rowStart] = 0
+ for (let x = 0; x < width; x += 1) {
+ const [r, g, b] = pixelAt(x, y)
+ const offset = rowStart + 1 + x * 3
+ raw[offset] = r
+ raw[offset + 1] = g
+ raw[offset + 2] = b
+ }
+ }
+
+ const ihdr = Buffer.alloc(13)
+ ihdr.writeUInt32BE(width, 0)
+ ihdr.writeUInt32BE(height, 4)
+ ihdr[8] = 8 // bit depth
+ ihdr[9] = 2 // color type: truecolor RGB
+ ihdr[10] = 0 // compression
+ ihdr[11] = 0 // filter
+ ihdr[12] = 0 // interlace
+
+ return Buffer.concat([
+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ pngChunk('IHDR', ihdr),
+ pngChunk('IDAT', deflateSync(raw, { level: 9 })),
+ pngChunk('IEND', Buffer.alloc(0)),
+ ])
+}
+
+/**
+ * Builds the ordered tile grid. Pass an explicit seed to reproduce a run; the
+ * default seed is random so the sequence cannot be memorized between runs.
+ */
+export function buildImageFixture(seed?: number): ImageFixture {
+ const resolvedSeed = seed ?? Math.floor(Math.random() * 0xffffffff)
+ const random = mulberry32(resolvedSeed)
+
+ const pool = [...IMAGE_FIXTURE_PALETTE]
+ const orderedColors: string[] = []
+ const tileCount = IMAGE_FIXTURE_COLUMNS * IMAGE_FIXTURE_ROWS
+ for (let index = 0; index < tileCount; index += 1) {
+ const pick = Math.floor(random() * pool.length)
+ orderedColors.push(pool.splice(pick, 1)[0]!)
+ }
+
+ const width = IMAGE_FIXTURE_COLUMNS * IMAGE_FIXTURE_TILE_WIDTH
+ const height = IMAGE_FIXTURE_ROWS * IMAGE_FIXTURE_TILE_HEIGHT
+ const png = encodePng(width, height, (x, y) => {
+ const column = Math.floor(x / IMAGE_FIXTURE_TILE_WIDTH)
+ const row = Math.floor(y / IMAGE_FIXTURE_TILE_HEIGHT)
+ const color = orderedColors[row * IMAGE_FIXTURE_COLUMNS + column]!
+ return IMAGE_FIXTURE_RGB[color as keyof typeof IMAGE_FIXTURE_RGB]
+ })
+
+ return {
+ png,
+ orderedColors,
+ fileName: 'visual-input.png',
+ }
+}
+
+/**
+ * Case-insensitive matcher for the model's report. Tolerates a chatty sentence
+ * around the list while still requiring the exact ordered sequence.
+ */
+export function orderedColorListRegex(orderedColors: string[]): RegExp {
+ const escaped = orderedColors.map(color => color.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+ return new RegExp(`\\b${escaped.join('\\s*,\\s*')}\\b`, 'i')
+}
diff --git a/desktop-app/test/e2e-playwright/playwright.image-capabilities.config.ts b/desktop-app/test/e2e-playwright/playwright.image-capabilities.config.ts
new file mode 100644
index 000000000..60a8c43d7
--- /dev/null
+++ b/desktop-app/test/e2e-playwright/playwright.image-capabilities.config.ts
@@ -0,0 +1,65 @@
+import { defineConfig } from '@playwright/test'
+import path from 'node:path'
+import { requireImageCapabilitiesFixtureEnv } from './helpers/imageCapabilityEvidence'
+
+// E2E_GUARDIAN_IPC_FLOW: this file only configures the runner. The spec owns
+// visible IPC transitions and reads the external provider ledger as its wire oracle.
+
+/*
+ * Desktop App image-capability E2E lane (issue #654).
+ *
+ * This config is deliberately separate from playwright.qa-recorder.config.ts:
+ *
+ * - It loads NO env file. The sibling recorder config calls
+ * loadQaRecorderEnv(), which reads .env.qa-recorder into process.env; this
+ * lane must never inherit a developer's recorder identity, a paid opt-in, or
+ * a stray QA_RECORDER_ALLOW_REMOTE escape hatch. Every binding it needs is
+ * exported by the runner that starts it, and a missing or inconsistent
+ * binding fails here, at config load, before Playwright launches anything.
+ * - It matches only the image-capabilities journey, so no other recorder
+ * journey can run from this lane.
+ *
+ * The journey is a real end-to-end run against the branch-owned local stack:
+ * real Electron app, real sign-in through the visible form, real IPC, real
+ * host, real database, real RPC proxy. The only simulated party is the external
+ * ZAI origin, which the derived in-cluster fixture answers (see
+ * tests/e2e/fixtures/image-capabilities). That fixture is what makes the run
+ * deterministic and free, and its ledger is the journey's business oracle.
+ */
+
+const repoRoot = path.resolve(__dirname, '../../..')
+
+// NODE_ENV=test is this lane's contract, and it is safe here: no code under
+// desktop-app branches on NODE_ENV (verified), so pinning it cannot change
+// product behavior. An ambient non-test value is a misconfiguration, not
+// something to overwrite silently.
+if (process.env.NODE_ENV !== undefined && process.env.NODE_ENV !== 'test') {
+ throw new Error(
+ `NODE_ENV must be "test" (or unset) for the image-capabilities fixture lane; ` +
+ `received "${process.env.NODE_ENV}".`
+ )
+}
+process.env.NODE_ENV = 'test'
+
+// Fail at config load, with every missing binding listed at once.
+requireImageCapabilitiesFixtureEnv(process.env)
+
+const recorderRoot = process.env.QA_RECORDER_ROOT
+ ? path.resolve(process.env.QA_RECORDER_ROOT)
+ : path.join(repoRoot, '.local-notes', 'qa-recorder')
+
+export default defineConfig({
+ testDir: '.',
+ // Only the image-capability journey: every other qa-recorder spec talks to a
+ // real provider, which this lane must never do.
+ testMatch: /qa-recorder-image-capabilities\.spec\.ts/,
+ // Three chats (unknown-capability gate, visual answer, remove-image text
+ // answer) plus one real Electron launch and one real sign-in.
+ timeout: 300_000,
+ expect: { timeout: 30_000 },
+ retries: 0,
+ workers: 1,
+ reporter: [['list']],
+ outputDir: path.join(recorderRoot, 'runs', 'desktop-app-image-capabilities'),
+ preserveOutput: 'always',
+})
diff --git a/desktop-app/test/e2e-playwright/qa-recorder-helpers.ts b/desktop-app/test/e2e-playwright/qa-recorder-helpers.ts
index 0fd10996c..8aac2b570 100644
--- a/desktop-app/test/e2e-playwright/qa-recorder-helpers.ts
+++ b/desktop-app/test/e2e-playwright/qa-recorder-helpers.ts
@@ -122,7 +122,10 @@ export function configuredHostRef(): string {
* closing the app (use finalizeRecording in a finally block) so the video file
* is finalized on disk.
*/
-export async function launchDesktopApp(testInfo: TestInfo): Promise<{
+export async function launchDesktopApp(
+ testInfo: TestInfo,
+ isolationTarget?: string
+): Promise<{
app: ElectronApplication
page: Page
}> {
@@ -130,7 +133,10 @@ export async function launchDesktopApp(testInfo: TestInfo): Promise<{
throw new Error(`Desktop app build missing at ${MAIN_ENTRY}. Run npm run build first.`)
}
- const userDataDir = testInfo.outputPath('electron-user-data')
+ const isolationRunDir = testInfo.outputPath('electron-isolation')
+ const userDataDir = isolationTarget
+ ? path.join(isolationRunDir, 'user-data')
+ : testInfo.outputPath('electron-user-data')
const videoDir = testInfo.outputPath('video')
fs.mkdirSync(userDataDir, { recursive: true })
fs.mkdirSync(videoDir, { recursive: true })
@@ -144,7 +150,20 @@ export async function launchDesktopApp(testInfo: TestInfo): Promise<{
ELECTRON_RENDERER_URL: '',
EXTERNAL_REST_API_BASE_URL,
RPC_PROXY_BASE_URL,
- CLERUM_DESKTOP_CONFIG_PATH: path.join(userDataDir, 'runtime-config.json'),
+ CLERUM_DESKTOP_CONFIG_PATH: path.join(
+ isolationTarget ? isolationRunDir : userDataDir,
+ 'runtime-config.json'
+ ),
+ ...(isolationTarget
+ ? {
+ EVENFIRE_DEV_ISOLATION: '1',
+ EVENFIRE_DEV_ISOLATION_RUN_DIR: isolationRunDir,
+ EVENFIRE_DEV_ISOLATION_TARGET: isolationTarget,
+ EVENFIRE_DEV_ISOLATION_REST_URL: EXTERNAL_REST_API_BASE_URL,
+ EVENFIRE_DEV_ISOLATION_RPC_URL: RPC_PROXY_BASE_URL,
+ EVENFIRE_DEV_ISOLATION_APP_PATH: path.dirname(MAIN_ENTRY),
+ }
+ : {}),
},
recordVideo:
process.env.QA_RECORDER_VIDEO === '0'
diff --git a/desktop-app/test/e2e-playwright/qa-recorder-image-capabilities.spec.ts b/desktop-app/test/e2e-playwright/qa-recorder-image-capabilities.spec.ts
new file mode 100644
index 000000000..9197ac200
--- /dev/null
+++ b/desktop-app/test/e2e-playwright/qa-recorder-image-capabilities.spec.ts
@@ -0,0 +1,788 @@
+import { type ElectronApplication, type Page, type TestInfo, expect, test } from '@playwright/test'
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import {
+ FIXTURE_RESPONSE_KIND,
+ FIXTURE_TEXT_ONLY_CONTENT,
+ IMAGE_CAPABILITY_FIXTURE_MODELS,
+ appendedAttempts,
+ readImageCapabilityEvidence,
+ requireImageCapabilitiesFixtureEnv,
+ resolveImageCapabilitiesMode,
+ sha256Hex,
+} from './helpers/imageCapabilityEvidence'
+import { buildImageFixture, orderedColorListRegex } from './helpers/qaRecorderImageFixture'
+import {
+ DESKTOP_APP_ROOT,
+ EXTERNAL_REST_API_BASE_URL,
+ MAIN_ENTRY,
+ RPC_PROXY_BASE_URL,
+ assertAllowedTarget,
+ configuredHostRef,
+ desktopCredentials,
+ finalizeRecording,
+ launchDesktopApp,
+ login,
+ requireRecorderConfirm,
+ screenshotAndLog,
+} from './qa-recorder-helpers'
+
+function instanceBindingCheck(app: ElectronApplication, page: Page, testInfo: TestInfo) {
+ const expectedRun = path.resolve(testInfo.outputPath('electron-isolation'))
+ const expectedData = path.join(expectedRun, 'user-data')
+ const expectedConfig = path.join(expectedRun, 'runtime-config.json')
+ const expectedExecutable = createRequire(path.join(DESKTOP_APP_ROOT, 'package.json'))(
+ 'electron'
+ ) as string
+ // Public environment identity contract: both effective origins contribute.
+ // An env-only launch does not necessarily have a saved selector option.
+ const restOrigin = new URL(EXTERNAL_REST_API_BASE_URL).origin
+ const rpcOrigin = new URL(RPC_PROXY_BASE_URL).origin
+ const slug = `${restOrigin}_${rpcOrigin}`
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '_')
+ .replace(/^_+|_+$/g, '')
+ .slice(0, 48)
+ const expectedEnvKey = `${slug}-${sha256Hex(Buffer.from(`${restOrigin}|rpc=${rpcOrigin}`)).slice(0, 12)}`
+ let firstEnvKey: string | undefined
+ return async () => {
+ // Observe the running processes and IPC configuration, rather than trusting
+ // launch environment variables. This never changes selection or auth state.
+ const identity = await app.evaluate(({ app: electronApp }) => ({
+ pid: process.pid,
+ argv: process.argv,
+ executable: electronApp.getPath('exe'),
+ userData: electronApp.getPath('userData'),
+ }))
+ const runtime = await page.evaluate(async () => {
+ const state = await window.clerum.auth.getRuntimeConfigState()
+ return {
+ storagePath: state.storagePath,
+ envKey: state.envKey,
+ }
+ })
+ expect(identity.pid).toBe(app.process().pid)
+ expect(identity.argv.includes(MAIN_ENTRY)).toBe(true)
+ expect(fs.realpathSync(identity.executable)).toBe(fs.realpathSync(expectedExecutable))
+ expect(path.resolve(identity.userData)).toBe(expectedData)
+ expect(path.resolve(runtime.storagePath)).toBe(expectedConfig)
+ expect(runtime.envKey).toBe(expectedEnvKey)
+ if (firstEnvKey !== undefined) expect(runtime.envKey).toBe(firstEnvKey)
+ firstEnvKey = runtime.envKey
+ fs.writeFileSync(
+ testInfo.outputPath('instance-binding.json'),
+ JSON.stringify(
+ {
+ issue: 654,
+ pid: identity.pid,
+ mainEntry: MAIN_ENTRY,
+ executable: identity.executable,
+ userData: expectedData,
+ config: expectedConfig,
+ envKey: runtime.envKey,
+ expectedRest: EXTERNAL_REST_API_BASE_URL,
+ expectedRpc: RPC_PROXY_BASE_URL,
+ },
+ null,
+ 2
+ ),
+ { mode: 0o600 }
+ )
+ }
+}
+
+async function observeCompletedTask(
+ page: Page,
+ host: string,
+ expectedAnswer: RegExp
+): Promise<string> {
+ const visibleIds = await page
+ .locator('[data-chat-message-id]')
+ .evaluateAll(elements => elements.map(element => element.getAttribute('data-chat-message-id')))
+ expect(visibleIds).toHaveLength(2)
+ let observed: { taskId: string; result: string } | null = null
+ // Read-only business oracle AFTER the visible send and response. These IPC
+ // reads do not log in, create a chat, select a model, send or mutate state.
+ // They correlate the two rendered messages with one durable Host task.
+ await expect
+ .poll(
+ async () => {
+ observed = await page.evaluate(
+ async ({ hostRef, ids }) => {
+ const chats = await window.clerum.chat.list(hostRef)
+ for (const chat of chats.slice(0, 20)) {
+ const messages = await window.clerum.chat.loadMessages(hostRef, chat.id)
+ const pair = ids.map(id => messages.find(message => message.id === id))
+ const taskId = pair[0]?.task_id
+ if (!taskId || pair[1]?.task_id !== taskId) continue
+ const result = await window.clerum.rpc.getTaskResult(hostRef, taskId)
+ return { taskId, result: JSON.stringify(result) }
+ }
+ return null
+ },
+ { hostRef: host, ids: visibleIds }
+ )
+ return observed?.result ?? ''
+ },
+ { timeout: 30_000 }
+ )
+ .toMatch(expectedAnswer)
+ expect(observed).not.toBeNull()
+ return observed!.taskId
+}
+
+/*
+ * E2E_GUARDIAN_IPC_FLOW: Desktop chat, the model catalog, the agent list and the
+ * composer all travel over Electron IPC (main-process handlers in desktop-app/src),
+ * so the renderer has no HTTP request to await for any transition in this
+ * journey. The visible/business oracles are the composer's own DOM contracts,
+ * the persisted thread, and — in fixture mode — the provider-boundary ledger of
+ * the derived in-cluster fixture.
+ *
+ * Issue #654 regression guard: the image-input capability comes from the real
+ * host/catalog projection, never from a provider name or a local default.
+ *
+ * Two lanes share this file:
+ *
+ * 1. the real-provider smoke (no IMAGE_CAPABILITIES_RUN_ID), which is opt-in
+ * via QA_RECORDER_CONFIRM_CHAT because it spends provider tokens;
+ * 2. the fixture lane (IMAGE_CAPABILITIES_RUN_ID=image-capabilities-<12 hex>),
+ * which answers the external ZAI origin from a derived in-cluster fixture,
+ * so it is deterministic and free, and it is gated by its own run id plus
+ * the fixture ledger it reads before the first send.
+ *
+ * Both lanes drive the same real application, sign-in form, IPC, host and
+ * database. Only the external provider peer is simulated, in fixture mode only.
+ */
+
+/** The lane is selected by the environment alone; see the helper. */
+const MODE = resolveImageCapabilitiesMode()
+
+/** Model names exactly as the host catalog projects them. No invented defaults. */
+const SUPPORTED_MODEL = (process.env.QA_RECORDER_IMAGE_MODEL_SUPPORTED ?? '').trim()
+const UNSUPPORTED_MODEL = (process.env.QA_RECORDER_IMAGE_MODEL_UNSUPPORTED ?? '').trim()
+
+/**
+ * The prompt names neither the colors nor the tile order: the only way to
+ * answer it is to have received the pixels.
+ */
+const VISUAL_PROMPT =
+ 'This image is a grid of two columns and three rows of solid color tiles. ' +
+ 'Reply with the colors in reading order, left to right then top to bottom, ' +
+ 'as a single comma-separated list on one line.'
+
+/**
+ * Fail loud when the real-provider smoke DID start but the model configuration
+ * is unusable. There is deliberately no default: a guessed model name would
+ * silently test the wrong capability, which is exactly the false confidence
+ * issue #654 guards.
+ */
+function requireModelNames(): { supportedModel: string; unsupportedModel: string } {
+ if (!SUPPORTED_MODEL || !UNSUPPORTED_MODEL) {
+ throw new Error(
+ 'QA_RECORDER_IMAGE_MODEL_SUPPORTED and QA_RECORDER_IMAGE_MODEL_UNSUPPORTED are required: ' +
+ 'name the exact image-capable and text-only models from the real host catalog. This ' +
+ 'journey has no default model and must never guess one.'
+ )
+ }
+ if (SUPPORTED_MODEL === UNSUPPORTED_MODEL) {
+ throw new Error(
+ 'QA_RECORDER_IMAGE_MODEL_SUPPORTED and QA_RECORDER_IMAGE_MODEL_UNSUPPORTED must differ.'
+ )
+ }
+ return { supportedModel: SUPPORTED_MODEL, unsupportedModel: UNSUPPORTED_MODEL }
+}
+
+/**
+ * Match a catalog row by model name. The row's accessible name appends at most
+ * one hint tag ("no images", "images not verified"), so the row test id
+ * identifies exactly one row without a positional selector.
+ */
+function catalogModelRow(page: Page, model: string) {
+ return page.getByTestId(`model-option-${model}`)
+}
+
+function modelChip(page: Page) {
+ return page.getByTestId('selected-chat-model')
+}
+
+function modelMenu(page: Page) {
+ return page.getByRole('menu', { name: 'Select model' })
+}
+
+function composer(page: Page) {
+ return page.getByRole('textbox', { name: 'Agent message composer' })
+}
+
+function sendButton(page: Page) {
+ return page.getByTestId('send-button')
+}
+
+function capabilityNotice(page: Page) {
+ return page.getByTestId('composer-image-capability-notice')
+}
+
+function attachmentChips(page: Page) {
+ return page.locator('.composer-attachment-chip')
+}
+
+function attachContextMenu(page: Page) {
+ return page
+ .getByRole('menu')
+ .filter({ has: page.getByRole('menuitem', { name: 'Upload Files' }) })
+}
+
+/** Start a blank chat and prove the thread is empty before anything is sent. */
+async function startBlankChat(page: Page) {
+ await page.getByTestId('nav-new-chat').click()
+ await expect(composer(page)).toBeVisible({ timeout: 30_000 })
+ await expect(page.locator('[data-chat-message-id]')).toHaveCount(0, { timeout: 20_000 })
+}
+
+/**
+ * Land on the exact configured agent through the visible Switch chat agent
+ * menu. The composer is only trusted once the switch control reports the
+ * configured host reference, so an auto-selected agent cannot satisfy this.
+ */
+async function openConfiguredAgentChat(page: Page, hostRef: string) {
+ await page.getByTestId('nav-chat').click()
+ const switchAgent = page.getByRole('button', { name: 'Switch chat agent' })
+ await expect(switchAgent).toBeVisible({ timeout: 30_000 })
+ await switchAgent.click()
+ const visibleName = new RegExp(`^${hostRef.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'i')
+ const agentMenuItem = page.getByRole('menuitem', { name: visibleName })
+ await expect(agentMenuItem).toHaveCount(1)
+ await agentMenuItem.click()
+ await expect(switchAgent).toContainText(
+ new RegExp(hostRef.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+ )
+}
+
+/** The model options menu, opened from the composer's own chip. */
+async function openModelMenu(page: Page) {
+ await expect(modelChip(page)).toBeVisible({ timeout: 30_000 })
+ await modelChip(page).click()
+ const menu = modelMenu(page)
+ await expect(menu).toBeVisible({ timeout: 20_000 })
+ return menu
+}
+
+/**
+ * Selects a model through the visible popover, asserting the host-projected
+ * image capability hint for that model before the click.
+ */
+async function selectModel(
+ page: Page,
+ model: string,
+ imageState: 'supported' | 'unsupported' | 'unknown'
+) {
+ await openModelMenu(page)
+
+ const row = catalogModelRow(page, model)
+ await expect(row).toHaveCount(1)
+ await expect(row).toBeVisible()
+ await expect(row).toHaveAttribute('role', 'menuitemradio')
+ if (imageState === 'unsupported') {
+ await expect(row.getByText('no images', { exact: true })).toBeVisible()
+ } else if (imageState === 'unknown') {
+ // No evidence is not the same claim as "known to be text-only".
+ await expect(row.getByText('images not verified', { exact: true })).toBeVisible()
+ await expect(row.getByText('no images', { exact: true })).toHaveCount(0)
+ } else {
+ await expect(row.getByText('no images', { exact: true })).toHaveCount(0)
+ await expect(row.getByText('images not verified', { exact: true })).toHaveCount(0)
+ }
+ await row.click()
+
+ // State oracle: the chip now reports the model the catalog selected.
+ await expect(modelChip(page)).toHaveAttribute('data-model-id', model)
+ // Selection identity can render before capability refresh settles. Assert
+ // the selected model's visible capability before attempting the next action.
+ if (imageState === 'supported') {
+ await expect(modelChip(page)).not.toHaveAttribute('title', /cannot receive|not verified/i)
+ } else {
+ await expect(modelChip(page)).toHaveAttribute(
+ 'title',
+ imageState === 'unsupported' ? /cannot receive images/i : /not verified/i
+ )
+ }
+}
+
+/**
+ * Attach a real PNG exactly the way a user does: Add context -> Upload Files ->
+ * native picker. No storage write, no IPC mock, no forced event.
+ */
+async function attachFixturePng(
+ page: Page,
+ fixture: { png: Buffer; fileName: string }
+): Promise<void> {
+ const attachButton = page.getByRole('button', { name: 'Add context' })
+ await expect(attachButton).toBeEnabled()
+ await attachButton.click()
+ await expect(attachContextMenu(page)).toBeVisible({ timeout: 15_000 })
+ const uploadItem = page.getByRole('menuitem', { name: 'Upload Files' })
+ await expect(uploadItem).toBeEnabled()
+
+ const [fileChooser] = await Promise.all([
+ page.waitForEvent('filechooser', { timeout: 15_000 }),
+ uploadItem.click(),
+ ])
+ await fileChooser.setFiles({
+ name: fixture.fileName,
+ mimeType: 'image/png',
+ buffer: fixture.png,
+ })
+
+ const attachmentChip = attachmentChips(page).filter({ hasText: fixture.fileName })
+ await expect(attachmentChip).toHaveCount(1, { timeout: 20_000 })
+ await expect(attachmentChip).toBeVisible()
+}
+
+/**
+ * The blocked-send contract for a pending image on a model that cannot take
+ * one: the chip and the draft survive, the button is refused, Enter is refused,
+ * and the notice names the blocking model.
+ */
+async function expectImageSendBlocked(
+ page: Page,
+ model: string,
+ draft: string,
+ attachmentName: string,
+ messagePattern: RegExp
+) {
+ await expect(modelChip(page)).toHaveAttribute('data-model-id', model)
+ await expect(attachmentChips(page).filter({ hasText: attachmentName })).toBeVisible()
+ await expect(composer(page)).toHaveValue(draft)
+
+ await expect(sendButton(page)).toBeDisabled({ timeout: 20_000 })
+ const notice = capabilityNotice(page)
+ await expect(notice).toBeVisible()
+ await expect(notice).toContainText(model)
+ await expect(notice).toContainText(messagePattern)
+
+ // Enter must not reach the controller either: nothing is delivered, the draft
+ // survives, and the chip is still pending.
+ await composer(page).press('Enter')
+ await expect(page.locator('[data-chat-message-id]')).toHaveCount(0)
+ await expect(composer(page)).toHaveValue(draft)
+ await expect(attachmentChips(page).filter({ hasText: attachmentName })).toBeVisible()
+ await expect(sendButton(page)).toBeDisabled()
+}
+
+/**
+ * A model with no image evidence must refuse the picker itself: the native file
+ * chooser must never open, and the composer must say why.
+ *
+ * The bounded `waitForEvent('filechooser')` is a race against the product's own
+ * signal, not a sleep used as readiness: if the picker opened, the event fires
+ * within milliseconds and the assertion below fails.
+ */
+async function expectUploadRefused(page: Page, model: string, messagePattern: RegExp) {
+ const attachButton = page.getByRole('button', { name: 'Add context' })
+ await expect(attachButton).toBeEnabled()
+ await attachButton.click()
+ const uploadItem = page.getByRole('menuitem', { name: 'Upload Files' })
+ await expect(uploadItem).toBeVisible({ timeout: 15_000 })
+
+ let chooserOpened = false
+ const chooserProbe = page.waitForEvent('filechooser', { timeout: 2_000 }).then(
+ () => {
+ chooserOpened = true
+ },
+ () => undefined
+ )
+
+ await uploadItem.click()
+ const notice = page.getByRole('alert').filter({ hasText: messagePattern })
+ await expect(notice).toBeVisible()
+ await expect(notice).toContainText(model)
+ await expect(notice).toContainText(messagePattern)
+
+ await chooserProbe
+ expect(chooserOpened, `${model} must not open the native file picker`).toBe(false)
+ await expect(attachmentChips(page)).toHaveCount(0)
+
+ // Close the composer menu again through an ordinary click, the same way a
+ // user dismisses it, so the next step starts from a clean composer.
+ await composer(page).click()
+ await expect(uploadItem).toHaveCount(0)
+}
+
+/** Exactly one exchange in this chat, and the answer is not empty. */
+async function expectSingleExchange(page: Page) {
+ await expect(page.getByTestId('message-list')).toBeVisible({ timeout: 20_000 })
+ await expect(page.locator('[data-chat-message-id]')).toHaveCount(2, { timeout: 120_000 })
+ const response = page.getByTestId('agent-response')
+ await expect(response).toHaveCount(1, { timeout: 120_000 })
+ // The article also contains the timestamp; assert the answer body itself.
+ const body = response.locator('.message-block.markdown-content')
+ await expect(body).toHaveCount(1, { timeout: 120_000 })
+ await expect(body).not.toHaveText('', { timeout: 120_000 })
+ return body
+}
+
+/** Case-insensitive matcher for "any of these tile colors". */
+function anyColorRegex(colors: string[]): RegExp {
+ return new RegExp(colors.join('|'), 'i')
+}
+
+/**
+ * The fixture's text-only answer, matched from the exported marker rather than
+ * a retyped literal. The underscores are optional in the pattern because the
+ * bubble renders Markdown, which may treat the intraword underscores as
+ * emphasis; the provider ledger below pins the exact response kind regardless.
+ */
+function fixtureTextAnswerRegex(): RegExp {
+ return new RegExp(FIXTURE_TEXT_ONLY_CONTENT.replace(/_/g, '[_-]?'), 'i')
+}
+
+/**
+ * Reach the authenticated shell through the real form.
+ *
+ * The credential fields themselves are driven by the shared `login` helper: it
+ * already owns that form, and this journey only needs a deterministic decision
+ * between the two legitimate entry states (form vs. an already-authenticated
+ * shell left behind by a persisted session).
+ *
+ * The negative assertion in the middle is the point: while the form is still
+ * unsent, the authenticated surface must not be mounted at all. Otherwise the
+ * "authenticated" DOM of every later step would be indistinguishable from the
+ * pre-login DOM, and the whole journey could pass without a real sign-in.
+ */
+async function signIn(page: Page) {
+ await expect(page.locator('.boot-overlay')).toBeHidden({ timeout: 30_000 })
+
+ const emailInput = page.locator('#email-input')
+ const settingsMenu = page.getByTestId('nav-settings-menu')
+
+ const reached = await expect(emailInput.or(settingsMenu))
+ .toBeVisible({ timeout: 30_000 })
+ .then(
+ () => true,
+ () => false
+ )
+ if (!reached) {
+ throw new Error(
+ 'Desktop rendered neither #email-input nor nav-settings-menu after the boot overlay cleared.'
+ )
+ }
+ if (await settingsMenu.isVisible()) {
+ if ((await settingsMenu.getAttribute('aria-expanded')) !== 'true') {
+ await settingsMenu.click()
+ }
+ await expect(settingsMenu).toHaveAttribute('aria-expanded', 'true')
+ await page.getByTestId('logout-btn').click()
+ }
+
+ await expect(emailInput).toBeVisible({ timeout: 20_000 })
+
+ await expect(composer(page)).toHaveCount(0)
+ await expect(sendButton(page)).toHaveCount(0)
+ await expect(page.getByTestId('nav-chat')).toHaveCount(0)
+ await expect(page.getByTestId('nav-new-chat')).toHaveCount(0)
+
+ await login(page, desktopCredentials())
+ await expect(page.getByTestId('nav-chat')).toBeVisible({ timeout: 30_000 })
+}
+
+test('optional QA recorder: Desktop image capability — blocked on text-only model, answered from the image', async ({}, testInfo) => {
+ test.skip(
+ MODE === 'fixture',
+ 'IMAGE_CAPABILITIES_RUN_ID selects the derived-provider fixture lane; the real-provider ' +
+ 'smoke runs with it unset.'
+ )
+ requireRecorderConfirm(
+ 'QA_RECORDER_CONFIRM_CHAT',
+ 'This journey sends a real chat message and may incur model cost.'
+ )
+ const { supportedModel, unsupportedModel } = requireModelNames()
+
+ await assertAllowedTarget('EXTERNAL_REST_API_BASE_URL', EXTERNAL_REST_API_BASE_URL)
+ await assertAllowedTarget('RPC_PROXY_BASE_URL', RPC_PROXY_BASE_URL)
+
+ const hostRef = configuredHostRef()
+ const fixture = buildImageFixture()
+ fs.mkdirSync(testInfo.outputPath(), { recursive: true })
+ fs.writeFileSync(testInfo.outputPath(fixture.fileName), fixture.png)
+
+ let app: ElectronApplication | undefined
+ let recordedPage: Page | undefined
+
+ try {
+ const launched = await launchDesktopApp(
+ testInfo,
+ `issue654-minikube${new URL(EXTERNAL_REST_API_BASE_URL).port}`
+ )
+ app = launched.app
+ recordedPage = launched.page
+ // A `const` alias keeps the non-optional type inside `test.step` closures,
+ // where a captured `let` would widen back to `Page | undefined`.
+ const page = launched.page
+
+ await signIn(page)
+
+ // Land on the exact configured agent through the visible Switch chat agent
+ // menu. The composer is only trusted after the switch control reports the
+ // configured host reference, so an auto-selected agent cannot satisfy this.
+ await openConfiguredAgentChat(page, hostRef)
+
+ // Start a blank chat so a stale response from a previous thread cannot be
+ // mistaken for this journey's answer.
+ await startBlankChat(page)
+
+ // The catalog row itself carries the host-projected image capability. When a
+ // model is not image-capable, the selector renders the "no images" tag.
+ await selectModel(page, supportedModel, 'supported')
+ await selectModel(page, unsupportedModel, 'unsupported')
+ await selectModel(page, supportedModel, 'supported')
+
+ // Attach a real PNG exactly the way a user does: Add context -> Upload
+ // Files -> native picker.
+ await attachFixturePng(page, fixture)
+ await expect(composer(page)).toBeEnabled()
+
+ // A draft rides along with the pending image so the blocked-send assertions
+ // can prove the draft is preserved too.
+ await composer(page).fill(VISUAL_PROMPT)
+
+ // Switch to the text-only model. The attachment must stay pending and the
+ // composer must refuse to send it, by button and by Enter.
+ await selectModel(page, unsupportedModel, 'unsupported')
+ await expectImageSendBlocked(
+ page,
+ unsupportedModel,
+ VISUAL_PROMPT,
+ fixture.fileName,
+ /not supported/i
+ )
+
+ // Switch back to the image-capable model and send the pending image.
+ await selectModel(page, supportedModel, 'supported')
+ await expect(attachmentChips(page).filter({ hasText: fixture.fileName })).toBeVisible()
+ await expect(sendButton(page)).toBeEnabled({ timeout: 20_000 })
+ await expect(capabilityNotice(page)).toHaveCount(0)
+ await sendButton(page).click()
+
+ // The composer leaves its pending state; this alone is not proof of
+ // delivery. The correlated exchange and the visual answer below supply that
+ // proof.
+ await expect(attachmentChips(page)).toHaveCount(0, { timeout: 30_000 })
+
+ const response = await expectSingleExchange(page)
+ await expect(response).toContainText(orderedColorListRegex(fixture.orderedColors), {
+ timeout: 120_000,
+ })
+
+ await screenshotAndLog(page, testInfo, 'desktop-image-capabilities')
+ } finally {
+ await finalizeRecording(app, recordedPage)
+ }
+})
+
+test('image-capabilities fixture: image capability gates the composer and the provider answers from the delivered pixels', async ({}, testInfo) => {
+ test.skip(
+ MODE !== 'fixture',
+ 'Set IMAGE_CAPABILITIES_RUN_ID=image-capabilities-<12 hex> to run the derived-provider ' +
+ 'fixture journey.'
+ )
+
+ const env = requireImageCapabilitiesFixtureEnv()
+
+ // Loopback-only, and the shared helper also probes both health endpoints so a
+ // missing port-forward fails here instead of inside Electron. `env` already
+ // proves both URLs are loopback, so no remote path is reachable from this lane.
+ await assertAllowedTarget('EXTERNAL_REST_API_BASE_URL', env.externalRestApiBaseUrl)
+ await assertAllowedTarget('RPC_PROXY_BASE_URL', env.rpcProxyBaseUrl)
+
+ // Precondition read, before anything is sent: the derived fixture must already
+ // be live in the deployment that serves this host, and its ledger must belong
+ // to this run and this profile. If it does not, this fails before the first
+ // send, so a journey can never quietly reach the real provider.
+ const baseline = readImageCapabilityEvidence(env)
+ expect(baseline.runId).toBe(env.runId)
+ expect(baseline.profile).toBe(env.profile)
+
+ // In fixture mode the shared helper reads the same two bindings the validator
+ // above already required, so its local fallbacks cannot apply and this journey
+ // always runs as the identity the runner seeded.
+ const visualFixture = buildImageFixture()
+ const textFixture = buildImageFixture()
+ for (const [name, fixture] of [
+ ['visual-chat', visualFixture],
+ ['text-chat', textFixture],
+ ] as const) {
+ fs.mkdirSync(testInfo.outputPath(name), { recursive: true })
+ fs.writeFileSync(testInfo.outputPath(name, fixture.fileName), fixture.png)
+ }
+ const visualSha = sha256Hex(visualFixture.png)
+ const textSha = sha256Hex(textFixture.png)
+ let visualTaskId = ''
+
+ let app: ElectronApplication | undefined
+ let recordedPage: Page | undefined
+
+ try {
+ const launched = await launchDesktopApp(
+ testInfo,
+ `issue654-minikube${new URL(EXTERNAL_REST_API_BASE_URL).port}`
+ )
+ app = launched.app
+ recordedPage = launched.page
+ // A `const` alias keeps the non-optional type inside the `test.step`
+ // closures below, where a captured `let` would widen back to `| undefined`.
+ const page = launched.page
+
+ const assertBinding = instanceBindingCheck(app, page, testInfo)
+ await assertBinding()
+ await signIn(page)
+ await assertBinding()
+ await openConfiguredAgentChat(page, env.hostRef)
+
+ await test.step('a model with no image evidence refuses the picker and sends nothing', async () => {
+ await startBlankChat(page)
+ await selectModel(page, env.unknownModel, 'unknown')
+ // The chip carries the same projection as the row hint.
+ await expect(modelChip(page)).toHaveAttribute('title', /not verified/i)
+
+ await expectUploadRefused(page, env.unknownModel, /not verified/i)
+ await expect(page.locator('[data-chat-message-id]')).toHaveCount(0)
+
+ // The refused picker must not have produced any provider attempt carrying
+ // pixels, and nothing at all may have carried an image during launch,
+ // sign-in or navigation.
+ const afterUnknown = readImageCapabilityEvidence(env)
+ const appended = appendedAttempts(baseline, afterUnknown)
+ expect(appended.filter(row => row.imageSha256 !== null)).toHaveLength(0)
+ expect(afterUnknown.counters.imageAttempts - baseline.counters.imageAttempts).toBe(0)
+ })
+
+ await test.step('an image-capable model accepts the PNG while a text-only model refuses to send it', async () => {
+ await startBlankChat(page)
+
+ await selectModel(page, env.supportedModel, 'supported')
+ await attachFixturePng(page, visualFixture)
+ await composer(page).fill(VISUAL_PROMPT)
+
+ // The attachment and the draft must both survive the switch to a model
+ // that cannot take an image, and neither Enter nor the button may send it.
+ await selectModel(page, env.unsupportedModel, 'unsupported')
+ await expectImageSendBlocked(
+ page,
+ env.unsupportedModel,
+ VISUAL_PROMPT,
+ visualFixture.fileName,
+ /not supported/i
+ )
+
+ await selectModel(page, env.supportedModel, 'supported')
+ await expect(attachmentChips(page).filter({ hasText: visualFixture.fileName })).toBeVisible()
+ await expect(capabilityNotice(page)).toHaveCount(0)
+ await expect(sendButton(page)).toBeEnabled({ timeout: 20_000 })
+ })
+
+ await test.step('the accepted send is answered from the delivered pixels and reaches the provider once', async () => {
+ const before = readImageCapabilityEvidence(env)
+
+ await assertBinding()
+ await sendButton(page).click()
+ await expect(attachmentChips(page)).toHaveCount(0, { timeout: 30_000 })
+
+ const response = await expectSingleExchange(page)
+ await expect(response).toContainText(orderedColorListRegex(visualFixture.orderedColors), {
+ timeout: 120_000,
+ })
+ visualTaskId = await observeCompletedTask(
+ page,
+ env.hostRef,
+ orderedColorListRegex(visualFixture.orderedColors)
+ )
+
+ const after = readImageCapabilityEvidence(env)
+ const appended = appendedAttempts(before, after)
+ const tileRows = appended.filter(row => row.responseKind === FIXTURE_RESPONSE_KIND.tileColors)
+
+ // Exactly one pixel-derived answer, produced by the image model, from the
+ // exact bytes this journey attached.
+ expect(tileRows).toHaveLength(1)
+ expect(tileRows[0]?.model).toBe(IMAGE_CAPABILITY_FIXTURE_MODELS.supported)
+ expect(tileRows[0]?.imageSha256).toBe(visualSha)
+ // No other attempt carried these pixels, so the text-only model never saw
+ // them and neither did any other model.
+ expect(appended.filter(row => row.imageSha256 === visualSha)).toHaveLength(1)
+ expect(after.counters.tileColorResponses - before.counters.tileColorResponses).toBe(1)
+ })
+
+ await test.step('removing the pending image lifts the block and the text-only model answers in text', async () => {
+ await startBlankChat(page)
+
+ await selectModel(page, env.supportedModel, 'supported')
+ await attachFixturePng(page, textFixture)
+ await composer(page).fill('Reply with the fixture text marker.')
+
+ await selectModel(page, env.unsupportedModel, 'unsupported')
+ await expectImageSendBlocked(
+ page,
+ env.unsupportedModel,
+ 'Reply with the fixture text marker.',
+ textFixture.fileName,
+ /not supported/i
+ )
+
+ // The real chip remove action must lift the block without touching the
+ // draft: this is the user-visible way out of the refusal.
+ const removeButton = page.getByRole('button', { name: `Remove ${textFixture.fileName}` })
+ await expect(removeButton).toBeVisible()
+ await removeButton.click()
+ await expect(attachmentChips(page)).toHaveCount(0)
+ await expect(capabilityNotice(page)).toHaveCount(0)
+ await expect(composer(page)).toHaveValue('Reply with the fixture text marker.')
+ await expect(sendButton(page)).toBeEnabled({ timeout: 20_000 })
+
+ const before = readImageCapabilityEvidence(env)
+ await assertBinding()
+ await sendButton(page).click()
+
+ const response = await expectSingleExchange(page)
+ // The marker is the fixture's text-only answer.
+ await expect(response).toContainText(fixtureTextAnswerRegex(), { timeout: 120_000 })
+ // A request without pixels can never produce a color list.
+ await expect(response).not.toContainText(anyColorRegex(textFixture.orderedColors))
+ const textTaskId = await observeCompletedTask(page, env.hostRef, fixtureTextAnswerRegex())
+ expect(textTaskId).not.toBe(visualTaskId)
+
+ const after = readImageCapabilityEvidence(env)
+ const appended = appendedAttempts(before, after)
+
+ // The removed image never reached the wire at all.
+ expect(appended.filter(row => row.imageSha256 !== null)).toHaveLength(0)
+ expect(appended.filter(row => row.imageSha256 === textSha)).toHaveLength(0)
+ // A delivered-but-undecodable image is recorded with `imageSha256: null` and
+ // `responseKind: 'rejected'`, so the row checks above cannot see it. The
+ // fixture still counts that attempt, so the image-attempt counter must not
+ // move either.
+ expect(after.counters.imageAttempts - before.counters.imageAttempts).toBe(0)
+
+ const textRows = appended.filter(
+ row =>
+ row.responseKind === FIXTURE_RESPONSE_KIND.textOnly && row.model === env.unsupportedModel
+ )
+ expect(textRows.length).toBeGreaterThanOrEqual(1)
+ // The fixture never had to refuse an image on the text model, because the
+ // composer's own guard stopped it: this proves the client-side block, not
+ // the fixture's refusal.
+ expect(after.counters.textModelImageRefusals - before.counters.textModelImageRefusals).toBe(0)
+ })
+
+ await screenshotAndLog(page, testInfo, 'desktop-image-capabilities-fixture')
+ } catch (error) {
+ if (recordedPage && !recordedPage.isClosed()) {
+ await recordedPage
+ .screenshot({ path: testInfo.outputPath('failure.png') })
+ .catch(() => undefined)
+ }
+ throw error
+ } finally {
+ await finalizeRecording(app, recordedPage)
+ }
+})
diff --git a/desktop-app/ui/src/components/agents/ComposerPanel.tsx b/desktop-app/ui/src/components/agents/ComposerPanel.tsx
index 265800452..25d915df9 100644
--- a/desktop-app/ui/src/components/agents/ComposerPanel.tsx
+++ b/desktop-app/ui/src/components/agents/ComposerPanel.tsx
@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
import { useAgentChatActionsContext } from '@contexts/AgentChatActionsContext'
import { useChatComposerStateContext } from '@contexts/ChatComposerStateContext'
import { useMcpRuntimeContext } from '@contexts/McpRuntimeContext'
@@ -22,12 +22,13 @@ import {
COMPOSER_ACCEPT_IMAGE_MIME_TYPES,
COMPOSER_MAX_IMAGE_ATTACHMENTS,
COMPOSER_MAX_IMAGE_BYTES,
- ZAI_IMAGE_ATTACHMENT_UNSUPPORTED_MESSAGE,
+ COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES,
} from '@constants/attachments'
import { useContextsDataController } from '@hooks/domain/useContextsDataController'
import { useMcpServersDataController } from '@hooks/domain/useMcpServersDataController'
import { useClickOutside } from '@hooks/useClickOutside'
import { useComposerDraft } from '@hooks/useComposerDraft'
+import { useHostModels } from '@hooks/useHostModels'
import type { WorkflowRecipeListResult } from '../../../../src/types'
import type { ComposerImageAttachment, ComposerReferenceAttachment } from '../../uiTypes'
import { AnnotationCanvas } from './AnnotationCanvas'
@@ -83,8 +84,10 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
handleRemoveComposerReferenceAttachment: onRemoveComposerReferenceAttachment,
handleSendAgentMessage: onSend,
handleRetryFailedAgentSend: onRetryFailedSend,
+ handleRecoverFailedAgentSend: onRecoverFailedSend,
+ handleDiscardFailedAgentSend: onDiscardFailedSend,
} = useAgentChatActionsContext()
- const { hostRuntimeStatus, activeLlmProvider } = useMcpRuntimeContext()
+ const { hostRuntimeStatus } = useMcpRuntimeContext()
const {
selectedAgentMcpServers,
agentContextByName,
@@ -118,7 +121,16 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
const composerFileInputRef = useRef<HTMLInputElement | null>(null)
const composerMenuRef = useRef<HTMLSpanElement | null>(null)
- const activeProviderDoesNotSupportImages = activeLlmProvider === 'zai'
+ // Issue #654: image capability comes from the host-projected per-model
+ // decision shared with the selector and the send path — never from the
+ // provider id. `visualSendBlocked` covers all three blocking shapes:
+ // `unsupported` (known text-only), `unknown` (no/stale evidence) and an
+ // unsettled selection write (the model may still be changing under us).
+ // It gates SENDING images, never selecting them (#678): the picker, paste and
+ // drop always attach, and the notice below explains a blocked send, so the
+ // user can still switch to a capable model with the images kept.
+ const hostModelSelection = useHostModels(selectedAgent ?? '', activeChatId ?? '')
+ const imageAttachmentBlockMessage = hostModelSelection.imageBlockMessage
const selectedAgentContext = selectedAgent
? String(agentContextByName[selectedAgent] || '').trim()
: ''
@@ -279,9 +291,17 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
// The controller clears the draft store only when the send is actually accepted
// (it bails out early if the chat already has an in-flight task), so a no-op send
// naturally keeps the text — no optimistic clear needed here.
+ // Issue #654: with pending images and an unsettled/incompatible effective
+ // model, Enter must not reach the controller. The chips and the draft stay
+ // exactly as they are, and the notice below explains the block.
+ const imagesBlockedForSend =
+ composerImageAttachments.length > 0 && hostModelSelection.visualSendBlocked
+ // Per-instance id: the main panel and the chat drawer can both be mounted.
+ const imageNoticeId = useId()
const handleSend = useCallback(() => {
+ if (imagesBlockedForSend) return
void onSend(draft)
- }, [onSend, draft])
+ }, [onSend, draft, imagesBlockedForSend])
const handleComposerKeyDown = useCallback(
(event: React.KeyboardEvent<HTMLTextAreaElement>) => {
@@ -321,14 +341,10 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
)
const openUploadPicker = useCallback(() => {
- if (activeProviderDoesNotSupportImages) {
- setComposerAttachmentError(ZAI_IMAGE_ATTACHMENT_UNSUPPORTED_MESSAGE)
- return
- }
setComposerMenuOpen(false)
setComposerSubmenu(null)
composerFileInputRef.current?.click()
- }, [activeProviderDoesNotSupportImages])
+ }, [])
const openAgentFilesModal = useCallback(() => {
if (agentFilesLoading) {
@@ -417,14 +433,30 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
const prepareComposerImageAttachments = useCallback(
async (files: File[] | FileList, source: 'picker' | 'clipboard' = 'picker') => {
- if (activeProviderDoesNotSupportImages) {
- setComposerAttachmentError(ZAI_IMAGE_ATTACHMENT_UNSUPPORTED_MESSAGE)
- return
- }
-
const candidates = Array.from(files || [])
if (!candidates.length) return
+ // Drop and paste can carry any file. Unsupported files are refused here,
+ // before the free image slots are counted, so they never take an image's
+ // place or inflate the skipped count.
+ const validationErrors: string[] = []
+ const imageCandidates: Array<{
+ file: File
+ mimeType: ComposerImageAttachment['mimeType']
+ }> = []
+ for (const file of candidates) {
+ const mimeType = inferComposerImageMimeType(file)
+ if (mimeType && COMPOSER_ACCEPT_IMAGE_MIME_TYPES.includes(mimeType)) {
+ imageCandidates.push({ file, mimeType })
+ } else {
+ validationErrors.push(`${file.name || 'Image'} is not supported. Use PNG or JPEG.`)
+ }
+ }
+ if (!imageCandidates.length) {
+ setComposerAttachmentError(validationErrors[0] ?? null)
+ return
+ }
+
const availableSlots = COMPOSER_MAX_IMAGE_ATTACHMENTS - composerImageAttachments.length
if (availableSlots <= 0) {
setComposerAttachmentError(
@@ -434,15 +466,23 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
}
const accepted: ComposerImageAttachment[] = []
- const validationErrors: string[] = []
- const selected = candidates.slice(0, availableSlots)
+ const selected = imageCandidates.slice(0, availableSlots)
+ if (imageCandidates.length > availableSlots) {
+ const skipped = imageCandidates.length - availableSlots
+ validationErrors.push(
+ `You can attach up to ${COMPOSER_MAX_IMAGE_ATTACHMENTS} images per message; ${skipped} ${
+ skipped === 1 ? 'image was' : 'images were'
+ } not added.`
+ )
+ }
+ // The images travel inline in one request body; an image that would push
+ // the message past the combined budget is refused here, not at send time.
+ let totalBase64Bytes = composerImageAttachments.reduce(
+ (total, attachment) => total + attachment.dataBase64.length,
+ 0
+ )
- for (const [index, file] of selected.entries()) {
- const mimeType = inferComposerImageMimeType(file)
- if (!mimeType || !COMPOSER_ACCEPT_IMAGE_MIME_TYPES.includes(mimeType)) {
- validationErrors.push(`${file.name || 'Image'} is not supported. Use PNG or JPEG.`)
- continue
- }
+ for (const [index, { file, mimeType }] of selected.entries()) {
if (file.size > COMPOSER_MAX_IMAGE_BYTES) {
validationErrors.push(
`${file.name || 'Image'} is too large. Max size is ${Math.round(
@@ -467,6 +507,16 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
revokePreviewUrl(previewUrl)
continue
}
+ if (totalBase64Bytes + dataBase64.length > COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES) {
+ validationErrors.push(
+ `${file.name || 'Image'} does not fit in this message: the images in one message are limited to ${Math.round(
+ COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES / (1024 * 1024)
+ )} MB in total. Send the attached images first or remove one.`
+ )
+ revokePreviewUrl(previewUrl)
+ continue
+ }
+ totalBase64Bytes += dataBase64.length
accepted.push({
id: crypto.randomUUID(),
name: buildAttachmentName(file, source, mimeType, index),
@@ -489,9 +539,8 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
setComposerAttachmentError(validationErrors.length ? (validationErrors[0] ?? null) : null)
},
[
- activeProviderDoesNotSupportImages,
buildAttachmentName,
- composerImageAttachments.length,
+ composerImageAttachments,
inferComposerImageMimeType,
onAddComposerImageAttachments,
readFileAsDataUrl,
@@ -870,11 +919,13 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
disabled={
isDegraded ||
agentSending ||
+ imagesBlockedForSend ||
(!draft.trim() &&
composerImageAttachments.length === 0 &&
composerReferenceAttachments.length === 0)
}
aria-label={agentSending ? 'Sending message' : 'Send message'}
+ aria-describedby={imagesBlockedForSend ? imageNoticeId : undefined}
label={agentSending ? 'Sending message' : 'Send message'}
size="sm"
title={agentSending ? 'Sending...' : 'Send message'}
@@ -892,13 +943,21 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
</span>
</div>
</div>
- {composerAttachmentError && (
+ {imagesBlockedForSend || composerAttachmentError ? (
<div className="composer-attachments">
- <p className="composer-attachment-error" role="alert">
- {composerAttachmentError}
+ <p
+ className="composer-attachment-error"
+ role="alert"
+ id={imagesBlockedForSend ? imageNoticeId : undefined}
+ data-testid={imagesBlockedForSend ? 'composer-image-capability-notice' : undefined}
+ >
+ {imagesBlockedForSend
+ ? (imageAttachmentBlockMessage ??
+ 'Image attachments are not available for this model yet.')
+ : composerAttachmentError}
</p>
</div>
- )}
+ ) : null}
{agentError ? (
<div className="composer-footer">
{failedAgentSend?.kind === 'waking' ? (
@@ -945,6 +1004,18 @@ export function ComposerPanel({ inline = false, agentSelector }: ComposerPanelPr
)}
</div>
) : null}
+ {failedAgentSend ? (
+ <div className="composer-footer">
+ <div className="action-row">
+ <Button onClick={onRecoverFailedSend} disabled={agentSending} size="xs" variant="ghost">
+ Recover input
+ </Button>
+ <Button onClick={onDiscardFailedSend} disabled={agentSending} size="xs" variant="ghost">
+ Discard failed input
+ </Button>
+ </div>
+ </div>
+ ) : null}
{previewAttachment && (
<AnnotationCanvas
diff --git a/desktop-app/ui/src/components/agents/ModelSelector.tsx b/desktop-app/ui/src/components/agents/ModelSelector.tsx
index 397ee290d..63d0698c7 100644
--- a/desktop-app/ui/src/components/agents/ModelSelector.tsx
+++ b/desktop-app/ui/src/components/agents/ModelSelector.tsx
@@ -1,7 +1,9 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
import type { HostModelOption } from '@hooks/useChatStore'
import { useClickOutside } from '@hooks/useClickOutside'
import { useHostModels } from '@hooks/useHostModels'
+import { isBrokerBackedProvider } from '@lib/hostModelSelectionStore'
+import { resolveImageInputDecision } from '../../../../src/imageInputDecision'
import { Pill } from '../Common'
export interface ModelSelectorProps {
@@ -23,10 +25,6 @@ const APPLIED_BADGE_MS = 4000
/** Broker-backed hosts have no static default; the operator must name a model. */
const SELECT_MODEL_LABEL = 'Select model'
-function isBrokerBackedProvider(provider: string): boolean {
- return provider === 'codex-subscription' || provider === 'grok-subscription'
-}
-
function isOfferedForNewPick(option: HostModelOption, sessionModel: string | null): boolean {
const isCurrent = Boolean(sessionModel) && option.name === sessionModel
if (isCurrent) return true
@@ -49,9 +47,11 @@ function modelLabel(name: string, options: HostModelOption[]): string {
* ("applies to your next message" — R2.5).
*
* Visibility / degraded rules:
- * - Hidden entirely until the model list loads, and when the host predates the
- * endpoint or the fetch failed (`data` null/undefined) — no noisy error
- * (R2.6).
+ * - Hidden entirely until the model list loads and when the host predates the
+ * endpoint (`data` null/undefined) — no noisy error (R2.6).
+ * - A FAILED fetch (`state === 'error'`, #654 M7) is different: nothing is
+ * known, so the chip stays visible as a retry affordance rather than
+ * silently leaving the composer without a capability verdict.
* - `degraded` (allowlist ConfigMap unavailable, R3.5): the chip is disabled
* and shows only the host default with an explanatory tooltip.
* - `sessionModelBlocked` (R2.2): a warning notice tells the user their prior
@@ -59,7 +59,20 @@ function modelLabel(name: string, options: HostModelOption[]): string {
* - A `model_not_allowed` rejection (R2, 403): inline error, selection unchanged.
*/
export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSelectorProps) {
- const { data, saving, error, selectModel, clearError } = useHostModels(agentRef, chatId)
+ const {
+ data,
+ saving,
+ error,
+ selectModel,
+ clearError,
+ refresh,
+ effectiveModel,
+ pending,
+ conflicted,
+ imageInput,
+ state,
+ loadError,
+ } = useHostModels(agentRef, chatId)
const [open, setOpen] = useState(false)
const [applied, setApplied] = useState(false)
const containerRef = useRef<HTMLDivElement | null>(null)
@@ -91,9 +104,6 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
return () => window.clearTimeout(timeoutId)
}, [applied])
- const effectiveModel = data
- ? (data.sessionModel ?? (isBrokerBackedProvider(data.provider) ? '' : data.hostDefault))
- : ''
const effectiveLabel = useMemo(() => {
if (!data) return ''
if (!effectiveModel && isBrokerBackedProvider(data.provider)) return SELECT_MODEL_LABEL
@@ -104,6 +114,15 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
data ? data.models.filter(option => isOfferedForNewPick(option, data.sessionModel)) : [],
[data]
)
+ // `title` alone is not announced by screen readers, so the image hint is also
+ // exposed through aria-describedby.
+ const imageHintId = useId()
+ const imageHint =
+ imageInput.state === 'supported'
+ ? undefined
+ : imageInput.state === 'unsupported'
+ ? 'This model cannot receive images.'
+ : 'Image input is not verified for this model yet.'
const handleSelect = useCallback(
async (model: string) => {
@@ -123,8 +142,30 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
const caretPointsUp = placement === 'up' ? !open : open
const caretPath = caretPointsUp ? 'm4.5 10 3.5-3.5L11.5 10' : 'm4.5 6 3.5 3.5L11.5 6'
+ // #654 M7 — a failed fetch is not "this host has no models". Offer a retry
+ // instead of hiding, so the user is not left with a silently capability-less
+ // composer and no way to recover.
+ if (!data && state === 'error') {
+ return (
+ <div className={rootClassName}>
+ <Pill
+ tone="warning"
+ size="sm"
+ interactive
+ className="model-selector-chip"
+ aria-label="Models unavailable — retry loading the model list"
+ title={loadError ?? 'The model list could not be loaded. Retry.'}
+ onClick={() => void refresh()}
+ >
+ <span className="model-selector-chip-glyph" aria-hidden="true" />
+ <span className="model-selector-chip-label">Models unavailable</span>
+ </Pill>
+ </div>
+ )
+ }
+
// Hidden until we have a model list to show (undefined = loading first fetch,
- // null = unsupported host / failed fetch). No flashing empty chip.
+ // null = the host predates the model endpoint). No flashing empty chip.
if (!data) return null
// Degraded: the allowlist is unavailable, so only the host default is usable.
@@ -156,8 +197,13 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
aria-haspopup="menu"
aria-expanded={open}
aria-label={`Model — ${effectiveLabel}`}
+ data-testid="selected-chat-model"
+ data-model-id={effectiveModel}
+ title={imageHint}
+ aria-describedby={imageHint ? imageHintId : undefined}
onClick={() => {
clearError()
+ if (!open) void refresh()
setOpen(prev => !prev)
}}
>
@@ -172,8 +218,13 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
<path d={caretPath} />
</svg>
</Pill>
+ {imageHint && (
+ <span id={imageHintId} className="visually-hidden">
+ {imageHint}
+ </span>
+ )}
- {applied && (
+ {(applied || pending) && (
<span className="model-selector-applied" role="status" aria-live="polite">
Applies to your next message
</span>
@@ -187,6 +238,11 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
using the default.
</p>
)}
+ {conflicted && (
+ <p className="model-selector-notice model-selector-notice--warning" role="status">
+ This chat’s model changed elsewhere — re-checking the current selection.
+ </p>
+ )}
{error && (
<p className="model-selector-notice model-selector-notice--error" role="alert">
{error}
@@ -196,11 +252,21 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
<ul className="model-selector-list">
{offeredModels.map(option => {
const isActive = option.name === effectiveModel
+ const optionImageInput = resolveImageInputDecision(option.imageInput)
+ // Every option carries an image tag, so a missing tag is never
+ // read as "not checked".
+ const imageHint =
+ optionImageInput.state === 'supported'
+ ? 'images'
+ : optionImageInput.state === 'unsupported'
+ ? 'no images'
+ : 'images not verified'
return (
<li key={option.name}>
<button
type="button"
role="menuitemradio"
+ data-testid={`model-option-${option.name}`}
aria-checked={isActive}
className={`model-selector-item${isActive ? ' model-selector-item--active' : ''}`}
disabled={saving}
@@ -211,6 +277,11 @@ export function ModelSelector({ agentRef, chatId, placement = 'down' }: ModelSel
{option.name === data.hostDefault && (
<span className="model-selector-item-tag">default</span>
)}
+ {imageHint && (
+ <span className="model-selector-item-tag" title={optionImageInput.reason}>
+ {imageHint}
+ </span>
+ )}
</span>
{isActive && (
<svg
diff --git a/desktop-app/ui/src/components/agents/__tests__/ComposerPanel.test.tsx b/desktop-app/ui/src/components/agents/__tests__/ComposerPanel.test.tsx
index 15baecd24..f056c2d79 100644
--- a/desktop-app/ui/src/components/agents/__tests__/ComposerPanel.test.tsx
+++ b/desktop-app/ui/src/components/agents/__tests__/ComposerPanel.test.tsx
@@ -1,8 +1,20 @@
// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { ChatComposerStateContextValue } from '@contexts/ChatComposerStateContext'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
+import {
+ COMPOSER_MAX_IMAGE_ATTACHMENTS,
+ COMPOSER_MAX_IMAGE_BYTES,
+ COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES,
+} from '@constants/attachments'
+import type { HostModelsResult } from '@hooks/useChatStore'
+import {
+ type ImageInputDecision,
+ imageInputBlockMessage,
+} from '../../../../../src/imageInputDecision'
+import type { ComposerImageAttachment, FailedAgentSend } from '../../../uiTypes'
import { ComposerPanel } from '../ComposerPanel'
// Resolve the stylesheet relative to THIS test file (not process.cwd()) so the
@@ -11,7 +23,7 @@ import { ComposerPanel } from '../ComposerPanel'
// to desktop-app/ui/ui/src/styles.css and failed with ENOENT.
const composerStyles = readFileSync(resolve(__dirname, '../../../styles.css'), 'utf8')
-const composerState = {
+const composerState: ChatComposerStateContextValue = {
composerImageAttachments: [],
composerReferenceAttachments: [],
agentSending: false,
@@ -24,17 +36,22 @@ const composerState = {
const draftState = { value: '', set: vi.fn() }
+/** Stable action spies so guard tests can assert what did (not) reach the controller. */
+const actionsMock = {
+ clearComposerSendError: vi.fn(),
+ handleAddComposerImageAttachments: vi.fn(),
+ handleUpdateComposerImageAttachment: vi.fn(),
+ handleRemoveComposerImageAttachment: vi.fn(),
+ handleAddComposerReferenceAttachments: vi.fn(),
+ handleRemoveComposerReferenceAttachment: vi.fn(),
+ handleSendAgentMessage: vi.fn(),
+ handleRetryFailedAgentSend: vi.fn(),
+ handleRecoverFailedAgentSend: vi.fn(),
+ handleDiscardFailedAgentSend: vi.fn(),
+}
+
vi.mock('@contexts/AgentChatActionsContext', () => ({
- useAgentChatActionsContext: () => ({
- clearComposerSendError: vi.fn(),
- handleAddComposerImageAttachments: vi.fn(),
- handleUpdateComposerImageAttachment: vi.fn(),
- handleRemoveComposerImageAttachment: vi.fn(),
- handleAddComposerReferenceAttachments: vi.fn(),
- handleRemoveComposerReferenceAttachment: vi.fn(),
- handleSendAgentMessage: vi.fn(),
- handleRetryFailedAgentSend: vi.fn(),
- }),
+ useAgentChatActionsContext: () => actionsMock,
}))
vi.mock('@contexts/ChatComposerStateContext', () => ({
@@ -65,21 +82,40 @@ vi.mock('@hooks/useComposerDraft', () => ({
useComposerDraft: () => [draftState.value, draftState.set],
}))
+/**
+ * Shared model-selection view (issue #654). Mutable so a test can swap the
+ * capability/state per case; every field of the hook's real return shape must be
+ * present because ModelSelector reads them directly.
+ */
+const composerModelState = {
+ data: {
+ provider: 'claude',
+ hostDefault: 'claude-haiku-4-5',
+ sessionModel: null,
+ degraded: false,
+ models: [{ name: 'claude-haiku-4-5', displayName: 'Haiku 4.5' }],
+ } as HostModelsResult | null | undefined,
+ loading: false,
+ saving: false,
+ error: null as string | null,
+ state: 'ready' as 'unloaded' | 'loading' | 'ready' | 'unavailable',
+ effectiveModel: 'claude-haiku-4-5',
+ intentModel: null as string | null,
+ pending: false,
+ selectionUnsettled: false,
+ conflicted: false,
+ confirmedRevision: null as number | null,
+ imageInput: { state: 'unknown' as const, reason: 'model_unknown' },
+ canAttachImages: false,
+ imageBlockMessage: null as string | null,
+ visualSendBlocked: false,
+ selectModel: vi.fn(async () => true),
+ clearError: vi.fn(),
+ refresh: vi.fn(async () => undefined),
+}
+
vi.mock('@hooks/useHostModels', () => ({
- useHostModels: () => ({
- data: {
- provider: 'claude',
- hostDefault: 'claude-haiku-4-5',
- sessionModel: null,
- degraded: false,
- models: [{ name: 'claude-haiku-4-5', displayName: 'Haiku 4.5' }],
- },
- loading: false,
- saving: false,
- error: null,
- selectModel: vi.fn(async () => true),
- clearError: vi.fn(),
- }),
+ useHostModels: () => composerModelState,
}))
vi.mock('../ComposerAgentFilesModal', () => ({ ComposerAgentFilesModal: () => null }))
vi.mock('../ComposerGlobalFilesModal', () => ({ ComposerGlobalFilesModal: () => null }))
@@ -100,7 +136,23 @@ afterEach(() => {
cleanup()
draftState.value = ''
draftState.set.mockReset()
- composerState.composerFocusRequestId = 0
+ Object.assign(composerState, {
+ composerImageAttachments: [],
+ composerReferenceAttachments: [],
+ agentSending: false,
+ agentError: null,
+ failedAgentSend: null,
+ activeChatId: null,
+ activeMessageCount: 0,
+ composerFocusRequestId: 0,
+ })
+ Object.assign(composerModelState, {
+ visualSendBlocked: false,
+ canAttachImages: false,
+ imageBlockMessage: null,
+ imageInput: { state: 'unknown', reason: 'model_unknown' },
+ })
+ for (const spy of Object.values(actionsMock)) spy.mockReset()
delete (window as Partial<typeof window>).clerum
})
@@ -193,3 +245,507 @@ describe.each([
otherInput.remove()
})
})
+
+// ---------------------------------------------------------------------------
+// Issue #654: composer image attachments through real DOM events.
+//
+// These drive the real component. jsdom has no file dialog and no DataTransfer,
+// so the helpers below stand in for exactly those unavailable browser
+// primitives; the accept filter, the FileReader byte preparation and every guard
+// stay real. The jsdom environment does provide URL.createObjectURL, so chip
+// previews are real `blob:` object URLs.
+// ---------------------------------------------------------------------------
+
+/** PNG signature bytes, so "the file's bytes reached the controller" is literal. */
+const PNG_BYTES = [137, 80, 78, 71, 13, 10, 26, 10, 0, 1, 2, 3]
+/** JPEG SOI/APP0 bytes for the cases that carry a .jpg file. */
+const JPEG_BYTES = [255, 216, 255, 224, 0, 16, 74, 70, 73, 70]
+
+function imageFile(name: string, type: string, bytes: Uint8Array | number[] = PNG_BYTES): File {
+ return new File([new Uint8Array(bytes)], name, { type })
+}
+
+function decodedBytes(base64: string): number[] {
+ return Array.from(atob(base64), char => char.charCodeAt(0))
+}
+
+function addedBatches(): ComposerImageAttachment[][] {
+ return actionsMock.handleAddComposerImageAttachments.mock.calls.map(([batch]) => batch)
+}
+
+/** Asserts that the controller received exactly one batch with one prepared image. */
+function expectSinglePreparedImage(): ComposerImageAttachment {
+ const batches = addedBatches()
+ expect(batches).toHaveLength(1)
+ expect(batches[0]).toHaveLength(1)
+ const attachment = batches[0]?.[0]
+ if (!attachment) throw new Error('expected one prepared image attachment')
+ return attachment
+}
+
+function pickerInput(container: HTMLElement): HTMLInputElement {
+ const input = container.querySelector('.composer-file-input')
+ if (!(input instanceof HTMLInputElement)) throw new Error('expected the composer file picker')
+ return input
+}
+
+function capabilityMessage(decision: ImageInputDecision): string {
+ const message = imageInputBlockMessage(composerModelState.effectiveModel, decision)
+ if (!message) throw new Error('expected a blocking image-capability message')
+ return message
+}
+
+/**
+ * jsdom cannot open a native file dialog, so the picker click is the boundary
+ * that stays observable: intercept it, and let the test fire the `change` event
+ * that a real dialog would produce.
+ */
+async function withPickerClick<T>(run: (timesClicked: () => number) => Promise<T>): Promise<T> {
+ const clickSpy = vi.spyOn(HTMLInputElement.prototype, 'click').mockImplementation(() => {})
+ try {
+ return await run(() => clickSpy.mock.calls.length)
+ } finally {
+ clickSpy.mockRestore()
+ }
+}
+
+const SUPPORTED_CAPABILITY = {
+ imageInput: { state: 'supported', reason: 'supported' } as ImageInputDecision,
+ canAttachImages: true,
+ imageBlockMessage: null,
+ visualSendBlocked: false,
+}
+
+const BLOCKED_CAPABILITIES: Array<[string, ImageInputDecision]> = [
+ ['unsupported', { state: 'unsupported', reason: 'model_unsupported' }],
+ ['unverified', { state: 'unknown', reason: 'model_unknown' }],
+]
+
+describe.each(BLOCKED_CAPABILITIES)(
+ 'ComposerPanel with %s image capability',
+ (_label, decision) => {
+ const blockMessage = capabilityMessage(decision)
+
+ beforeEach(() => {
+ Object.assign(composerModelState, {
+ imageInput: decision,
+ canAttachImages: false,
+ imageBlockMessage: blockMessage,
+ visualSendBlocked: true,
+ })
+ })
+
+ // #678: capability gates sending images, never selecting them. The picked
+ // image is kept so the user can switch to a capable model; the send-time
+ // notice (covered below) explains the block once the chip is pending.
+ it('opens the Upload Files picker and attaches the picked image', async () => {
+ await withPickerClick(async timesClicked => {
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.click(screen.getByRole('button', { name: 'Add context' }))
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Upload Files' }))
+ expect(timesClicked()).toBe(1)
+
+ fireEvent.change(pickerInput(container), {
+ target: { files: [imageFile('photo.png', 'image/png')] },
+ })
+
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ expect(expectSinglePreparedImage()).toMatchObject({ name: 'photo.png' })
+ expect(screen.queryByText(blockMessage)).toBeNull()
+ })
+ })
+
+ it('attaches a pasted image', async () => {
+ render(<ComposerPanel inline />)
+ const textarea = screen.getByTestId('chat-input')
+
+ const notPrevented = fireEvent.paste(textarea, {
+ clipboardData: { files: [imageFile('clipboard.png', 'image/png')], items: [] },
+ })
+
+ // Consumed like a real paste so the image never lands as text either.
+ expect(notPrevented).toBe(false)
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ expect(expectSinglePreparedImage().mimeType).toBe('image/png')
+ expect(screen.queryByText(blockMessage)).toBeNull()
+ })
+
+ it('attaches a dropped image and clears the drop overlay', async () => {
+ const { container } = render(<ComposerPanel inline />)
+ const shell = container.querySelector('.composer-input-shell') as HTMLElement
+
+ fireEvent.dragEnter(shell, { dataTransfer: { types: ['Files'] } })
+ expect(screen.getByText('Drop files here')).toBeTruthy()
+
+ const notPrevented = fireEvent.drop(shell, {
+ dataTransfer: { files: [imageFile('dropped.png', 'image/png')], types: ['Files'] },
+ })
+
+ expect(notPrevented).toBe(false)
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ expect(expectSinglePreparedImage()).toMatchObject({ name: 'dropped.png' })
+ expect(screen.queryByText('Drop files here')).toBeNull()
+ expect(screen.queryByText(blockMessage)).toBeNull()
+ })
+ }
+)
+
+describe('ComposerPanel with an image-capable model', () => {
+ beforeEach(() => {
+ Object.assign(composerModelState, SUPPORTED_CAPABILITY)
+ })
+
+ it('opens the picker and hands the picked PNG bytes to the controller', async () => {
+ await withPickerClick(async timesClicked => {
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.click(screen.getByRole('button', { name: 'Add context' }))
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Upload Files' }))
+ expect(timesClicked()).toBe(1)
+
+ const fileInput = pickerInput(container)
+ expect(fileInput.accept).toBe('image/jpeg,image/png')
+ expect(fileInput.multiple).toBe(true)
+ fireEvent.change(fileInput, { target: { files: [imageFile('photo.png', 'image/png')] } })
+
+ await waitFor(() => expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalled())
+ const attachment = expectSinglePreparedImage()
+ expect(attachment).toMatchObject({
+ name: 'photo.png',
+ mimeType: 'image/png',
+ sizeBytes: PNG_BYTES.length,
+ })
+ expect(decodedBytes(attachment.dataBase64)).toEqual(PNG_BYTES)
+ // createObjectURL is available here, so the chip preview is an object URL
+ // for the picked file rather than the FileReader fallback.
+ expect(attachment.previewDataUrl).toMatch(/^blob:/)
+ expect(screen.queryByRole('alert')).toBeNull()
+ })
+ })
+
+ it('prepares a pasted PNG once when the clipboard reports it as both file and item', async () => {
+ render(<ComposerPanel inline />)
+ const textarea = screen.getByTestId('chat-input')
+ const pasted = imageFile('image.png', 'image/png')
+
+ fireEvent.paste(textarea, {
+ clipboardData: {
+ files: [pasted],
+ items: [{ kind: 'file', getAsFile: () => pasted }],
+ },
+ })
+
+ await waitFor(() => expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalled())
+ const attachment = expectSinglePreparedImage()
+ // A generic clipboard name is replaced with a distinguishable pasted-image name.
+ expect(attachment.name).toMatch(/^pasted-image-\d+-1\.png$/)
+ expect(attachment.mimeType).toBe('image/png')
+ expect(decodedBytes(attachment.dataBase64)).toEqual(PNG_BYTES)
+ })
+
+ it('prepares a dropped JPEG and clears the drop overlay after the drop', async () => {
+ const { container } = render(<ComposerPanel inline />)
+ const shell = container.querySelector('.composer-input-shell') as HTMLElement
+
+ fireEvent.dragEnter(shell, { dataTransfer: { types: ['Files'] } })
+ expect(screen.getByText('Drop files here')).toBeTruthy()
+
+ fireEvent.drop(shell, {
+ dataTransfer: {
+ files: [imageFile('dropped.jpg', 'image/jpeg', JPEG_BYTES)],
+ types: ['Files'],
+ },
+ })
+
+ await waitFor(() => expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalled())
+ const attachment = expectSinglePreparedImage()
+ expect(attachment).toMatchObject({
+ name: 'dropped.jpg',
+ mimeType: 'image/jpeg',
+ sizeBytes: JPEG_BYTES.length,
+ })
+ expect(decodedBytes(attachment.dataBase64)).toEqual(JPEG_BYTES)
+ expect(screen.queryByText('Drop files here')).toBeNull()
+ })
+
+ it('infers the mime type from the file name when the OS reports none', async () => {
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.change(pickerInput(container), {
+ target: { files: [imageFile('screenshot.png', '')] },
+ })
+
+ await waitFor(() => expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalled())
+ expect(expectSinglePreparedImage().mimeType).toBe('image/png')
+ })
+
+ it('explains a rejected file type and still attaches the valid image in the same batch', async () => {
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.change(pickerInput(container), {
+ target: {
+ files: [imageFile('animation.gif', 'image/gif'), imageFile('good.png', 'image/png')],
+ },
+ })
+
+ await waitFor(() => expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalled())
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'animation.gif is not supported. Use PNG or JPEG.'
+ )
+ expect(expectSinglePreparedImage().name).toBe('good.png')
+ })
+
+ it('explains an oversize image and attaches nothing', async () => {
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.change(pickerInput(container), {
+ target: {
+ files: [imageFile('huge.png', 'image/png', new Uint8Array(COMPOSER_MAX_IMAGE_BYTES + 1))],
+ },
+ })
+
+ await waitFor(() => expect(screen.getByRole('alert')).toBeTruthy())
+ expect(screen.getByRole('alert').textContent).toBe('huge.png is too large. Max size is 3 MB.')
+ expect(actionsMock.handleAddComposerImageAttachments).not.toHaveBeenCalled()
+ })
+
+ it('attaches 20 images from one pick and says how many did not fit', async () => {
+ expect(COMPOSER_MAX_IMAGE_ATTACHMENTS).toBe(20)
+ const { container } = render(<ComposerPanel inline />)
+ const files = Array.from({ length: 22 }, (_, index) =>
+ imageFile(`photo-${index + 1}.png`, 'image/png', [...PNG_BYTES, index])
+ )
+
+ fireEvent.change(pickerInput(container), { target: { files } })
+
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ const [batch] = addedBatches()
+ expect(batch?.map(attachment => attachment.name)).toEqual(
+ files.slice(0, 20).map(file => file.name)
+ )
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'You can attach up to 20 images per message; 2 images were not added.'
+ )
+ })
+
+ it('refuses an image that would push the message past the combined image budget', async () => {
+ const { container } = render(<ComposerPanel inline />)
+ // Each image is under the per-image cap; two fit the combined budget and
+ // the third would push it past what the request body can carry.
+ const rawBytes = Math.floor(COMPOSER_MAX_IMAGE_BYTES * 0.8)
+ const base64Bytes = Math.ceil(rawBytes / 3) * 4
+ expect(base64Bytes * 2).toBeLessThanOrEqual(COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES)
+ expect(base64Bytes * 3).toBeGreaterThan(COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES)
+ const files = ['first.png', 'second.png', 'third.png'].map((name, index) => {
+ const bytes = new Uint8Array(rawBytes)
+ bytes.set(PNG_BYTES)
+ bytes[PNG_BYTES.length] = index
+ return imageFile(name, 'image/png', bytes)
+ })
+
+ fireEvent.change(pickerInput(container), { target: { files } })
+
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ const [batch] = addedBatches()
+ expect(batch?.map(attachment => attachment.name)).toEqual(['first.png', 'second.png'])
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'third.png does not fit in this message: the images in one message are limited to 8 MB in total. Send the attached images first or remove one.'
+ )
+ })
+
+ it('counts images already in the composer toward the combined budget', async () => {
+ composerState.composerImageAttachments = [
+ {
+ id: 'already-attached',
+ name: 'already.png',
+ mimeType: 'image/png',
+ dataBase64: 'A'.repeat(COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES - 8),
+ sizeBytes: 1,
+ previewDataUrl: 'data:image/png;base64,AAAA',
+ },
+ ]
+ const { container } = render(<ComposerPanel inline />)
+
+ fireEvent.change(pickerInput(container), {
+ target: { files: [imageFile('small.png', 'image/png')] },
+ })
+
+ // Witness: the picked file was read and judged (the alert names it).
+ await waitFor(() =>
+ expect(screen.getByRole('alert').textContent).toMatch(/^small\.png does not fit/)
+ )
+ expect(actionsMock.handleAddComposerImageAttachments).not.toHaveBeenCalled()
+ })
+
+ it('does not let a dropped non-image take one of the free image slots', async () => {
+ // 18 of the 20 slots are taken; the drop carries a PDF ahead of two PNGs.
+ composerState.composerImageAttachments = Array.from({ length: 18 }, (_, index) => ({
+ id: `attached-${index + 1}`,
+ name: `attached-${index + 1}.png`,
+ mimeType: 'image/png' as const,
+ dataBase64: 'iVBORw0KGgo=',
+ sizeBytes: 8,
+ previewDataUrl: 'data:image/png;base64,iVBORw0KGgo=',
+ }))
+ const { container } = render(<ComposerPanel inline />)
+ const shell = container.querySelector('.composer-input-shell') as HTMLElement
+
+ fireEvent.drop(shell, {
+ dataTransfer: {
+ files: [
+ imageFile('doc.pdf', 'application/pdf'),
+ imageFile('a.png', 'image/png', [...PNG_BYTES, 1]),
+ imageFile('b.png', 'image/png', [...PNG_BYTES, 2]),
+ ],
+ types: ['Files'],
+ },
+ })
+
+ await waitFor(() =>
+ expect(actionsMock.handleAddComposerImageAttachments).toHaveBeenCalledTimes(1)
+ )
+ const [batch] = addedBatches()
+ expect(batch?.map(attachment => attachment.name)).toEqual(['a.png', 'b.png'])
+ // The only message is the PDF refusal: no image was counted as skipped.
+ expect(screen.getByRole('alert').textContent).toBe('doc.pdf is not supported. Use PNG or JPEG.')
+ })
+})
+
+describe('ComposerPanel with a pending image after a model switch', () => {
+ const pendingImage: ComposerImageAttachment = {
+ id: 'pending-image-1',
+ name: 'pending.png',
+ mimeType: 'image/png',
+ dataBase64: 'iVBORw0KGgo=',
+ sizeBytes: 8,
+ previewDataUrl: 'data:image/png;base64,iVBORw0KGgo=',
+ }
+ const switchedAway: ImageInputDecision = { state: 'unknown', reason: 'model_unknown' }
+
+ beforeEach(() => {
+ composerState.composerImageAttachments = [pendingImage]
+ draftState.value = 'inspect this image'
+ Object.assign(composerModelState, SUPPORTED_CAPABILITY)
+ })
+
+ it('keeps the pending chip, shows the block notice, and refuses Enter and the send button', () => {
+ const { rerender } = render(<ComposerPanel inline />)
+ expect(screen.queryByTestId('composer-image-capability-notice')).toBeNull()
+
+ // The host now reports the effective model as unable to receive images.
+ Object.assign(composerModelState, {
+ imageInput: switchedAway,
+ canAttachImages: false,
+ imageBlockMessage: capabilityMessage(switchedAway),
+ visualSendBlocked: true,
+ })
+ rerender(<ComposerPanel inline />)
+
+ // The pending attachment is still there, with the reason it cannot be sent.
+ expect(screen.getByRole('button', { name: 'Remove pending.png' })).toBeTruthy()
+ const notice = screen.getByTestId('composer-image-capability-notice')
+ expect(notice.getAttribute('role')).toBe('alert')
+ expect(notice.textContent).toBe(capabilityMessage(switchedAway))
+ // The disabled send button points assistive technology at the reason.
+ const describedBy = screen.getByTestId('send-button').getAttribute('aria-describedby')
+ expect(describedBy).toBeTruthy()
+ expect(document.getElementById(describedBy as string)).toBe(notice)
+
+ const textarea = screen.getByTestId('chat-input') as HTMLTextAreaElement
+ expect((screen.getByTestId('send-button') as HTMLButtonElement).disabled).toBe(true)
+ expect(fireEvent.keyDown(textarea, { key: 'Enter' })).toBe(false)
+ expect(actionsMock.handleSendAgentMessage).not.toHaveBeenCalled()
+ // Shift+Enter is still a newline, and still not a send.
+ expect(fireEvent.keyDown(textarea, { key: 'Enter', shiftKey: true })).toBe(true)
+ expect(actionsMock.handleSendAgentMessage).not.toHaveBeenCalled()
+ })
+
+ it('sends the pending image with Enter while the model can receive images', () => {
+ render(<ComposerPanel inline />)
+ expect(screen.queryByTestId('composer-image-capability-notice')).toBeNull()
+ expect(screen.getByTestId('send-button').hasAttribute('aria-describedby')).toBe(false)
+ const textarea = screen.getByTestId('chat-input') as HTMLTextAreaElement
+
+ expect((screen.getByTestId('send-button') as HTMLButtonElement).disabled).toBe(false)
+ expect(fireEvent.keyDown(textarea, { key: 'Enter' })).toBe(false)
+ expect(actionsMock.handleSendAgentMessage).toHaveBeenCalledWith('inspect this image')
+
+ fireEvent.click(screen.getByTestId('send-button'))
+ expect(actionsMock.handleSendAgentMessage).toHaveBeenCalledTimes(2)
+ })
+
+ it('renders the pending image chip and dispatches removal with its id', () => {
+ render(<ComposerPanel inline />)
+
+ expect(screen.getByText('pending.png')).toBeTruthy()
+ fireEvent.click(screen.getByRole('button', { name: 'Remove pending.png' }))
+ expect(actionsMock.handleRemoveComposerImageAttachment).toHaveBeenCalledWith('pending-image-1')
+ })
+})
+
+describe('ComposerPanel failed-send recovery actions', () => {
+ const failedSend: FailedAgentSend = {
+ content: 'inspect this image',
+ attachments: [],
+ references: [],
+ message: 'Image input evidence changed',
+ kind: 'upstream',
+ timestamp: 1,
+ agentRef: 'agent-1',
+ chatId: 'chat-1',
+ }
+
+ it('offers explicit recovery and dispatch and routes each action to the controller', () => {
+ composerState.failedAgentSend = failedSend
+ composerState.agentError = 'Sending failed'
+ render(<ComposerPanel inline />)
+
+ expect(screen.getByText('Sending failed')).toBeTruthy()
+ expect(screen.getByText('Image input evidence changed')).toBeTruthy()
+
+ fireEvent.click(screen.getByRole('button', { name: 'Recover input' }))
+ expect(actionsMock.handleRecoverFailedAgentSend).toHaveBeenCalledTimes(1)
+ expect(actionsMock.handleDiscardFailedAgentSend).not.toHaveBeenCalled()
+
+ fireEvent.click(screen.getByRole('button', { name: 'Discard failed input' }))
+ expect(actionsMock.handleDiscardFailedAgentSend).toHaveBeenCalledTimes(1)
+
+ fireEvent.click(screen.getByRole('button', { name: 'Retry last send' }))
+ expect(actionsMock.handleRetryFailedAgentSend).toHaveBeenCalledTimes(1)
+ })
+
+ it('disables recovery while a send is in flight', () => {
+ composerState.failedAgentSend = failedSend
+ composerState.agentError = 'Sending failed'
+ composerState.agentSending = true
+ render(<ComposerPanel inline />)
+
+ for (const name of ['Recover input', 'Discard failed input', 'Retry last send']) {
+ expect((screen.getByRole('button', { name }) as HTMLButtonElement).disabled).toBe(true)
+ }
+ })
+
+ it('explains the waking state and routes its retry to the controller', () => {
+ composerState.failedAgentSend = { ...failedSend, kind: 'waking' }
+ composerState.agentError = 'Sending failed'
+ render(<ComposerPanel inline />)
+
+ const waking = screen.getByTestId('waking-state')
+ expect(waking.getAttribute('role')).toBe('status')
+ expect(waking.textContent).toContain('Agent is waking up')
+
+ fireEvent.click(screen.getByRole('button', { name: 'Retry last send' }))
+ expect(actionsMock.handleRetryFailedAgentSend).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/desktop-app/ui/src/components/agents/__tests__/ModelSelector.test.tsx b/desktop-app/ui/src/components/agents/__tests__/ModelSelector.test.tsx
index 0e3eaca49..34a0e34cc 100644
--- a/desktop-app/ui/src/components/agents/__tests__/ModelSelector.test.tsx
+++ b/desktop-app/ui/src/components/agents/__tests__/ModelSelector.test.tsx
@@ -6,22 +6,68 @@ import { ModelSelector } from '../ModelSelector'
;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
-// Drive the component purely through the hook's return shape.
-const hookState = {
- data: undefined as HostModelsResult | null | undefined,
- loading: false,
- saving: false,
- error: null as string | null,
- selectModel: vi.fn(async (_model: string) => true),
- clearError: vi.fn(),
+// Drive the component purely through the hook's return shape. Every field of the
+// real return shape must exist here — the component reads them directly.
+type HookState = {
+ data: HostModelsResult | null | undefined
+ loading: boolean
+ saving: boolean
+ error: string | null
+ state: 'unloaded' | 'loading' | 'ready' | 'unavailable' | 'error'
+ effectiveModel: string
+ intentModel: string | null
+ pending: boolean
+ selectionUnsettled: boolean
+ conflicted: boolean
+ confirmedRevision: number | null
+ imageInput: {
+ state: 'supported' | 'unsupported' | 'unknown'
+ reason: string
+ validUntil?: string
+ }
+ canAttachImages: boolean
+ imageBlockMessage: string | null
+ loadError: string | null
+ visualSendBlocked: boolean
+ selectModel: (model: string) => Promise<boolean>
+ clearError: () => void
+ refresh: () => Promise<void>
}
+function makeHookState(overrides: Partial<HookState> = {}): HookState {
+ const data = overrides.data
+ return {
+ data,
+ loading: false,
+ saving: false,
+ error: null,
+ state: data === undefined ? 'unloaded' : data === null ? 'unavailable' : 'ready',
+ effectiveModel: data ? (data.sessionModel ?? data.hostDefault) : '',
+ intentModel: null,
+ pending: false,
+ selectionUnsettled: false,
+ conflicted: false,
+ confirmedRevision: null,
+ imageInput: { state: 'unknown', reason: 'model_unknown' },
+ canAttachImages: false,
+ imageBlockMessage: null,
+ loadError: null,
+ visualSendBlocked: false,
+ selectModel: vi.fn(async (_model: string) => true),
+ clearError: vi.fn(),
+ refresh: vi.fn(async () => undefined),
+ ...overrides,
+ }
+}
+
+let hookState: HookState = makeHookState()
+
vi.mock('@hooks/useHostModels', () => ({
useHostModels: () => hookState,
}))
-function setHook(overrides: Partial<typeof hookState>) {
- Object.assign(hookState, overrides)
+function setHook(overrides: Partial<HookState>) {
+ hookState = makeHookState(overrides)
}
function baseData(overrides: Partial<HostModelsResult> = {}): HostModelsResult {
@@ -44,14 +90,7 @@ function renderSelector() {
afterEach(() => {
cleanup()
- setHook({
- data: undefined,
- loading: false,
- saving: false,
- error: null,
- selectModel: vi.fn(async () => true),
- clearError: vi.fn(),
- })
+ hookState = makeHookState()
vi.clearAllMocks()
})
@@ -68,6 +107,80 @@ describe('ModelSelector', () => {
expect(container.firstChild).toBeNull()
})
+ // #654 M7 — a failed fetch is not the host saying "I have no models". Hiding
+ // the chip there left the user with a capability-less composer and no way to
+ // recover; the chip stays as the retry affordance.
+ it('shows a retry chip when the model list failed to load', () => {
+ const refresh = vi.fn(async () => undefined)
+ setHook({
+ data: undefined,
+ state: 'error',
+ error: 'The model list could not be loaded. Retry.',
+ loadError: 'The model list could not be loaded. Retry.',
+ refresh,
+ })
+ renderSelector()
+
+ const chip = screen.getByRole('button', { name: /Models unavailable/ })
+ expect(chip.getAttribute('title')).toMatch(/could not be loaded/)
+
+ fireEvent.click(chip)
+ expect(refresh).toHaveBeenCalledTimes(1)
+ })
+
+ it('announces the image hint through aria-describedby for a model that cannot receive images', () => {
+ setHook({
+ data: baseData(),
+ imageInput: { state: 'unsupported', reason: 'model_unsupported' },
+ })
+ renderSelector()
+ const chip = screen.getByRole('button', { name: /Model — Haiku 4.5/ })
+ const describedBy = chip.getAttribute('aria-describedby')
+ expect(describedBy).toBeTruthy()
+ expect(document.getElementById(describedBy as string)?.textContent).toBe(
+ 'This model cannot receive images.'
+ )
+ })
+
+ it('has no image hint for a model that can receive images', () => {
+ setHook({ data: baseData(), imageInput: { state: 'supported', reason: 'supported' } })
+ renderSelector()
+ // Witness: the chip rendered.
+ const chip = screen.getByRole('button', { name: /Model — Haiku 4.5/ })
+ expect(chip.hasAttribute('aria-describedby')).toBe(false)
+ expect(chip.hasAttribute('title')).toBe(false)
+ })
+
+ it('tags every listed model with its image capability, including supported ones', () => {
+ setHook({
+ data: baseData({
+ models: [
+ {
+ name: 'claude-opus-4-8',
+ displayName: 'Opus 4.8',
+ imageInput: { state: 'supported', reason: 'supported' },
+ },
+ {
+ name: 'claude-haiku-4-5',
+ displayName: 'Haiku 4.5',
+ imageInput: { state: 'unsupported', reason: 'model_unsupported' },
+ },
+ { name: 'claude-sonnet-5', displayName: 'Sonnet 5' },
+ ],
+ }),
+ })
+ renderSelector()
+ fireEvent.click(screen.getByRole('button', { name: /Model —/ }))
+
+ const tagsOf = (name: RegExp) =>
+ Array.from(
+ screen.getByRole('menuitemradio', { name }).querySelectorAll('.model-selector-item-tag')
+ ).map(tag => tag.textContent)
+ expect(tagsOf(/Opus 4\.8/)).toEqual(['default', 'images'])
+ expect(tagsOf(/Haiku 4\.5/)).toEqual(['no images'])
+ expect(tagsOf(/Sonnet 5/)).toEqual(['images not verified'])
+ })
+
it('shows the effective model (sessionModel over hostDefault)', () => {
setHook({ data: baseData() })
renderSelector()
diff --git a/desktop-app/ui/src/constants/agents.ts b/desktop-app/ui/src/constants/agents.ts
index 61eeda483..bcb1127bb 100644
--- a/desktop-app/ui/src/constants/agents.ts
+++ b/desktop-app/ui/src/constants/agents.ts
@@ -14,4 +14,9 @@ export const AGENT_ERROR_CODE_LABELS: Record<string, string> = {
LLM_MODEL_NOT_AVAILABLE: 'Model Not Available',
LLM_CONTENT_FILTERED: 'Content Filtered',
LLM_API_CALL_FAILED: 'Connection Error',
+ LLM_IMAGE_INPUT_UNSUPPORTED: 'Image Input Unsupported',
+ LLM_IMAGE_INPUT_UNKNOWN: 'Image Input Unverified',
+ LLM_INVALID_ATTACHMENT: 'Invalid Attachment',
+ LLM_MODEL_SELECTION_CONFLICT: 'Model Selection Changed',
+ LLM_MODEL_NOT_ALLOWED: 'Model Not Allowed',
}
diff --git a/desktop-app/ui/src/constants/attachments.ts b/desktop-app/ui/src/constants/attachments.ts
index ef3dc30ba..9da241ad6 100644
--- a/desktop-app/ui/src/constants/attachments.ts
+++ b/desktop-app/ui/src/constants/attachments.ts
@@ -1,5 +1,12 @@
-export const COMPOSER_MAX_IMAGE_ATTACHMENTS = 3
+// Must match INCOMING_IMAGE_MAX_COUNT in mcp-host/src/agent/incomingImageAttachments.ts.
+export const COMPOSER_MAX_IMAGE_ATTACHMENTS = 20
export const COMPOSER_MAX_IMAGE_BYTES = 3 * 1024 * 1024
+/**
+ * Combined base64 size of the images in one message. rpc-proxy and mcp-host
+ * parse the message JSON with a 10 MB body limit, and the images travel inline
+ * in that body; 2 MB is left for the text and the request envelope. 10 MB is
+ * also the smallest documented provider request limit (Cerebras, 10 MiB), and
+ * mcp-host forwards the images inline to the model.
+ */
+export const COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES = 8 * 1024 * 1024
export const COMPOSER_ACCEPT_IMAGE_MIME_TYPES = ['image/jpeg', 'image/png'] as const
-export const ZAI_IMAGE_ATTACHMENT_UNSUPPORTED_MESSAGE =
- 'Image attachments are not supported for agents running on Z AI yet. Switch this agent to a provider with image input support before attaching images.'
diff --git a/desktop-app/ui/src/contexts/AgentChatActionsContext/types.ts b/desktop-app/ui/src/contexts/AgentChatActionsContext/types.ts
index fd9753c6e..81beab82a 100644
--- a/desktop-app/ui/src/contexts/AgentChatActionsContext/types.ts
+++ b/desktop-app/ui/src/contexts/AgentChatActionsContext/types.ts
@@ -23,6 +23,8 @@ export interface AgentChatActionsContextValue {
handleRemoveComposerReferenceAttachment: (attachmentId: string) => void
handleSendAgentMessage: (text: string) => Promise<void>
handleRetryFailedAgentSend: () => Promise<void>
+ handleRecoverFailedAgentSend: () => void
+ handleDiscardFailedAgentSend: () => void
}
export interface AgentChatActionsProviderProps {
diff --git a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
index 8400de60e..7d61459f1 100644
--- a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
+++ b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
@@ -663,6 +663,29 @@ export class TaskTracker implements AgentTaskTracker {
if (this.states.get(key)?.taskId !== completedTaskId) return
const reply = extractAssistantReply(result)
const attachments = buildResponseFileAttachments(result)
+ // A durable failure may arrive after a terminal event with no error
+ // detail. Preserve that authoritative envelope; treating it as a reply
+ // would release the retained visual input and report false success.
+ const envelope = result as {
+ success?: boolean
+ error?: string | { message?: string; code?: string; provider?: string }
+ }
+ if (envelope.error || envelope.success === false || td.status === 'failed') {
+ const error = envelope.error
+ this.mutate(key, s => {
+ s.status = 'failed'
+ s.terminalResult = {
+ kind: 'error',
+ source: 'failed',
+ message: typeof error === 'string' ? error : (error?.message ?? 'The task failed.'),
+ code: typeof error === 'object' ? error.code : undefined,
+ provider: typeof error === 'object' ? error.provider : undefined,
+ ...(attachments.length ? { attachments } : {}),
+ }
+ })
+ await this.fireTerminal(key)
+ return
+ }
this.mutate(key, s => {
s.status = 'completed'
s.terminalResult = {
diff --git a/desktop-app/ui/src/hooks/__tests__/useChatStore.test.tsx b/desktop-app/ui/src/hooks/__tests__/useChatStore.test.tsx
index 2a4493a9e..9503dfad9 100644
--- a/desktop-app/ui/src/hooks/__tests__/useChatStore.test.tsx
+++ b/desktop-app/ui/src/hooks/__tests__/useChatStore.test.tsx
@@ -28,33 +28,31 @@ describe('useChatStore remote request cache', () => {
expect(listSessions).toHaveBeenCalledTimes(2)
})
- it('does not reuse remote session or model cache entries across cache scopes', async () => {
+ it('does not reuse remote session cache entries across cache scopes', async () => {
const listSessions = vi.fn(async () => ({ items: [] }))
- const getHostModels = vi.fn(async () => ({ models: [] }))
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { rpc: { listSessions, getHostModels } },
+ value: { rpc: { listSessions } },
})
const { result } = renderHook(() => useChatStore())
result.current.setRemoteCacheScope('authenticated:team-a')
await result.current.listSessions('cache-test-host', { limit: 50 })
- await result.current.getHostModels('cache-test-host', 'chat-1')
await result.current.listSessions('cache-test-host', { limit: 50 })
- await result.current.getHostModels('cache-test-host', 'chat-1')
expect(listSessions).toHaveBeenCalledTimes(1)
- expect(getHostModels).toHaveBeenCalledTimes(1)
result.current.setRemoteCacheScope('authenticated:team-b')
await result.current.listSessions('cache-test-host', { limit: 50 })
- await result.current.getHostModels('cache-test-host', 'chat-1')
expect(listSessions).toHaveBeenCalledTimes(2)
- expect(getHostModels).toHaveBeenCalledTimes(2)
})
- it('invalidates the scoped host-model cache after changing a model', async () => {
+ // #654 M12 — the host-model catalog has exactly one cache, in
+ // `hostModelSelectionStore`, which also owns revision ordering. A second TTL
+ // layer here could only serve a response read BEFORE a write, which is the
+ // stale revision the CAS must never be armed with.
+ it('never caches host models: each call reaches the IPC bridge', async () => {
const getHostModels = vi.fn(async () => ({ models: [] }))
const setHostModel = vi.fn(async () => ({ success: true }))
Object.defineProperty(window, 'clerum', {
@@ -65,11 +63,31 @@ describe('useChatStore remote request cache', () => {
result.current.setRemoteCacheScope('authenticated:team-a')
await result.current.getHostModels('cache-test-host', 'chat-1')
- await result.current.setHostModel('cache-test-host', 'chat-1', 'model-b')
await result.current.getHostModels('cache-test-host', 'chat-1')
+ // Back-to-back and identical: the old layer answered the second from cache.
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+
+ // Even concurrently — there is no in-flight coalescing at this layer either.
+ await Promise.all([
+ result.current.getHostModels('cache-test-host', 'chat-1'),
+ result.current.getHostModels('cache-test-host', 'chat-1'),
+ ])
+ expect(getHostModels).toHaveBeenCalledTimes(4)
+ expect(getHostModels).toHaveBeenLastCalledWith('cache-test-host', 'chat-1')
+ })
+
+ it('forwards the CAS revision to the model write without a cache round-trip', async () => {
+ const setHostModel = vi.fn(async () => ({ success: true }))
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: { rpc: { setHostModel } },
+ })
+ const { result } = renderHook(() => useChatStore())
+
+ await result.current.setHostModel('cache-test-host', 'chat-1', 'model-b', 7)
expect(setHostModel).toHaveBeenCalledTimes(1)
- expect(getHostModels).toHaveBeenCalledTimes(2)
+ expect(setHostModel).toHaveBeenCalledWith('cache-test-host', 'chat-1', 'model-b', undefined, 7)
})
it('does not carry pending model selections across an identity scope change', () => {
diff --git a/desktop-app/ui/src/hooks/__tests__/useHostModels.test.tsx b/desktop-app/ui/src/hooks/__tests__/useHostModels.test.tsx
index 412574a4c..aaffd0e77 100644
--- a/desktop-app/ui/src/hooks/__tests__/useHostModels.test.tsx
+++ b/desktop-app/ui/src/hooks/__tests__/useHostModels.test.tsx
@@ -1,6 +1,7 @@
// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { act, renderHook, waitFor } from '@testing-library/react'
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react'
+import { resetHostModelSelectionStore } from '../../lib/hostModelSelectionStore'
import type { HostModelsResult } from '../useChatStore'
import { useChatStore } from '../useChatStore'
import { useHostModels } from '../useHostModels'
@@ -54,7 +55,11 @@ async function renderLoaded(setHostModel: ReturnType<typeof vi.fn>) {
}
afterEach(() => {
+ cleanup()
delete (window as { clerum?: unknown }).clerum
+ // The selection store is a module singleton (one entry per agent/chat): each
+ // case must start from a clean slate or a previous fetch would be reused.
+ resetHostModelSelectionStore()
vi.restoreAllMocks()
})
@@ -75,7 +80,8 @@ describe('useHostModels.selectModel — R2 "Option A" optimistic + pending', ()
})
expect(ok).toBe(true)
- expect(result.current.models.data?.sessionModel).toBe('claude-opus-4-8')
+ // The effective selection is the model the next send will use.
+ expect(result.current.models.effectiveModel).toBe('claude-opus-4-8')
expect(result.current.models.error).toBeNull()
expect(result.current.store.getPendingModel(AGENT, CHAT)).toBeUndefined()
})
@@ -93,7 +99,7 @@ describe('useHostModels.selectModel — R2 "Option A" optimistic + pending', ()
expect(ok).toBe(false)
// Reverted to the pre-optimistic selection.
- expect(result.current.models.data?.sessionModel).toBe('claude-haiku-4-5')
+ expect(result.current.models.effectiveModel).toBe('claude-haiku-4-5')
expect(result.current.models.error).toMatch(/no longer allowed/i)
expect(result.current.store.getPendingModel(AGENT, CHAT)).toBeUndefined()
})
@@ -113,7 +119,8 @@ describe('useHostModels.selectModel — R2 "Option A" optimistic + pending', ()
store: useChatStore(),
}))
await waitFor(() => expect(result.current.models.data).toBeTruthy())
- expect(result.current.models.data?.sessionModel).toBe('claude-haiku-4-5')
+ expect(result.current.models.effectiveModel).toBe('claude-haiku-4-5')
+ expect(result.current.models.pending).toBe(true)
act(() => result.current.store.clearPendingModel(AGENT, CHAT))
})
@@ -132,7 +139,8 @@ describe('useHostModels.selectModel — R2 "Option A" optimistic + pending', ()
// Optimistically accepted (the selector shows "applies to next message").
expect(ok).toBe(true)
- expect(result.current.models.data?.sessionModel).toBe('claude-opus-4-8')
+ expect(result.current.models.effectiveModel).toBe('claude-opus-4-8')
+ expect(result.current.models.pending).toBe(true)
// No hard error surfaced — swallowed + logged.
expect(result.current.models.error).toBeNull()
expect(warnSpy).toHaveBeenCalled()
@@ -182,7 +190,7 @@ describe('useHostModels — R2 new-chat composer (no chatId yet)', () => {
// Held in the agent-keyed pre-chat slot for the first send to migrate.
expect(result.current.store.getPreChatModel(AGENT)).toBe('claude-haiku-4-5')
// Chip reflects the pick immediately.
- expect(result.current.models.data?.sessionModel).toBe('claude-haiku-4-5')
+ expect(result.current.models.effectiveModel).toBe('claude-haiku-4-5')
act(() => result.current.store.clearPreChatModel(AGENT))
})
@@ -200,12 +208,40 @@ describe('useHostModels — R2 new-chat composer (no chatId yet)', () => {
}))
await waitFor(() => expect(result.current.models.data).toBeTruthy())
// The server has no session selection, but the pre-chat slot restores the pick.
- expect(result.current.models.data?.sessionModel).toBe('claude-haiku-4-5')
+ expect(result.current.models.effectiveModel).toBe('claude-haiku-4-5')
act(() => result.current.store.clearPreChatModel(AGENT))
})
})
+describe('useHostModels — one shared selection source (selector + composer)', () => {
+ it('reflects a pick made through one hook instance in every other consumer', async () => {
+ const setHostModel = vi.fn(async () => ({
+ effective: 'next-task' as const,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ }))
+ const getHostModels = vi.fn(async () => baseModels())
+ installClerum(getHostModels, setHostModel)
+
+ // Two mounted consumers (the selector chip and the composer guard) subscribe
+ // to the SAME (agent, chat) entry instead of holding isolated copies.
+ const selector = renderHook(() => useHostModels(AGENT, CHAT))
+ const composer = renderHook(() => useHostModels(AGENT, CHAT))
+ await waitFor(() => expect(selector.result.current.data).toBeTruthy())
+ await waitFor(() => expect(composer.result.current.data).toBeTruthy())
+ // The host-level list is fetched once for both consumers.
+ expect(getHostModels).toHaveBeenCalledTimes(1)
+
+ await act(async () => {
+ await selector.result.current.selectModel('claude-opus-4-8')
+ })
+
+ await waitFor(() => expect(composer.result.current.effectiveModel).toBe('claude-opus-4-8'))
+ expect(composer.result.current.intentModel).toBeNull()
+ })
+})
+
describe('useHostModels — Codex subscription (no silent default)', () => {
it('does not seed a Codex session from the first catalog model when hostDefault is empty', async () => {
const getHostModels = vi.fn(async () =>
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/imageInputJourney.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/imageInputJourney.test.tsx
new file mode 100644
index 000000000..f3f1d9027
--- /dev/null
+++ b/desktop-app/ui/src/hooks/domain/__tests__/imageInputJourney.test.tsx
@@ -0,0 +1,336 @@
+// @vitest-environment jsdom
+// Renderer integration: real controller/selection/recovery, fake IPC boundary.
+// This is deliberately not evidence for the separately executed Electron E2E.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, waitFor } from '@testing-library/react'
+import {
+ getComposerDraft,
+ resetComposerDraftStore,
+ setComposerDraft,
+} from '@lib/composerDraftStore'
+import {
+ loadHostModels,
+ readHostModelSelection,
+ resetHostModelSelectionStore,
+ selectHostModel,
+} from '@lib/hostModelSelectionStore'
+import type { HostModelsResult } from '../../../../../src/types'
+import type { ComposerImageAttachment } from '../../../uiTypes'
+import { renderController } from './__fixtures__/controllerHarness'
+import { type MockClerum, installMockClerum, uninstallMockClerum } from './__fixtures__/mockClerum'
+
+let bridge: MockClerum
+const image: ComposerImageAttachment = {
+ id: 'input-image',
+ name: 'input.png',
+ mimeType: 'image/png',
+ dataBase64: 'YWJj',
+ sizeBytes: 3,
+ previewDataUrl: 'data:image/png;base64,YWJj',
+}
+// Byte identity is tested here; PNG decoding belongs to the real E2E fixture.
+const catalog: HostModelsResult = {
+ provider: 'zai',
+ hostDefault: 'glm-5.3-flash',
+ sessionModel: null,
+ degraded: false,
+ modelSelectionRevision: 0,
+ models: [
+ { name: 'glm-5.3-flash', imageInput: { state: 'supported', reason: 'supported' } },
+ { name: 'glm-5.3', imageInput: { state: 'unsupported', reason: 'model_unsupported' } },
+ { name: 'glm-5.3-vision', imageInput: { state: 'supported', reason: 'supported' } },
+ ],
+}
+const modelTransport = {
+ getHostModels: vi.fn(async () => catalog),
+ setHostModel: vi.fn(async (_host: string, _chat: string, model: string) => ({
+ effective: 'next-task' as const,
+ provider: 'zai',
+ model,
+ modelSelectionRevision: 1,
+ })),
+}
+
+beforeEach(() => {
+ bridge = installMockClerum()
+ Object.assign(bridge.rpc, modelTransport)
+})
+afterEach(() => {
+ cleanup()
+ resetHostModelSelectionStore()
+ resetComposerDraftStore()
+ uninstallMockClerum()
+ vi.clearAllMocks()
+})
+
+async function mountedVisualController() {
+ const rendered = renderController()
+ await waitFor(() => expect(bridge.chat.getIndex).toHaveBeenCalled())
+ await act(async () => {
+ await loadHostModels(modelTransport, 'agent-x', null)
+ })
+ act(() => rendered.result.current.handleAddComposerImageAttachments([image]))
+ return rendered
+}
+
+describe('#654 visual send and recovery', () => {
+ it('blocks pending images after selecting a text-only model, before creating a chat', async () => {
+ const { result } = await mountedVisualController()
+ await act(async () => {
+ await selectHostModel(modelTransport, 'agent-x', null, 'glm-5.3')
+ })
+ await act(async () => {
+ await result.current.handleSendAgentMessage('inspect')
+ })
+ expect(bridge.chat.create).not.toHaveBeenCalled()
+ expect(bridge.rpc.invokeHostMessage).not.toHaveBeenCalled()
+ expect(result.current.composerImageAttachments).toHaveLength(1)
+ expect(result.current.agentError).toContain('not supported')
+ })
+
+ it('retains a synchronous error envelope without a success boolean and recovers only on explicit action', async () => {
+ let reply!: (value: unknown) => void
+ bridge.rpc.invokeHostMessage.mockReturnValue(
+ new Promise(resolve => {
+ reply = resolve
+ })
+ )
+ const { result, spies } = await mountedVisualController()
+ let send!: Promise<void>
+ act(() => {
+ send = result.current.handleSendAgentMessage('inspect this image')
+ })
+ await waitFor(() => expect(bridge.rpc.invokeHostMessage).toHaveBeenCalledTimes(1))
+ const chat = result.current.activeChatId!
+ act(() => setComposerDraft(chat, 'a newer draft'))
+ await act(async () => {
+ reply({
+ error: { code: 'LLM_IMAGE_INPUT_UNKNOWN', message: 'Evidence changed', retryable: false },
+ })
+ await send
+ })
+ expect(bridge.rpc.invokeHostMessage.mock.calls[0]?.[1]).toMatchObject({
+ model: 'glm-5.3-flash',
+ attachments: [{ dataBase64: image.dataBase64 }],
+ })
+ expect(result.current.failedAgentSend).toMatchObject({
+ agentRef: 'agent-x',
+ chatId: chat,
+ content: 'inspect this image',
+ })
+ expect(getComposerDraft(chat)).toBe('a newer draft')
+ act(() => result.current.handleRecoverFailedAgentSend())
+ expect(getComposerDraft(chat)).toBe('a newer draft')
+ expect(spies.pushToast).toHaveBeenCalledWith(expect.stringContaining('current draft'), 'error')
+ act(() => setComposerDraft(chat, ''))
+ act(() => result.current.handleRecoverFailedAgentSend())
+ expect(getComposerDraft(chat)).toBe('inspect this image')
+ expect(result.current.composerImageAttachments[0]?.dataBase64).toBe(image.dataBase64)
+ expect(result.current.failedAgentSend).toBeNull()
+ expect(bridge.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
+ })
+
+ it('keeps the failed payload when its retry is blocked before dispatch (#654 M5)', async () => {
+ bridge.rpc.invokeHostMessage.mockResolvedValueOnce({
+ error: { code: 'LLM_IMAGE_INPUT_UNKNOWN', message: 'Evidence changed', retryable: false },
+ })
+ const { result, spies } = await mountedVisualController()
+ await act(async () => {
+ await result.current.handleSendAgentMessage('inspect this image')
+ })
+ const chat = result.current.activeChatId!
+ expect(result.current.failedAgentSend?.attachments[0]?.dataBase64).toBe(image.dataBase64)
+
+ // The chat now points at a text-only model, so the send-time guard refuses
+ // the retry before it retains anything of its own.
+ await act(async () => {
+ await selectHostModel(modelTransport, 'agent-x', chat, 'glm-5.3')
+ })
+ await act(async () => {
+ await result.current.handleRetryFailedAgentSend()
+ })
+
+ // Witness: the guard ran and refused the retry without dispatching it.
+ expect(spies.pushToast).toHaveBeenCalledWith(
+ expect.stringContaining('for model "glm-5.3"'),
+ 'error'
+ )
+ expect(bridge.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
+ // The failed attempt's snapshot is the only copy of the image; it survives.
+ expect(result.current.failedAgentSend?.attachments[0]?.dataBase64).toBe(image.dataBase64)
+ })
+
+ it('keeps asynchronous failure input with its original chat after the tracker releases it', async () => {
+ bridge.rpc.invokeHostMessage.mockResolvedValue({ taskId: 'visual-task' })
+ bridge.rpc.getTaskResult.mockResolvedValue({
+ status: 'failed',
+ error: {
+ code: 'LLM_IMAGE_INPUT_UNSUPPORTED',
+ message: 'Fallback cannot receive images',
+ retryable: false,
+ },
+ })
+ const { result } = await mountedVisualController()
+ await act(async () => {
+ await result.current.handleSendAgentMessage('inspect')
+ })
+ const originalChat = result.current.activeChatId!
+ await waitFor(() => expect(bridge.hasProgressHandler('visual-task')).toBe(true))
+ await act(async () => {
+ await result.current.switchToChat('agent-x', 'another-chat')
+ })
+ await act(async () => {
+ bridge.emitTaskProgress('visual-task', {
+ type: 'terminal',
+ data: { taskId: 'visual-task', status: 'failed' },
+ })
+ })
+ await waitFor(() => expect(bridge.rpc.getTaskResult).toHaveBeenCalled())
+ expect(result.current.failedAgentSend).toBeNull()
+ expect(getComposerDraft('another-chat')).toBe('')
+ await act(async () => {
+ await result.current.switchToChat('agent-x', originalChat)
+ })
+ await waitFor(() =>
+ expect(result.current.failedAgentSend?.attachments[0]?.dataBase64).toBe(image.dataBase64)
+ )
+ act(() => result.current.handleDiscardFailedAgentSend())
+ expect(result.current.failedAgentSend).toBeNull()
+ })
+
+ // #654 H1 — the send IS the conditional write, so its ack carries the revision
+ // that write produced. A client that keeps the revision it read before sending
+ // arms the next send with a revision the server has already superseded, and
+ // loses a race it had won.
+ it('sends the second image with the revision acknowledged by the first send', async () => {
+ // The first image rides on a model the session does not run on yet, so the
+ // Host writes the selection and acknowledges the revision that write
+ // produced (0 → 1).
+ bridge.rpc.invokeHostMessage.mockResolvedValue({
+ success: true,
+ taskId: 'visual-task-1',
+ modelSelectionRevision: 1,
+ })
+ bridge.rpc.getTaskResult.mockResolvedValue({ status: 'completed', response: 'ok' })
+ const { result } = await mountedVisualController()
+ await act(async () => {
+ await selectHostModel(modelTransport, 'agent-x', null, 'glm-5.3-vision')
+ })
+
+ await act(async () => {
+ await result.current.handleSendAgentMessage('first image')
+ })
+ const chatId = result.current.activeChatId!
+ await waitFor(() => expect(bridge.hasProgressHandler('visual-task-1')).toBe(true))
+ await act(async () => {
+ bridge.emitTaskProgress('visual-task-1', {
+ type: 'terminal',
+ data: { taskId: 'visual-task-1', status: 'completed' },
+ })
+ })
+ await waitFor(() => expect(bridge.rpc.getTaskResult).toHaveBeenCalled())
+
+ // The chat now exists, so its own catalog read settles — carrying the server's
+ // OWN revision 0, which is older than the ack and must not overwrite it.
+ await act(async () => {
+ await loadHostModels(modelTransport, 'agent-x', chatId)
+ })
+ act(() => result.current.handleAddComposerImageAttachments([image]))
+ await act(async () => {
+ await result.current.handleSendAgentMessage('second image')
+ })
+
+ expect(bridge.rpc.invokeHostMessage).toHaveBeenCalledTimes(2)
+ // Witness: the first send carried the revision READ from the catalog…
+ expect(bridge.rpc.invokeHostMessage.mock.calls[0]?.[1]).toMatchObject({
+ model: 'glm-5.3-vision',
+ modelSelectionRevision: 0,
+ })
+ // …and the second carries the one the first send's ack produced.
+ expect(bridge.rpc.invokeHostMessage.mock.calls[1]?.[1]).toMatchObject({
+ model: 'glm-5.3-vision',
+ modelSelectionRevision: 1,
+ })
+ })
+
+ // #654 M3 — an image send on the model the session already runs on (here the
+ // Host default, with no explicit selection) is admitted without a write, so
+ // its ack carries the CURRENT revision, unchanged. Adopting it must leave the
+ // selection settled and the next image send armed with that same revision.
+ it('keeps the selection settled when the ack reports an unchanged revision', async () => {
+ bridge.rpc.invokeHostMessage.mockResolvedValue({
+ success: true,
+ taskId: 'visual-task-1',
+ modelSelectionRevision: 0,
+ })
+ bridge.rpc.getTaskResult.mockResolvedValue({ status: 'completed', response: 'ok' })
+ const { result } = await mountedVisualController()
+
+ await act(async () => {
+ await result.current.handleSendAgentMessage('first image')
+ })
+ const chatId = result.current.activeChatId!
+ await waitFor(() => expect(bridge.hasProgressHandler('visual-task-1')).toBe(true))
+ // The ack was adopted for the chat it created: same model, same revision,
+ // nothing pending, nothing conflicted, and images still allowed.
+ expect(readHostModelSelection('agent-x', chatId)).toMatchObject({
+ effectiveModel: 'glm-5.3-flash',
+ confirmedRevision: 0,
+ intentModel: null,
+ pending: false,
+ conflicted: false,
+ selectionUnsettled: false,
+ })
+ await act(async () => {
+ bridge.emitTaskProgress('visual-task-1', {
+ type: 'terminal',
+ data: { taskId: 'visual-task-1', status: 'completed' },
+ })
+ })
+ await waitFor(() => expect(bridge.rpc.getTaskResult).toHaveBeenCalled())
+
+ await act(async () => {
+ await loadHostModels(modelTransport, 'agent-x', chatId)
+ })
+ expect(readHostModelSelection('agent-x', chatId).canAttachImages).toBe(true)
+ act(() => result.current.handleAddComposerImageAttachments([image]))
+ await act(async () => {
+ await result.current.handleSendAgentMessage('second image')
+ })
+
+ // Witness: both image sends were dispatched; each still carries the model
+ // and the revision the CAS needs, and the second reuses the unchanged one.
+ expect(bridge.rpc.invokeHostMessage).toHaveBeenCalledTimes(2)
+ for (const call of bridge.rpc.invokeHostMessage.mock.calls) {
+ expect(call[1]).toMatchObject({ model: 'glm-5.3-flash', modelSelectionRevision: 0 })
+ }
+ expect(readHostModelSelection('agent-x', chatId)).toMatchObject({
+ effectiveModel: 'glm-5.3-flash',
+ confirmedRevision: 0,
+ conflicted: false,
+ })
+ })
+
+ it('does not resurrect input when a POST fails after logout/reset', async () => {
+ let reject!: (reason: Error) => void
+ bridge.rpc.invokeHostMessage.mockReturnValue(
+ new Promise((_resolve, rejectPromise) => {
+ reject = rejectPromise
+ })
+ )
+ const { result } = await mountedVisualController()
+ let send!: Promise<void>
+ act(() => {
+ send = result.current.handleSendAgentMessage('private draft for this session')
+ })
+ await waitFor(() => expect(bridge.rpc.invokeHostMessage).toHaveBeenCalled())
+ act(() => result.current.resetChat())
+ await act(async () => {
+ reject(new Error('offline'))
+ await send
+ })
+ expect(result.current.failedAgentSend).toBeNull()
+ expect(result.current.agentError).toBeNull()
+ expect(bridge.chat.appendMessages).not.toHaveBeenCalled()
+ })
+})
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/retainedSendRelease.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/retainedSendRelease.test.tsx
new file mode 100644
index 000000000..ce8bda452
--- /dev/null
+++ b/desktop-app/ui/src/hooks/domain/__tests__/retainedSendRelease.test.tsx
@@ -0,0 +1,320 @@
+// @vitest-environment jsdom
+/**
+ * #654 M6 — every terminal outcome of an async send releases the payload the
+ * controller retained for recovery. A snapshot that is held but carries no
+ * failure is invisible through the public hook API (`failedAgentSend` only
+ * surfaces snapshots with a failure), so these tests wrap the real store factory
+ * to read the store the controller created. Each test asserts the snapshot was
+ * held before the terminal outcome and is gone after it.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, waitFor } from '@testing-library/react'
+import { readHostModelSelection, resetHostModelSelectionStore } from '@lib/hostModelSelectionStore'
+import type { RetainedSendSnapshot } from '@lib/retainedSendStore'
+import type { ComposerImageAttachment } from '../../../uiTypes'
+import { renderController } from './__fixtures__/controllerHarness'
+import { type MockClerum, installMockClerum, uninstallMockClerum } from './__fixtures__/mockClerum'
+
+type RetainedSendStore = ReturnType<
+ (typeof import('@lib/retainedSendStore'))['createRetainedSendStore']
+>
+
+const captured = vi.hoisted(() => ({
+ stores: [] as RetainedSendStore[],
+ retained: [] as RetainedSendSnapshot[],
+}))
+
+vi.mock('@lib/retainedSendStore', async importOriginal => {
+ const actual = await importOriginal<typeof import('@lib/retainedSendStore')>()
+ return {
+ ...actual,
+ createRetainedSendStore: (changed: () => void) => {
+ const store = actual.createRetainedSendStore(changed)
+ const retainSendSnapshot = (snapshot: RetainedSendSnapshot) => {
+ captured.retained.push(snapshot)
+ store.retainSendSnapshot(snapshot)
+ }
+ const wrapped = { ...store, retainSendSnapshot }
+ captured.stores.push(wrapped)
+ return wrapped
+ },
+ }
+})
+
+let clerum: MockClerum
+let uuidCounter = 0
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+beforeEach(() => {
+ uuidCounter = 0
+ captured.stores.length = 0
+ captured.retained.length = 0
+ vi.spyOn(globalThis.crypto, 'randomUUID').mockImplementation(
+ () => `uuid-${++uuidCounter}` as `${string}-${string}-${string}-${string}-${string}`
+ )
+ clerum = installMockClerum()
+})
+
+afterEach(() => {
+ vi.restoreAllMocks()
+ vi.useRealTimers()
+ resetHostModelSelectionStore()
+ uninstallMockClerum()
+})
+
+const image: ComposerImageAttachment = {
+ id: 'input-image',
+ name: 'input.png',
+ mimeType: 'image/png',
+ dataBase64: 'YWJj',
+ sizeBytes: 3,
+ previewDataUrl: 'data:image/png;base64,YWJj',
+}
+
+async function settleMount() {
+ await waitFor(() => expect(clerum.chat.getIndex).toHaveBeenCalled())
+}
+
+/** The snapshot the single send retained, read back from the live store. */
+function heldSnapshot(): RetainedSendSnapshot | undefined {
+ expect(captured.stores).toHaveLength(1)
+ expect(captured.retained).toHaveLength(1)
+ const [store] = captured.stores
+ const [retained] = captured.retained
+ return store!.getRetainedSendSnapshot(
+ retained!.agentRef!,
+ retained!.chatId,
+ retained!.userMessageId!
+ )
+}
+
+async function sendAsync(result: ReturnType<typeof renderController>['result'], taskId: string) {
+ clerum.rpc.invokeHostMessage.mockResolvedValue({ taskId })
+ const send = act(async () => {
+ await result.current.handleSendAgentMessage('keep this payload')
+ })
+ await waitFor(() => expect(clerum.hasProgressHandler(taskId)).toBe(true))
+ await send
+ // Liveness: the send retained its payload and the task id is attached to it.
+ expect(heldSnapshot()).toMatchObject({ content: 'keep this payload', taskId })
+}
+
+describe('retained send release on terminal outcomes (#654 M6)', () => {
+ it('releases the retained send on a terminal reply', async () => {
+ clerum.rpc.getTaskResult.mockResolvedValue({ status: 'completed', response: 'all done' })
+ const { result } = renderController()
+ await settleMount()
+ await sendAsync(result, 'task-reply')
+
+ await act(async () => {
+ clerum.emitTaskProgress('task-reply', {
+ type: 'terminal',
+ data: { taskId: 'task-reply', status: 'completed' },
+ })
+ })
+
+ // Witness that the reply branch ran: the durable reply was persisted.
+ await waitFor(() =>
+ expect(clerum.chat.appendMessages).toHaveBeenCalledWith(
+ 'agent-x',
+ expect.any(String),
+ expect.arrayContaining([
+ expect.objectContaining({ role: 'assistant', content: 'all done' }),
+ ])
+ )
+ )
+ expect(heldSnapshot()).toBeUndefined()
+ })
+
+ it('releases the retained send when a lost stream is reconciled to a durable reply', async () => {
+ // The stream closes without a terminal; the reconcile finds the durable
+ // per-task result and materializes it.
+ clerum.rpc.getTaskResult.mockResolvedValue({ status: 'completed', response: 'recovered' })
+ const { result } = renderController()
+ await settleMount()
+ await sendAsync(result, 'task-lost')
+
+ await act(async () => {
+ clerum.emitTaskProgress('task-lost', { type: 'closed' })
+ })
+
+ // Witness that the reconcile recovered the reply rather than falling
+ // through to the Resend affordance.
+ await waitFor(() =>
+ expect(clerum.chat.appendMessages).toHaveBeenCalledWith(
+ 'agent-x',
+ expect.any(String),
+ expect.arrayContaining([
+ expect.objectContaining({ role: 'assistant', content: 'recovered' }),
+ ])
+ )
+ )
+ await waitFor(() => expect(heldSnapshot()).toBeUndefined())
+ expect(result.current.failedAgentSend).toBeNull()
+ })
+
+ it('releases the retained send when the user cancels the task', async () => {
+ const { result } = renderController()
+ await settleMount()
+ await sendAsync(result, 'task-cancel')
+
+ await act(async () => {
+ await result.current.cancelTask('task-cancel')
+ })
+
+ expect(clerum.rpc.cancelTask).toHaveBeenCalledWith('agent-x', 'task-cancel')
+ expect(heldSnapshot()).toBeUndefined()
+ })
+
+ it('releases the retained send when the task is already gone upstream (404 on cancel)', async () => {
+ clerum.rpc.cancelTask.mockRejectedValue(new Error('404 Not Found'))
+ const { result } = renderController()
+ await settleMount()
+ await sendAsync(result, 'task-gone')
+
+ await act(async () => {
+ await result.current.cancelTask('task-gone')
+ })
+
+ expect(clerum.rpc.cancelTask).toHaveBeenCalledWith('agent-x', 'task-gone')
+ expect(heldSnapshot()).toBeUndefined()
+ })
+
+ it('keeps the payload when cancelling fails for another reason', async () => {
+ clerum.rpc.cancelTask.mockRejectedValue(new Error('500 upstream exploded'))
+ const { result, spies } = renderController()
+ await settleMount()
+ await sendAsync(result, 'task-keep')
+
+ await act(async () => {
+ await result.current.cancelTask('task-keep')
+ })
+
+ // Witness: the failure path ran and told the user.
+ expect(spies.pushToast).toHaveBeenCalledWith(
+ expect.stringContaining('Failed to cancel task'),
+ 'error'
+ )
+ expect(heldSnapshot()).toMatchObject({ taskId: 'task-keep' })
+ })
+})
+
+describe('older failures of a chat (#654 M2)', () => {
+ /** Sends one message whose POST throws, leaving a retained failure. */
+ async function sendFailing(result: ReturnType<typeof renderController>['result'], text: string) {
+ clerum.rpc.invokeHostMessage.mockRejectedValueOnce(new Error('network down'))
+ await act(async () => {
+ await result.current.handleSendAgentMessage(text)
+ })
+ expect(result.current.failedAgentSend?.content).toBe(text)
+ }
+
+ /** Failed snapshots still held by the controller's store. */
+ function heldFailures(): RetainedSendSnapshot[] {
+ expect(captured.stores).toHaveLength(1)
+ const [store] = captured.stores
+ return captured.retained
+ .map(retained =>
+ store!.getRetainedSendSnapshot(retained.agentRef, retained.chatId, retained.userMessageId)
+ )
+ .filter((snapshot): snapshot is RetainedSendSnapshot => Boolean(snapshot?.failure))
+ }
+
+ it('hides an older failure once a later synchronous send succeeds', async () => {
+ const { result, spies } = renderController()
+ await settleMount()
+ await sendFailing(result, 'first try')
+
+ clerum.rpc.invokeHostMessage.mockResolvedValueOnce({ response: 'direct answer' })
+ await act(async () => {
+ await result.current.handleSendAgentMessage('second try')
+ })
+
+ // Witness: the second send reached the synchronous success branch.
+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(2)
+ expect(spies.pushToast).toHaveBeenCalledWith('Message sent to agent-x.', 'success')
+ expect(result.current.failedAgentSend).toBeNull()
+ expect(heldFailures()).toEqual([])
+ })
+
+ it('hides an older failure once a later task replies, not before', async () => {
+ clerum.rpc.getTaskResult.mockResolvedValue({ status: 'completed', response: 'all done' })
+ const { result } = renderController()
+ await settleMount()
+ await sendFailing(result, 'first try')
+
+ clerum.rpc.invokeHostMessage.mockResolvedValueOnce({ taskId: 'task-later' })
+ const send = act(async () => {
+ await result.current.handleSendAgentMessage('second try')
+ })
+ await waitFor(() => expect(clerum.hasProgressHandler('task-later')).toBe(true))
+ await send
+ // The later send has not reached a terminal yet, so it supersedes nothing.
+ expect(result.current.failedAgentSend?.content).toBe('first try')
+
+ await act(async () => {
+ clerum.emitTaskProgress('task-later', {
+ type: 'terminal',
+ data: { taskId: 'task-later', status: 'completed' },
+ })
+ })
+
+ // Witness: the reply branch ran and persisted the durable reply.
+ await waitFor(() =>
+ expect(clerum.chat.appendMessages).toHaveBeenCalledWith(
+ 'agent-x',
+ expect.any(String),
+ expect.arrayContaining([
+ expect.objectContaining({ role: 'assistant', content: 'all done' }),
+ ])
+ )
+ )
+ await waitFor(() => expect(result.current.failedAgentSend).toBeNull())
+ expect(heldFailures()).toEqual([])
+ })
+
+ it('does not resurface an older failure after the newest one is discarded', async () => {
+ const { result } = renderController()
+ await settleMount()
+ await sendFailing(result, 'first try')
+ await sendFailing(result, 'second try')
+ // Witness: both failures are held, and the newest one is the visible one.
+ expect(heldFailures().map(snapshot => snapshot.content)).toEqual(['first try', 'second try'])
+ expect(result.current.failedAgentSend?.content).toBe('second try')
+
+ act(() => {
+ result.current.handleDiscardFailedAgentSend()
+ })
+
+ expect(result.current.failedAgentSend).toBeNull()
+ expect(heldFailures()).toEqual([])
+ })
+
+ it('shows a fresh send-time error over an older retained failure', async () => {
+ const { result } = renderController()
+ await settleMount()
+ await sendFailing(result, 'first try')
+
+ // With no fresh error, the banner falls back to the retained failure.
+ act(() => result.current.clearComposerSendError())
+ expect(result.current.agentError).toBe('network down')
+
+ // An image send is blocked before any POST: the model selection for this
+ // chat was never loaded, so the send-time guard reports a fresh error.
+ const chatId = result.current.activeChatId
+ const blocker = readHostModelSelection('agent-x', chatId).imageBlockMessage
+ expect(blocker).toEqual(expect.any(String))
+ act(() => result.current.handleAddComposerImageAttachments([image]))
+ await act(async () => {
+ await result.current.handleSendAgentMessage('with an image')
+ })
+
+ // Witness: the older failure is still retained and visible as the Resend
+ // target, and the blocked send never reached the Host.
+ expect(heldFailures().map(snapshot => snapshot.content)).toEqual(['first try'])
+ expect(result.current.failedAgentSend?.content).toBe('first try')
+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
+ expect(result.current.agentError).toBe(blocker)
+ })
+})
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.characterization.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.characterization.test.tsx
index c900e5f84..3958fa963 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.characterization.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.characterization.test.tsx
@@ -127,13 +127,68 @@ describe('sendAgentMessage — POST failure', () => {
const secondReq = clerum.rpc.invokeHostMessage.mock.calls[1]?.[1] as { content?: string }
expect(secondReq?.content).toContain('retry me')
+ // #654 M5 — the retry ran under a new userMessageId, so the failed attempt's
+ // retained snapshot has to be released explicitly. `failedAgentSend` is
+ // derived from the newest retained snapshot carrying a failure, so it stays
+ // non-null for as long as that snapshot survives. Asserted before the
+ // terminal event so the terminal handling cannot be what cleared it.
+ await act(async () => {
+ await retryPromise
+ })
+ expect(result.current.failedAgentSend).toBeNull()
+
await act(async () => {
clerum.emitTaskProgress('task-retry', {
type: 'terminal',
data: { taskId: 'task-retry', status: 'cancelled', reason: 'cleanup' },
})
})
- await retryPromise
+ })
+
+ it('a second retry click while the first retry is in flight does not send twice (#654 M5)', async () => {
+ clerum.rpc.invokeHostMessage.mockRejectedValueOnce(new Error('network down'))
+ const { result } = renderController()
+ await settleMount()
+
+ await act(async () => {
+ await result.current.handleSendAgentMessage('retry once')
+ })
+ expect(result.current.failedAgentSend?.content).toBe('retry once')
+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
+
+ // Hold the retry's POST open so the second click lands while it is in flight.
+ let resolvePost: (value: { taskId: string }) => void = () => undefined
+ clerum.rpc.invokeHostMessage.mockImplementationOnce(
+ () =>
+ new Promise<{ taskId: string }>(resolve => {
+ resolvePost = resolve
+ })
+ )
+ // Both clicks hit the same rendered callback, as two fast clicks on one
+ // button would, before React re-renders with `agentSending: true`.
+ const retry = result.current.handleRetryFailedAgentSend
+ const first = retry().catch(() => undefined)
+ const second = retry().catch(() => undefined)
+ // The POST is reached only after the send's own awaits; resolving before it
+ // is issued would resolve nothing.
+ await waitFor(() => expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(2))
+ await act(async () => {
+ resolvePost({ taskId: 'task-retry-once' })
+ await first
+ await second
+ })
+
+ // Exactly one original send plus one retry: the witness that the first retry
+ // ran and the count that proves the second one did not.
+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(2)
+ expect(result.current.failedAgentSend).toBeNull()
+
+ await act(async () => {
+ clerum.emitTaskProgress('task-retry-once', {
+ type: 'terminal',
+ data: { taskId: 'task-retry-once', status: 'cancelled', reason: 'cleanup' },
+ })
+ })
})
})
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/sessionStateRecovery.characterization.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/sessionStateRecovery.characterization.test.tsx
index 2b65386da..8065de512 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/sessionStateRecovery.characterization.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/sessionStateRecovery.characterization.test.tsx
@@ -254,8 +254,8 @@ describe('onTrackerTerminal — recover via reconcile catch', () => {
'Message to agent-x failed: Budget exceeded',
'error'
)
- // Recovered (not lost) → no scary Resend affordance.
- expect(result.current.failedAgentSend).toBeNull()
+ // A durable failure still retains the input for explicit recovery/retry.
+ expect(result.current.failedAgentSend).toMatchObject({ content: 'spend' })
await sendPromise
})
})
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.pendingModel.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.pendingModel.test.tsx
index 8bab5bb52..041c5b4fb 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.pendingModel.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.pendingModel.test.tsx
@@ -2,8 +2,8 @@
/**
* R2 "Option A" send-path piggyback: a per-session model chosen while the host
* was suspended is held as pending (module-level, in `useChatStore`) and carried
- * on the next `invokeHostMessage` as `model`, then cleared once the POST is
- * accepted. Sends with no pending must omit `model` entirely (additive/optional).
+ * on the next `invokeHostMessage` as `model`, then cleared after an authoritative
+ * read confirms it. Sends with no pending omit `model` entirely.
*
* Harness mirrors `useAgentChatController.crossChat.test.tsx` — a rendered
* component so the real send path runs — trimmed to a single agent + chat.
@@ -15,6 +15,7 @@ import { useAgentChatController } from '@hooks/domain/useAgentChatController'
import { useChatStore } from '@hooks/useChatStore'
import { useComposerDraft } from '@hooks/useComposerDraft'
import { resetComposerDraftStore } from '@lib/composerDraftStore'
+import { resetHostModelSelectionStore } from '@lib/hostModelSelectionStore'
import type { TaskProgressStreamEvent } from '../../../../../src/types'
type ProgressHandler = (event: TaskProgressStreamEvent) => void | Promise<void>
@@ -24,15 +25,29 @@ function createChatMeta(chatId: string) {
return { id: chatId, title: 'New Chat', createdAt: now, updatedAt: now, messageCount: 0 }
}
+const HOST_DEFAULT_MODEL = 'claude-opus-4-8'
+
function installClerumHarness() {
let taskIndex = 0
const chats: Array<ReturnType<typeof createChatMeta>> = []
const messagesByChat = new Map<string, unknown[]>()
const progressHandlers = new Map<string, ProgressHandler>()
+ let sessionModel: string | null = null
+ let modelSelectionRevision = 0
- const invokeHostMessage = vi.fn(async (_agentRef: string, _payload: { model?: string }) => {
+ // Models the Host contract (#654 M3): a piggybacked `model` is written, and
+ // the revision bumped, only when it differs from the session's effective
+ // model (the explicit selection, else the Host default). Whenever a model
+ // rode along, the ack reports the current revision.
+ const invokeHostMessage = vi.fn(async (_agentRef: string, payload: { model?: string }) => {
taskIndex += 1
- return { taskId: `task-${taskIndex}`, status: 'pending' }
+ const ack = { taskId: `task-${taskIndex}`, status: 'pending' }
+ if (payload.model === undefined) return ack
+ if (payload.model !== (sessionModel ?? HOST_DEFAULT_MODEL)) {
+ sessionModel = payload.model
+ modelSelectionRevision += 1
+ }
+ return { ...ack, modelSelectionRevision }
})
Object.defineProperty(window, 'clerum', {
@@ -66,6 +81,14 @@ function installClerumHarness() {
dismissOnboarding: vi.fn(async () => undefined),
},
rpc: {
+ getHostModels: vi.fn(async () => ({
+ provider: 'anthropic',
+ hostDefault: HOST_DEFAULT_MODEL,
+ sessionModel,
+ degraded: false,
+ models: [{ name: HOST_DEFAULT_MODEL }],
+ modelSelectionRevision,
+ })),
listSessions: vi.fn(async () => ({ items: [] })),
loadSessionMessages: vi.fn(async () => ({ agent: 'trader', chatId: '', turns: [] })),
subscribeHostActivity: vi.fn(async () => async () => undefined),
@@ -167,10 +190,13 @@ describe('useAgentChatController — R2 "Option A" pending-model piggyback', ()
cleanup()
vi.restoreAllMocks()
resetComposerDraftStore()
+ // The send path now writes revisions into the selection store, so its entries
+ // must not survive into the next test.
+ resetHostModelSelectionStore()
delete (window as { clerum?: unknown }).clerum
})
- it('(d) includes the pending model on the next send and clears it once accepted', async () => {
+ it('(d) includes the pending model and clears it after the host confirms selection', async () => {
const { invokeHostMessage } = installClerumHarness()
render(
<AgentTaskTrackerProvider>
@@ -190,8 +216,8 @@ describe('useAgentChatController — R2 "Option A" pending-model piggyback', ()
threadId: chatId,
model: 'claude-opus-4-8',
})
- // …and the accepted POST drained it (a persisted selection needs no replay).
- expect(readPending(chatId)).toBeUndefined()
+ // The fresh host projection confirms persistence, not just HTTP acceptance.
+ await waitFor(() => expect(readPending(chatId)).toBeUndefined())
})
it('does not invent a Codex catalog default when sending without a pending model', async () => {
@@ -210,6 +236,62 @@ describe('useAgentChatController — R2 "Option A" pending-model piggyback', ()
expect('model' in payload).toBe(false)
})
+ // #654 L8 — contract change. An ack that carries `modelSelectionRevision` means
+ // "your piggybacked model is persisted"; a successful ack WITHOUT it, after a
+ // piggyback was sent, means the Host ignored the model. Keeping the intent there
+ // (the previous behaviour) re-sent a pick the Host refuses on every subsequent
+ // message and left the chip promising a model the session never had.
+ it('drops the pending choice when the host acknowledges the send without a revision', async () => {
+ const { invokeHostMessage } = installClerumHarness()
+ // A Host that ignored the piggybacked model (one that predates it) acks the
+ // send with no revision; the current Host always reports one when a model
+ // rode along, so this ack is modelled explicitly.
+ invokeHostMessage.mockResolvedValueOnce({ taskId: 'task-1', status: 'pending' })
+ const getHostModels = vi.spyOn(window.clerum.rpc, 'getHostModels').mockResolvedValue({
+ provider: 'anthropic',
+ hostDefault: 'claude-opus-4-8',
+ sessionModel: null,
+ degraded: false,
+ models: [{ name: 'claude-opus-4-8' }],
+ modelSelectionRevision: 0,
+ })
+ render(
+ <AgentTaskTrackerProvider>
+ <AgentChatHarness />
+ </AgentTaskTrackerProvider>
+ )
+ const chatId = await createChat()
+ setPending(chatId, 'claude-opus-4-8')
+ fireEvent.click(screen.getByRole('button', { name: 'Send message' }))
+ await waitFor(() => expect(invokeHostMessage).toHaveBeenCalledTimes(1))
+ // Witnesses: the piggyback did ride along, and the confirmation read did run —
+ // so the drop below is a decision the path made, not a path that never ran.
+ expect(invokeHostMessage.mock.calls[0]?.[1]).toMatchObject({
+ threadId: chatId,
+ model: 'claude-opus-4-8',
+ })
+ await waitFor(() => expect(getHostModels).toHaveBeenCalled())
+ await waitFor(() => expect(readPending(chatId)).toBeUndefined())
+ })
+
+ // The complement of the L8 drop: a send that never reached the Host says nothing
+ // about the model, so the pick must survive for the retry.
+ it('keeps the pending choice when the POST itself fails', async () => {
+ const { invokeHostMessage } = installClerumHarness()
+ invokeHostMessage.mockRejectedValueOnce(new Error('offline'))
+ render(
+ <AgentTaskTrackerProvider>
+ <AgentChatHarness />
+ </AgentTaskTrackerProvider>
+ )
+ const chatId = await createChat()
+ setPending(chatId, 'claude-opus-4-8')
+ fireEvent.click(screen.getByRole('button', { name: 'Send message' }))
+ await waitFor(() => expect(invokeHostMessage).toHaveBeenCalledTimes(1))
+ await waitFor(() => expect(screen.getByTestId('agent-sending').textContent).toBe('false'))
+ expect(readPending(chatId)).toBe('claude-opus-4-8')
+ })
+
it('(e) omits model entirely when there is no pending selection', async () => {
const { invokeHostMessage } = installClerumHarness()
render(
@@ -252,7 +334,7 @@ describe('useAgentChatController — R2 "Option A" pending-model piggyback', ()
})
// …the pre-chat slot was consumed (no stale carry-over to the next new chat)…
expect(readPreChat()).toBeUndefined()
- // …and the migrated pending slot was drained once the POST was accepted.
- expect(readPending(chatId)).toBeUndefined()
+ // The migrated pending slot drains after the authoritative read confirms it.
+ await waitFor(() => expect(readPending(chatId)).toBeUndefined())
})
})
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
index 7e319ded1..9e82e9687 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
@@ -957,9 +957,10 @@ describe('useAgentChatController — characterization (D.0)', () => {
'Message to agent-x failed: Token budget exceeded for this workspace.',
'error'
)
- // … and the session is idle/recoverable — NOT the "Lost connection" resend UX.
- expect(result.current.failedAgentSend).toBeNull()
- expect(result.current.agentError).toBeNull()
+ // #654 deliberately retains failed input, while preserving the real
+ // budget error instead of presenting a misleading lost-connection error.
+ expect(result.current.failedAgentSend).toMatchObject({ content: 'hola', kind: 'upstream' })
+ expect(result.current.agentError).toContain('budget exceeded')
// The session must settle back to idle (no residual "processing" spinner) —
// the recovery path always calls setIdle, not just the fallback path.
expect(
diff --git a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
index a9f828caa..d37893f25 100644
--- a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
+++ b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
@@ -11,7 +11,20 @@ import {
buildResponseFileAttachments,
} from '@lib/chatMessageAttachments'
import { truncateTitle } from '@lib/chatTitle'
+import {
+ getComposerDraft,
+ getComposerDraftRevision,
+ setComposerDraft,
+} from '@lib/composerDraftStore'
import { buildComposerRequestContent } from '@lib/composerReferencesPrompt'
+import {
+ confirmHostModelSelectionFromSend,
+ dropIgnoredHostModelIntent,
+ loadHostModels,
+ noteHostModelSelectionConflict,
+ readHostModelSelection,
+} from '@lib/hostModelSelectionStore'
+import { createRetainedSendStore } from '@lib/retainedSendStore'
import {
mergeAuthoritativeServerMessages,
messageServerTurnNumber,
@@ -468,6 +481,39 @@ export function useAgentChatController({
const [agentSending, setAgentSending] = useState(false)
const [agentError, setAgentError] = useState<string | null>(null)
const [failedAgentSend, setFailedAgentSend] = useState<FailedAgentSend | null>(null)
+ const [retainedRevision, setRetainedRevision] = useState(0)
+ const [retainedSends] = useState(() =>
+ createRetainedSendStore(() => setRetainedRevision(value => value + 1))
+ )
+ const {
+ retainSendSnapshot,
+ attachTaskIdToRetainedSend,
+ releaseRetainedSend,
+ releaseRetainedSendsForTask,
+ releaseRetainedFailuresForChat,
+ releaseSucceededRetainedSend,
+ releaseSucceededRetainedSendsForTask,
+ markRetainedSendReason,
+ failRetainedSend,
+ } = retainedSends
+ const sendScopeGeneration = useRef(0)
+ // #654 M5 — the userMessageId of the most recent send that retained its
+ // payload. A retry compares it before and after to learn whether it retained
+ // a snapshot of its own; `sendAgentMessage` has several early returns (image
+ // guard, running task, send in flight) that retain nothing.
+ const lastRetainedSendIdRef = useRef<string | null>(null)
+ const lastRetentionScope = useRef(`${isAuthenticated}:${authenticatedScope}`)
+ useEffect(() => {
+ const scope = `${isAuthenticated}:${authenticatedScope}`
+ if (lastRetentionScope.current === scope) return
+ lastRetentionScope.current = scope
+ sendScopeGeneration.current += 1
+ agentSendInFlightRef.current = false
+ setAgentSending(false)
+ retainedSends.resetRetainedSendStore()
+ setFailedAgentSend(null)
+ setAgentError(null)
+ }, [authenticatedScope, isAuthenticated, retainedSends])
const activityUnsubByAgentRef = useRef<Record<string, () => Promise<void>>>({})
const activityInFlightByAgentRef = useRef<Record<string, string[]>>({})
@@ -580,6 +626,7 @@ export function useAgentChatController({
const {
composerImageAttachments,
+ composerAttachmentRevisionRef,
composerReferenceAttachments,
resetComposerAttachments,
clearComposerAfterSend,
@@ -777,6 +824,9 @@ export function useAgentChatController({
// effects — append a message, push a toast — after the session is gone. The
// main-process half (`stopAllStreams` on logout) is Fase 4.
tracker.releaseAll()
+ sendScopeGeneration.current += 1
+ agentSendInFlightRef.current = false
+ retainedSends.resetRetainedSendStore()
// Abort any in-flight reconcile so a run mid-backoff can't resurrect a
// just-cleared tracker/FSM entry after this teardown (security review).
reconcileChatRef.current?.reset()
@@ -1696,6 +1746,7 @@ export function useAgentChatController({
const message = typeof durableError === 'string' ? durableError : durableError.message
const errorCode = typeof durableError === 'string' ? undefined : durableError.code
const errorProvider = typeof durableError === 'string' ? undefined : durableError.provider
+ markRetainedSendReason(taskIdHint ?? '', 'async_task_failed', message, 'upstream')
const attachments = buildResponseFileAttachments(taskResult)
await appendAssistantMessage(agentRef, chatId, {
id: crypto.randomUUID(),
@@ -1991,6 +2042,7 @@ export function useAgentChatController({
if (durableError) {
const message = typeof durableError === 'string' ? durableError : durableError.message
const errorCode = typeof durableError === 'string' ? undefined : durableError.code
+ markRetainedSendReason(state.taskId, 'async_task_failed', message, 'upstream')
const errorProvider =
typeof durableError === 'string' ? undefined : durableError.provider
const attachments = buildResponseFileAttachments(taskResult)
@@ -2113,7 +2165,11 @@ export function useAgentChatController({
case 'reconcile_replaced':
case 'recovered_from_task_result':
// The reconcile branch materialized a durable reply. Repaint the
- // stepper green and flip the FSM to idle.
+ // stepper green and flip the FSM to idle. #654 M6 — the durable reply
+ // exists, so this is as terminal as the `reply` branch below: release
+ // the retained payload instead of leaving it to accumulate, together
+ // with the older failures of this chat that the reply supersedes.
+ releaseSucceededRetainedSendsForTask(state.taskId)
dropActivity()
paintProgressDone()
setIdle()
@@ -2122,6 +2178,8 @@ export function useAgentChatController({
// The reconcile branch rendered (and toasted) a durable ERROR (budget
// deny etc.). Repaint the stepper + activity red — a green "completed"
// under an error bubble would misreport (code-review Should-fix).
+ // The payload stays retained for recovery; `reconcileChat` already
+ // recorded the durable error as its reason before returning here.
dropActivity()
updateMessageProgress(agentRef, state.userMessageId, () => ({
taskId: state.taskId,
@@ -2143,6 +2201,9 @@ export function useAgentChatController({
// The turn already covered the task, or the chat switched away
// mid-reconcile — settle without re-rendering (a reopen reconcile
// re-derives if a newer send didn't already take over via R1).
+ // #654 M6 — either way this task will never produce another terminal,
+ // so its retained payload has no reader left.
+ releaseRetainedSendsForTask(state.taskId)
dropActivity()
setIdle()
break
@@ -2176,6 +2237,11 @@ export function useAgentChatController({
}
if (result?.kind === 'reply') {
+ // Terminal success: the durable reply exists, so the retained send
+ // payload for this task can be released (idempotent — duplicate SSE/poll
+ // terminals only release once). The success also supersedes the older
+ // failures of this chat, which would otherwise resurface under the reply.
+ releaseSucceededRetainedSendsForTask(state.taskId)
if (result.content && result.content !== 'Message failed') {
const toolSteps = toMessageToolSteps(state.steps)
await appendAssistantMessage(agentRef, chatId, {
@@ -2190,6 +2256,13 @@ export function useAgentChatController({
}
liveDepsRef.current.pushToast(`Message sent to ${agentRef}.`, 'success')
} else if (result?.kind === 'error') {
+ // Terminal failure: the payload stays retained for explicit recovery.
+ markRetainedSendReason(
+ state.taskId,
+ result.source === 'failed' ? 'async_task_failed' : 'stream_lost',
+ result.message,
+ 'upstream'
+ )
if (result.source === 'failed') {
await appendAssistantMessage(agentRef, chatId, {
id: crypto.randomUUID(),
@@ -2418,8 +2491,13 @@ export function useAgentChatController({
async (
content: string,
attachments: ComposerImageAttachment[] = composerImageAttachments,
- references: ComposerReferenceAttachment[] = composerReferenceAttachments
+ references: ComposerReferenceAttachment[] = composerReferenceAttachments,
+ preserveComposer = false
) => {
+ const sendScope = sendScopeGeneration.current
+ const originalDraftChat = activeChatVisibilityRef.current.activeChatId
+ const originalDraftRevision = getComposerDraftRevision(originalDraftChat)
+ const originalAttachmentRevision = composerAttachmentRevisionRef.current
const trimmedContent = content.trim()
const effectiveAttachments = [...attachments]
const effectiveReferences = [...references]
@@ -2437,7 +2515,37 @@ export function useAgentChatController({
if (agentSendInFlightRef.current) return
agentSendInFlightRef.current = true
const sendAgent = selectedAgent
+ // Issue #654 — send-time image guard. Runs BEFORE the chat is created (a
+ // blocked visual send must not leave a stray empty chat) and long before
+ // the optimistic message/attachment clear. `readHostModelSelection` is the
+ // same shared source the composer and the selector read, so what is
+ // enforced here is exactly what the chip shows. Text-only sends keep the
+ // previous behavior and are never blocked by a missing capability.
+ let visualModelForSend: string | undefined
+ let visualModelRevisionForSend: number | undefined
+ if (effectiveAttachments.length > 0) {
+ const selection = readHostModelSelection(
+ sendAgent,
+ activeChatVisibilityRef.current.activeChatId ?? null
+ )
+ if (selection.visualSendBlocked) {
+ const blocker =
+ selection.imageBlockMessage ??
+ 'Image attachments are not available for the selected model yet.'
+ setAgentError(blocker)
+ pushToast(blocker, 'error')
+ agentSendInFlightRef.current = false
+ return
+ }
+ // Capture the model the guard just validated; the request below must
+ // carry exactly this identity (no re-reading an intent after the awaits).
+ visualModelForSend = selection.intentModel ?? selection.effectiveModel ?? undefined
+ visualModelRevisionForSend = selection.confirmedRevision ?? undefined
+ }
let sendChatId = activeChatId
+ // Captured for the retention snapshot: the model this attempt actually
+ // asked for (issue #654), readable from the catch below.
+ let requestModelForRetention: string | undefined
// B10: when a chat is auto-created by this send, the `chatList` captured in
// this closure predates it, so the auto-title lookup below would miss it and
// never title the chat on message 1 (then mis-title it on message 2). Keep
@@ -2447,6 +2555,7 @@ export function useAgentChatController({
try {
const chatId = crypto.randomUUID()
const meta = await chatStore.createChat(sendAgent, chatId)
+ if (sendScope !== sendScopeGeneration.current) return
chatStore.clearCachedRemoteData()
autoCreatedMeta = meta
appendNewEntry(sendAgent, meta)
@@ -2470,7 +2579,9 @@ export function useAgentChatController({
setActiveChatId(chatId)
setChatMessages([])
await chatStore.setLastActive(sendAgent, chatId)
+ if (sendScope !== sendScopeGeneration.current) return
} catch (error) {
+ if (sendScope !== sendScopeGeneration.current) return
const message = error instanceof Error ? error.message : String(error)
pushToast(`Could not create a chat session: ${message}`, 'error')
agentSendInFlightRef.current = false
@@ -2552,7 +2663,34 @@ export function useAgentChatController({
activityTaskToMessageByAgentRef.current[sendAgent] = {}
}
- clearComposerAfterSend(sendChatId)
+ const pendingModelForSend = sendChatId
+ ? chatStore.getPendingModel(sendAgent, sendChatId)
+ : undefined
+ requestModelForRetention = effectiveAttachments.length
+ ? visualModelForSend
+ : pendingModelForSend
+ retainSendSnapshot({
+ agentRef: sendAgent,
+ chatId: sendChatId ?? null,
+ userMessageId,
+ content: trimmedContent,
+ attachments: effectiveAttachments,
+ references: effectiveReferences,
+ model: requestModelForRetention,
+ reason: 'awaiting_terminal',
+ timestamp: Date.now(),
+ draftRevision: originalDraftRevision,
+ })
+ lastRetainedSendIdRef.current = userMessageId
+ if (
+ !preserveComposer &&
+ activeChatVisibilityRef.current.selectedAgent === sendAgent &&
+ activeChatVisibilityRef.current.activeChatId === sendChatId &&
+ composerAttachmentRevisionRef.current === originalAttachmentRevision &&
+ getComposerDraftRevision(originalDraftChat) === originalDraftRevision
+ ) {
+ clearComposerAfterSend(sendChatId)
+ }
setAgentError(null)
setFailedAgentSend(null)
setAgentSending(true)
@@ -2562,9 +2700,9 @@ export function useAgentChatController({
// R2 "Option A": a per-session model chosen while the host was suspended
// couldn't be persisted server-side, so it was held as pending. Piggyback
// it here — this send wakes the host and applies the model to this task.
- const pendingModel = sendChatId
- ? chatStore.getPendingModel(sendAgent, sendChatId)
- : undefined
+ if (sendScope !== sendScopeGeneration.current) return
+ const pendingModel = pendingModelForSend
+ const requestModel = requestModelForRetention
const request = {
content: effectiveContentForRequest,
channelType: 'rpc',
@@ -2574,7 +2712,10 @@ export function useAgentChatController({
effectiveAttachments.length > 0
? mapComposerAttachmentsToHostRequest(effectiveAttachments)
: undefined,
- ...(pendingModel ? { model: pendingModel } : {}),
+ ...(requestModel ? { model: requestModel } : {}),
+ ...(visualModelRevisionForSend === undefined
+ ? {}
+ : { modelSelectionRevision: visualModelRevisionForSend }),
}
const response = await window.clerum.rpc.invokeHostMessage(
@@ -2588,13 +2729,43 @@ export function useAgentChatController({
// A successful send creates or updates the durable server session. Do not
// let the short-lived sidebar cache hide that new catalog state.
chatStore.clearCachedRemoteData()
- // The runtime accepted the POST (sync reply or async task) — it received
- // the piggybacked model, so drop the pending entry. A thrown POST skips
- // this (the catch below leaves it set) so the next attempt retries it.
- if (pendingModel && sendChatId) {
- chatStore.clearPendingModel(sendAgent, sendChatId)
- }
+ if (sendScope !== sendScopeGeneration.current) return
const responseRecord = response as Record<string, unknown>
+ const ackOk = !responseRecord.error && responseRecord.success !== false
+ // #654 H1 — the send IS the write. Its ack carries the revision that
+ // write produced, and adopting it is what arms the NEXT conditional
+ // write correctly; without it the client keeps the revision it read
+ // before sending and loses a race it already won. A send on the model
+ // the session already runs on writes nothing and acks the current,
+ // unchanged revision, which confirms the same state.
+ const ackRevision = responseRecord.modelSelectionRevision
+ if (ackOk && requestModel && typeof ackRevision === 'number') {
+ confirmHostModelSelectionFromSend(
+ sendAgent,
+ sendChatId || null,
+ requestModel,
+ ackRevision
+ )
+ } else if (ackOk && pendingModel) {
+ // #654 L8 — a success with no revision after a piggyback is the Host
+ // saying it ignored the model. Drop the intent instead of resending it
+ // on every subsequent message.
+ dropIgnoredHostModelIntent(sendAgent, sendChatId || null, pendingModel)
+ }
+ // Confirm a held intent against a fresh authoritative read. An HTTP
+ // acknowledgement alone can contain a structured failure or an ignored
+ // legacy model selection; it must not clear a newer intent.
+ if (ackOk && pendingModel && sendChatId) {
+ void loadHostModels(
+ {
+ getHostModels: chatStore.getHostModels,
+ setHostModel: chatStore.setHostModel,
+ },
+ sendAgent,
+ sendChatId,
+ { force: true }
+ )
+ }
const taskId =
(typeof responseRecord.taskId === 'string' ? responseRecord.taskId : undefined) ||
(typeof responseRecord.id === 'string' ? responseRecord.id : undefined)
@@ -2604,6 +2775,11 @@ export function useAgentChatController({
const errorRecord = responseRecord.error as
| { message?: string; code?: string; provider?: string }
| undefined
+ // Issue #654: a synchronous failure can arrive as `{error: …}` OR as
+ // `{success: false}` without an error object. Both are failures — HTTP
+ // 200 or a missing `success` boolean never imply success.
+ const explicitFailure = responseRecord.success === false
+ const isErrorResponse = Boolean(errorRecord) || explicitFailure
const content =
typeof errorRecord?.message === 'string'
? errorRecord.message
@@ -2615,24 +2791,56 @@ export function useAgentChatController({
content,
timestamp: Date.now(),
...(responseAttachments.length ? { attachments: responseAttachments } : {}),
- ...(errorRecord && {
+ ...(isErrorResponse && {
isError: true,
- errorCode: errorRecord.code,
- errorProvider: errorRecord.provider,
+ errorCode: errorRecord?.code,
+ errorProvider: errorRecord?.provider,
}),
}
if (sendChatId) {
await chatStore.appendMessages(sendAgent, sendChatId, [userMessage])
}
await appendAssistantMessage(sendAgent, sendChatId, assistantMessage)
- if (errorRecord) {
+ if (isErrorResponse) {
+ // #654 M3 — a CAS conflict is not a capability verdict. Adopt the
+ // winning revision the Host reported (so an explicit retry is armed
+ // without a separate read) and re-read the authoritative selection.
+ if (errorRecord?.code === 'LLM_MODEL_SELECTION_CONFLICT') {
+ const conflictRevision = responseRecord.modelSelectionRevision
+ noteHostModelSelectionConflict(
+ {
+ getHostModels: chatStore.getHostModels,
+ setHostModel: chatStore.setHostModel,
+ },
+ sendAgent,
+ sendChatId || null,
+ requestModel ?? '',
+ typeof conflictRevision === 'number' ? conflictRevision : undefined
+ )
+ }
+ // The input was cleared before the round-trip: retain it (memory
+ // only) so the failure is recoverable, and restore the text into the
+ // composer only when it is still the same chat with no newer draft.
+ const failureMessage =
+ typeof errorRecord?.message === 'string' ? errorRecord.message : content
+ failRetainedSend(
+ sendAgent,
+ sendChatId ?? null,
+ userMessageId,
+ 'sync_error_envelope',
+ failureMessage,
+ 'upstream'
+ )
updateMessageActivity(sendAgent, userMessageId, previous => ({
...previous,
status: 'error',
- errorMessage: errorRecord.message,
+ errorMessage: failureMessage,
}))
- pushToast(`Message to ${sendAgent} failed: ${errorRecord.message ?? 'error'}`, 'error')
+ pushToast(`Message to ${sendAgent} failed: ${failureMessage || 'error'}`, 'error')
} else {
+ // Terminal success: release this payload and the older failures of
+ // the chat it supersedes.
+ releaseSucceededRetainedSend(sendAgent, sendChatId ?? null, userMessageId)
updateMessageActivity(sendAgent, userMessageId, previous => ({
...previous,
status: previous.events.length ? 'completed' : 'no_activity',
@@ -2654,6 +2862,7 @@ export function useAgentChatController({
if (sendChatId) {
await chatStore.appendMessages(sendAgent, sendChatId, [persistedUserMessage])
}
+ attachTaskIdToRetainedSend(sendAgent, sendChatId ?? null, userMessageId, taskId)
activityTaskToMessageByAgentRef.current[sendAgent] = {
...(activityTaskToMessageByAgentRef.current[sendAgent] || {}),
[taskId]: userMessageId,
@@ -2689,6 +2898,7 @@ export function useAgentChatController({
fsm.dispatch(taskKey, { type: 'TASK_CREATED', taskId })
}
} catch (error) {
+ if (sendScope !== sendScopeGeneration.current) return
const message = error instanceof Error ? error.message : String(error)
const normalized = message.toLowerCase()
const isRequestEntityTooLarge =
@@ -2708,6 +2918,10 @@ export function useAgentChatController({
? 'Access issue while sending to this agent.'
: 'Unable to send message to this agent.'
setAgentError(`${friendlyMessage} ${fallback}`)
+ // Issue #654 — keep the payload recoverable and record WHO it belongs
+ // to, so recovery can never overwrite a different chat's composer or a
+ // newer draft. Memory only; released on terminal success/discard.
+ failRetainedSend(sendAgent, sendChatId ?? null, userMessageId, 'post_failed', message, kind)
setFailedAgentSend({
content: trimmedContent,
attachments: effectiveAttachments,
@@ -2715,6 +2929,10 @@ export function useAgentChatController({
message,
kind,
timestamp: Date.now(),
+ agentRef: sendAgent,
+ chatId: sendChatId ?? null,
+ userMessageId,
+ model: requestModelForRetention,
})
updateMessageActivity(sendAgent, userMessageId, previous => ({
...previous,
@@ -2751,8 +2969,10 @@ export function useAgentChatController({
} finally {
// Fire & forget: release the synchronous setup guard immediately. The
// task (if any) keeps running in the tracker.
- agentSendInFlightRef.current = false
- setAgentSending(false)
+ if (sendScope === sendScopeGeneration.current) {
+ agentSendInFlightRef.current = false
+ setAgentSending(false)
+ }
}
},
[
@@ -2785,14 +3005,100 @@ export function useAgentChatController({
[composerImageAttachments, composerReferenceAttachments, sendAgentMessage]
)
+ const visibleRetainedFailure = useMemo(() => {
+ const snapshot = selectedAgent
+ ? retainedSends.getLatestRetainedSendSnapshotForChat(selectedAgent, activeChatId)
+ : undefined
+ if (!snapshot?.failure) return null
+ return {
+ ...snapshot,
+ message: snapshot.failure.message,
+ kind: snapshot.failure.kind,
+ } satisfies FailedAgentSend
+ }, [retainedSends, retainedRevision, selectedAgent, activeChatId])
+ const visibleFailure =
+ visibleRetainedFailure ??
+ (failedAgentSend &&
+ (!failedAgentSend.agentRef ||
+ (failedAgentSend.agentRef === selectedAgent && failedAgentSend.chatId === activeChatId))
+ ? failedAgentSend
+ : null)
+
+ // #654 M5 — a retry re-sends under a NEW `userMessageId`, so the snapshot the
+ // failed attempt retained is not the one the retry writes. Without an explicit
+ // release the old snapshot stays in the store forever, holding its attachment
+ // bytes and still answering `getLatestRetainedSendSnapshotForChat` (which picks
+ // the newest snapshot *carrying a failure*).
const handleRetryFailedAgentSend = useCallback(async () => {
- if (!failedAgentSend) return
- await sendAgentMessage(
- failedAgentSend.content,
- failedAgentSend.attachments,
- failedAgentSend.references
+ if (!visibleFailure) return
+ const previous = visibleFailure
+ const retainedBefore = lastRetainedSendIdRef.current
+ await sendAgentMessage(previous.content, previous.attachments, previous.references, true)
+ // A retry refused before dispatch (image guard, running task, a send already
+ // in flight) retained nothing, so the old snapshot is still the only copy of
+ // the payload: keep it and the failure it shows. Once a newer send has
+ // retained its own snapshot, the old one is redundant whatever that send's
+ // outcome — on failure the payload lives on in the newer snapshot.
+ if (lastRetainedSendIdRef.current === retainedBefore) return
+ if (previous.agentRef && previous.userMessageId) {
+ releaseRetainedSend(previous.agentRef, previous.chatId ?? null, previous.userMessageId)
+ }
+ setFailedAgentSend(null)
+ }, [visibleFailure, sendAgentMessage, releaseRetainedSend])
+
+ const handleDiscardFailedAgentSend = useCallback(() => {
+ if (visibleFailure?.agentRef && visibleFailure.userMessageId) {
+ releaseRetainedSend(
+ visibleFailure.agentRef,
+ visibleFailure.chatId ?? null,
+ visibleFailure.userMessageId
+ )
+ // The visible failure is the newest one of this chat; the older failures
+ // behind it would otherwise resurface one by one after each discard.
+ releaseRetainedFailuresForChat(
+ visibleFailure.agentRef,
+ visibleFailure.chatId ?? null,
+ visibleFailure.timestamp
+ )
+ }
+ setFailedAgentSend(null)
+ setAgentError(null)
+ }, [visibleFailure, releaseRetainedSend, releaseRetainedFailuresForChat])
+
+ const handleRecoverFailedAgentSend = useCallback(() => {
+ if (
+ !visibleFailure ||
+ visibleFailure.agentRef !== activeChatVisibilityRef.current.selectedAgent ||
+ visibleFailure.chatId !== activeChatVisibilityRef.current.activeChatId
)
- }, [failedAgentSend, sendAgentMessage])
+ return
+ if (
+ getComposerDraft(activeChatId) ||
+ composerImageAttachments.length ||
+ composerReferenceAttachments.length
+ ) {
+ pushToast('Keep or clear the current draft before recovering the earlier input.', 'error')
+ return
+ }
+ setComposerDraft(activeChatId, visibleFailure.content)
+ handleAddComposerImageAttachments(
+ visibleFailure.attachments.map(attachment => ({
+ ...attachment,
+ previewDataUrl: `data:${attachment.mimeType};base64,${attachment.dataBase64}`,
+ }))
+ )
+ handleAddComposerReferenceAttachments(visibleFailure.references)
+ handleDiscardFailedAgentSend()
+ }, [
+ visibleFailure,
+ activeChatId,
+ composerImageAttachments,
+ composerReferenceAttachments,
+ pushToast,
+ handleAddComposerImageAttachments,
+ handleAddComposerReferenceAttachments,
+ handleDiscardFailedAgentSend,
+ ])
const cancelTask = useCallback(
async (taskId: string) => {
@@ -2841,10 +3147,16 @@ export function useAgentChatController({
try {
await window.clerum.rpc.cancelTask(hostRef, taskId)
markCancelled('Cancelled by user.')
+ // #654 M6 — a cancel is terminal by intent: the user does not want this
+ // payload resent, so nothing will read the retained snapshot again.
+ releaseRetainedSendsForTask(taskId)
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
if (message.includes('404') || message.toLowerCase().includes('task not found')) {
markCancelled('Task already finished or is no longer active.')
+ // The task is gone upstream, so it can no longer produce a terminal
+ // event — same reasoning as the successful cancel above.
+ releaseRetainedSendsForTask(taskId)
pushToast('That task is no longer active.', 'info')
return
}
@@ -2852,7 +3164,7 @@ export function useAgentChatController({
pushToast(`Failed to cancel task: ${message}`, 'error')
}
},
- [pushToast, selectedAgent]
+ [pushToast, selectedAgent, releaseRetainedSendsForTask]
)
const setPendingChatSelection = useCallback(
@@ -2962,8 +3274,11 @@ export function useAgentChatController({
composerImageAttachments,
composerReferenceAttachments,
agentSending,
- agentError,
- failedAgentSend,
+ // A fresh send-time error (a blocked image send, a new POST failure) wins;
+ // the retained failure's message covers the banner only when nothing newer
+ // has been reported.
+ agentError: agentError ?? visibleRetainedFailure?.message ?? null,
+ failedAgentSend: visibleFailure,
chatEndRef,
scrollChatToBottom,
activityByMessageId,
@@ -2986,6 +3301,8 @@ export function useAgentChatController({
loadMoreChatSessions,
handleSendAgentMessage,
handleRetryFailedAgentSend,
+ handleRecoverFailedAgentSend,
+ handleDiscardFailedAgentSend,
clearComposerSendError,
handleAddComposerImageAttachments,
handleUpdateComposerImageAttachment,
diff --git a/desktop-app/ui/src/hooks/domain/useComposerAttachments.ts b/desktop-app/ui/src/hooks/domain/useComposerAttachments.ts
index 820ef5e8c..04c54c222 100644
--- a/desktop-app/ui/src/hooks/domain/useComposerAttachments.ts
+++ b/desktop-app/ui/src/hooks/domain/useComposerAttachments.ts
@@ -33,8 +33,10 @@ export function useComposerAttachments({
ComposerReferenceAttachment[]
>([])
const composerAttachmentOrderRef = useRef(0)
+ const composerAttachmentRevisionRef = useRef(0)
const revokeComposerPreviewUrls = useCallback((attachments: ComposerImageAttachment[]) => {
+ composerAttachmentRevisionRef.current += 1
const canRevokeObjectUrl =
typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function'
if (!canRevokeObjectUrl) return
@@ -49,6 +51,7 @@ export function useComposerAttachments({
}, [])
const clearComposerImageAttachments = useCallback(() => {
+ composerAttachmentRevisionRef.current += 1
setComposerImageAttachments(previous => {
revokeComposerPreviewUrls(previous)
return []
@@ -81,6 +84,7 @@ export function useComposerAttachments({
const handleAddComposerImageAttachments = useCallback(
(attachments: ComposerImageAttachment[]) => {
+ composerAttachmentRevisionRef.current += 1
if (!attachments.length) return
setComposerImageAttachments(previous => {
const next = [...previous]
@@ -114,6 +118,7 @@ export function useComposerAttachments({
const handleUpdateComposerImageAttachment = useCallback(
(attachment: ComposerImageAttachment) => {
+ composerAttachmentRevisionRef.current += 1
setComposerImageAttachments(previous => {
const index = previous.findIndex(item => item.id === attachment.id)
if (index === -1) {
@@ -135,6 +140,7 @@ export function useComposerAttachments({
const handleRemoveComposerImageAttachment = useCallback(
(attachmentId: string) => {
+ composerAttachmentRevisionRef.current += 1
setComposerImageAttachments(previous => {
const removed = previous.filter(att => att.id === attachmentId)
if (removed.length) {
@@ -148,6 +154,7 @@ export function useComposerAttachments({
const handleAddComposerReferenceAttachments = useCallback(
(attachments: ComposerReferenceAttachment[]) => {
+ composerAttachmentRevisionRef.current += 1
if (!attachments.length) return
setComposerReferenceAttachments(previous => {
const next = [...previous]
@@ -168,11 +175,13 @@ export function useComposerAttachments({
)
const handleRemoveComposerReferenceAttachment = useCallback((attachmentId: string) => {
+ composerAttachmentRevisionRef.current += 1
setComposerReferenceAttachments(previous => previous.filter(att => att.id !== attachmentId))
}, [])
return {
composerImageAttachments,
+ composerAttachmentRevisionRef,
composerReferenceAttachments,
resetComposerAttachments,
clearComposerAfterSend,
diff --git a/desktop-app/ui/src/hooks/useAgentChatActionsValue.ts b/desktop-app/ui/src/hooks/useAgentChatActionsValue.ts
index 29c93e92c..739d9c2dc 100644
--- a/desktop-app/ui/src/hooks/useAgentChatActionsValue.ts
+++ b/desktop-app/ui/src/hooks/useAgentChatActionsValue.ts
@@ -37,6 +37,8 @@ export function useAgentChatActionsValue(vm: AppVm): AgentChatActionsContextValu
)
const handleSendAgentMessage = useStableCallback(vm.handleSendAgentMessage)
const handleRetryFailedAgentSend = useStableCallback(vm.handleRetryFailedAgentSend)
+ const handleRecoverFailedAgentSend = useStableCallback(vm.handleRecoverFailedAgentSend)
+ const handleDiscardFailedAgentSend = useStableCallback(vm.handleDiscardFailedAgentSend)
return useMemo(
() => ({
@@ -56,6 +58,8 @@ export function useAgentChatActionsValue(vm: AppVm): AgentChatActionsContextValu
handleRemoveComposerReferenceAttachment,
handleSendAgentMessage,
handleRetryFailedAgentSend,
+ handleRecoverFailedAgentSend,
+ handleDiscardFailedAgentSend,
}),
[
chatEndRef,
@@ -74,6 +78,8 @@ export function useAgentChatActionsValue(vm: AppVm): AgentChatActionsContextValu
handleRemoveComposerReferenceAttachment,
handleSendAgentMessage,
handleRetryFailedAgentSend,
+ handleRecoverFailedAgentSend,
+ handleDiscardFailedAgentSend,
]
)
}
diff --git a/desktop-app/ui/src/hooks/useAppController.ts b/desktop-app/ui/src/hooks/useAppController.ts
index 4c666e375..3ca1a8da9 100644
--- a/desktop-app/ui/src/hooks/useAppController.ts
+++ b/desktop-app/ui/src/hooks/useAppController.ts
@@ -1387,6 +1387,8 @@ export function useAppController() {
loadMoreChatSessions: chat.loadMoreChatSessions,
handleSendAgentMessage: chat.handleSendAgentMessage,
handleRetryFailedAgentSend: chat.handleRetryFailedAgentSend,
+ handleRecoverFailedAgentSend: chat.handleRecoverFailedAgentSend,
+ handleDiscardFailedAgentSend: chat.handleDiscardFailedAgentSend,
clearComposerSendError: chat.clearComposerSendError,
handleAddComposerImageAttachments: chat.handleAddComposerImageAttachments,
handleUpdateComposerImageAttachment: chat.handleUpdateComposerImageAttachment,
diff --git a/desktop-app/ui/src/hooks/useChatStore.ts b/desktop-app/ui/src/hooks/useChatStore.ts
index cc6771514..4569da3cf 100644
--- a/desktop-app/ui/src/hooks/useChatStore.ts
+++ b/desktop-app/ui/src/hooks/useChatStore.ts
@@ -1,12 +1,23 @@
import { useCallback } from 'react'
import type {
ChatMessage,
- HostModelsResult,
ReplaceChatMessagesOptions,
SessionMessagesQuery,
SessionsListQuery,
SessionsListResult,
} from '../../../src/types'
+import {
+ clearPendingModelIntent,
+ clearPreChatModelIntent,
+ getPendingModelIntent,
+ getPreChatModelIntent,
+ setPendingModelIntent,
+ setPreChatModelIntent,
+} from '../lib/hostModelIntentStore'
+import {
+ markHostModelSelectionChanged,
+ resetHostModelSelectionStore,
+} from '../lib/hostModelSelectionStore'
// The session lifecycle types live in the shared `src/types` (they cross the
// IPC bridge from the server). Re-exported here so existing UI imports from
@@ -23,36 +34,7 @@ export type {
SetHostModelResult,
} from '../../../src/types'
-/**
- * Per-chat PENDING model selections (R2 "Option A"). When a user changes the
- * model while the agent host is SUSPENDED (`replicas=0`), the `POST /model`
- * write can't reach the runtime, so the choice can't be persisted server-side.
- * Rather than silently drop it, the selection is held here — keyed by the same
- * `(agentRef, chatId)` pair sessions are keyed by — and PIGGYBACKED onto the
- * next message send, which wakes the host and applies the model to that task.
- *
- * This is a module-level singleton (not React state): it is written by
- * `useHostModels.selectModel` and drained by the send path in
- * `useAgentChatController`, two independent consumers that never share a render
- * tree, and neither needs to re-render when it changes (the optimistic UI is
- * owned by `useHostModels`' own state). Keeping it out of React state avoids a
- * context/provider just to shuttle one imperative value between them.
- */
-const pendingModelByChat: Record<string, string> = {}
-
-/**
- * PRE-CHAT model selections (R2 new-chat composer). On the new-chat composer the
- * user can pick a model BEFORE any chat exists, so there is no `chatId` to key a
- * pending entry by (and no server round-trip is possible — there is no session to
- * `POST /model` for). The pick is held here keyed by agent alone, kept purely
- * local so it creates NO stray/empty chat. On the first send the controller
- * migrates it into `pendingModelByChat` under the freshly-created `chatId` and
- * piggybacks it onto the outgoing message. Same module-singleton rationale as
- * `pendingModelByChat`.
- */
-const preChatModelByAgent: Record<string, string> = {}
const SESSION_CATALOG_TTL_MS = 5_000
-const HOST_MODELS_TTL_MS = 30_000
type CachedRequest<T> = {
expiresAt: number
@@ -60,20 +42,9 @@ type CachedRequest<T> = {
}
const sessionCatalogRequests = new Map<string, CachedRequest<SessionsListResult>>()
-const hostModelRequests = new Map<string, CachedRequest<HostModelsResult | null>>()
let sessionCatalogSource: typeof window.clerum.rpc.listSessions | null = null
-let hostModelsSource: typeof window.clerum.rpc.getHostModels | null = null
let remoteCacheScope = 'unknown'
-/** Composite key mirroring the session `chatKey` convention (`agentRef::chatId`). */
-function pendingModelKey(agentRef: string, chatId: string): string {
- return `${agentRef}::${chatId}`
-}
-
-function hostModelKey(hostRef: string, chatId: string): string {
- return `${remoteCacheScope}:${hostRef}:${chatId}`
-}
-
function pruneExpiredSessionCatalogRequests(now = Date.now()): void {
for (const [key, cached] of sessionCatalogRequests) {
if (cached.expiresAt <= now) {
@@ -199,28 +170,20 @@ export function useChatStore() {
window.clerum.rpc.getContextBreakdown(hostRef, agent, chatId),
[]
)
- const getHostModels = useCallback((hostRef: string, chatId: string) => {
- const source = window.clerum.rpc.getHostModels
- if (hostModelsSource !== source) {
- hostModelRequests.clear()
- hostModelsSource = source
- }
- const key = hostModelKey(hostRef, chatId)
- const cached = hostModelRequests.get(key)
- if (cached && cached.expiresAt > Date.now()) return cached.promise
-
- const promise = source(hostRef, chatId).catch(error => {
- hostModelRequests.delete(key)
- throw error
- })
- hostModelRequests.set(key, { expiresAt: Date.now() + HOST_MODELS_TTL_MS, promise })
- return promise
- }, [])
- const setHostModel = useCallback(async (hostRef: string, chatId: string, model: string) => {
- const result = await window.clerum.rpc.setHostModel(hostRef, chatId, model)
- hostModelRequests.delete(hostModelKey(hostRef, chatId))
- return result
- }, [])
+ // #654 M12 — no cache layer here. `hostModelSelectionStore` owns request
+ // deduplication AND revision ordering; a second TTL cache in front of it could
+ // only serve a response fetched before a write, which is exactly the stale
+ // revision the CAS must not be armed with. Both call sites already bypassed
+ // it with `force: true`, so the layer had no reader left.
+ const getHostModels = useCallback(
+ (hostRef: string, chatId: string) => window.clerum.rpc.getHostModels(hostRef, chatId),
+ []
+ )
+ const setHostModel = useCallback(
+ (hostRef: string, chatId: string, model: string, expectedRevision?: number) =>
+ window.clerum.rpc.setHostModel(hostRef, chatId, model, undefined, expectedRevision),
+ []
+ )
// Spec 15 Fase B — propagate an explicit user rename to the server. In this app
// hostRef === agent === agentRef (same key used by listSessions). Rejections
// propagate so the pending-rename queue can branch on the HTTP status.
@@ -231,55 +194,50 @@ export function useChatStore() {
)
const clearCachedRemoteData = useCallback(() => {
sessionCatalogRequests.clear()
- hostModelRequests.clear()
sessionCatalogSource = null
- hostModelsSource = null
}, [])
const setRemoteCacheScope = useCallback((scope: string) => {
if (remoteCacheScope === scope) return
remoteCacheScope = scope
sessionCatalogRequests.clear()
- hostModelRequests.clear()
// Pending selections are session-owned even though they are not remote
// responses. Never carry an unpersisted model choice across logout, user,
// or team boundaries where the same agent/chat identifiers may reappear.
- for (const key of Object.keys(pendingModelByChat)) delete pendingModelByChat[key]
- for (const key of Object.keys(preChatModelByAgent)) delete preChatModelByAgent[key]
+ resetHostModelSelectionStore()
}, [])
// --- Pending (unpersisted) model selections — R2 "Option A" (see the
- // `pendingModelByChat` note above). Only UNPERSISTED selections are tracked:
+ // header of `lib/hostModelIntentStore.ts`). Only UNPERSISTED selections are tracked:
// a selection accepted by the runtime survives host suspension in the session
// store and needs no piggybacking.
const setPendingModel = useCallback((agentRef: string, chatId: string, model: string) => {
- if (!agentRef || !chatId || !model) return
- pendingModelByChat[pendingModelKey(agentRef, chatId)] = model
+ setPendingModelIntent(agentRef, chatId, model)
+ markHostModelSelectionChanged(agentRef, chatId)
}, [])
const getPendingModel = useCallback(
(agentRef: string, chatId: string): string | undefined =>
- agentRef && chatId ? pendingModelByChat[pendingModelKey(agentRef, chatId)] : undefined,
+ getPendingModelIntent(agentRef, chatId),
[]
)
const clearPendingModel = useCallback((agentRef: string, chatId: string) => {
- if (!agentRef || !chatId) return
- delete pendingModelByChat[pendingModelKey(agentRef, chatId)]
+ clearPendingModelIntent(agentRef, chatId)
+ markHostModelSelectionChanged(agentRef, chatId)
}, [])
// --- Pre-chat (unpersisted, no chatId yet) model selection — R2 new-chat
// composer selector. Keyed by agent alone; migrated to a `pendingModelByChat`
// entry by the send path once the first send creates the chatId.
const setPreChatModel = useCallback((agentRef: string, model: string) => {
- if (!agentRef || !model) return
- preChatModelByAgent[agentRef] = model
+ setPreChatModelIntent(agentRef, model)
+ markHostModelSelectionChanged(agentRef, null)
}, [])
const getPreChatModel = useCallback(
- (agentRef: string): string | undefined =>
- agentRef ? preChatModelByAgent[agentRef] : undefined,
+ (agentRef: string): string | undefined => getPreChatModelIntent(agentRef),
[]
)
const clearPreChatModel = useCallback((agentRef: string) => {
- if (!agentRef) return
- delete preChatModelByAgent[agentRef]
+ clearPreChatModelIntent(agentRef)
+ markHostModelSelectionChanged(agentRef, null)
}, [])
return {
diff --git a/desktop-app/ui/src/hooks/useHostModels.ts b/desktop-app/ui/src/hooks/useHostModels.ts
index bad3b045b..ad3dc0e94 100644
--- a/desktop-app/ui/src/hooks/useHostModels.ts
+++ b/desktop-app/ui/src/hooks/useHostModels.ts
@@ -1,200 +1,114 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { type HostModelsResult, useChatStore } from './useChatStore'
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react'
+import {
+ type HostModelSelectionTransport,
+ type HostModelSelectionView,
+ clearHostModelSelectionError,
+ getHostModelSelectionSnapshot,
+ loadHostModels,
+ markHostModelSelectionChanged,
+ selectHostModel,
+ subscribeHostModelSelection,
+} from '../lib/hostModelSelectionStore'
+import { useChatStore } from './useChatStore'
/**
- * A model selection is OPTIMISTIC (R2 "Option A"): the UI reflects the choice at
- * once, then the `POST /model` write is attempted. The outcome splits three ways:
+ * Per-session model selection for one `(agentRef, chatId)` pair (R2 model
+ * selector). A thin subscription over the shared
+ * {@link ../lib/hostModelSelectionStore}: the chip, the composer image guard and
+ * the send path all read the same entry, so an optimistic pick is immediately
+ * enforced everywhere without a new provider tree.
*
- * - 200 → persisted server-side; clear any pending for the chat.
- * - 403 model_not_allowed → a real allowlist rejection; revert + surface error.
- * - anything else → the host is suspended / unreachable (connection error,
- * 5xx, wake-eligible 503); KEEP the optimistic UI, record
- * the model as pending, and swallow+log — the next send
- * wakes the host and applies it (piggyback).
+ * A selection is OPTIMISTIC (R2 "Option A"): the UI reflects the choice at once,
+ * then the `POST /model` write is attempted. The outcome splits four ways:
*
- * The 403 vs transport split is done on the error MESSAGE, not an HTTP status:
- * Electron IPC serializes errors down to their message string, so the status set
- * on the `ApiError` in `rpcProxyClient` does NOT cross the bridge. Only the
- * allowlist rejection embeds the `model_not_allowed` token in that message
- * (rpcProxyClient keys off the body's `error` code, not the status) — every other
- * failure, including a host-access 403, is treated as host-unavailable.
- */
-
-/**
- * Per-session model selection state for one `(agentRef, chatId)` pair (R2 model
- * selector). Sibling of `useContextBreakdown`: the agent IS the hostRef for
- * desktop chats.
+ * - 200 → persisted server-side; clear the intent.
+ * - 409 model_selection_conflict → another writer moved the session selection;
+ * keep the last confirmed state, refetch, and
+ * block images until the authoritative read lands.
+ * - 403 model_not_allowed → a real allowlist rejection; drop the intent
+ * and surface the inline error.
+ * - anything else → the host is suspended / unreachable
+ * (connection error, 5xx, wake-eligible 503);
+ * KEEP the optimistic UI, record the model as
+ * pending, and swallow+log — the next send
+ * wakes the host and applies it (piggyback).
*
- * `data` is:
- * - `undefined` while the first fetch is in flight (selector hides — no flash),
- * - `null` when the host predates the endpoint or the fetch failed (the bridge
- * resolves 404/501 to `null`, and any error is swallowed to `null`) — the
- * selector stays hidden rather than surfacing a noisy error (R2.6),
- * - the model list + current selection otherwise.
- *
- * A model-list fetch or a failed set must never break the chat surface, so
- * fetch errors are swallowed and set errors surface only as inline copy.
+ * The transport split is done on the error MESSAGE, not an HTTP status: Electron
+ * IPC serializes errors down to their message string, so the status set on the
+ * `ApiError` in `rpcProxyClient` does NOT cross the bridge. Both terminal
+ * rejections embed their token in that message.
*/
-/** Token embedded in the rejection message when a model is outside the allowlist. */
-const MODEL_NOT_ALLOWED = 'model_not_allowed'
-
-export interface UseHostModelsResult {
- data: HostModelsResult | null | undefined
- loading: boolean
- saving: boolean
- /** Inline error from the last `selectModel` (e.g. a 403 model_not_allowed). */
- error: string | null
- /** Applies the model to the session. Resolves `true` on success. */
+export interface UseHostModelsResult extends HostModelSelectionView {
+ refresh: () => Promise<void>
+ /** Applies the model to the session. Resolves `true` when usable next send. */
selectModel: (model: string) => Promise<boolean>
clearError: () => void
}
export function useHostModels(agentRef: string, chatId: string): UseHostModelsResult {
- const {
- getHostModels,
- setHostModel,
- setPendingModel,
- clearPendingModel,
- getPendingModel,
- setPreChatModel,
- getPreChatModel,
- } = useChatStore()
- const [data, setData] = useState<HostModelsResult | null | undefined>(undefined)
- const [loading, setLoading] = useState(false)
- const [saving, setSaving] = useState(false)
- const [error, setError] = useState<string | null>(null)
- // Monotonic guard: a stale response for a previous chat must not overwrite the
- // current selection after a fast chat switch.
- const requestSeqRef = useRef(0)
- // Latest-value mirror of `data` so `selectModel` can capture the pre-optimistic
- // selection for revert without listing `data` in its deps (which would rebuild
- // the callback on every fetch). Same pattern used across the controllers.
- const dataRef = useRef(data)
- dataRef.current = data
+ const { getHostModels, setHostModel } = useChatStore()
+ const selectionChatId = chatId || null
+
+ const transport = useMemo<HostModelSelectionTransport>(
+ () => ({
+ getHostModels: (hostRef: string, id: string) => getHostModels(hostRef, id),
+ setHostModel: (hostRef: string, id: string, model: string, expectedRevision?: number) =>
+ setHostModel(hostRef, id, model, expectedRevision),
+ }),
+ [getHostModels, setHostModel]
+ )
+
+ const subscribe = useCallback(
+ (listener: () => void) => subscribeHostModelSelection(agentRef, selectionChatId, listener),
+ [agentRef, selectionChatId]
+ )
+ const getSnapshot = useCallback(
+ () => getHostModelSelectionSnapshot(agentRef, selectionChatId),
+ [agentRef, selectionChatId]
+ )
+ const view = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
useEffect(() => {
- // `chatId` is OPTIONAL (R2 new-chat composer): with no chat yet we still fetch
- // the host-level model list so the selector can render before the first send.
- // Only the agent (== hostRef) is required to resolve the list.
- if (!agentRef) {
- setData(undefined)
- return
- }
- const seq = ++requestSeqRef.current
- setLoading(true)
- setError(null)
- void (async () => {
- try {
- const result = await getHostModels(agentRef, chatId)
- if (seq !== requestSeqRef.current) return
- // Reflect any locally-held (unpersisted) selection the server hasn't yet
- // applied: a PRE-CHAT pick (no chatId) or a PENDING pick recorded while the
- // host was suspended. The server's persisted `sessionModel` always wins;
- // the local slot only fills in when the server has none, so the chip keeps
- // showing the user's choice across a refetch/remount (e.g. the pre-chat →
- // first-chat transition) instead of flashing back to the host default.
- if (result && !result.sessionModel) {
- const localModel = chatId ? getPendingModel(agentRef, chatId) : getPreChatModel(agentRef)
- if (localModel) {
- setData({ ...result, sessionModel: localModel })
- return
- }
- }
- setData(result)
- } catch (err) {
- if (seq !== requestSeqRef.current) return
- // Never break the chat surface — hide the selector and log (mirrors
- // useContextBreakdown's swallow policy).
- console.warn('[useHostModels] fetch failed (ignored):', err)
- setData(null)
- } finally {
- if (seq === requestSeqRef.current) setLoading(false)
- }
- })()
- }, [agentRef, chatId, getHostModels, getPendingModel, getPreChatModel])
+ if (!agentRef) return
+ void loadHostModels(transport, agentRef, selectionChatId)
+ }, [transport, agentRef, selectionChatId, view.scopeGeneration])
- const clearError = useCallback(() => setError(null), [])
+ useEffect(() => {
+ const validUntil = view.imageInput.validUntil
+ if (!validUntil || view.imageInput.state !== 'supported') return
+ let timer: ReturnType<typeof setTimeout>
+ const schedule = () => {
+ const remaining = Date.parse(validUntil) - Date.now()
+ if (remaining <= 0) {
+ markHostModelSelectionChanged(agentRef, selectionChatId)
+ return
+ }
+ timer = setTimeout(schedule, Math.min(remaining, 2_147_483_647))
+ }
+ schedule()
+ return () => clearTimeout(timer)
+ }, [agentRef, selectionChatId, view.imageInput.state, view.imageInput.validUntil])
const selectModel = useCallback(
- async (model: string): Promise<boolean> => {
- if (!agentRef || !model) return false
- // PRE-CHAT (no chatId yet): there is no session to `POST /model` for, so the
- // pick is held locally keyed by agent. It creates NO stray chat; the send
- // path migrates it to the new chat's pending slot and piggybacks it on the
- // first message. Reflect it optimistically so the chip updates at once.
- if (!chatId) {
- setPreChatModel(agentRef, model)
- setData(prev =>
- prev ? { ...prev, sessionModel: model, sessionModelBlocked: undefined } : prev
- )
- return true
- }
- // Same monotonic guard as the fetch effect, applied to the WRITE path: the
- // component is mounted un-keyed, so a POST started for chat A can resolve
- // after a fast switch to chat B. Without this, chat A's accepted model
- // would overwrite chat B's `sessionModel` and clear its blocked-model
- // notice. Capture the seq now; a stale resolution is dropped silently
- // (the server selection is unaffected and self-corrects on next fetch).
- const seq = requestSeqRef.current
- // Capture the FULL pre-optimistic snapshot so a real rejection can revert
- // to it — both the selection and the blocked-model notice, which the
- // optimistic set below clears.
- const previousSelection = dataRef.current?.sessionModel ?? null
- const previousBlocked = dataRef.current?.sessionModelBlocked
- setSaving(true)
- setError(null)
- // Optimistic: reflect the choice immediately (R2 "Option A"). Clearing
- // `sessionModelBlocked` dismisses the stale "reverted to default" notice.
- setData(prev =>
- prev ? { ...prev, sessionModel: model, sessionModelBlocked: undefined } : prev
- )
- try {
- const result = await setHostModel(agentRef, chatId, model)
- if (seq !== requestSeqRef.current) return false
- // Persisted server-side — reconcile to the canonical model the runtime
- // echoed and drop any pending piggyback for this chat.
- setData(prev =>
- prev ? { ...prev, sessionModel: result.model, sessionModelBlocked: undefined } : prev
- )
- clearPendingModel(agentRef, chatId)
- return true
- } catch (err) {
- // Stale after a fast chat-switch: intentionally drop this pending too —
- // the selection was for a chat the user navigated away from, so we do
- // NOT record a piggyback for it (the closure still holds the old chatId).
- if (seq !== requestSeqRef.current) return false
- const message = err instanceof Error ? err.message : String(err)
- if (message.includes(MODEL_NOT_ALLOWED)) {
- // Real allowlist rejection (host was reachable): revert the optimistic
- // UI to the FULL pre-optimistic snapshot (selection + blocked notice)
- // and surface the error. NOT a wake case — record no pending.
- setData(prev =>
- prev
- ? { ...prev, sessionModel: previousSelection, sessionModelBlocked: previousBlocked }
- : prev
- )
- setError('That model is no longer allowed — selection unchanged.')
- return false
- }
- // Host unavailable (suspended / transport / 5xx): keep the optimistic UI
- // and record the model as pending so the next message send carries it and
- // wakes the host. Swallow + log, mirroring the fetch path's policy.
- console.warn(
- '[useHostModels] set failed; host likely suspended — keeping optimistic selection, will piggyback on next send:',
- err
- )
- setPendingModel(agentRef, chatId, model)
- return true
- } finally {
- // Always clear the transient saving flag — it is a single UI-local
- // boolean, and gating it on the seq would leave it stuck true on the
- // post-switch instance (which reuses this hook), disabling the menu.
- setSaving(false)
- }
- },
- [agentRef, chatId, setHostModel, setPendingModel, clearPendingModel, setPreChatModel]
+ (model: string) => selectHostModel(transport, agentRef, selectionChatId, model),
+ [transport, agentRef, selectionChatId]
+ )
+ const refresh = useCallback(() => {
+ if (getHostModelSelectionSnapshot(agentRef, selectionChatId).loading) return Promise.resolve()
+ return loadHostModels(transport, agentRef, selectionChatId, { force: true })
+ }, [transport, agentRef, selectionChatId])
+ useEffect(() => {
+ const onFocus = () => {
+ void refresh()
+ }
+ window.addEventListener('focus', onFocus)
+ return () => window.removeEventListener('focus', onFocus)
+ }, [refresh])
+ const clearError = useCallback(
+ () => clearHostModelSelectionError(agentRef, selectionChatId),
+ [agentRef, selectionChatId]
)
- return { data, loading, saving, error, selectModel, clearError }
+ return { ...view, selectModel, clearError, refresh }
}
diff --git a/desktop-app/ui/src/lib/__tests__/hostModelSelectionStore.test.ts b/desktop-app/ui/src/lib/__tests__/hostModelSelectionStore.test.ts
new file mode 100644
index 000000000..365d9731d
--- /dev/null
+++ b/desktop-app/ui/src/lib/__tests__/hostModelSelectionStore.test.ts
@@ -0,0 +1,889 @@
+// @vitest-environment jsdom
+import { type Mock, afterEach, describe, expect, it, vi } from 'vitest'
+import fc from 'fast-check'
+import type { HostModelsResult, SetHostModelResult } from '../../../../src/types'
+import {
+ getPendingModelIntent,
+ getPreChatModelIntent,
+ setPendingModelIntent,
+ setPreChatModelIntent,
+} from '../hostModelIntentStore'
+import {
+ type HostModelSelectionTransport,
+ confirmHostModelSelectionFromSend,
+ getHostModelSelectionSnapshot,
+ loadHostModels,
+ noteHostModelSelectionConflict,
+ readHostModelSelection,
+ resetHostModelSelectionStore,
+ selectHostModel,
+} from '../hostModelSelectionStore'
+
+const AGENT = 'trader'
+const CHAT = 'chat-1'
+
+function deferred<T>() {
+ let resolve!: (value: T) => void
+ let reject!: (reason: Error) => void
+ const promise = new Promise<T>((res, rej) => {
+ resolve = res
+ reject = rej
+ })
+ return { promise, resolve, reject }
+}
+
+function baseResult(overrides: Partial<HostModelsResult> = {}): HostModelsResult {
+ return {
+ provider: 'zai',
+ hostDefault: 'glm-5.3',
+ sessionModel: null,
+ degraded: false,
+ models: [
+ { name: 'glm-5.3', imageInput: { state: 'unsupported', reason: 'model_unsupported' } },
+ { name: 'glm-5.3-flash', imageInput: { state: 'supported', reason: 'supported' } },
+ ],
+ ...overrides,
+ }
+}
+
+/**
+ * The returned spies are read back OFF the resolved transport, never off the
+ * defaults. Returning the defaults means a test that overrides a member asserts
+ * against a function nobody calls, and every such assertion — especially a
+ * negative one — passes vacuously.
+ */
+function makeTransport(overrides: Partial<HostModelSelectionTransport> = {}) {
+ const transport: HostModelSelectionTransport = {
+ getHostModels: vi.fn(async () => baseResult()),
+ setHostModel: vi.fn(
+ async (_agentRef: string, _chatId: string, model: string): Promise<SetHostModelResult> => ({
+ effective: 'next-task',
+ provider: 'zai',
+ model,
+ })
+ ),
+ ...overrides,
+ }
+ return {
+ transport,
+ getHostModels: transport.getHostModels as Mock<HostModelSelectionTransport['getHostModels']>,
+ setHostModel: transport.setHostModel as Mock<HostModelSelectionTransport['setHostModel']>,
+ }
+}
+
+afterEach(() => {
+ resetHostModelSelectionStore()
+ vi.restoreAllMocks()
+})
+
+describe('hostModelSelectionStore — effective selection + capability', () => {
+ it('resolves capability for the effective model, not for the provider', async () => {
+ const { transport } = makeTransport()
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.effectiveModel).toBe('glm-5.3')
+ expect(view.imageInput.state).toBe('unsupported')
+ expect(view.canAttachImages).toBe(false)
+ expect(view.imageBlockMessage).toMatch(/not supported/)
+ })
+
+ it('allows images once the effective model carries valid evidence', async () => {
+ const { transport } = makeTransport({
+ getHostModels: async () => baseResult({ sessionModel: 'glm-5.3-flash' }),
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.effectiveModel).toBe('glm-5.3-flash')
+ expect(view.canAttachImages).toBe(true)
+ expect(view.imageBlockMessage).toBeNull()
+ })
+
+ it('blocks images while an attachment decision is missing (legacy host)', async () => {
+ const { transport } = makeTransport({
+ getHostModels: async () =>
+ baseResult({
+ sessionModel: 'glm-5.3-flash',
+ models: [{ name: 'glm-5.3-flash' }],
+ }),
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.imageInput).toEqual({ state: 'unknown', reason: 'model_unknown' })
+ expect(view.visualSendBlocked).toBe(true)
+ expect(view.imageBlockMessage).toMatch(/not verified/)
+ })
+
+ it('downgrades expired evidence to unknown on read', async () => {
+ const { transport } = makeTransport({
+ getHostModels: async () =>
+ baseResult({
+ sessionModel: 'glm-5.3-flash',
+ models: [
+ {
+ name: 'glm-5.3-flash',
+ imageInput: {
+ state: 'supported',
+ reason: 'curated',
+ validUntil: '2026-09-15T00:00:00.000Z',
+ },
+ },
+ ],
+ }),
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const view = readHostModelSelection(AGENT, CHAT, Date.parse('2026-09-16T10:00:00.000Z'))
+ expect(view.imageInput).toEqual({
+ state: 'unknown',
+ reason: 'evidence_expired',
+ validUntil: '2026-09-15T00:00:00.000Z',
+ })
+ expect(view.visualSendBlocked).toBe(true)
+ })
+})
+
+describe('hostModelSelectionStore — optimistic intent', () => {
+ it('keeps an unpersisted intent when the host is unreachable (piggyback)', async () => {
+ const suspendedWrite = vi.fn(async () => {
+ throw new Error('host suspended')
+ })
+ const { transport } = makeTransport({
+ setHostModel: suspendedWrite,
+ })
+ vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+ const ok = await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+
+ expect(ok).toBe(true)
+ expect(suspendedWrite).toHaveBeenCalledTimes(1)
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.effectiveModel).toBe('glm-5.3-flash')
+ expect(view.pending).toBe(true)
+ expect(view.intentModel).toBe('glm-5.3-flash')
+ })
+
+ it('clears the intent only after the matching write is acknowledged', async () => {
+ const { transport } = makeTransport()
+ const ok = await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ expect(ok).toBe(true)
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.intentModel).toBeNull()
+ expect(view.pending).toBe(false)
+ })
+
+ it('holds a pre-chat pick without any POST (no stray chat)', async () => {
+ const { transport, setHostModel, getHostModels } = makeTransport()
+ const ok = await selectHostModel(transport, AGENT, null, 'glm-5.3-flash')
+
+ expect(ok).toBe(true)
+ expect(setHostModel).not.toHaveBeenCalled()
+ expect(getHostModels).not.toHaveBeenCalled()
+ expect(readHostModelSelection(AGENT, null).intentModel).toBe('glm-5.3-flash')
+ })
+})
+
+describe('hostModelSelectionStore — list fetch failure', () => {
+ // #654 M7 — `data === null` is the HOST's answer ("I predate the model
+ // endpoint"). A thrown fetch knows nothing, so it must not borrow that answer
+ // and must not be reported as a capability verdict about the model.
+ it('reports a fetch failure as a load error, not as unverified evidence', async () => {
+ const getHostModels = vi.fn(async () => {
+ throw new Error('ECONNREFUSED')
+ })
+ const { transport } = makeTransport({ getHostModels })
+
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ // Witness: the fetch really ran and really settled, so the assertions below
+ // describe a decision rather than an untouched initial state.
+ expect(getHostModels).toHaveBeenCalledTimes(1)
+ expect(view.loading).toBe(false)
+ expect(view.state).toBe('error')
+ expect(view.error).toMatch(/could not be loaded/)
+ expect(view.loadError).toMatch(/could not be loaded/)
+ expect(view.imageBlockMessage).toMatch(/could not be loaded/)
+ expect(view.imageBlockMessage).not.toMatch(/not verified/)
+ expect(view.canAttachImages).toBe(false)
+ })
+
+ it('says the first load is checking, not that the model lacks evidence', async () => {
+ const firstRead = deferred<HostModelsResult>()
+ const getHostModels = vi
+ .fn<HostModelSelectionTransport['getHostModels']>()
+ .mockReturnValueOnce(firstRead.promise)
+ const { transport } = makeTransport({ getHostModels })
+
+ const pending = loadHostModels(transport, AGENT, CHAT)
+ const during = readHostModelSelection(AGENT, CHAT)
+ expect(getHostModels).toHaveBeenCalledTimes(1)
+ expect(during.loading).toBe(true)
+ expect(during.visualSendBlocked).toBe(true)
+ expect(during.imageBlockMessage).toMatch(/^Checking the model’s image support/)
+ expect(during.imageBlockMessage).not.toMatch(/operator/)
+
+ firstRead.resolve(baseResult({ sessionModel: 'glm-5.3-flash' }))
+ await pending
+ const after = readHostModelSelection(AGENT, CHAT)
+ expect(after.canAttachImages).toBe(true)
+ expect(after.imageBlockMessage).toBeNull()
+ })
+
+ // Closing the OS file picker refocuses the window, and the focus listener
+ // forces a refetch right before the picked files arrive. A refetch over a
+ // settled read must not turn a supported model into "checking".
+ it('keeps a settled capability while a forced background refetch is in flight', async () => {
+ const refetch = deferred<HostModelsResult>()
+ const getHostModels = vi
+ .fn<HostModelSelectionTransport['getHostModels']>()
+ .mockResolvedValueOnce(baseResult({ sessionModel: 'glm-5.3-flash' }))
+ .mockReturnValueOnce(refetch.promise)
+ const { transport } = makeTransport({ getHostModels })
+ await loadHostModels(transport, AGENT, CHAT)
+ expect(readHostModelSelection(AGENT, CHAT).canAttachImages).toBe(true)
+
+ const pending = loadHostModels(transport, AGENT, CHAT, { force: true })
+ const during = readHostModelSelection(AGENT, CHAT)
+ // Witness: the refetch is really in flight while capability is read.
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+ expect(during.loading).toBe(true)
+ expect(during.imageInput.state).toBe('supported')
+ expect(during.canAttachImages).toBe(true)
+ expect(during.visualSendBlocked).toBe(false)
+ expect(during.imageBlockMessage).toBeNull()
+
+ refetch.resolve(baseResult({ sessionModel: 'glm-5.3-flash' }))
+ await pending
+ const after = readHostModelSelection(AGENT, CHAT)
+ expect(after.loading).toBe(false)
+ expect(after.canAttachImages).toBe(true)
+ })
+
+ it('applies the refetched selection when it lands during a background refetch', async () => {
+ const refetch = deferred<HostModelsResult>()
+ const getHostModels = vi
+ .fn<HostModelSelectionTransport['getHostModels']>()
+ .mockResolvedValueOnce(baseResult({ sessionModel: 'glm-5.3-flash' }))
+ .mockReturnValueOnce(refetch.promise)
+ const { transport } = makeTransport({ getHostModels })
+ await loadHostModels(transport, AGENT, CHAT)
+
+ const pending = loadHostModels(transport, AGENT, CHAT, { force: true })
+ expect(readHostModelSelection(AGENT, CHAT).canAttachImages).toBe(true)
+
+ // Another client moved this chat to a text-only model.
+ refetch.resolve(baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 8 }))
+ await pending
+ const after = readHostModelSelection(AGENT, CHAT)
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+ expect(after.effectiveModel).toBe('glm-5.3')
+ expect(after.imageInput.state).toBe('unsupported')
+ expect(after.visualSendBlocked).toBe(true)
+ })
+
+ it('keeps a previous good read usable when a later fetch fails', async () => {
+ const getHostModels = vi
+ .fn()
+ .mockResolvedValueOnce(
+ baseResult({ sessionModel: 'glm-5.3-flash', modelSelectionRevision: 2 })
+ )
+ .mockRejectedValueOnce(new Error('ECONNREFUSED'))
+ const { transport } = makeTransport({ getHostModels })
+
+ await loadHostModels(transport, AGENT, CHAT)
+ await loadHostModels(transport, AGENT, CHAT, { force: true })
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+ // The failure does not erase what we already know: the list stays usable and
+ // the state stays `ready`, only the inline error reports the failed refresh.
+ expect(view.state).toBe('ready')
+ expect(view.effectiveModel).toBe('glm-5.3-flash')
+ expect(view.canAttachImages).toBe(true)
+ expect(view.loadError).toBeNull()
+ expect(view.error).toMatch(/could not be loaded/)
+ })
+})
+
+describe('hostModelSelectionStore — serialized, coalesced writes', () => {
+ // #654 L7 — an A→B→A sequence leaves a newer intent for A that the accepted A
+ // write already satisfies. Comparing the intent against what we SENT (plus a
+ // sequence guard) left it pending forever; comparing it against what the
+ // SERVER confirmed clears it.
+ it('clears an A→B→A intent once the A write is acknowledged', async () => {
+ const write = deferred<SetHostModelResult>()
+ const { transport, setHostModel } = makeTransport({
+ setHostModel: vi.fn(() => write.promise),
+ })
+
+ const first = selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3')
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ expect(readHostModelSelection(AGENT, CHAT).intentModel).toBe('glm-5.3-flash')
+
+ write.resolve({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 3,
+ })
+ expect(await first).toBe(true)
+
+ // Witness: the queued A was NOT re-written, because it equals the model the
+ // server just confirmed — one write, and no lingering pending state.
+ expect(setHostModel).toHaveBeenCalledTimes(1)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ intentModel: null,
+ pending: false,
+ effectiveModel: 'glm-5.3-flash',
+ confirmedRevision: 3,
+ })
+ })
+
+ it('serializes A→B so the final server state is the last intent', async () => {
+ let resolveFirst: (() => void) | undefined
+ const firstGate = new Promise<void>(resolve => {
+ resolveFirst = resolve
+ })
+ const calls: string[] = []
+ const serializedWrite = vi.fn(
+ async (_agent: string, _chat: string, model: string): Promise<SetHostModelResult> => {
+ calls.push(model)
+ if (calls.length === 1) await firstGate
+ return { effective: 'next-task', provider: 'zai', model }
+ }
+ )
+ const { transport } = makeTransport({ setHostModel: serializedWrite })
+
+ const first = selectHostModel(transport, AGENT, CHAT, 'glm-5.3')
+ const second = selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+
+ // The second pick coalesces onto the in-flight writer instead of racing it.
+ expect(calls).toEqual(['glm-5.3'])
+ resolveFirst?.()
+ await Promise.all([first, second])
+
+ expect(calls).toEqual(['glm-5.3', 'glm-5.3-flash'])
+ expect(serializedWrite).toHaveBeenCalledTimes(2)
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.effectiveModel).toBe('glm-5.3-flash')
+ expect(view.intentModel).toBeNull()
+ })
+
+ it('does not let an older read overwrite a newer intent', async () => {
+ let resolveRead: ((value: HostModelsResult) => void) | undefined
+ const readGate = new Promise<HostModelsResult>(resolve => {
+ resolveRead = resolve
+ })
+ const { transport, setHostModel } = makeTransport({
+ getHostModels: () => readGate,
+ })
+
+ const load = loadHostModels(transport, AGENT, CHAT)
+ // The user picks while the read is still in flight.
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ resolveRead?.(baseResult({ sessionModel: 'glm-5.3' }))
+ await load
+
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.effectiveModel).toBe('glm-5.3-flash')
+ // A read that raced a newer intent must not lend its revision to a CAS write.
+ expect(setHostModel).toHaveBeenCalledWith(AGENT, CHAT, 'glm-5.3-flash', undefined)
+ })
+})
+
+describe('hostModelSelectionStore — CAS conflict', () => {
+ it('retries a newer queued choice on the revision the refetch adopted', async () => {
+ const firstWrite = deferred<SetHostModelResult>()
+ const secondWrite = deferred<SetHostModelResult>()
+ const refetch = deferred<HostModelsResult>()
+ const setHostModel = vi
+ .fn<HostModelSelectionTransport['setHostModel']>()
+ .mockImplementationOnce(() => firstWrite.promise)
+ .mockImplementationOnce(() => secondWrite.promise)
+ const { transport } = makeTransport({
+ getHostModels: vi
+ .fn()
+ .mockResolvedValueOnce(baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 4 }))
+ .mockImplementation(() => refetch.promise),
+ setHostModel,
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+ const older = selectHostModel(transport, AGENT, CHAT, 'glm-5.3')
+ // Arrives while the older write is in flight, so it is queued, not written.
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ firstWrite.reject(new Error('model_selection_conflict'))
+
+ await vi.waitFor(() => {
+ expect(readHostModelSelection(AGENT, CHAT).conflicted).toBe(true)
+ })
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ intentModel: 'glm-5.3-flash',
+ visualSendBlocked: true,
+ })
+ expect(setHostModel).toHaveBeenCalledTimes(1)
+
+ refetch.resolve(baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 9 }))
+
+ // #654 M4 — the queued pick is retried instead of being dropped, and it is
+ // armed with revision 9: the one the authoritative read just adopted, not
+ // the stale 4 the conflicting write used.
+ await vi.waitFor(() => {
+ expect(setHostModel).toHaveBeenCalledTimes(2)
+ })
+ expect(setHostModel).toHaveBeenLastCalledWith(AGENT, CHAT, 'glm-5.3-flash', 9)
+
+ secondWrite.resolve({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 10,
+ })
+ expect(await older).toBe(true)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ intentModel: null,
+ pending: false,
+ conflicted: false,
+ confirmedRevision: 10,
+ effectiveModel: 'glm-5.3-flash',
+ visualSendBlocked: false,
+ })
+ })
+
+ it('does not revive a selection after its owner scope resets', async () => {
+ const write = deferred<SetHostModelResult>()
+ const { transport } = makeTransport({ setHostModel: () => write.promise })
+ const selecting = selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ resetHostModelSelectionStore()
+ write.resolve({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 8,
+ })
+ expect(await selecting).toBe(false)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ intentModel: null,
+ confirmedRevision: null,
+ effectiveModel: '',
+ })
+ })
+
+ it('retains the newer revision when a superseded read completes', async () => {
+ const read = deferred<HostModelsResult>()
+ const { transport } = makeTransport({
+ getHostModels: vi
+ .fn()
+ .mockResolvedValueOnce(baseResult({ modelSelectionRevision: 4 }))
+ .mockImplementation(() => read.promise),
+ setHostModel: async () => ({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 5,
+ }),
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+ const loading = loadHostModels(transport, AGENT, CHAT, { force: true })
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ read.resolve(baseResult({ modelSelectionRevision: 4 }))
+ await loading
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ confirmedRevision: 5,
+ effectiveModel: 'glm-5.3-flash',
+ })
+ })
+ it('keeps the last confirmed state, drops the intent and refetches', async () => {
+ let resolveRefetch: ((value: HostModelsResult) => void) | undefined
+ const refetchGate = new Promise<HostModelsResult>(resolve => {
+ resolveRefetch = resolve
+ })
+ const getHostModels = vi
+ .fn()
+ .mockResolvedValueOnce(baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 4 }))
+ .mockImplementation(() => refetchGate)
+ const conflictingWrite = vi.fn(async () => {
+ throw new Error('Set host model conflicted (model_selection_conflict)')
+ })
+ const { transport } = makeTransport({
+ getHostModels,
+ setHostModel: conflictingWrite,
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+ expect(readHostModelSelection(AGENT, CHAT).confirmedRevision).toBe(4)
+
+ // #654 M4 — the write no longer settles at the conflict: it awaits the
+ // authoritative read, because that read carries the revision a retry must
+ // be armed with. So hold the promise and inspect the interim state.
+ const pendingSelect = selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ await vi.waitFor(() => {
+ expect(readHostModelSelection(AGENT, CHAT).conflicted).toBe(true)
+ })
+ expect(conflictingWrite).toHaveBeenCalledWith(AGENT, CHAT, 'glm-5.3-flash', 4)
+
+ // The rejected intent is never piggybacked and the effective model stays the
+ // last confirmed one; capability is withheld until the refetch lands.
+ const conflictedView = readHostModelSelection(AGENT, CHAT)
+ expect(conflictedView.effectiveModel).toBe('glm-5.3')
+ expect(conflictedView.intentModel).toBeNull()
+ expect(conflictedView.visualSendBlocked).toBe(true)
+ // Witness: the forced re-read is in flight, and it did not wipe the conflict
+ // message the user needs to see while it runs.
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+ expect(conflictedView.loading).toBe(true)
+ expect(conflictedView.error).toBe(
+ 'This chat’s model was changed elsewhere — re-checking the current selection.'
+ )
+ // Never trust the rejected snapshot's capability while the conflict stands.
+ expect(conflictedView.imageInput.state).toBe('unknown')
+
+ resolveRefetch?.(baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 9 }))
+ expect(await pendingSelect).toBe(false)
+ expect(readHostModelSelection(AGENT, CHAT).conflicted).toBe(false)
+ expect(readHostModelSelection(AGENT, CHAT).confirmedRevision).toBe(9)
+ // The re-check landed: the message now says the pick was not applied, and it
+ // stays until the user picks again.
+ expect(readHostModelSelection(AGENT, CHAT).error).toBe(
+ 'This chat’s model was changed elsewhere — your model choice was not applied.'
+ )
+ // No newer pick was queued, so the conflict is terminal: exactly one write.
+ expect(conflictingWrite).toHaveBeenCalledTimes(1)
+ })
+
+ describe('a pick made during the re-read that follows a conflict', () => {
+ // The desktop holds m-a at revision 4; another client already moved the
+ // session to m-x at revision 5. The pick of m-b conflicts, and the next pick
+ // lands while the forced re-read is in flight, superseding that read.
+ function conflictDuringReread() {
+ const refetch = deferred<HostModelsResult>()
+ const setHostModel = vi
+ .fn<HostModelSelectionTransport['setHostModel']>()
+ .mockRejectedValueOnce(new Error('Set host model conflicted (model_selection_conflict)'))
+ .mockImplementation(async (_agentRef, _chatId, model) => ({
+ effective: 'next-task',
+ provider: 'zai',
+ model,
+ modelSelectionRevision: 6,
+ }))
+ const getHostModels = vi
+ .fn<HostModelSelectionTransport['getHostModels']>()
+ .mockResolvedValueOnce(baseResult({ sessionModel: 'm-a', modelSelectionRevision: 4 }))
+ .mockImplementation(() => refetch.promise)
+ const { transport } = makeTransport({ getHostModels, setHostModel })
+ return { transport, refetch, setHostModel, getHostModels }
+ }
+
+ async function pickDuringReread(model: string) {
+ const scenario = conflictDuringReread()
+ const { transport, refetch, setHostModel, getHostModels } = scenario
+ await loadHostModels(transport, AGENT, CHAT)
+ const first = selectHostModel(transport, AGENT, CHAT, 'm-b')
+ await vi.waitFor(() => {
+ expect(readHostModelSelection(AGENT, CHAT).conflicted).toBe(true)
+ })
+ // Witness: the conflicting write ran on revision 4 and the re-read is in
+ // flight when the next pick lands.
+ expect(setHostModel).toHaveBeenNthCalledWith(1, AGENT, CHAT, 'm-b', 4)
+ expect(getHostModels).toHaveBeenCalledTimes(2)
+ expect(readHostModelSelection(AGENT, CHAT).loading).toBe(true)
+
+ expect(await selectHostModel(transport, AGENT, CHAT, model)).toBe(true)
+ refetch.resolve(baseResult({ sessionModel: 'm-x', modelSelectionRevision: 5 }))
+ return { first: await first, setHostModel }
+ }
+
+ it('sends a new model on the revision the superseded re-read reported', async () => {
+ const { first, setHostModel } = await pickDuringReread('m-c')
+
+ expect(setHostModel).toHaveBeenCalledTimes(2)
+ expect(setHostModel).toHaveBeenLastCalledWith(AGENT, CHAT, 'm-c', 5)
+ expect(first).toBe(true)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ effectiveModel: 'm-c',
+ intentModel: null,
+ pending: false,
+ conflicted: false,
+ confirmedRevision: 6,
+ error: null,
+ })
+ })
+
+ it('sends the pre-conflict model when the server holds another one', async () => {
+ const { first, setHostModel } = await pickDuringReread('m-a')
+
+ // m-a equals the model this client held before the conflict, but the
+ // server holds m-x, so the pick must still be written.
+ expect(setHostModel).toHaveBeenCalledTimes(2)
+ expect(setHostModel).toHaveBeenLastCalledWith(AGENT, CHAT, 'm-a', 5)
+ expect(first).toBe(true)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ effectiveModel: 'm-a',
+ intentModel: null,
+ conflicted: false,
+ confirmedRevision: 6,
+ })
+ })
+
+ it('settles without a write when the server already holds the pick', async () => {
+ const { first, setHostModel } = await pickDuringReread('m-x')
+
+ // Witness: the conflicting write happened; the pick of m-x needs no second one.
+ expect(setHostModel).toHaveBeenCalledTimes(1)
+ expect(first).toBe(true)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ effectiveModel: 'm-x',
+ intentModel: null,
+ pending: false,
+ conflicted: false,
+ confirmedRevision: 5,
+ error: null,
+ })
+ })
+ })
+})
+
+describe('hostModelSelectionStore — allowlist rejection', () => {
+ it('preserves a newer intent migrated by the send path during an older rejection', async () => {
+ const write = deferred<SetHostModelResult>()
+ const { transport } = makeTransport({ setHostModel: () => write.promise })
+ const first = selectHostModel(transport, AGENT, CHAT, 'removed-model')
+ // Pre-chat migration uses this entry point, independently of the POST queue.
+ setPendingModelIntent(AGENT, CHAT, 'glm-5.3-flash')
+ write.reject(new Error('model_not_allowed'))
+ expect(await first).toBe(false)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ effectiveModel: 'glm-5.3-flash',
+ intentModel: 'glm-5.3-flash',
+ pending: true,
+ })
+ })
+ it('applies the newer queued choice after the old choice is rejected', async () => {
+ const older = deferred<SetHostModelResult>()
+ const setHostModel = vi
+ .fn()
+ .mockImplementationOnce(() => older.promise)
+ .mockResolvedValueOnce({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 5,
+ })
+ const { transport } = makeTransport({
+ getHostModels: async () => baseResult({ modelSelectionRevision: 4 }),
+ setHostModel,
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+ const first = selectHostModel(transport, AGENT, CHAT, 'removed-model')
+ await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ older.reject(new Error('model_not_allowed'))
+ expect(await first).toBe(true)
+ expect(setHostModel).toHaveBeenLastCalledWith(AGENT, CHAT, 'glm-5.3-flash', 4)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ effectiveModel: 'glm-5.3-flash',
+ confirmedRevision: 5,
+ pending: false,
+ })
+ })
+ it('drops the optimistic intent and surfaces the targeted error', async () => {
+ const { transport } = makeTransport({
+ setHostModel: vi.fn(async () => {
+ throw new Error('Set host model rejected (model_not_allowed)')
+ }),
+ })
+ const ok = await selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+
+ expect(ok).toBe(false)
+ const view = readHostModelSelection(AGENT, CHAT)
+ expect(view.intentModel).toBeNull()
+ expect(view.error).toMatch(/no longer allowed/)
+ })
+})
+
+describe('hostModelSelectionStore — revision monotonicity', () => {
+ it('keeps the newer ack revision when an older write reply lands late', async () => {
+ const write = deferred<SetHostModelResult>()
+ const { transport, setHostModel } = makeTransport({
+ getHostModels: async () => baseResult({ sessionModel: 'glm-5.3', modelSelectionRevision: 4 }),
+ setHostModel: vi.fn(() => write.promise),
+ })
+ await loadHostModels(transport, AGENT, CHAT)
+ expect(readHostModelSelection(AGENT, CHAT).confirmedRevision).toBe(4)
+
+ const selecting = selectHostModel(transport, AGENT, CHAT, 'glm-5.3-flash')
+ await vi.waitFor(() => expect(setHostModel).toHaveBeenCalledTimes(1))
+ expect(setHostModel).toHaveBeenLastCalledWith(AGENT, CHAT, 'glm-5.3-flash', 4)
+
+ // A send ack lands while the write is in flight and raises the CAS base.
+ confirmHostModelSelectionFromSend(AGENT, CHAT, 'glm-5.3', 7)
+ expect(readHostModelSelection(AGENT, CHAT).confirmedRevision).toBe(7)
+
+ write.resolve({
+ effective: 'next-task',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 5,
+ })
+ // Witness: the write path ran to completion and processed the reply.
+ expect(await selecting).toBe(true)
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ confirmedRevision: 7,
+ selectionUnsettled: false,
+ })
+ })
+
+ type RevisionEvent =
+ | { kind: 'ack'; model: string; revision: number }
+ | { kind: 'read'; model: string; revision: number }
+ | { kind: 'conflict'; model: string; revision: number }
+ | { kind: 'write-start'; model: string }
+ | { kind: 'write-reply'; revision: number }
+
+ const modelArb = fc.constantFrom('glm-5.3', 'glm-5.3-flash')
+ const revisionArb = fc.integer({ min: 0, max: 12 })
+ const eventArb: fc.Arbitrary<RevisionEvent> = fc.oneof(
+ fc.record({ kind: fc.constant('ack' as const), model: modelArb, revision: revisionArb }),
+ fc.record({ kind: fc.constant('read' as const), model: modelArb, revision: revisionArb }),
+ fc.record({ kind: fc.constant('conflict' as const), model: modelArb, revision: revisionArb }),
+ fc.record({ kind: fc.constant('write-start' as const), model: modelArb }),
+ fc.record({ kind: fc.constant('write-reply' as const), revision: revisionArb })
+ )
+
+ /** Lets the store's awaited transport replies and follow-up reads settle. */
+ const settle = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+
+ it('never lowers confirmedRevision and is idempotent under replayed ack/read/conflict events', async () => {
+ const witness = { staleWriteReplies: 0, replays: 0, adoptions: 0 }
+
+ await fc.assert(
+ fc.asyncProperty(fc.array(eventArb, { minLength: 1, maxLength: 16 }), async events => {
+ resetHostModelSelectionStore()
+ let readRevision = 0
+ let readModel: string | null = null
+ const pendingWrites: Array<{
+ model: string
+ resolve: (value: SetHostModelResult) => void
+ }> = []
+ const { transport } = makeTransport({
+ getHostModels: async () =>
+ baseResult({ sessionModel: readModel, modelSelectionRevision: readRevision }),
+ setHostModel: (_agentRef, _chatId, model) => {
+ const write = deferred<SetHostModelResult>()
+ pendingWrites.push({ model, resolve: write.resolve })
+ return write.promise
+ },
+ })
+
+ const apply = async (event: RevisionEvent): Promise<void> => {
+ switch (event.kind) {
+ case 'ack':
+ confirmHostModelSelectionFromSend(AGENT, CHAT, event.model, event.revision)
+ return
+ case 'read':
+ readRevision = event.revision
+ readModel = event.model
+ await loadHostModels(transport, AGENT, CHAT, { force: true })
+ return
+ case 'conflict':
+ // The Host reports the winning revision and the re-read observes it.
+ readRevision = event.revision
+ readModel = event.model
+ noteHostModelSelectionConflict(transport, AGENT, CHAT, event.model, event.revision)
+ await settle()
+ return
+ case 'write-start':
+ void selectHostModel(transport, AGENT, CHAT, event.model)
+ await settle()
+ return
+ case 'write-reply': {
+ const head = pendingWrites.shift()
+ if (!head) return
+ const held = readHostModelSelection(AGENT, CHAT).confirmedRevision
+ if (held !== null && event.revision < held) witness.staleWriteReplies += 1
+ head.resolve({
+ effective: 'next-task',
+ provider: 'zai',
+ model: head.model,
+ modelSelectionRevision: event.revision,
+ })
+ await settle()
+ return
+ }
+ }
+ }
+
+ let previous: number | null = null
+ const expectNotLowered = () => {
+ const current = readHostModelSelection(AGENT, CHAT).confirmedRevision
+ if (previous !== null) {
+ expect(current).not.toBeNull()
+ expect(current as number).toBeGreaterThanOrEqual(previous)
+ }
+ if (current !== previous) witness.adoptions += 1
+ previous = current
+ }
+
+ for (const event of events) {
+ await apply(event)
+ expectNotLowered()
+ if (event.kind === 'ack' || event.kind === 'read' || event.kind === 'conflict') {
+ const once = readHostModelSelection(AGENT, CHAT)
+ await apply(event)
+ witness.replays += 1
+ expect(readHostModelSelection(AGENT, CHAT)).toEqual(once)
+ expectNotLowered()
+ }
+ }
+ // Drain writes still in flight (including queued picks they pick up).
+ while (pendingWrites.length > 0) {
+ await apply({ kind: 'write-reply', revision: 0 })
+ expectNotLowered()
+ }
+ }),
+ { numRuns: 300 }
+ )
+
+ // Witnesses: the adversarial interleaving (a write reply older than the held
+ // revision) was generated, replays ran, and revisions were actually adopted.
+ expect(witness.staleWriteReplies).toBeGreaterThan(0)
+ expect(witness.replays).toBeGreaterThan(0)
+ expect(witness.adoptions).toBeGreaterThan(0)
+ })
+})
+
+describe('hostModelSelectionStore — subscriptions', () => {
+ it('publishes a stable snapshot that changes only when the entry changes', async () => {
+ const { transport } = makeTransport()
+ const before = getHostModelSelectionSnapshot(AGENT, CHAT)
+ expect(before).toBe(getHostModelSelectionSnapshot(AGENT, CHAT))
+
+ await loadHostModels(transport, AGENT, CHAT)
+ expect(getHostModelSelectionSnapshot(AGENT, CHAT)).not.toBe(before)
+ expect(getHostModelSelectionSnapshot(AGENT, CHAT).effectiveModel).toBe('glm-5.3')
+ })
+})
+
+describe('hostModelSelectionStore — reset', () => {
+ it('one reset clears the selection entries and the pending intents', async () => {
+ const { transport } = makeTransport()
+ await loadHostModels(transport, AGENT, CHAT)
+ setPendingModelIntent(AGENT, CHAT, 'glm-5.3-flash')
+ setPreChatModelIntent(AGENT, 'glm-5.3-flash')
+ // Witnesses: all three pieces of state exist before the reset.
+ expect(readHostModelSelection(AGENT, CHAT).effectiveModel).toBe('glm-5.3-flash')
+ expect(getPendingModelIntent(AGENT, CHAT)).toBe('glm-5.3-flash')
+ expect(getPreChatModelIntent(AGENT)).toBe('glm-5.3-flash')
+
+ resetHostModelSelectionStore()
+
+ expect(getPendingModelIntent(AGENT, CHAT)).toBeUndefined()
+ expect(getPreChatModelIntent(AGENT)).toBeUndefined()
+ expect(readHostModelSelection(AGENT, CHAT)).toMatchObject({
+ intentModel: null,
+ effectiveModel: '',
+ })
+ })
+})
diff --git a/desktop-app/ui/src/lib/__tests__/retainedSendStore.test.ts b/desktop-app/ui/src/lib/__tests__/retainedSendStore.test.ts
new file mode 100644
index 000000000..a8bfc86e4
--- /dev/null
+++ b/desktop-app/ui/src/lib/__tests__/retainedSendStore.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from 'vitest'
+import { type RetainedSendSnapshot, createRetainedSendStore } from '../retainedSendStore'
+
+function snapshot(
+ userMessageId: string,
+ timestamp: number,
+ overrides: Partial<RetainedSendSnapshot> = {}
+): RetainedSendSnapshot {
+ return {
+ agentRef: 'agent-x',
+ chatId: 'chat-1',
+ userMessageId,
+ content: userMessageId,
+ attachments: [],
+ references: [],
+ reason: 'post_failed',
+ timestamp,
+ draftRevision: 0,
+ failure: { message: `${userMessageId} failed`, kind: 'network' },
+ ...overrides,
+ }
+}
+
+function held(store: ReturnType<typeof createRetainedSendStore>, ids: string[]): string[] {
+ return ids.filter(id => {
+ const [chatId, userMessageId] = id.split('/') as [string, string]
+ return store.getRetainedSendSnapshot('agent-x', chatId, userMessageId) !== undefined
+ })
+}
+
+describe('retainedSendStore — superseded failures (#654 M2)', () => {
+ function seed() {
+ const changed = vi.fn()
+ const store = createRetainedSendStore(changed)
+ store.retainSendSnapshot(snapshot('old-failure', 100))
+ // Still awaiting its terminal: it can still fail and be the only copy.
+ store.retainSendSnapshot(
+ snapshot('awaiting', 150, { reason: 'awaiting_terminal', failure: undefined })
+ )
+ store.retainSendSnapshot(
+ snapshot('succeeded', 200, { reason: 'awaiting_terminal', failure: undefined })
+ )
+ store.retainSendSnapshot(snapshot('newer-failure', 300))
+ store.retainSendSnapshot(snapshot('other-chat', 100, { chatId: 'chat-2' }))
+ changed.mockClear()
+ return { store, changed }
+ }
+ const ALL = [
+ 'chat-1/old-failure',
+ 'chat-1/awaiting',
+ 'chat-1/succeeded',
+ 'chat-1/newer-failure',
+ 'chat-2/other-chat',
+ ]
+
+ it('a successful send releases itself and only the older failures of its chat', () => {
+ const { store, changed } = seed()
+
+ store.releaseSucceededRetainedSend('agent-x', 'chat-1', 'succeeded')
+
+ expect(changed).toHaveBeenCalled()
+ expect(held(store, ALL)).toEqual([
+ 'chat-1/awaiting',
+ 'chat-1/newer-failure',
+ 'chat-2/other-chat',
+ ])
+ })
+
+ it('a successful task releases itself and only the older failures of its chat', () => {
+ const { store, changed } = seed()
+ store.attachTaskIdToRetainedSend('agent-x', 'chat-1', 'succeeded', 'task-ok')
+
+ store.releaseSucceededRetainedSendsForTask('task-ok')
+
+ expect(changed).toHaveBeenCalled()
+ expect(held(store, ALL)).toEqual([
+ 'chat-1/awaiting',
+ 'chat-1/newer-failure',
+ 'chat-2/other-chat',
+ ])
+ })
+
+ it('releases failures up to a timestamp and keeps sends awaiting their terminal', () => {
+ const { store } = seed()
+
+ store.releaseRetainedFailuresForChat('agent-x', 'chat-1', 300)
+
+ expect(held(store, ALL)).toEqual(['chat-1/awaiting', 'chat-1/succeeded', 'chat-2/other-chat'])
+ expect(store.getLatestRetainedSendSnapshotForChat('agent-x', 'chat-1')).toBeUndefined()
+ })
+})
diff --git a/desktop-app/ui/src/lib/composerDraftStore.ts b/desktop-app/ui/src/lib/composerDraftStore.ts
index 5137048ce..8fce8e031 100644
--- a/desktop-app/ui/src/lib/composerDraftStore.ts
+++ b/desktop-app/ui/src/lib/composerDraftStore.ts
@@ -18,6 +18,8 @@ type Listener = () => void
const NO_CHAT_DRAFT_KEY = '__no_chat__'
const drafts = new Map<string, string>()
+let revision = 0
+const revisions = new Map<string, number>()
const listenersByKey = new Map<string, Set<Listener>>()
function keyFor(chatId: string | null): string {
@@ -30,6 +32,10 @@ function emit(key: string): void {
for (const listener of listeners) listener()
}
+export function getComposerDraftRevision(chatId: string | null): number {
+ return revisions.get(keyFor(chatId)) ?? 0
+}
+
export function getComposerDraft(chatId: string | null): string {
return drafts.get(keyFor(chatId)) ?? ''
}
@@ -37,6 +43,7 @@ export function getComposerDraft(chatId: string | null): string {
export function setComposerDraft(chatId: string | null, value: string): void {
const key = keyFor(chatId)
if ((drafts.get(key) ?? '') === value) return
+ revisions.set(key, ++revision)
if (value) drafts.set(key, value)
else drafts.delete(key)
emit(key)
@@ -69,5 +76,6 @@ export function subscribeComposerDraft(chatId: string | null, listener: Listener
/** Test helper: wipe all drafts and listeners. */
export function resetComposerDraftStore(): void {
drafts.clear()
+ revisions.clear()
listenersByKey.clear()
}
diff --git a/desktop-app/ui/src/lib/hostModelIntentStore.ts b/desktop-app/ui/src/lib/hostModelIntentStore.ts
new file mode 100644
index 000000000..b270a9d48
--- /dev/null
+++ b/desktop-app/ui/src/lib/hostModelIntentStore.ts
@@ -0,0 +1,64 @@
+/**
+ * Unpersisted model-selection intents (R2 "Option A").
+ *
+ * When a user changes the model while the agent host is SUSPENDED (`replicas=0`)
+ * the `POST /model` write cannot reach the runtime, so the choice cannot be
+ * persisted server-side. Rather than silently drop it, the selection is held
+ * here — keyed by `(agentRef, chatId)` like sessions — and PIGGYBACKED onto the
+ * next send, which wakes the host and applies the model to that task.
+ *
+ * A PRE-CHAT pick (no chatId yet) is keyed by agent alone; the send path
+ * migrates it into the chat-keyed slot once the first send creates the chat.
+ *
+ * This is a module-level singleton (not React state): it is written by the
+ * shared `hostModelSelectionStore` and read by the composer/send path, two
+ * consumers that never share a render tree. Keeping it out of React state avoids
+ * a context/provider just to shuttle one imperative value between them.
+ */
+
+const pendingModelByChat: Record<string, string> = {}
+const preChatModelByAgent: Record<string, string> = {}
+
+/** Composite key mirroring the session `chatKey` convention (`agentRef::chatId`). */
+export function pendingModelKey(agentRef: string, chatId: string): string {
+ return `${agentRef}::${chatId}`
+}
+
+export function setPendingModelIntent(agentRef: string, chatId: string, model: string): void {
+ if (!agentRef || !chatId || !model) return
+ pendingModelByChat[pendingModelKey(agentRef, chatId)] = model
+}
+
+export function getPendingModelIntent(agentRef: string, chatId: string): string | undefined {
+ if (!agentRef || !chatId) return undefined
+ return pendingModelByChat[pendingModelKey(agentRef, chatId)]
+}
+
+export function clearPendingModelIntent(agentRef: string, chatId: string): void {
+ if (!agentRef || !chatId) return
+ delete pendingModelByChat[pendingModelKey(agentRef, chatId)]
+}
+
+export function setPreChatModelIntent(agentRef: string, model: string): void {
+ if (!agentRef || !model) return
+ preChatModelByAgent[agentRef] = model
+}
+
+export function getPreChatModelIntent(agentRef: string): string | undefined {
+ return agentRef ? preChatModelByAgent[agentRef] : undefined
+}
+
+export function clearPreChatModelIntent(agentRef: string): void {
+ if (!agentRef) return
+ delete preChatModelByAgent[agentRef]
+}
+
+/**
+ * Drops every intent. Called on logout/user/team scope changes: an unpersisted
+ * model choice must never carry across identity boundaries where the same
+ * agent/chat identifiers may reappear.
+ */
+export function resetHostModelIntentStore(): void {
+ for (const key of Object.keys(pendingModelByChat)) delete pendingModelByChat[key]
+ for (const key of Object.keys(preChatModelByAgent)) delete preChatModelByAgent[key]
+}
diff --git a/desktop-app/ui/src/lib/hostModelSelectionStore.ts b/desktop-app/ui/src/lib/hostModelSelectionStore.ts
new file mode 100644
index 000000000..dba8239bd
--- /dev/null
+++ b/desktop-app/ui/src/lib/hostModelSelectionStore.ts
@@ -0,0 +1,731 @@
+/**
+ * Single source of truth for the per-session model selection (R2 selector).
+ *
+ * The selector chip, the composer image guard and the send path all read this
+ * store, so an optimistic pick made in one place is immediately visible — and
+ * enforced — in the others. It is module-scoped (not React state or a context)
+ * because up to two `ComposerPanel`s can be mounted at once (main panel +
+ * chat drawer) and the send path lives in the controller, outside both trees.
+ *
+ * Invariants (issue #654):
+ * - One monotone generation per `(agentRef, chatId)`. A response from an older
+ * generation never overwrites a newer user intent.
+ * - Selection writes are SERIALIZED per key and coalesced toward the latest
+ * intent: a second pick while a write is in flight does not race it.
+ * - The local intent (unpersisted pick) wins over an older server read until
+ * the matching write is acknowledged; it is cleared only by compare-and-clear.
+ * - A CAS conflict (`model_selection_conflict`) is terminal: the store keeps the
+ * last confirmed state, drops the rejected intent so it is never silently
+ * piggybacked, and blocks image capability until a refetch lands.
+ * - Image capability is always resolved for the EFFECTIVE model from the host
+ * projection. A first load or a conflicted state reads as `unknown`, which
+ * blocks images and never text; a refetch over a settled read keeps it.
+ *
+ * Module singletons on purpose: this store is read by `ModelSelector`,
+ * `useHostModels` and the send path in `useAgentChatController`, which never
+ * share a render tree; the pending intents it layers over the server read live
+ * in `hostModelIntentStore` (written here and through `useChatStore`). Both are
+ * cleared by the single `resetHostModelSelectionStore()`, which `useChatStore`
+ * calls when the remote cache scope changes (logout, user or team switch).
+ * `retainedSendStore` is a per-controller factory instead, because retained
+ * bytes must die with the controller identity.
+ */
+import {
+ type ImageInputDecision,
+ canSendImagesWith,
+ imageInputBlockMessage,
+ resolveModelImageInput,
+} from '../../../src/imageInputDecision'
+import type { HostModelsResult, SetHostModelResult } from '../../../src/types'
+import {
+ clearPendingModelIntent,
+ clearPreChatModelIntent,
+ getPendingModelIntent,
+ getPreChatModelIntent,
+ resetHostModelIntentStore,
+ setPendingModelIntent,
+ setPreChatModelIntent,
+} from './hostModelIntentStore'
+
+/** Token embedded in a rejection message when the model is outside the allowlist. */
+const MODEL_NOT_ALLOWED_TOKEN = 'model_not_allowed'
+/** Token embedded in a rejection message when the CAS precondition fails. */
+const MODEL_SELECTION_CONFLICT_TOKEN = 'model_selection_conflict'
+/** Inline error while the list fetch failed; a new load attempt replaces it. */
+const LOAD_FAILED_ERROR = 'The model list could not be loaded. Retry.'
+/** Inline error from a CAS conflict until the authoritative re-read lands. */
+const CONFLICT_RECHECKING_ERROR =
+ 'This chat’s model was changed elsewhere — re-checking the current selection.'
+/** Inline error once that re-read landed: the rejected pick stays unapplied. */
+const CONFLICT_SETTLED_ERROR =
+ 'This chat’s model was changed elsewhere — your model choice was not applied.'
+/** Broker-backed hosts have no static default; the operator must name a model. */
+const CODEX_SUBSCRIPTION_PROVIDER = 'codex-subscription'
+const GROK_SUBSCRIPTION_PROVIDER = 'grok-subscription'
+
+/**
+ * `unavailable` means the host answered and has no model endpoint (it predates
+ * it); `error` means the fetch itself failed and we know nothing. Collapsing the
+ * two would report a transport failure as evidence about the host.
+ */
+export type HostModelSelectionState = 'unloaded' | 'loading' | 'ready' | 'unavailable' | 'error'
+
+export interface HostModelSelectionView {
+ scopeGeneration: number
+ data: HostModelsResult | null | undefined
+ loading: boolean
+ saving: boolean
+ error: string | null
+ state: HostModelSelectionState
+ /** Model the NEXT send will use: local intent > server selection > host default. */
+ effectiveModel: string
+ /** Unpersisted local intent (pre-chat pick or pending piggyback), if any. */
+ intentModel: string | null
+ /** True when `effectiveModel` comes from an unconfirmed local intent. */
+ pending: boolean
+ /** True when a write is in flight or an intent awaits acknowledgement. */
+ selectionUnsettled: boolean
+ /** True after a CAS conflict, until a refetch lands. */
+ conflicted: boolean
+ /** Revision the last read/write was based on; null → never send `expectedRevision`. */
+ confirmedRevision: number | null
+ /** Image capability of `effectiveModel` (unknown during the first load or a conflict). */
+ imageInput: ImageInputDecision
+ canAttachImages: boolean
+ /** User copy explaining why images are blocked; null when allowed. */
+ imageBlockMessage: string | null
+ /** Set only while the model list could not be fetched AND none was ever read,
+ * so the UI can offer a retry instead of reporting a capability verdict. */
+ loadError: string | null
+ /** Images must not be sent yet, even if the model is capable (unsettled/loading). */
+ visualSendBlocked: boolean
+}
+
+export interface HostModelSelectionTransport {
+ getHostModels: (agentRef: string, chatId: string) => Promise<HostModelsResult | null>
+ setHostModel: (
+ agentRef: string,
+ chatId: string,
+ model: string,
+ expectedRevision?: number
+ ) => Promise<SetHostModelResult>
+}
+
+interface Entry {
+ scopeGeneration: number
+ agentRef: string
+ chatId: string | null
+ data: HostModelsResult | null | undefined
+ loading: boolean
+ saving: boolean
+ error: string | null
+ conflicted: boolean
+ /** True when the last list fetch threw. Distinct from `data === null`, which
+ * is the host's own answer "I have no model endpoint". */
+ loadFailed: boolean
+ confirmedRevision: number | null
+ /** Newest selection known to be on the server (accepted write or fresh read). */
+ lastConfirmedModel: string | null
+ /** True when the last read raced a newer write/intent, so its projection is old. */
+ staleRead: boolean
+ /** Monotone generation: bumped by every user intent and every explicit load. */
+ seq: number
+ fetchInFlight: boolean
+ /**
+ * Set while `loadHostModels` awaits, so a superseded read can still publish the
+ * model LIST (host-level) while withholding the stale revision.
+ */
+ lastFetchSeq: number
+ /** Latest model requested while a write was in flight (coalescing). */
+ queuedModel: string | null
+ listeners: Set<() => void>
+ view: HostModelSelectionView | null
+}
+
+const entries = new Map<string, Entry>()
+let scopeGeneration = 0
+
+function keyFor(agentRef: string, chatId: string | null): string {
+ return `${agentRef}::${chatId ?? ''}`
+}
+
+export function isBrokerBackedProvider(provider: string | null | undefined): boolean {
+ return provider === CODEX_SUBSCRIPTION_PROVIDER || provider === GROK_SUBSCRIPTION_PROVIDER
+}
+
+function getEntry(agentRef: string, chatId: string | null): Entry {
+ const key = keyFor(agentRef, chatId)
+ let entry = entries.get(key)
+ if (!entry) {
+ entry = {
+ scopeGeneration,
+ agentRef,
+ chatId,
+ data: undefined,
+ loading: false,
+ saving: false,
+ error: null,
+ conflicted: false,
+ loadFailed: false,
+ confirmedRevision: null,
+ lastConfirmedModel: null,
+ staleRead: false,
+ seq: 0,
+ fetchInFlight: false,
+ lastFetchSeq: 0,
+ queuedModel: null,
+ listeners: new Set(),
+ view: null,
+ }
+ entries.set(key, entry)
+ }
+ return entry
+}
+
+function intentFor(entry: Entry): string | null {
+ if (!entry.agentRef) return null
+ if (!entry.chatId) return getPreChatModelIntent(entry.agentRef) ?? null
+ return getPendingModelIntent(entry.agentRef, entry.chatId) ?? null
+}
+
+function effectiveModelFor(entry: Entry): { model: string; pending: boolean } {
+ const intent = intentFor(entry)
+ if (intent) return { model: intent, pending: true }
+ const data = entry.data
+ if (data) {
+ // A read that lost the race against a newer write/intent must not resurrect
+ // the model it observed before that write.
+ if (!entry.staleRead && data.sessionModel) return { model: data.sessionModel, pending: false }
+ if (entry.lastConfirmedModel) return { model: entry.lastConfirmedModel, pending: false }
+ if (!isBrokerBackedProvider(data.provider)) {
+ return { model: data.hostDefault ?? '', pending: false }
+ }
+ return { model: '', pending: false }
+ }
+ // No projection (yet): an accepted write is still the newest known selection.
+ if (entry.lastConfirmedModel) return { model: entry.lastConfirmedModel, pending: false }
+ return { model: '', pending: false }
+}
+
+function buildView(entry: Entry, nowMs: number): HostModelSelectionView {
+ const { model: effectiveModel, pending } = effectiveModelFor(entry)
+ const data = entry.data
+ const state: HostModelSelectionState =
+ data === undefined && entry.loading
+ ? 'loading'
+ : data === undefined && entry.loadFailed
+ ? 'error'
+ : data === undefined
+ ? 'unloaded'
+ : data === null
+ ? 'unavailable'
+ : 'ready'
+ const loadError = state === 'error' ? entry.error : null
+
+ // Image capability is only trusted from a settled read: before the first read
+ // lands or while a CAS conflict is unresolved, images read as unknown (text
+ // stays allowed). A background refetch (window focus, menu open, post-send)
+ // over an existing read does not unsettle it: the model list is host-level,
+ // the refetch result replaces the view when it lands, and the host re-checks
+ // the selected model's capability when it admits the message. Treating
+ // every refetch as unknown blocked images whenever the OS file picker closed
+ // and refocused the window.
+ const firstLoad = entry.loading && data === undefined
+ const unsettledEvidence = firstLoad || entry.conflicted
+ const imageInput: ImageInputDecision = unsettledEvidence
+ ? { state: 'unknown', reason: 'model_unknown' }
+ : resolveModelImageInput(data?.models, effectiveModel, nowMs)
+
+ const canAttachImages = !entry.saving && !unsettledEvidence && canSendImagesWith(imageInput)
+ const visualSendBlocked = !canAttachImages
+ const imageBlockMessage = canAttachImages
+ ? null
+ : // A failed fetch is not a verdict about the model: say the list could not
+ // be loaded rather than claiming the model has no image evidence.
+ state === 'error'
+ ? 'The model list could not be loaded, so image capability cannot be checked. Retry the model list.'
+ : entry.saving
+ ? 'Applying the model change — wait for it to settle before sending images.'
+ : // The first fetch in flight is not a verdict about the model's
+ // evidence either.
+ firstLoad
+ ? 'Checking the model’s image support — images can be sent once the model list refreshes.'
+ : entry.conflicted
+ ? 'This chat’s model changed elsewhere — re-checking the current selection before images can be sent.'
+ : imageInputBlockMessage(effectiveModel, imageInput)
+
+ return {
+ scopeGeneration: entry.scopeGeneration,
+ data,
+ loading: entry.loading,
+ saving: entry.saving,
+ error: entry.error,
+ state,
+ effectiveModel,
+ intentModel: intentFor(entry),
+ pending,
+ selectionUnsettled: entry.saving || pending || entry.conflicted,
+ conflicted: entry.conflicted,
+ confirmedRevision: entry.confirmedRevision,
+ imageInput,
+ canAttachImages,
+ imageBlockMessage,
+ loadError,
+ visualSendBlocked,
+ }
+}
+
+function notify(entry: Entry): void {
+ entry.view = null
+ for (const listener of entry.listeners) listener()
+}
+
+/**
+ * Cached immutable view for React subscriptions: stable between store changes,
+ * which is what `useSyncExternalStore` requires.
+ */
+export function getHostModelSelectionSnapshot(
+ agentRef: string,
+ chatId: string | null
+): HostModelSelectionView {
+ const entry = getEntry(agentRef, chatId)
+ if (!entry.view) entry.view = buildView(entry, Date.now())
+ return entry.view
+}
+
+/**
+ * Fresh evaluation for imperative guards (send path). `validUntil` is
+ * re-checked here on every call, so evidence that expires while the app is open
+ * is enforced at the next attempt without needing a store write.
+ */
+export function readHostModelSelection(
+ agentRef: string,
+ chatId: string | null,
+ nowMs: number = Date.now()
+): HostModelSelectionView {
+ return buildView(getEntry(agentRef, chatId), nowMs)
+}
+
+export function subscribeHostModelSelection(
+ agentRef: string,
+ chatId: string | null,
+ listener: () => void
+): () => void {
+ const entry = getEntry(agentRef, chatId)
+ entry.listeners.add(listener)
+ return () => {
+ entry.listeners.delete(listener)
+ }
+}
+
+/**
+ * Re-reads a key after an external intent change (e.g. the send path migrated a
+ * pre-chat pick into the chat's pending slot) so subscribers see it at once.
+ */
+export function markHostModelSelectionChanged(agentRef: string, chatId: string | null): void {
+ const entry = entries.get(keyFor(agentRef, chatId))
+ if (entry) notify(entry)
+}
+
+/** Dismisses the last inline error (e.g. a stale rejection notice). */
+export function clearHostModelSelectionError(agentRef: string, chatId: string | null): void {
+ const entry = entries.get(keyFor(agentRef, chatId))
+ if (!entry || entry.error === null) return
+ entry.error = null
+ notify(entry)
+}
+
+/** Drops the pending intent for `model` when nothing is in flight to satisfy it. */
+function clearIntentIfStill(entry: Entry, model: string): boolean {
+ if (entry.saving || intentFor(entry) !== model) return false
+ if (entry.chatId) clearPendingModelIntent(entry.agentRef, entry.chatId)
+ else clearPreChatModelIntent(entry.agentRef)
+ return true
+}
+
+/**
+ * Adopts a Host-reported revision as the CAS base only when it is a valid
+ * revision at or past the one already held. Host revisions are monotone, so an
+ * older one is a reply that raced a newer ack or read, and adopting it would arm
+ * the next conditional write with a revision the Host has moved past.
+ */
+function adoptRevisionIfNotOlder(entry: Entry, revision: number | undefined): void {
+ if (
+ typeof revision === 'number' &&
+ Number.isSafeInteger(revision) &&
+ revision >= 0 &&
+ (entry.confirmedRevision === null || revision >= entry.confirmedRevision)
+ ) {
+ entry.confirmedRevision = revision
+ }
+}
+
+/**
+ * #654 H1 — a message ack confirmed the model it carried, so adopt the revision
+ * that write produced as the CAS base. Without this the client keeps the
+ * revision it read before sending, and its next conditional write loses a race
+ * it has already won.
+ */
+export function confirmHostModelSelectionFromSend(
+ agentRef: string,
+ chatId: string | null,
+ model: string,
+ revision: number
+): void {
+ if (!agentRef || !model) return
+ if (!Number.isSafeInteger(revision) || revision < 0) return
+ // The key is materialized, not looked up: message 1 of a chat CREATES that
+ // chat, so its key has no entry yet when the ack lands. Dropping the revision
+ // there would rearm the next send with the pre-send read — the exact loss this
+ // function exists to prevent.
+ const entry = getEntry(agentRef, chatId)
+ // An ack older than what we already hold says nothing new; the read path's own
+ // ordering guard covers the rest.
+ if (entry.confirmedRevision !== null && revision < entry.confirmedRevision) return
+ entry.confirmedRevision = revision
+ entry.lastConfirmedModel = model
+ entry.conflicted = false
+ // The held projection predates this write, so it must not resurrect the model
+ // it observed; the next settled read takes over.
+ entry.staleRead = true
+ clearIntentIfStill(entry, model)
+ notify(entry)
+}
+
+/**
+ * #654 L8 — the send succeeded but carried no revision after a piggyback, which
+ * is the Host's way of saying it ignored the model. Drop the intent so the UI
+ * stops resending a pick the Host will keep refusing.
+ */
+export function dropIgnoredHostModelIntent(
+ agentRef: string,
+ chatId: string | null,
+ model: string
+): void {
+ if (!agentRef || !model) return
+ // The intent itself lives in the chat store, outside this entry, so a missing
+ // entry would leave it to be resent forever; materialize the key to clear it.
+ const entry = getEntry(agentRef, chatId)
+ if (clearIntentIfStill(entry, model)) notify(entry)
+}
+
+/**
+ * #654 M3 — the send was refused with a CAS conflict. Adopt the winning revision
+ * the Host reported (so the retry is armed correctly without a separate read)
+ * and re-read the authoritative selection.
+ */
+export function noteHostModelSelectionConflict(
+ transport: HostModelSelectionTransport,
+ agentRef: string,
+ chatId: string | null,
+ model: string,
+ revision: number | undefined
+): void {
+ if (!agentRef) return
+ // Materialized for the same reason as the ack path: the conflict can be the
+ // answer to message 1 of a chat this send just created.
+ const entry = getEntry(agentRef, chatId)
+ adoptRevisionIfNotOlder(entry, revision)
+ entry.conflicted = true
+ entry.error = CONFLICT_RECHECKING_ERROR
+ if (model) clearIntentIfStill(entry, model)
+ notify(entry)
+ void loadHostModels(transport, agentRef, chatId, { force: true })
+}
+
+export async function loadHostModels(
+ transport: HostModelSelectionTransport,
+ agentRef: string,
+ chatId: string | null,
+ options: { force?: boolean } = {}
+): Promise<void> {
+ await readHostModels(transport, agentRef, chatId, options)
+}
+
+/**
+ * Loads the model list and selection for a key. Resolves the session model the
+ * read reported when that read is at least as new as the held CAS base (`null`
+ * means the session has no explicit selection), and `undefined` when no such
+ * evidence came back (skipped, failed, host without a model endpoint, or a read
+ * older than the held revision). The conflict retry compares against it.
+ */
+async function readHostModels(
+ transport: HostModelSelectionTransport,
+ agentRef: string,
+ chatId: string | null,
+ options: { force?: boolean }
+): Promise<string | null | undefined> {
+ if (!agentRef) return undefined
+ const entry = getEntry(agentRef, chatId)
+ if (entry.fetchInFlight && !options.force) return undefined
+ if (entry.data !== undefined && !options.force) return undefined
+
+ const ownerScope = entry.scopeGeneration
+ const fetchSeq = ++entry.seq
+ entry.lastFetchSeq = fetchSeq
+ entry.fetchInFlight = true
+ entry.loading = true
+ entry.loadFailed = false
+ // A new attempt replaces the previous load failure. Any other error (a CAS
+ // conflict, an allowlist rejection) stays visible: this read is not an answer
+ // to it, and a forced reload is exactly how a conflict is re-checked.
+ if (entry.error === LOAD_FAILED_ERROR) entry.error = null
+ notify(entry)
+
+ try {
+ const result = await transport.getHostModels(agentRef, chatId ?? '')
+ if (entry.scopeGeneration !== ownerScope) return undefined
+ const revision =
+ result &&
+ Number.isSafeInteger(result.modelSelectionRevision) &&
+ result.modelSelectionRevision! >= 0
+ ? result.modelSelectionRevision!
+ : null
+ const olderRevision =
+ revision !== null && entry.confirmedRevision !== null && revision < entry.confirmedRevision
+ // Revisions are monotone on the Host, so a read at or past the held CAS base
+ // is current evidence of the revision even when a newer intent or load
+ // superseded it. Withholding it armed the next conditional write with a
+ // revision the Host had already moved past: a pick made during the reload
+ // that follows a conflict then conflicted again and was dropped.
+ if (revision !== null && !olderRevision) entry.confirmedRevision = revision
+ const readModel = result && !olderRevision ? (result.sessionModel ?? null) : undefined
+ if (entry.lastFetchSeq !== fetchSeq) return readModel
+ const superseded = entry.seq !== fetchSeq || olderRevision
+ entry.data = result
+ entry.staleRead = superseded
+ if (!superseded) {
+ entry.lastConfirmedModel = result?.sessionModel ?? null
+ entry.conflicted = false
+ // The re-check this message announced has landed; the rejected pick
+ // stays unapplied until the user picks again.
+ if (entry.error === CONFLICT_RECHECKING_ERROR) entry.error = CONFLICT_SETTLED_ERROR
+ const pending = intentFor(entry)
+ if (pending && result?.sessionModel === pending && !entry.saving) {
+ if (chatId) clearPendingModelIntent(agentRef, chatId)
+ else clearPreChatModelIntent(agentRef)
+ }
+ }
+ // A superseded read must not erase a known CAS base and turn the next
+ // write into an unconditional legacy update.
+ return readModel
+ } catch (error) {
+ if (entry.lastFetchSeq !== fetchSeq) return undefined
+ console.warn('[hostModelSelectionStore] host models fetch failed:', error)
+ if (entry.seq === fetchSeq) {
+ // `data` is left as it was: a previous good read stays usable, and
+ // `undefined` stays `undefined` so the view reports `error`, never
+ // `unavailable` (which is the host's own answer, not ours).
+ entry.loadFailed = true
+ entry.error = LOAD_FAILED_ERROR
+ }
+ return undefined
+ } finally {
+ if (entry.lastFetchSeq === fetchSeq) {
+ entry.fetchInFlight = false
+ entry.loading = false
+ notify(entry)
+ }
+ }
+}
+
+/**
+ * Applies a model choice. Resolves `true` when the selection is usable for the
+ * next send (accepted, or kept as an unpersisted intent because the host is
+ * unreachable), `false` on a terminal rejection (allowlist, CAS conflict).
+ */
+export async function selectHostModel(
+ transport: HostModelSelectionTransport,
+ agentRef: string,
+ chatId: string | null,
+ model: string
+): Promise<boolean> {
+ if (!agentRef || !model) return false
+ const entry = getEntry(agentRef, chatId)
+
+ if (!chatId) {
+ entry.seq += 1
+ // PRE-CHAT: there is no session to POST to. Hold the pick locally keyed by
+ // agent; the send path migrates it and piggybacks it on message 1.
+ setPreChatModelIntent(agentRef, model)
+ entry.error = null
+ notify(entry)
+ return true
+ }
+
+ // New generation for this key: any response started earlier is superseded.
+ const intentSeq = ++entry.seq
+ setPendingModelIntent(agentRef, chatId, model)
+ entry.error = null
+ entry.conflicted = false
+ notify(entry)
+
+ if (entry.saving) {
+ // Serialize: coalesce toward the latest intent; the in-flight writer drains it.
+ entry.queuedModel = model
+ return true
+ }
+ return runSelectionWrites(transport, entry, intentSeq, model)
+}
+
+async function runSelectionWrites(
+ transport: HostModelSelectionTransport,
+ entry: Entry,
+ seq: number,
+ model: string
+): Promise<boolean> {
+ const chatId = entry.chatId as string
+ const ownerScope = entry.scopeGeneration
+ entry.saving = true
+ notify(entry)
+
+ let currentModel = model
+ let currentSeq = seq
+
+ const finish = (ok: boolean): boolean => {
+ entry.saving = false
+ entry.queuedModel = null
+ notify(entry)
+ return ok
+ }
+
+ for (;;) {
+ try {
+ const expectedRevision = entry.confirmedRevision ?? undefined
+ const result = await transport.setHostModel(
+ entry.agentRef,
+ chatId,
+ currentModel,
+ expectedRevision
+ )
+ if (entry.scopeGeneration !== ownerScope) return false
+ // A send ack can land while this write is in flight and raise the CAS base
+ // past the revision this write produced; the late reply must not lower it.
+ adoptRevisionIfNotOlder(entry, result?.modelSelectionRevision)
+ entry.conflicted = false
+ const serverModel =
+ typeof result?.model === 'string' && result.model ? result.model : currentModel
+ entry.lastConfirmedModel = serverModel
+ // The held projection was read BEFORE this accepted write, so it must not
+ // resurrect the previous session model; the next successful read refreshes
+ // `staleRead` and takes over again.
+ entry.staleRead = true
+ // Compare-and-clear against what the SERVER now holds, not against what we
+ // sent: an A→B→A sequence leaves a newer intent for A that the accepted A
+ // write already satisfies, and keeping it would strand the UI as pending.
+ if (intentFor(entry) === serverModel) {
+ clearPendingModelIntent(entry.agentRef, chatId)
+ }
+ const queued = entry.queuedModel
+ if (queued && queued !== serverModel) {
+ entry.queuedModel = null
+ currentModel = queued
+ currentSeq = entry.seq
+ continue
+ }
+ entry.error = null
+ return finish(true)
+ } catch (error) {
+ if (entry.scopeGeneration !== ownerScope) return false
+ const message = error instanceof Error ? error.message : String(error)
+ if (entry.queuedModel && currentSeq !== entry.seq && message.includes('model_not_allowed')) {
+ currentModel = entry.queuedModel
+ currentSeq = entry.seq
+ entry.queuedModel = null
+ continue
+ }
+
+ if (message.includes(MODEL_NOT_ALLOWED_TOKEN)) {
+ // Real allowlist rejection (host was reachable): drop the optimistic
+ // intent so the previous server selection is what a refetch shows.
+ if (intentFor(entry) === currentModel && currentSeq === entry.seq) {
+ clearPendingModelIntent(entry.agentRef, chatId)
+ }
+ entry.error = 'That model is no longer allowed — selection unchanged.'
+ return finish(false)
+ }
+
+ if (message.includes(MODEL_SELECTION_CONFLICT_TOKEN)) {
+ // CAS precondition failed: another writer moved the session selection.
+ // Keep the last confirmed state, never piggyback the rejected intent, and
+ // withhold image capability until the authoritative read lands.
+ if (intentFor(entry) === currentModel && currentSeq === entry.seq) {
+ clearPendingModelIntent(entry.agentRef, chatId)
+ }
+ entry.conflicted = true
+ entry.error = CONFLICT_RECHECKING_ERROR
+ notify(entry)
+ // `entry.saving` stays true across the await so no second writer starts
+ // (`selectHostModel` queues instead); the read adopts the winning
+ // revision, which is the CAS base the retry below needs.
+ const serverModel = await readHostModels(transport, entry.agentRef, chatId, {
+ force: true,
+ })
+ if (entry.scopeGeneration !== ownerScope) return false
+ const queuedAfterConflict = entry.queuedModel
+ if (!queuedAfterConflict) return finish(false)
+ entry.queuedModel = null
+ // Compare the newer pick with what the SERVER holds now, never with
+ // `lastConfirmedModel`: that pick superseded the re-read, so
+ // `lastConfirmedModel` is still the pre-conflict model, and a pick of
+ // that model was skipped although the server holds another one.
+ if (serverModel === undefined || queuedAfterConflict !== serverModel) {
+ // A newer pick arrived while the older write lost the race. Dropping it
+ // here is what made the user's last choice vanish silently.
+ currentModel = queuedAfterConflict
+ currentSeq = entry.seq
+ continue
+ }
+ // The server already holds the newest pick, proven by a read at or past
+ // the held revision: nothing to write, and the conflict is resolved.
+ entry.lastConfirmedModel = serverModel
+ entry.staleRead = true
+ entry.conflicted = false
+ entry.error = null
+ if (intentFor(entry) === serverModel) clearPendingModelIntent(entry.agentRef, chatId)
+ return finish(true)
+ }
+
+ const queued = entry.queuedModel
+ if (queued && queued !== currentModel) {
+ // Host was unreachable for the older pick; try the newest intent once.
+ entry.queuedModel = null
+ currentModel = queued
+ currentSeq = entry.seq
+ continue
+ }
+
+ // Host unavailable (suspended / transport / 5xx): keep the optimistic UI
+ // and the pending intent so the next send carries it and wakes the host.
+ console.warn(
+ '[hostModelSelectionStore] set failed; host likely suspended — keeping optimistic selection, will piggyback on next send:',
+ error
+ )
+ return finish(true)
+ }
+ }
+}
+
+/** Test helper: wipe every entry, listener and intent. */
+export function resetHostModelSelectionStore(): void {
+ scopeGeneration += 1
+ resetHostModelIntentStore()
+ for (const [key, entry] of entries) {
+ entry.scopeGeneration = scopeGeneration
+ entry.seq += 1
+ entry.lastFetchSeq = -1
+ entry.data = undefined
+ entry.loading = false
+ entry.fetchInFlight = false
+ entry.saving = false
+ entry.error = null
+ entry.conflicted = false
+ entry.loadFailed = false
+ entry.confirmedRevision = null
+ entry.lastConfirmedModel = null
+ entry.staleRead = false
+ entry.queuedModel = null
+ notify(entry)
+ if (entry.listeners.size === 0) entries.delete(key)
+ }
+}
diff --git a/desktop-app/ui/src/lib/retainedSendStore.ts b/desktop-app/ui/src/lib/retainedSendStore.ts
new file mode 100644
index 000000000..e12d7d4ea
--- /dev/null
+++ b/desktop-app/ui/src/lib/retainedSendStore.ts
@@ -0,0 +1,217 @@
+/**
+ * Memory-only retention of a send whose outcome is not a terminal acknowledgement
+ * (issue #654 §4.4 "Transactional send retention").
+ *
+ * The composer clears its draft and attachments as soon as a send is accepted
+ * for delivery, so a POST that throws, a synchronous `error` envelope, or an
+ * asynchronous task that fails would otherwise drop the user's input (including
+ * images that can no longer be re-attached by hand).
+ *
+ * A snapshot is keyed by the send identity `(agentRef, chatId, userMessageId)`
+ * and released only on an explicit terminal outcome: its own successful reply
+ * or cancel, a user-initiated discard (which also drops the older failures of
+ * that chat), or a newer send for the same chat that reaches a successful
+ * terminal, which supersedes every failure recorded before it. A snapshot still
+ * awaiting its own terminal is never released by another send. Receiving a
+ * `taskId` is NOT a terminal acknowledgement — a started task can still fail —
+ * so it never releases the snapshot by itself.
+ *
+ * Nothing here is persisted: recovery lives for the Desktop process lifetime
+ * only, until the durable-history contract (#652) exists.
+ */
+import type {
+ ComposerImageAttachment,
+ ComposerReferenceAttachment,
+ FailedAgentSend,
+} from '../uiTypes'
+
+export interface RetainedSendSnapshot {
+ agentRef: string
+ chatId: string | null
+ userMessageId: string
+ /** Task id once known; never used to release the snapshot on its own. */
+ taskId?: string
+ content: string
+ attachments: ComposerImageAttachment[]
+ references: ComposerReferenceAttachment[]
+ /** Model the guard validated for this send, when one was captured. */
+ model?: string
+ /** Why the snapshot is still retained (stable code for tests/telemetry). */
+ reason: RetainedSendReason
+ timestamp: number
+ draftRevision: number
+ failure?: { message: string; kind: FailedAgentSend['kind'] }
+}
+
+export type RetainedSendReason =
+ /** Retained as soon as the composer cleared; outcome still unknown. */
+ 'awaiting_terminal' | 'post_failed' | 'sync_error_envelope' | 'async_task_failed' | 'stream_lost'
+
+/** Each controller owns its bytes; no module-global data survives an identity change. */
+export function createRetainedSendStore(changed: () => void) {
+ const snapshots = new Map<string, RetainedSendSnapshot>()
+
+ function keyFor(agentRef: string, chatId: string | null, userMessageId: string): string {
+ return `${agentRef}::${chatId ?? ''}::${userMessageId}`
+ }
+
+ function retainSendSnapshot(snapshot: RetainedSendSnapshot): void {
+ if (!snapshot.agentRef || !snapshot.userMessageId) return
+ snapshots.set(keyFor(snapshot.agentRef, snapshot.chatId, snapshot.userMessageId), snapshot)
+ changed()
+ }
+
+ function getRetainedSendSnapshot(
+ agentRef: string,
+ chatId: string | null,
+ userMessageId: string
+ ): RetainedSendSnapshot | undefined {
+ return snapshots.get(keyFor(agentRef, chatId, userMessageId))
+ }
+
+ /** Newest snapshot for a chat, regardless of which message produced it. */
+ function getLatestRetainedSendSnapshotForChat(
+ agentRef: string,
+ chatId: string | null
+ ): RetainedSendSnapshot | undefined {
+ let latest: RetainedSendSnapshot | undefined
+ for (const snapshot of snapshots.values()) {
+ if (snapshot.agentRef !== agentRef || snapshot.chatId !== chatId || !snapshot.failure)
+ continue
+ if (!latest || snapshot.timestamp >= latest.timestamp) latest = snapshot
+ }
+ return latest
+ }
+
+ /** Attaches the task id once the async task is accepted (still retained). */
+ function attachTaskIdToRetainedSend(
+ agentRef: string,
+ chatId: string | null,
+ userMessageId: string,
+ taskId: string
+ ): void {
+ const key = keyFor(agentRef, chatId, userMessageId)
+ const existing = snapshots.get(key)
+ if (!existing) return
+ snapshots.set(key, { ...existing, taskId })
+ changed()
+ }
+
+ function releaseRetainedSend(
+ agentRef: string,
+ chatId: string | null,
+ userMessageId: string
+ ): void {
+ if (snapshots.delete(keyFor(agentRef, chatId, userMessageId))) changed()
+ }
+
+ function releaseRetainedSendsForTask(taskId: string): void {
+ let released = false
+ for (const [key, snapshot] of snapshots) {
+ if (snapshot.taskId === taskId) {
+ snapshots.delete(key)
+ released = true
+ }
+ }
+ if (released) changed()
+ }
+
+ /**
+ * Releases the failed snapshots of one chat recorded at or before
+ * `upToTimestamp`. Snapshots without a failure are still awaiting their own
+ * terminal and stay held: that send can still fail, and then its snapshot is
+ * the only copy of the payload.
+ */
+ function releaseRetainedFailuresForChat(
+ agentRef: string,
+ chatId: string | null,
+ upToTimestamp: number
+ ): void {
+ let released = false
+ for (const [key, snapshot] of snapshots) {
+ if (snapshot.agentRef !== agentRef || snapshot.chatId !== chatId) continue
+ if (!snapshot.failure || snapshot.timestamp > upToTimestamp) continue
+ snapshots.delete(key)
+ released = true
+ }
+ if (released) changed()
+ }
+
+ /**
+ * A synchronous send reached a successful terminal: release it and every
+ * older failure of its chat, which the success supersedes. Without the second
+ * part the newest older failure resurfaced under the successful reply.
+ */
+ function releaseSucceededRetainedSend(
+ agentRef: string,
+ chatId: string | null,
+ userMessageId: string
+ ): void {
+ const succeeded = snapshots.get(keyFor(agentRef, chatId, userMessageId))
+ if (succeeded) {
+ releaseRetainedFailuresForChat(succeeded.agentRef, succeeded.chatId, succeeded.timestamp)
+ }
+ releaseRetainedSend(agentRef, chatId, userMessageId)
+ }
+
+ /** Task-based counterpart of `releaseSucceededRetainedSend`. */
+ function releaseSucceededRetainedSendsForTask(taskId: string): void {
+ const succeeded = [...snapshots.values()].filter(snapshot => snapshot.taskId === taskId)
+ for (const snapshot of succeeded) {
+ releaseRetainedFailuresForChat(snapshot.agentRef, snapshot.chatId, snapshot.timestamp)
+ }
+ releaseRetainedSendsForTask(taskId)
+ }
+
+ /**
+ * Records why a snapshot is still held once the async outcome is known. Keeps
+ * the payload and identity untouched; only the recovery code changes.
+ */
+ function markRetainedSendReason(
+ taskId: string,
+ reason: RetainedSendReason,
+ message: string,
+ kind: FailedAgentSend['kind']
+ ): void {
+ for (const [key, snapshot] of snapshots) {
+ if (snapshot.taskId !== taskId) continue
+ snapshots.set(key, { ...snapshot, reason, failure: { message, kind } })
+ changed()
+ }
+ }
+
+ /** Release retained input on logout/reset or controller teardown. */
+ function resetRetainedSendStore(): void {
+ snapshots.clear()
+ changed()
+ }
+
+ function failRetainedSend(
+ agentRef: string,
+ chatId: string | null,
+ userMessageId: string,
+ reason: RetainedSendReason,
+ message: string,
+ kind: FailedAgentSend['kind']
+ ): void {
+ const key = keyFor(agentRef, chatId, userMessageId)
+ const existing = snapshots.get(key)
+ if (!existing) return
+ snapshots.set(key, { ...existing, reason, failure: { message, kind } })
+ changed()
+ }
+ return {
+ retainSendSnapshot,
+ getRetainedSendSnapshot,
+ getLatestRetainedSendSnapshotForChat,
+ attachTaskIdToRetainedSend,
+ releaseRetainedSend,
+ releaseRetainedSendsForTask,
+ releaseRetainedFailuresForChat,
+ releaseSucceededRetainedSend,
+ releaseSucceededRetainedSendsForTask,
+ markRetainedSendReason,
+ failRetainedSend,
+ resetRetainedSendStore,
+ }
+}
diff --git a/desktop-app/ui/src/uiTypes.ts b/desktop-app/ui/src/uiTypes.ts
index 9b52fe13c..b14c07e5b 100644
--- a/desktop-app/ui/src/uiTypes.ts
+++ b/desktop-app/ui/src/uiTypes.ts
@@ -163,6 +163,16 @@ export type FailedAgentSend = {
message: string
kind: AppErrorKind
timestamp: number
+ /**
+ * Send identity of the failed attempt (issue #654). Lets the recovery path tie
+ * the retained snapshot to its owner/chat/message instead of guessing, and
+ * never overwrite the composer of a different chat or a newer draft.
+ */
+ agentRef?: string
+ chatId?: string | null
+ userMessageId?: string
+ /** Model validated by the image guard when this attempt carried images. */
+ model?: string
}
export type HostConnectionTone = 'healthy' | 'degraded' | 'offline'
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index 8de8e0063..8165acdc5 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -84,7 +84,7 @@ class, `OpenAICompatibleProvider`.
| Moonshot | `moonshot` | `moonshot-api-key` | `kimi-k2.6` |
| Nebius | `nebius` | `nebius-api-key` | `Qwen/Qwen3-235B-A22B-Instruct-2507` |
| Novita AI | `novita` | `novita-api-key` | `deepseek/deepseek-v3.2` |
-| MiniMax | `minimax` | `minimax-api-key` | `MiniMax-M2` |
+| MiniMax | `minimax` | `minimax-api-key` | `MiniMax-M2` |
`openai` itself also speaks this protocol but uses the official SDK (Group B).
@@ -246,6 +246,65 @@ to the `clerum-llm-allowed-models` ConfigMap for the runtime.
the runtime degrades explicitly: only the model already configured on the
Host/step is permitted. Neither open nor bricked.
+### Image input capability (`image_input`)
+
+Whether a model accepts images is a property of the **(provider, model) pair**,
+declared per row and backed by evidence — never inferred from the model name, its
+family, or an "OpenAI-compatible" request shape.
+
+- Each row carries `image_input` (`{ state, evidence? }`). Absent or malformed
+ metadata reads as `unknown`. `supported` / `unsupported` require evidence: a
+ public `https://` documentation reference with no query string, fragment or
+ userinfo (or a sanitized `evidence:<id>`) plus the date it was read.
+ `validUntil` is required for any discovery-sourced `supported` / `unsupported`
+ and equals `checkedAt + LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS` (default 30 days);
+ curated evidence carries it only when the vendor document states an expiry.
+- **Unknown blocks images, never text.** Text-only chat keeps working on an
+ unverified model; attaching an image is what stops, with the model and the
+ reason surfaced.
+- The catalog sync derives `supported` / `unsupported` from models.dev
+ `modalities.input` (`image` present / absent) and records `unknown` when the
+ entry has no usable `modalities`; `attachment` is not consulted. Discovery
+ evidence never overwrites curated evidence and never overwrites newer
+ discovery evidence.
+- **Transport is a second gate.** Even `supported` evidence is refused when the
+ Host's driver family has no image serializer for the dispatch method
+ (`TRANSPORT_SUPPORT` in `mcp-host/src/llm/imageInput.ts`); the Desktop shows
+ this as a transport refusal, not as a model refusal.
+- Renaming a row's provider or model clears its evidence (it belonged to the old
+ pair), and editing capability never changes `enabled`.
+- A capability change re-materializes the ConfigMap `imageInput` field, so
+ running Hosts pick it up without a redeploy. The sync re-materializes
+ `clerum-llm-allowed-models` when it changed `image_input` on an enabled row; it
+ still never enables, disables or edits any other served column.
+
+#### Rollout and refresh cadence
+
+- On upgrade, migration `0115_llm_allowed_models_image_input` only adds the
+ nullable column and its `CHECK`; it seeds no evidence. Existing rows stay `unknown` (images refused, text unaffected) until a
+ catalog sync runs, on demand or from the cron. With the cron enabled (the
+ base deploy enables it) the first sync runs a few seconds after control-api
+ starts, not one interval later, and fills every pair models.dev lists (29 of
+ the 44 seeded pairs). The 15 seeded pairs models.dev does not list stay
+ `unknown` until an operator curates them through the admin API
+ (`PUT /admin/llm-models/:id` with an `image_input` field; see
+ [adding-a-provider.md](adding-a-provider.md)).
+- Discovery evidence expires `LLM_CATALOG_IMAGE_EVIDENCE_TTL_MS` after the
+ capture it came from. An expired claim resolves to `unknown` with reason
+ `evidence_expired`, and images are refused with that reason until the next
+ sync.
+- With `LLM_CATALOG_SYNC_CRON_ENABLED=true` (code default off; set to `true` in
+ `deploy/base/control-plane/configmaps.yaml`) the refresh is automatic: one
+ sync shortly after start, then one every `LLM_CATALOG_SYNC_INTERVAL_MS`; the config refuses a TTL shorter than twice
+ `LLM_CATALOG_SYNC_INTERVAL_MS`. Without the cron, run
+ `POST /admin/llm-models/discovery/sync` at least once per TTL (monthly at the
+ default; every two weeks leaves margin). The endpoint runs the same code path
+ as the cron.
+- A vendored (offline) run stamps evidence with the snapshot's capture date, so
+ it cannot keep evidence live past `capture + TTL`. Regenerate the snapshot with
+ `control-api/scripts/regenerate-models-dev-snapshot.mjs` (after
+ `npm run build` in `control-api`) when shipping a release.
+
Beyond the global allowlist there are two narrower scopes:
| Scope | Where | Purpose |
diff --git a/docs/llm-providers/adding-a-provider.md b/docs/llm-providers/adding-a-provider.md
index 602aa3566..3c5687495 100644
--- a/docs/llm-providers/adding-a-provider.md
+++ b/docs/llm-providers/adding-a-provider.md
@@ -30,6 +30,7 @@ stay local to **`mcp-host/src/llm/registryCore.ts`** (`RUNTIME_FIELDS`) and
Example: adding `groq`.
### 1. Shared package — `packages/llm-providers/`
+
- `index.cjs`: add the id to `PROVIDER_IDS`, a credential slot to
`PROVIDER_CREDENTIAL_SLOTS` (use the `apiKeySlot('<id>-api-key', '<ID>_API_KEY')`
helper), a brand label to `PROVIDER_DISPLAY_LABELS`, and an **empty**
@@ -38,8 +39,10 @@ Example: adding `groq`.
`LlmProviderId` union derives from it).
### 2. mcp-host runtime row — `registryCore.ts` `RUNTIME_FIELDS`
+
Add `{ baseURL, defaultModel, tokenizer: 'fallback' }`. The data-driven arm in
`makeProvider` picks up anything carrying a `baseURL` — **no driver needed**.
+
- `baseURL` must be exact so `${baseURL}/chat/completions` resolves. Watch the
path: some include `/v1` (`https://api.mistral.ai/v1`), some don't
(`https://api.perplexity.ai`), Fireworks needs an id prefix, DeepInfra is
@@ -47,6 +50,7 @@ Add `{ baseURL, defaultModel, tokenizer: 'fallback' }`. The data-driven arm in
- `tokenizer: 'fallback'` for non-OpenAI models (`'openai'` only for GPT-family).
### 3. CRD enums — `charts/clerum-crds/crds/`
+
- `host.yaml`: add the id to the `spec.model.provider` enum **and** the
`spec.llmPolicy.fallbacks[].provider` enum.
- `workflowrecipe.yaml`: add it to both provider enums **iff** the provider is
@@ -54,18 +58,99 @@ Add `{ baseURL, defaultModel, tokenizer: 'fallback' }`. The data-driven arm in
api-key providers qualify). These enums are additive — old resources stay valid.
### 4. Allowlist seed — control-api migration (`control-api/src/db.ts`)
+
Append a new migration (next `NNNN_…` version, append-only + idempotent) that
`INSERT … ON CONFLICT DO NOTHING`s one sensible default `(provider, model, vendor)`
into `llm_allowed_models`. Operators curate the rest from `/llm-models`.
-### 5. control-ui — `control-ui/lib/llm.ts`
+### 5. Image-input capability — `llm_allowed_models.image_input` (#654)
+
+Declare image support **per exact `(provider, model)` pair**, never from the
+model name, family, or an OpenAI-compatible request shape. Do it in one of two
+ways:
+
+- **Seed it** in the same migration as step 4 for ids the provider's own
+ documentation covers. Keep it to exact ids (no family extrapolation),
+ reference the public `https://` doc page, and set `checkedAt` to the date the
+ doc was **read** — never the deploy date, so re-running the migration cannot
+ rejuvenate evidence.
+- **Let the operator curate it.** The catalog sync fills the column from
+ models.dev first; the operator overrides only where the vendor documentation
+ disagrees, through the admin API — `POST /admin/llm-models` or
+ `PUT /admin/llm-models/:id` with the `image_input` field. The Control UI
+ `/llm-models` page has no editor for this field. A row with no metadata reads
+ as `unknown`: text keeps working, images are refused with the model named.
+
+The seed is one idempotent statement. Curated evidence replaces discovery
+evidence; once curated evidence is in place a re-run changes nothing:
+
+```sql
+UPDATE llm_allowed_models
+ SET image_input = $1::jsonb
+ WHERE provider = $2 AND model = $3
+ AND (image_input IS NULL OR image_input->'evidence'->>'source' = 'discovery')
+```
+
+Shape (validated by `@clerum/llm-providers` `parseImageInputCapability`;
+`GET /admin/llm-models` always returns it normalized):
+
+```json
+{
+ "state": "supported",
+ "evidence": {
+ "source": "curated",
+ "reference": "https://docs.example.com/models/vision-flash",
+ "checkedAt": "2026-09-16T00:00:00.000Z"
+ }
+}
+```
+
+A `supported`/`unsupported` claim REQUIRES `evidence`; a `discovery`-sourced
+claim also requires `validUntil`. `null` clears (and normalizes to `unknown`),
+and renaming a row's provider/model clears it automatically. The catalog sync
+derives `supported` / `unsupported` from models.dev `modalities.input` (`image`
+present / absent) and records `unknown` when the entry has no usable
+`modalities`; `attachment` is not consulted. Discovery evidence never overwrites
+curated evidence and never overwrites newer discovery evidence — see
+`discoveryImageInput` in `control-api/src/services/llmCatalogSync.ts`.
+
+What operators still curate:
+
+1. ids models.dev does not list — 15 of the 44 pairs the allowlist seeds today
+ (for example `zai:glm-5`, `zai:glm-5.1`, the Bedrock Claude ids,
+ `openai:gpt-5.1-codex`, `openrouter:anthropic/claude-sonnet-latest`). After a
+ deploy, the sync that runs shortly after control-api starts fills
+ `image_input` for the 29 listed pairs; the unlisted ones stay `unknown`
+ (images refused, text unaffected) until an operator curates them with
+ `PUT /admin/llm-models/:id` and an `image_input` field;
+2. models where the vendor documentation disagrees with models.dev (curated
+ evidence wins and is never overwritten);
+3. nothing on installations that run the cron — but without it and without a
+ sync inside the TTL the evidence expires, and running a sync restores it.
+
+#### Transport registration (mcp-host)
+
+Evidence is necessary, not sufficient. `mcp-host/src/llm/imageInput.ts` maps
+every provider id to a wire family (`EXPLICIT_DRIVER_FAMILY`,
+`imageWireFamilyFor`), and `TRANSPORT_SUPPORT` declares, per family and per
+dispatch method, whether the serializer carries image parts. A provider whose
+family is not registered (or registered `false`) resolves to
+`transport_unsupported` even with curated `supported` evidence. Path A providers
+get the `openai-compatible` family automatically when their descriptor carries a
+`baseURL`; without one they resolve to `unregistered`. Path B drivers must add an
+`EXPLICIT_DRIVER_FAMILY` entry and an `imageInputTransport.test.ts` case for each
+method they implement.
+
+### 6. control-ui — `control-ui/lib/llm.ts`
+
Add the provider's default model to `LLM_DEFAULT_MODEL_BY_PROVIDER` (a
`Record<LlmProvider, …>`, so it **must** be exhaustive — tsc enforces it). The
provider dropdown (`LLM_PROVIDER_OPTIONS`), the multi-slot secrets form
(`LLM_CREDENTIAL_GROUPS`) and the field label all **auto-derive** from the
package — no other UI change. A nicer `SECRET_FIELD_HINTS` placeholder is optional.
-### 6. Param compatibility (important)
+### 7. Param compatibility (important)
+
The OpenAI-compatible driver (`mcp-host/src/llm/openaiCompatible.ts`) shares the
`openai` provider's request shape. Some providers **reject** params: Groq
(`n>1`, `logprobs`, `logit_bias`), Cerebras (`frequency_penalty`/`presence_penalty`),
@@ -74,7 +159,8 @@ reasoner (sampling params). Keep the default request to a **conservative,
portable set** (model + messages + tools). If a provider needs something special,
gate it per-provider — don't broaden the shared default.
-### 7. Tests
+### 8. Tests
+
`mcp-host` registry tests (provider present + constructs), the control-api
migration/enum test, and confirm the credential-exclusion leak test still passes
with the expanded slot set (it derives from `ALL_PROVIDERS`, so it should).
@@ -86,12 +172,16 @@ with the expanded slot set (it derives from `ALL_PROVIDERS`, so it should).
Everything in Path A, **plus**:
### makeProvider arm — `registry.ts`
+
Add an explicit `case '<id>':` that builds the provider. Load any SDK **lazily**
with a synchronous `require()` inside the arm (mcp-host is CommonJS) so the SDK is
only parsed when the provider is actually used, and a broken dependency can't take
-down startup. Never route a driver provider through the `baseURL` arm.
+down startup. Never route a driver provider through the `baseURL` arm. Register
+the driver's image wire family (step 5, Transport registration) or images are
+refused for it.
### Credentials & non-secret env
+
- Multi-credential providers (Bedrock: key pair; Vertex: SA JSON) list every slot
in `PROVIDER_CREDENTIAL_SLOTS`. The credential-exclusion boundary
(`userEnvSnapshot`) derives from the full slot set — never `primarySlot()`.
@@ -104,34 +194,36 @@ down startup. Never route a driver provider through the `baseURL` arm.
mid-workflow (this is why `bedrock` and `azure` are host-only).
### Azure OpenAI — the reference non-vanilla case
+
Azure is OpenAI-compatible in shape but not a `baseURL + Bearer` row:
+
- **No fixed base URL** — the operator supplies `AZURE_OPENAI_ENDPOINT`
(non-secret env). The driver builds `${endpoint}/openai/v1/` (v1 GA path).
- **Auth is the `api-key` header**, not `Authorization: Bearer`.
- **`model` is the deployment name**, not a catalog id.
-Its `RUNTIME_FIELDS.azure` carries a `defaultModel` + `tokenizer: 'openai'` but
-**no static baseURL**, so it takes the explicit `case 'azure':` arm and reads the
-endpoint from `process.env` at construction. Fail-closed if the endpoint is absent.
+ Its `RUNTIME_FIELDS.azure` carries a `defaultModel` + `tokenizer: 'openai'` but
+ **no static baseURL**, so it takes the explicit `case 'azure':` arm and reads the
+ endpoint from `process.env` at construction. Fail-closed if the endpoint is absent.
---
## Gotchas encoded in the registry (2026)
-| provider | base_url quirk | param / behavior gotcha |
-|---|---|---|
-| fireworks | model id needs prefix `accounts/fireworks/models/<name>` | — |
-| deepinfra | base path is `/v1/openai` (not `/v1`) | tool-calling only on ~most models |
-| perplexity | **no** `/v1` in base URL | every call is web-grounded (returns citations) |
-| deepseek | accepts with or without `/v1` | reasoner mode restricts sampling params |
-| moonshot | `.ai` (global) vs `.cn` (China) host | **no** `tool_choice: 'required'`; temperature `[0,1]` |
-| groq | — | rejects `n>1`, `logprobs`, `logit_bias` |
-| cerebras | — | rejects `frequency_penalty`/`presence_penalty` |
-| openrouter | — | router: same slug may hit different upstreams; tool support per-model |
-| nebius | two brands mid-rename (tokenfactory / studio) | `org/model` namespaced ids |
-| together / novita / nebius | — | `org/model` namespaced ids |
-| gemini (compat) | `…/v1beta/openai/` | beta: unsupported params silently ignored; distinct from `vertex` |
-| minimax | `.io` (international) vs `api.minimaxi.com` (China) host | JWT-shaped api key; portable `[0,2]` temperature (no gating) |
-| azure | per-resource endpoint (env) | `api-key` header; `model` = deployment name |
+| provider | base_url quirk | param / behavior gotcha |
+| -------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
+| fireworks | model id needs prefix `accounts/fireworks/models/<name>` | — |
+| deepinfra | base path is `/v1/openai` (not `/v1`) | tool-calling only on ~most models |
+| perplexity | **no** `/v1` in base URL | every call is web-grounded (returns citations) |
+| deepseek | accepts with or without `/v1` | reasoner mode restricts sampling params |
+| moonshot | `.ai` (global) vs `.cn` (China) host | **no** `tool_choice: 'required'`; temperature `[0,1]` |
+| groq | — | rejects `n>1`, `logprobs`, `logit_bias` |
+| cerebras | — | rejects `frequency_penalty`/`presence_penalty` |
+| openrouter | — | router: same slug may hit different upstreams; tool support per-model |
+| nebius | two brands mid-rename (tokenfactory / studio) | `org/model` namespaced ids |
+| together / novita / nebius | — | `org/model` namespaced ids |
+| gemini (compat) | `…/v1beta/openai/` | beta: unsupported params silently ignored; distinct from `vertex` |
+| minimax | `.io` (international) vs `api.minimaxi.com` (China) host | JWT-shaped api key; portable `[0,2]` temperature (no gating) |
+| azure | per-resource endpoint (env) | `api-key` header; `model` = deployment name |
## Hand-maintained mirrors — not type-checked
@@ -150,6 +242,7 @@ grep -rn --include='*.sh' --include='*.md' --include='*.ts' --include='*.tsx' \
```
Surfaces to update:
+
- `scripts/minikube/apply-llm-secret.sh` — the `SLOTS` array (`<id>-api-key|<ID>_API_KEY|`).
- `scripts/check-prereqs.sh` — the `PROVIDER_KEYS` list.
- `scripts/e2e/e2e-plugin-workload-sdk.sh`, `scripts/e2e/seed-e2e-data.sh` — the
@@ -162,6 +255,7 @@ Surfaces to update:
## Checklist
**Type-checked source of truth** (tsc fails if missed):
+
- [ ] `packages/llm-providers/index.cjs` — id, slot(s), label, non-secret env
- [ ] `packages/llm-providers/index.d.ts` — id in the `PROVIDER_IDS` tuple
- [ ] `mcp-host/src/llm/registryCore.ts` — `RUNTIME_FIELDS` row (baseURL/defaultModel/tokenizer)
@@ -170,13 +264,22 @@ Surfaces to update:
- [ ] `control-ui/lib/llm.ts` — `LLM_DEFAULT_MODEL_BY_PROVIDER` entry
**Data / assets** (not type-checked, but required for the provider to work end-to-end):
+
- [ ] `control-api/src/db.ts` — allowlist seed migration (append-only, idempotent)
+- [ ] `control-api/src/db.ts` — curated `image_input` evidence only for ids that
+ models.dev does not list, or where the vendor document contradicts
+ models.dev (exact ids, `checkedAt` = the date the doc was read)
- [ ] `control-api/src/data/modelsDevSnapshot.ts` — vendored offline snapshot block, **derived from live models.dev** (the offline catalog-sync fallback; keys must match `PROVIDER_KEY_MAP`)
+- [ ] `control-api/src/data/modelsDevSnapshot.ts` — bump
+ `VENDORED_MODELS_DEV_SNAPSHOT_CAPTURED_AT` to the regeneration commit's
+ date (`git log -1 --format=%cI -- <file>`); discovery provenance is stamped
+ with it, so leaving it stale misdates evidence
- [ ] `charts/clerum-crds/crds/host.yaml` — both provider enums
- [ ] `charts/clerum-crds/crds/workflowrecipe.yaml` — enums (single-credential only)
- [ ] `control-ui/public/provider-icons/<id>.svg` — brand icon (the picker renders `/provider-icons/${provider}.svg`; degrades to the label initial if absent). Add a theme-knockout rule in `control-ui/app/globals.css` only if the mark is monochrome.
**Hand-maintained mirrors** (run both greps above, then):
+
- [ ] `scripts/minikube/apply-llm-secret.sh` · `scripts/check-prereqs.sh` · both `scripts/e2e/*.sh` case arms
- [ ] `README.md` · `docs/meta/claims-guardrails.md` · `docs/crds/workflowrecipe.md` · `docs/llms.txt` · `Makefile`
- [ ] operator doc updated (`docs/deploy/llm-providers.md`) and overview (`docs/llm-providers/README.md`) — counts + tables
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index aa84e757f..8e5935da1 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -9,7 +9,7 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.8.1',
externalRestApiVersion: '0.1.82',
- rpcProxyVersion: '0.1.80',
+ rpcProxyVersion: '0.1.82',
desktopVersion: '0.8.1',
minimumDesktopVersion: '0.1.252',
}
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 98cae4676..4862d18f2 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.347",
+ "version": "0.1.356",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.347",
+ "version": "0.1.356",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 8aa4e44c6..83805f035 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.347",
+ "version": "0.1.356",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
index 698397409..ee5742318 100644
--- a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
+++ b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
@@ -13,6 +13,7 @@
import { describe, expect, it, vi } from 'vitest'
import { EventEmitter } from 'events'
import { TaskLifecycle } from '../lifecycle/taskLifecycle'
+import { logger } from '../logger'
import { IncomingMessageHandler, PendingTaskEntry } from '../messageHandler'
import { MessageQueue } from '../queue/messageQueue'
import { ResultStore } from '../resultStore'
@@ -65,7 +66,7 @@ describe('IncomingMessageHandler — duplicate delivery suppression', () => {
expect(firstResult.response).toBe('first answer')
// Second delivery of the SAME message (rpc-proxy redelivery — fresh uuid).
- const warn = vi.spyOn(console, 'warn')
+ const warn = vi.spyOn(logger, 'warn')
const second = new IncomingMessageHandler(message, deps)
const secondResult = await second.execute()
@@ -77,7 +78,7 @@ describe('IncomingMessageHandler — duplicate delivery suppression', () => {
expect(deps.messageQueue.dequeue()).toBeNull()
expect(deps.taskLifecycle.getStats().total).toBe(1)
expect(
- warn.mock.calls.some(args => String(args[0]).includes('duplicate delivery suppressed'))
+ warn.mock.calls.some(args => String(args[1]).includes('duplicate delivery suppressed'))
).toBe(true)
warn.mockRestore()
})
diff --git a/mcp-host/src/__tests__/server.attachments.test.ts b/mcp-host/src/__tests__/server.attachments.test.ts
index 23dc4f547..f2f330493 100644
--- a/mcp-host/src/__tests__/server.attachments.test.ts
+++ b/mcp-host/src/__tests__/server.attachments.test.ts
@@ -143,3 +143,72 @@ describe('RPCServer attachment responses', () => {
}
})
})
+
+describe('RPCServer message body limit', () => {
+ // Desktop sends up to 8 MB of base64 images inline (COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES).
+ const IMAGE_BUDGET_BYTES = 8 * 1024 * 1024
+ const BODY_LIMIT_BYTES = 10 * 1024 * 1024
+
+ function messageBody(dataBase64Length: number): string {
+ return JSON.stringify({
+ content: 'describe these images',
+ channelType: 'telegram',
+ channelId: 'chan-1',
+ sender: 'user-1',
+ timestamp: new Date().toISOString(),
+ messageId: 'msg-large',
+ hostRef: 'chatllm',
+ attachments: [{ ...sampleAttachment, dataBase64: 'A'.repeat(dataBase64Length) }],
+ })
+ }
+
+ async function postMessage(baseUrl: string, body: string): Promise<Response> {
+ return fetch(`${baseUrl}/v1/runtime/messages`, {
+ method: 'POST',
+ headers: channelReaderEdgeHeaders(
+ { channelType: 'telegram', channelId: 'chan-1', sender: 'user-1' },
+ { 'Content-Type': 'application/json' }
+ ),
+ body,
+ })
+ }
+
+ it('accepts a message carrying the full 8 MB image budget', async () => {
+ const received: number[] = []
+ const { server, baseUrl } = await startServer(rpcServer => {
+ rpcServer.onMessage(async message => {
+ received.push(message.attachments?.[0]?.dataBase64.length ?? -1)
+ return { success: true, status: 'completed', response: 'ok' }
+ })
+ })
+
+ try {
+ const response = await postMessage(baseUrl, messageBody(IMAGE_BUDGET_BYTES))
+ expect(response.status).toBe(200)
+ expect(received).toEqual([IMAGE_BUDGET_BYTES])
+ } finally {
+ await server.stop()
+ }
+ })
+
+ it('rejects a body over 10 MB with 413 before the message handler runs', async () => {
+ const received: number[] = []
+ const { server, baseUrl } = await startServer(rpcServer => {
+ rpcServer.onMessage(async message => {
+ received.push(message.attachments?.[0]?.dataBase64.length ?? -1)
+ return { success: true, status: 'completed', response: 'ok' }
+ })
+ })
+
+ try {
+ const body = messageBody(BODY_LIMIT_BYTES)
+ expect(body.length).toBeGreaterThan(BODY_LIMIT_BYTES)
+ const response = await postMessage(baseUrl, body)
+ // Witness: the server read and judged the body (413 is its answer).
+ expect(response.status).toBe(413)
+ expect(received).toEqual([])
+ } finally {
+ await server.stop()
+ }
+ })
+})
diff --git a/mcp-host/src/__tests__/workflow/workflowRouter.test.ts b/mcp-host/src/__tests__/workflow/workflowRouter.test.ts
index 545d81115..56a70ff7f 100644
--- a/mcp-host/src/__tests__/workflow/workflowRouter.test.ts
+++ b/mcp-host/src/__tests__/workflow/workflowRouter.test.ts
@@ -260,16 +260,22 @@ describe('workflowRouter — JWT auth middleware', () => {
}
})
- it('POST /execute with valid token + execute scope passes to handler (200 or 400)', async () => {
+ it.each([
+ { instruction: 'do it', status: 200 },
+ { instruction: null, status: 400 },
+ { instruction: 42, status: 400 },
+ { instruction: {}, status: 400 },
+ { instruction: [], status: 400 },
+ ])('validates the text instruction before executing: %j', async ({ instruction, status }) => {
const token = await signWorkflowToken({ scopes: ['execute'] })
const { baseUrl, server } = await createTestApp(publicKeyPem)
try {
const res = await fetch(`${baseUrl}/api/v1/workflow/execute`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
- body: JSON.stringify({ stepId: 's1', instruction: 'do it' }),
+ body: JSON.stringify({ stepId: 's1', instruction }),
})
- expect([200, 400]).toContain(res.status)
+ expect(res.status).toBe(status)
} finally {
server.close()
}
diff --git a/mcp-host/src/agent/__tests__/imageInputWiring.test.ts b/mcp-host/src/agent/__tests__/imageInputWiring.test.ts
new file mode 100644
index 000000000..061e3267f
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/imageInputWiring.test.ts
@@ -0,0 +1,559 @@
+/**
+ * Issue #654 — the LIVE wiring of the image-input guard.
+ *
+ * The guard itself is covered elsewhere (`core/adapters/__tests__/
+ * llmPortAdapter.imageInput.test.ts`, `llm/__tests__/imageInput.test.ts`,
+ * `llm/__tests__/imageInputTransport.test.ts`, `llm/__tests__/
+ * claudeToolImageWire.test.ts`). This suite covers what those cannot: which
+ * resolver instance actually reaches the port each production call site builds,
+ * and what the resumed turn does when the capability changed while the approval
+ * was pending.
+ *
+ * Boundary: the tool-use loop is mocked because it is the one component that
+ * would otherwise execute real tools. Everything under test stays real —
+ * `AgentStateMachine` → `TaskExecutor` → `LlmPortAdapter` → the provider stub.
+ * Where the loop would dispatch to the model, these tests call the loop config's
+ * real `reasoning` port (the production `defaultReasoningPort` the executor
+ * built), which is the same object the real loop calls.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { LlmPortAdapter } from '../../core/adapters/llmPortAdapter'
+import { LlmError, LlmErrorCode } from '../../core/errors'
+import { executeSingleTool, runToolUseLoop } from '../../core/orchestration/toolUseLoop'
+import { appendToolResults } from '../../core/orchestration/toolUseLoopMessages'
+import {
+ type Attachment,
+ type ChatMessage,
+ FinishReason,
+ type ReasoningContext,
+ type RespondResult,
+} from '../../core/types'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import type { ImageInputResolver } from '../../llm/imageInput'
+import { MessageQueue } from '../../queue/messageQueue'
+import type { Task, TaskError } from '../../queue/types'
+import { AgentStateMachine } from '../stateMachine'
+
+vi.mock('../../config', () => ({
+ config: {
+ devMode: true,
+ enableApproval: true,
+ enableNudge: false,
+ nudgeMaxIterations: 3,
+ devModelName: 'test-model',
+ devModelProvider: 'openai',
+ contextMaxTokens: 100000,
+ tokenizerOffline: true,
+ tokenizerDryrun: false,
+ compactionStructuredSummary: false,
+ promptCacheEnabled: false,
+ nativeTool: {
+ workspacePath: '/tmp',
+ shellTimeout: 5000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ },
+ },
+}))
+
+vi.mock('../../core/orchestration/toolUseLoop', () => ({
+ runToolUseLoop: vi.fn(),
+ executeSingleTool: vi.fn(),
+ validateToolLinkages: vi.fn(),
+ extractInputPreview: vi.fn(() => 'ls'),
+ buildOutputPreview: vi.fn((content: string) =>
+ content
+ ? {
+ headLines: String(content).split('\n').slice(0, 3),
+ tailLines: [],
+ totalLines: String(content).split('\n').length,
+ truncated: false,
+ }
+ : undefined
+ ),
+}))
+
+const EVIDENCE = {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+
+const IMAGE_B64 = 'QUJD'
+const SESSION_KEY = 'user-1:rpc:wiring-session:default'
+
+function usage() {
+ return { input_tokens: 1, output_tokens: 1, total_tokens: 2 }
+}
+
+function stubProvider(type: string) {
+ return {
+ completeSingleTurn: vi.fn(async (_messages: ChatMessage[], _options?: unknown) => ({
+ content: 'ok',
+ usage: usage(),
+ finish_reason: FinishReason.Stop,
+ })),
+ completeSingleTurnWithTools: vi.fn(
+ async (_messages: ChatMessage[], _tools: unknown[], _options?: unknown) => ({
+ content: 'ok',
+ tool_calls: [],
+ usage: usage(),
+ finish_reason: FinishReason.Stop,
+ })
+ ),
+ getProviderType: () => type,
+ }
+}
+
+type StubProvider = ReturnType<typeof stubProvider>
+
+function imageMessage(role: ChatMessage['role'] = 'user'): ChatMessage {
+ return {
+ role,
+ content: 'look at this',
+ contentParts: [
+ { type: 'text', text: 'look at this' },
+ { type: 'image', mimeType: 'image/png', data: IMAGE_B64 },
+ ],
+ }
+}
+
+function imageTask(
+ channelId = 'chat-image'
+): Task & { responseCallback: ReturnType<typeof vi.fn> } {
+ const responseCallback = vi.fn(async () => {})
+ return {
+ id: `task-${channelId}-${Math.random().toString(36).slice(2, 6)}`,
+ source: 'channel',
+ sourceMessage: {
+ sender: 'user-1',
+ content: 'look at this',
+ channelType: 'rpc',
+ channelId,
+ messageId: 'msg-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'test-host',
+ attachments: [
+ {
+ id: 'att-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: IMAGE_B64,
+ },
+ ],
+ },
+ priority: 'normal',
+ status: 'pending',
+ conversationHistory: [{ role: 'user', content: 'look at this', timestamp: new Date() }],
+ responseCallback,
+ createdAt: new Date(),
+ } as unknown as Task & { responseCallback: ReturnType<typeof vi.fn> }
+}
+
+interface LoopConfigLike {
+ reasoning: { respondWithTools: (context: ReasoningContext) => Promise<RespondResult> }
+}
+
+/**
+ * What the real loop does with the config it is handed: it asks the reasoning
+ * port for the next model turn. Calling the same object keeps the assertion on
+ * the production path (reasoning port → adapter → guard → provider).
+ */
+function dispatchThroughReasoning(
+ config: unknown,
+ messages: ChatMessage[]
+): Promise<RespondResult> {
+ return (config as LoopConfigLike).reasoning.respondWithTools({
+ messages,
+ available_tools: [],
+ })
+}
+
+/** The typed denial carried by a failed `RespondResult`, if any. */
+function errorOf(result: RespondResult | undefined): LlmError | undefined {
+ const failed = result as Extract<RespondResult, { type: 'error' }> | undefined
+ return failed?.error as LlmError | undefined
+}
+
+describe('#654 image-input guard wiring', () => {
+ let agent: AgentStateMachine
+ let queue: MessageQueue
+ let lifecycle: TaskLifecycle
+ let provider: StubProvider
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ vi.mocked(executeSingleTool).mockReset()
+ queue = new MessageQueue()
+ lifecycle = new TaskLifecycle()
+ queue.setLifecycle(lifecycle)
+ agent = new AgentStateMachine(queue, lifecycle, { autoStart: false })
+ provider = stubProvider('openai')
+ agent.setLLMProvider(provider as never, 'gpt-4o')
+ agent.setMcpManager({ getAllTools: () => [], callTool: vi.fn() } as never)
+ agent.start()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('threads the live resolver into the port the task loop is handed', async () => {
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: { state: 'supported', evidence: EVIDENCE },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ let seenMessages: ChatMessage[] = []
+ let seenResult: RespondResult | undefined
+ vi.mocked(runToolUseLoop).mockImplementation(async (config, messages) => {
+ seenMessages = messages
+ seenResult = await dispatchThroughReasoning(config, messages)
+ return { type: 'response', content: 'ok', usage: usage() }
+ })
+
+ const task = imageTask()
+ await agent.executeTask(task)
+
+ // The executor assembled the composer image onto the last user message…
+ const last = seenMessages.at(-1)
+ expect(last?.role).toBe('user')
+ expect(last?.contentParts).toEqual([
+ { type: 'text', text: 'look at this' },
+ { type: 'image', mimeType: 'image/png', data: IMAGE_B64 },
+ ])
+
+ // …and the port behind that real reasoning call consulted the live catalog
+ // for the exact pair before dispatching, instead of failing closed.
+ expect(resolver).toHaveBeenCalledWith('openai', 'gpt-4o')
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ expect(seenResult?.type).toBe('text')
+
+ // The image survived the adapter: the provider received the content parts
+ // rather than a stripped text-only message.
+ const sentMessages = provider.completeSingleTurnWithTools.mock.calls[0]?.[0] as ChatMessage[]
+ expect(sentMessages.at(-1)?.contentParts).toEqual([
+ { type: 'text', text: 'look at this' },
+ { type: 'image', mimeType: 'image/png', data: IMAGE_B64 },
+ ])
+
+ expect(task.responseCallback).toHaveBeenCalledWith(expect.objectContaining({ response: 'ok' }))
+ })
+
+ it('leaves a text-only turn untouched, even with a cold resolver', async () => {
+ // A resolver that knows nothing about the pair: `unknown`, not support.
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: { state: 'unknown' },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ let seenResult: RespondResult | undefined
+ vi.mocked(runToolUseLoop).mockImplementation(async (config, messages) => {
+ seenResult = await dispatchThroughReasoning(config, messages)
+ return { type: 'response', content: 'ok', usage: usage() }
+ })
+
+ const task = imageTask('chat-text')
+ delete (task.sourceMessage as { attachments?: unknown }).attachments
+ await agent.executeTask(task)
+
+ expect(seenResult?.type).toBe('text')
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ // No image in the request → the guard never consults the catalog.
+ expect(resolver).not.toHaveBeenCalled()
+ expect(task.responseCallback).toHaveBeenCalledWith(expect.objectContaining({ response: 'ok' }))
+ })
+
+ it('refuses an image whose evidence expired instead of dropping it into a text-only turn', async () => {
+ // A validity window that has closed: `checkedAt < validUntil <= now`. The
+ // adapter reads the real clock, so the window is set well in the past.
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: {
+ state: 'supported',
+ evidence: {
+ ...EVIDENCE,
+ checkedAt: '2026-01-01T00:00:00Z',
+ validUntil: '2026-02-01T00:00:00Z',
+ },
+ },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ let seenResult: RespondResult | undefined
+ vi.mocked(runToolUseLoop).mockImplementation(async (config, messages) => {
+ seenResult = await dispatchThroughReasoning(config, messages)
+ return { type: 'response', content: 'handled', usage: usage() }
+ })
+
+ await agent.executeTask(imageTask('chat-expired'))
+
+ expect(seenResult?.type).toBe('error')
+ const error = errorOf(seenResult)
+ expect(error).toBeInstanceOf(LlmError)
+ // Expired evidence degrades to `unknown`, never to a silent text-only send.
+ expect(error?.code).toBe(LlmErrorCode.ImageInputUnknown)
+ expect(error?.message).toContain('expired')
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ })
+
+ it('re-checks the pair when an approval resumes and never sends the image after a change', async () => {
+ let state: 'supported' | 'unsupported' = 'supported'
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: { state, evidence: EVIDENCE },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ let resumedMessages: ChatMessage[] = []
+ let resumedResult: RespondResult | undefined
+ vi.mocked(runToolUseLoop)
+ // First pass: suspend for approval with a snapshot that already carries
+ // the image (this is what the resumed turn replays verbatim).
+ .mockImplementationOnce(async () => ({
+ type: 'need_approval',
+ approval: {
+ request_id: 'req-1',
+ tool_name: 'shell_exec',
+ parameters: { command: 'ls' },
+ description: 'Shell command',
+ tool_call_id: 'tc_1',
+ context_snapshot: [imageMessage()],
+ },
+ }))
+ // Resume: dispatch through the SAME reasoning port the executor rebuilt.
+ .mockImplementationOnce(async (config, messages) => {
+ resumedMessages = messages
+ resumedResult = await dispatchThroughReasoning(config, messages)
+ return { type: 'response', content: 'done', usage: usage() }
+ })
+ vi.mocked(executeSingleTool).mockResolvedValue({
+ tool_call_id: 'tc_1',
+ name: 'shell_exec',
+ content: '<tool_output tool="shell_exec">ok</tool_output>',
+ is_error: false,
+ })
+
+ const task = imageTask('chat-approval')
+ await agent.executeTask(task)
+ expect(agent.getState()).toBe('waiting_approval')
+
+ // The user's model lost image support while the approval was pending.
+ const resolverCallsBefore = resolver.mock.calls.length
+ const providerCallsBefore = provider.completeSingleTurnWithTools.mock.calls.length
+ state = 'unsupported'
+
+ await agent.handleApproval('user-1', 'req-1', false)
+ await vi.waitFor(() => expect(task.responseCallback).toHaveBeenCalled())
+
+ // The resumed attempt re-consulted the catalog for the same pair…
+ expect(resolver.mock.calls.length).toBeGreaterThan(resolverCallsBefore)
+ expect(resolver).toHaveBeenCalledWith('openai', 'gpt-4o')
+ // …the request really carried the image (so the refusal is about the image,
+ // not about an empty request)…
+ expect(resumedMessages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(true)
+ // …and the provider was never called with it.
+ expect(provider.completeSingleTurnWithTools.mock.calls.length).toBe(providerCallsBefore)
+ expect(resumedResult?.type).toBe('error')
+ expect(errorOf(resumedResult)?.code).toBe(LlmErrorCode.ImageInputUnsupported)
+ expect(task.responseCallback).toHaveBeenCalled()
+ })
+
+ it('threads the live resolver into the manual /compact port', async () => {
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: { state: 'supported', evidence: EVIDENCE },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ const cm = agent.getConversationManager()
+ // The force-summarize tier keeps the last 5 turns, so the session needs more
+ // than that before any turn is archived and the summarizer calls the port.
+ const conv = await cm.getOrCreate(SESSION_KEY)
+ for (let i = 0; i < 8; i++) {
+ await cm.startTurn(conv, `user ${i}`, `task-${i}`)
+ await cm.completeTurn(conv, `assistant ${i}`)
+ }
+
+ // Capture the adapter the compactor really uses.
+ const compactPorts: LlmPortAdapter[] = []
+ vi.spyOn(LlmPortAdapter.prototype, 'complete').mockImplementation(async function (
+ this: LlmPortAdapter
+ ) {
+ if (!compactPorts.includes(this)) compactPorts.push(this)
+ return {
+ content: 'summary of the archived turns',
+ usage: usage(),
+ finish_reason: FinishReason.Stop,
+ } as never
+ })
+
+ const result = await agent.compactSession({ sessionKey: SESSION_KEY })
+ expect(result.kind).toBe('ok')
+ expect(compactPorts).toHaveLength(1)
+
+ // Contract note: today's compaction converts archived turns to markdown
+ // text (`contextManager.ts` `formatTurnsAsMarkdown`) and sends a text-only
+ // summarization request, so no archived image can reach this port. What is
+ // asserted here is the WIRING: the port the compactor uses is the one
+ // carrying the live resolver, and it enforces it for an image request.
+ // The captured adapter is the compact port: same pair, and the injected
+ // resolver is the one wired on the state machine.
+ await compactPorts[0].completeWithTools({ messages: [imageMessage()], tools: [] })
+ expect(resolver).toHaveBeenCalledWith('openai', 'gpt-4o')
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ })
+
+ it('keeps an unwired compact port failing closed on images but not on text', async () => {
+ // No `setImageInputResolver` call at all: a cold host.
+ const cm = agent.getConversationManager()
+ const conv = await cm.getOrCreate(SESSION_KEY)
+ for (let i = 0; i < 8; i++) {
+ await cm.startTurn(conv, `user ${i}`, `task-${i}`)
+ await cm.completeTurn(conv, `assistant ${i}`)
+ }
+
+ const compactPorts: LlmPortAdapter[] = []
+ vi.spyOn(LlmPortAdapter.prototype, 'complete').mockImplementation(async function (
+ this: LlmPortAdapter
+ ) {
+ if (!compactPorts.includes(this)) compactPorts.push(this)
+ return {
+ content: 'summary of the archived turns',
+ usage: usage(),
+ finish_reason: FinishReason.Stop,
+ } as never
+ })
+
+ // Compaction itself is text-only, so a cold catalog must not break it.
+ const result = await agent.compactSession({ sessionKey: SESSION_KEY })
+ expect(result.kind).toBe('ok')
+ expect(compactPorts).toHaveLength(1)
+
+ await expect(
+ compactPorts[0].completeWithTools({ messages: [imageMessage()], tools: [] })
+ ).rejects.toMatchObject({
+ code: LlmErrorCode.ImageInputUnknown,
+ retryable: false,
+ })
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ })
+
+ it('a screenshot tool does not terminate a text-only task on an unverified model', async () => {
+ // A cold catalog: the pair resolves to `unknown`, which refuses a USER
+ // image. The task below never carries one — the image comes back from the
+ // agent's own tool, and that must not end the task.
+ const resolver = vi.fn<ImageInputResolver>(() => ({
+ capability: { state: 'unknown' },
+ }))
+ agent.setImageInputResolver(resolver)
+
+ const collectedAttachments: Attachment[] = []
+ let seenResult: RespondResult | undefined
+ vi.mocked(runToolUseLoop).mockImplementation(async (config, messages) => {
+ // The real message builder, so the `imageOrigin` flag under test is the
+ // one production writes rather than one this test invents.
+ appendToolResults(
+ messages,
+ [
+ {
+ tool_call_id: 'tc_1',
+ name: 'browser__screenshot',
+ content: 'captured the page',
+ is_error: false,
+ attachments: [
+ {
+ id: 'shot-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: IMAGE_B64,
+ sourceTool: 'browser__screenshot',
+ } as unknown as Attachment,
+ ],
+ },
+ ],
+ collectedAttachments
+ )
+ seenResult = await dispatchThroughReasoning(config, messages)
+ return { type: 'response', content: 'ok', usage: usage(), attachments: collectedAttachments }
+ })
+
+ const task = imageTask('chat-tool-shot')
+ delete (task.sourceMessage as { attachments?: unknown }).attachments
+ await agent.executeTask(task)
+
+ // Witness: the turn reached the model and came back as text, not as a
+ // typed image refusal.
+ expect(seenResult?.type).toBe('text')
+ expect(errorOf(seenResult)).toBeUndefined()
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ expect(resolver).toHaveBeenCalledWith('openai', 'gpt-4o')
+
+ // The screenshot was withheld from the wire and replaced by the notice.
+ const sent = provider.completeSingleTurnWithTools.mock.calls[0]?.[0] as ChatMessage[]
+ const screenshotMessage = sent.at(-1)
+ expect(screenshotMessage?.contentParts).toBeUndefined()
+ expect(screenshotMessage?.content).toContain('were not forwarded')
+
+ // …and it still reaches the user as an attachment on the reply: withholding
+ // is about what the MODEL can read, not about discarding the bytes.
+ expect(collectedAttachments).toHaveLength(1)
+ expect(task.responseCallback).toHaveBeenCalledWith(
+ expect.objectContaining({
+ response: 'ok',
+ attachments: [expect.objectContaining({ id: 'shot-1', kind: 'image' })],
+ })
+ )
+ })
+})
+
+/**
+ * The decision must also surface as a structured task error when it reaches the
+ * executor's failure path, so the channel reader sees a code it can act on.
+ */
+describe('#654 image-input denial is a structured task error', () => {
+ let agent: AgentStateMachine
+ let provider: StubProvider
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ vi.mocked(executeSingleTool).mockReset()
+ const queue = new MessageQueue()
+ const lifecycle = new TaskLifecycle()
+ queue.setLifecycle(lifecycle)
+ agent = new AgentStateMachine(queue, lifecycle, { autoStart: false })
+ provider = stubProvider('openai')
+ agent.setLLMProvider(provider as never, 'gpt-4o')
+ agent.setMcpManager({ getAllTools: () => [], callTool: vi.fn() } as never)
+ agent.start()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('delivers LLM_IMAGE_INPUT_UNSUPPORTED to the response callback', async () => {
+ agent.setImageInputResolver(() => ({
+ capability: { state: 'unsupported', evidence: EVIDENCE },
+ }))
+
+ // The real loop turns a reasoning error into the loop's error result.
+ vi.mocked(runToolUseLoop).mockImplementation(async config => {
+ const result = await dispatchThroughReasoning(config, [imageMessage()])
+ if (result.type === 'error') throw result.error
+ return { type: 'response', content: 'unexpected', usage: usage() }
+ })
+
+ const task = imageTask('chat-task-error')
+ await agent.executeTask(task)
+
+ expect(task.responseCallback).toHaveBeenCalledTimes(1)
+ const delivered = task.responseCallback.mock.calls[0][0] as { error?: TaskError }
+ expect(delivered.error?.code).toBe(LlmErrorCode.ImageInputUnsupported)
+ expect(delivered.error?.retryable).toBe(false)
+ expect(delivered.error?.provider).toBe('openai')
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
new file mode 100644
index 000000000..7733c3a92
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
@@ -0,0 +1,284 @@
+/**
+ * Image sends and the per-session model selection (review findings M3 / LM1).
+ *
+ * The Desktop sends `model` (the model it displays, usually the Host default)
+ * and `modelSelectionRevision` with every image. These tests wire the admission
+ * gate to the REAL selection core over a real `ConversationManager`, so the
+ * revision and the saved selections are the ones a later `GET /v1/runtime/models`
+ * would read:
+ * - asking for the model the session already runs on writes nothing;
+ * - an image the requested model cannot read is refused before any write.
+ */
+import { type Mock, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AllowlistView } from '../../config/allowlistCheck'
+import type { AllowedModelEntry } from '../../config/configStore'
+import { resolveSessionModel } from '../../config/modelResolution'
+import { ConversationManager } from '../../core/conversation/conversation'
+import type { IncomingMessage } from '../../server/types'
+import { serializeSessionKey } from '../../session'
+import { type IncomingAdmissionDeps, createIncomingAdmission } from '../incomingAdmission'
+import { applySessionModelSelection } from '../sessionModelSelection'
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const EVIDENCE = {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+const PROVIDER = 'zai'
+const HOST_DEFAULT = 'glm-5.3-flash'
+const VISION = 'glm-5.3-vision'
+const TEXT_ONLY = 'glm-5.3-text'
+const UNVERIFIED = 'glm-5.3-unverified'
+
+const USER = 'user-1'
+const AGENT = 'agent-1'
+const CHAT = 'chat-1'
+const sessionKey = serializeSessionKey({
+ userId: USER,
+ channelType: 'rpc',
+ channelId: AGENT,
+ threadId: CHAT,
+})
+
+const catalog = new Map<string, AllowedModelEntry[]>([
+ [
+ PROVIDER,
+ [
+ { model: HOST_DEFAULT, imageInput: { state: 'supported', evidence: EVIDENCE } },
+ { model: VISION, imageInput: { state: 'supported', evidence: EVIDENCE } },
+ { model: TEXT_ONLY, imageInput: { state: 'unsupported', evidence: EVIDENCE } },
+ { model: UNVERIFIED, imageInput: { state: 'unknown' } },
+ ] as AllowedModelEntry[],
+ ],
+])
+const view: AllowlistView = { allowlistAvailable: () => true, allowedModels: () => catalog }
+
+function imageMessage(overrides: Partial<IncomingMessage> = {}): IncomingMessage {
+ return {
+ content: 'look at this',
+ channelType: 'rpc',
+ channelId: AGENT,
+ sender: USER,
+ timestamp: '2026-09-17T10:00:00Z',
+ messageId: 'msg-1',
+ hostRef: 'host-1',
+ threadId: CHAT,
+ attachments: [
+ {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: PNG_SIGNATURE.toString('base64'),
+ },
+ ],
+ ...overrides,
+ }
+}
+
+describe('image sends and the session model selection', () => {
+ let cm: ConversationManager
+ let setModelSelection: Mock<ConversationManager['setModelSelection']>
+ let dispatch: Mock<IncomingAdmissionDeps['dispatch']>
+ let resolveTaskModel: Mock<IncomingAdmissionDeps['resolveTaskModel']>
+ let resolveImageInput: Mock<IncomingAdmissionDeps['resolveImageInput']>
+ let applySelection: Mock<IncomingAdmissionDeps['applySessionModelSelection']>
+ let admit: ReturnType<typeof createIncomingAdmission>
+
+ beforeEach(() => {
+ cm = new ConversationManager()
+ setModelSelection = vi.spyOn(cm, 'setModelSelection')
+ dispatch = vi.fn<IncomingAdmissionDeps['dispatch']>(() => ({
+ success: true,
+ taskId: 't-1',
+ status: 'pending',
+ }))
+ // Same resolution primitive as main.ts `resolveTaskModel`.
+ resolveTaskModel = vi.fn<IncomingAdmissionDeps['resolveTaskModel']>(selections => ({
+ provider: { getProviderType: () => PROVIDER },
+ model: resolveSessionModel(view, PROVIDER, HOST_DEFAULT, selections).model,
+ }))
+ resolveImageInput = vi.fn<IncomingAdmissionDeps['resolveImageInput']>((provider, model) => {
+ const entry = catalog.get(provider)?.find(candidate => candidate.model === model)
+ return entry ? { capability: entry.imageInput } : undefined
+ })
+ applySelection = vi.fn<IncomingAdmissionDeps['applySessionModelSelection']>(
+ (userSub, hostRef, chatId, model, expectedRevision, options) =>
+ applySessionModelSelection(
+ {
+ modelCfg: { provider: PROVIDER, name: HOST_DEFAULT },
+ allowlistView: view,
+ convManager: cm,
+ },
+ userSub,
+ hostRef,
+ chatId,
+ model,
+ expectedRevision,
+ options
+ )
+ )
+ admit = createIncomingAdmission({
+ limits: { maxCount: 4, maxBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => PROVIDER,
+ getConversationByKey: (key, userId) => cm.getSessionByKeyForUserAsync(key, userId),
+ resolveTaskModel,
+ resolveImageInput,
+ applySessionModelSelection: applySelection,
+ dispatch,
+ logger: { info: vi.fn(), warn: vi.fn() },
+ })
+ })
+
+ async function session() {
+ return cm.getOrCreate(sessionKey)
+ }
+
+ it('(a) admits an image on the Host default without pinning it', async () => {
+ const response = await admit(imageMessage({ model: HOST_DEFAULT, modelSelectionRevision: 0 }))
+
+ expect(response).toMatchObject({ success: true, taskId: 't-1', modelSelectionRevision: 0 })
+ // Witnesses: the selection core ran and the task was dispatched on the pair.
+ expect(applySelection).toHaveBeenCalledWith(USER, AGENT, CHAT, HOST_DEFAULT, 0, {
+ skipWriteWhenEffective: true,
+ })
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ expect(dispatch.mock.calls[0][0]).toMatchObject({
+ imageModel: { provider: PROVIDER, model: HOST_DEFAULT },
+ })
+ expect(setModelSelection).not.toHaveBeenCalled()
+ const conv = await session()
+ expect(conv.modelSelections ?? {}).toEqual({})
+ expect(conv.modelSelectionRevision).toBe(0)
+ })
+
+ it('(a) repeated default-model image sends keep the revision at 0', async () => {
+ for (const messageId of ['msg-1', 'msg-2', 'msg-3']) {
+ const response = await admit(
+ imageMessage({ messageId, model: HOST_DEFAULT, modelSelectionRevision: 0 })
+ )
+ expect(response).toMatchObject({ success: true, modelSelectionRevision: 0 })
+ }
+ expect(dispatch).toHaveBeenCalledTimes(3)
+ expect(applySelection).toHaveBeenCalledTimes(3)
+ expect(setModelSelection).not.toHaveBeenCalled()
+ expect((await session()).modelSelectionRevision).toBe(0)
+ })
+
+ it('(b) refuses a stale revision on the Host default with the winning revision', async () => {
+ // Another client selected the vision model: revision 1.
+ await admit(imageMessage({ model: VISION, modelSelectionRevision: 0 }))
+ expect((await session()).modelSelectionRevision).toBe(1)
+ // Then that client went back to the default: revision 2, default pinned.
+ await admit(
+ imageMessage({ messageId: 'msg-2', model: HOST_DEFAULT, modelSelectionRevision: 1 })
+ )
+ expect(await session()).toMatchObject({
+ modelSelections: { [PROVIDER]: HOST_DEFAULT },
+ modelSelectionRevision: 2,
+ })
+ dispatch.mockClear()
+ setModelSelection.mockClear()
+
+ // This client still holds revision 0 and asks for the (effective) default.
+ const response = await admit(
+ imageMessage({ messageId: 'msg-3', model: HOST_DEFAULT, modelSelectionRevision: 0 })
+ )
+
+ expect(response).toMatchObject({
+ success: false,
+ modelSelectionRevision: 2,
+ error: { code: 'LLM_MODEL_SELECTION_CONFLICT', retryable: true },
+ })
+ expect(applySelection).toHaveBeenLastCalledWith(USER, AGENT, CHAT, HOST_DEFAULT, 0, {
+ skipWriteWhenEffective: true,
+ })
+ expect(setModelSelection).not.toHaveBeenCalled()
+ expect(dispatch).not.toHaveBeenCalled()
+ expect((await session()).modelSelectionRevision).toBe(2)
+ })
+
+ it('(c) writes and bumps for an explicit different image-capable model', async () => {
+ const response = await admit(imageMessage({ model: VISION, modelSelectionRevision: 0 }))
+
+ expect(response).toMatchObject({ success: true, modelSelectionRevision: 1 })
+ expect(setModelSelection).toHaveBeenCalledTimes(1)
+ expect(resolveImageInput).toHaveBeenCalledWith(PROVIDER, VISION)
+ expect(dispatch.mock.calls[0][0]).toMatchObject({
+ imageModel: { provider: PROVIDER, model: VISION },
+ })
+ expect(await session()).toMatchObject({
+ modelSelections: { [PROVIDER]: VISION },
+ modelSelectionRevision: 1,
+ })
+ })
+
+ it.each([
+ [TEXT_ONLY, 'LLM_IMAGE_INPUT_UNSUPPORTED'],
+ [UNVERIFIED, 'LLM_IMAGE_INPUT_UNKNOWN'],
+ ])(
+ '(d) refuses an image for %s with %s and leaves the selection untouched',
+ async (model, code) => {
+ await admit(imageMessage({ model: VISION, modelSelectionRevision: 0 }))
+ dispatch.mockClear()
+ setModelSelection.mockClear()
+ applySelection.mockClear()
+ resolveImageInput.mockClear()
+
+ const response = await admit(
+ imageMessage({ messageId: 'msg-2', model, modelSelectionRevision: 1 })
+ )
+
+ expect(response).toEqual({
+ success: false,
+ error: expect.objectContaining({ code, retryable: false, provider: PROVIDER }),
+ })
+ // Witness: the capability of the REQUESTED model was what got checked.
+ expect(resolveTaskModel).toHaveBeenCalledWith({ [PROVIDER]: model })
+ expect(resolveImageInput).toHaveBeenCalledWith(PROVIDER, model)
+ expect(applySelection).not.toHaveBeenCalled()
+ expect(setModelSelection).not.toHaveBeenCalled()
+ expect(dispatch).not.toHaveBeenCalled()
+ expect(await session()).toMatchObject({
+ modelSelections: { [PROVIDER]: VISION },
+ modelSelectionRevision: 1,
+ })
+ }
+ )
+
+ it('(d) a text-only send with a model that cannot read images still writes it', async () => {
+ const response = await admit(
+ imageMessage({ attachments: undefined, model: TEXT_ONLY, modelSelectionRevision: undefined })
+ )
+
+ expect(response).toMatchObject({ success: true, modelSelectionRevision: 1 })
+ expect(resolveImageInput).not.toHaveBeenCalled()
+ expect(setModelSelection).toHaveBeenCalledTimes(1)
+ expect((await session()).modelSelections).toEqual({ [PROVIDER]: TEXT_ONLY })
+ })
+
+ it('a text-only piggyback of the Host default still pins it (no skip option)', async () => {
+ const response = await admit(
+ imageMessage({
+ attachments: undefined,
+ model: HOST_DEFAULT,
+ modelSelectionRevision: undefined,
+ })
+ )
+
+ expect(response).toMatchObject({ success: true, modelSelectionRevision: 1 })
+ expect(applySelection).toHaveBeenCalledWith(
+ USER,
+ AGENT,
+ CHAT,
+ HOST_DEFAULT,
+ undefined,
+ undefined
+ )
+ expect(setModelSelection).toHaveBeenCalledTimes(1)
+ expect((await session()).modelSelections).toEqual({ [PROVIDER]: HOST_DEFAULT })
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
new file mode 100644
index 000000000..3e37234ae
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
@@ -0,0 +1,310 @@
+/**
+ * Issue #654 — the admission gate, tested directly.
+ *
+ * Every refusal here costs the user their turn, and every acceptance pins the
+ * model the task will actually run on, so each case asserts BOTH the envelope
+ * the caller receives and the witness that the path really ran (the dispatch,
+ * the resolver call, or the structured log line the branch had to emit).
+ */
+import { type Mock, describe, expect, it, vi } from 'vitest'
+import type { IncomingMessage, MessageResponse, SetModelResult } from '../../server/types'
+import { type IncomingAdmissionDeps, createIncomingAdmission } from '../incomingAdmission'
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+const CURATED_SUPPORTED = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+ },
+}
+
+function imageAttachment() {
+ return {
+ id: 'image-1',
+ kind: 'image' as const,
+ mimeType: 'image/png' as const,
+ encoding: 'base64' as const,
+ dataBase64: PNG_SIGNATURE.toString('base64'),
+ }
+}
+
+function message(overrides: Partial<IncomingMessage> = {}): IncomingMessage {
+ return {
+ content: 'look at this',
+ channelType: 'rpc',
+ channelId: 'agent-1',
+ sender: 'user-1',
+ timestamp: '2026-09-17T10:00:00Z',
+ messageId: 'msg-1',
+ hostRef: 'host-1',
+ threadId: 'chat-1',
+ ...overrides,
+ }
+}
+
+function imageMessage(overrides: Partial<IncomingMessage> = {}): IncomingMessage {
+ return message({ attachments: [imageAttachment()], ...overrides })
+}
+
+/** The spies are read back OFF the resolved deps, never off the defaults, so a
+ * test that overrides a dependency still asserts against the function the gate
+ * actually called. Asserting on a replaced default would make every witness
+ * vacuously report zero calls. */
+type Spies = {
+ dispatch: Mock<IncomingAdmissionDeps['dispatch']>
+ resolveImageInput: Mock<IncomingAdmissionDeps['resolveImageInput']>
+ applySessionModelSelection: Mock<IncomingAdmissionDeps['applySessionModelSelection']>
+ resolveTaskModel: Mock<IncomingAdmissionDeps['resolveTaskModel']>
+ info: Mock<IncomingAdmissionDeps['logger']['info']>
+ warn: Mock<IncomingAdmissionDeps['logger']['warn']>
+}
+
+function makeAdmission(overrides: Partial<IncomingAdmissionDeps> = {}): {
+ admit: ReturnType<typeof createIncomingAdmission>
+ spies: Spies
+} {
+ const logger = {
+ info: vi.fn<IncomingAdmissionDeps['logger']['info']>(),
+ warn: vi.fn<IncomingAdmissionDeps['logger']['warn']>(),
+ }
+ const deps: IncomingAdmissionDeps = {
+ limits: { maxCount: 4, maxBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => 'zai',
+ getConversationByKey: async () => ({ modelSelections: { zai: 'glm-5.3-flash' } }),
+ resolveTaskModel: vi.fn<IncomingAdmissionDeps['resolveTaskModel']>(() => ({
+ provider: { getProviderType: () => 'zai' },
+ model: 'glm-5.3-flash',
+ })),
+ resolveImageInput: vi.fn<IncomingAdmissionDeps['resolveImageInput']>(() => ({
+ capability: CURATED_SUPPORTED,
+ })),
+ applySessionModelSelection: vi.fn<IncomingAdmissionDeps['applySessionModelSelection']>(),
+ dispatch: vi.fn<IncomingAdmissionDeps['dispatch']>(() => ({
+ success: true,
+ taskId: 't-1',
+ status: 'pending',
+ })),
+ logger,
+ ...overrides,
+ }
+ const spies: Spies = {
+ dispatch: deps.dispatch as Spies['dispatch'],
+ resolveImageInput: deps.resolveImageInput as Spies['resolveImageInput'],
+ applySessionModelSelection:
+ deps.applySessionModelSelection as Spies['applySessionModelSelection'],
+ resolveTaskModel: deps.resolveTaskModel as Spies['resolveTaskModel'],
+ info: deps.logger.info as Spies['info'],
+ warn: deps.logger.warn as Spies['warn'],
+ }
+ return { admit: createIncomingAdmission(deps), spies }
+}
+
+function refusalLogs(spies: Spies): Record<string, unknown>[] {
+ return spies.info.mock.calls
+ .map(call => call[0] as Record<string, unknown>)
+ .filter(fields => fields.event === 'message_image_refused')
+}
+
+describe('#654 incoming admission gate', () => {
+ it('passes a text-only message through with a caller-supplied imageModel cleared', async () => {
+ const { admit, spies } = makeAdmission()
+
+ // The caller claims a visual execution identity; only the gate may set one.
+ const response = await admit(message({ imageModel: { provider: 'zai', model: 'spoofed' } }))
+
+ expect(response).toMatchObject({ success: true, taskId: 't-1' })
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ const dispatched = spies.dispatch.mock.calls[0][0]
+ expect(dispatched.content).toBe('look at this')
+ expect(dispatched).toHaveProperty('imageModel', undefined)
+ // A text turn never consults the image catalog: the guard is a no-op here.
+ expect(spies.resolveImageInput).not.toHaveBeenCalled()
+ })
+
+ it('refuses an image on an unverified pair with LLM_IMAGE_INPUT_UNKNOWN and logs message_image_refused', async () => {
+ const { admit, spies } = makeAdmission({
+ resolveImageInput: vi.fn(() => ({ capability: { state: 'unknown' } })),
+ })
+
+ const response = await admit(imageMessage())
+
+ expect(response).toMatchObject({
+ success: false,
+ error: { code: 'LLM_IMAGE_INPUT_UNKNOWN', retryable: false, provider: 'zai' },
+ })
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ // Witness: the catalog WAS consulted and the refusal WAS recorded, so the
+ // zero dispatch above is a decision and not an unreached branch.
+ expect(refusalLogs(spies)).toEqual([
+ expect.objectContaining({
+ event: 'message_image_refused',
+ reason: 'model_unknown',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ code: 'LLM_IMAGE_INPUT_UNKNOWN',
+ }),
+ ])
+ })
+
+ it('admits an image on a supported pair and pins imageModel to the served pair', async () => {
+ const { admit, spies } = makeAdmission()
+
+ const response = await admit(imageMessage())
+
+ expect(response).toMatchObject({ success: true, taskId: 't-1' })
+ expect(spies.resolveImageInput).toHaveBeenCalledWith('zai', 'glm-5.3-flash')
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(spies.dispatch.mock.calls[0][0]).toMatchObject({
+ imageModel: { provider: 'zai', model: 'glm-5.3-flash' },
+ })
+ expect(refusalLogs(spies)).toHaveLength(0)
+ })
+
+ it('refuses an image when no task model can be resolved', async () => {
+ const { admit, spies } = makeAdmission({ resolveTaskModel: vi.fn(() => null) })
+
+ const response = await admit(imageMessage())
+
+ expect(response).toMatchObject({
+ success: false,
+ error: { code: 'LLM_IMAGE_INPUT_UNKNOWN', retryable: false },
+ })
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ expect(refusalLogs(spies)).toEqual([expect.objectContaining({ reason: 'no_model' })])
+ })
+
+ it('answers a piggybacked CAS conflict with LLM_MODEL_SELECTION_CONFLICT and the winning revision', async () => {
+ const applied: SetModelResult = {
+ ok: false,
+ reason: 'model_selection_conflict',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 7,
+ }
+ const { admit, spies } = makeAdmission({
+ applySessionModelSelection: vi.fn(async () => applied),
+ })
+
+ const response = await admit(
+ imageMessage({ model: 'glm-5.3-flash', modelSelectionRevision: 3 })
+ )
+
+ expect(response).toMatchObject({
+ success: false,
+ modelSelectionRevision: 7,
+ error: { code: 'LLM_MODEL_SELECTION_CONFLICT', retryable: true, provider: 'zai' },
+ })
+ // Witness: the CAS really ran, with the revision the client sent.
+ expect(spies.applySessionModelSelection).toHaveBeenCalledWith(
+ 'user-1',
+ 'agent-1',
+ 'chat-1',
+ 'glm-5.3-flash',
+ 3,
+ { skipWriteWhenEffective: true }
+ )
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ })
+
+ it('acknowledges an applied piggybacked selection with its revision (H1)', async () => {
+ const applySessionModelSelection = vi
+ .fn()
+ .mockResolvedValueOnce({
+ ok: true,
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 4,
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 5,
+ })
+ const { admit, spies } = makeAdmission({ applySessionModelSelection })
+
+ const first = await admit(imageMessage({ model: 'glm-5.3-flash', modelSelectionRevision: 3 }))
+ // The client adopts the acknowledged revision and sends it as the next CAS
+ // base — which is the whole point: without the ack it would still hold 3.
+ const second = await admit(
+ imageMessage({
+ messageId: 'msg-2',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: (first as MessageResponse).modelSelectionRevision,
+ })
+ )
+
+ expect(first).toMatchObject({ success: true, modelSelectionRevision: 4 })
+ expect(second).toMatchObject({ success: true, modelSelectionRevision: 5 })
+ expect(applySessionModelSelection.mock.calls[1][4]).toBe(4)
+ expect(spies.dispatch).toHaveBeenCalledTimes(2)
+ })
+
+ it('rejects an invalid revision with a conflict code and no revision', async () => {
+ const { admit, spies } = makeAdmission()
+
+ const response = await admit(
+ imageMessage({ model: 'glm-5.3-flash', modelSelectionRevision: -1 })
+ )
+
+ expect(response).toMatchObject({
+ success: false,
+ error: { code: 'LLM_MODEL_SELECTION_CONFLICT', retryable: true },
+ })
+ // No revision to adopt: the client must re-read the current selection.
+ expect('modelSelectionRevision' in response).toBe(false)
+ expect(spies.applySessionModelSelection).toHaveBeenCalledTimes(0)
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ expect(refusalLogs(spies)).toEqual([expect.objectContaining({ reason: 'invalid_revision' })])
+ })
+
+ it('reports a disallowed piggybacked model with LLM_MODEL_NOT_ALLOWED', async () => {
+ const { admit, spies } = makeAdmission({
+ applySessionModelSelection: vi.fn(async () => ({
+ ok: false as const,
+ reason: 'model_not_allowed' as const,
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ })),
+ })
+
+ const response = await admit(imageMessage({ model: 'glm-5.3-flash' }))
+
+ expect(response).toMatchObject({
+ success: false,
+ error: { code: 'LLM_MODEL_NOT_ALLOWED', retryable: false, provider: 'zai' },
+ })
+ expect('modelSelectionRevision' in response).toBe(false)
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ expect(refusalLogs(spies)).toEqual([
+ expect.objectContaining({ reason: 'model_not_allowed', code: 'LLM_MODEL_NOT_ALLOWED' }),
+ ])
+ })
+
+ it('ignores a piggybacked model on a text-only send and acknowledges without a revision (L8)', async () => {
+ const { admit, spies } = makeAdmission({
+ applySessionModelSelection: vi.fn(async () => ({
+ ok: false as const,
+ reason: 'model_not_allowed' as const,
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ })),
+ })
+
+ const response = await admit(message({ model: 'glm-5.3-flash' }))
+
+ // Fail-OPEN on the message: a rejected selection never drops the turn.
+ expect(response).toMatchObject({ success: true, taskId: 't-1' })
+ expect('modelSelectionRevision' in response).toBe(false)
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(spies.warn).toHaveBeenCalledWith(
+ expect.objectContaining({ event: 'message_model_ignored', reason: 'model_not_allowed' }),
+ 'Host runtime event'
+ )
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingDelivery.test.ts b/mcp-host/src/agent/__tests__/incomingDelivery.test.ts
new file mode 100644
index 000000000..ec25cc8f4
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingDelivery.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { ConversationManager } from '../../core/conversation/conversation'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { IncomingMessageHandler, type PendingTaskEntry } from '../../messageHandler'
+import { MessageQueue } from '../../queue/messageQueue'
+import { ResultStore } from '../../resultStore'
+import type { IncomingMessage, MessageResponse } from '../../server/types'
+import { IncomingDelivery } from '../incomingDelivery'
+import { applySessionModelSelection } from '../sessionModelSelection'
+
+const message: IncomingMessage = {
+ content: 'inspect',
+ channelType: 'rpc',
+ channelId: 'host',
+ hostRef: 'host',
+ sender: 'owner',
+ threadId: 'chat',
+ messageId: 'delivery',
+ timestamp: '2026-09-17T00:00:00Z',
+ model: 'vision-model',
+ modelSelectionRevision: 0,
+ attachments: [
+ { id: 'image', kind: 'image', mimeType: 'image/png', encoding: 'base64', dataBase64: 'YWJj' },
+ ],
+}
+
+function fixture() {
+ const queue = new MessageQueue()
+ const lifecycle = new TaskLifecycle()
+ queue.setLifecycle(lifecycle)
+ const conversations = new ConversationManager()
+ const deps = {
+ messageQueue: queue,
+ taskLifecycle: lifecycle,
+ agent: new EventEmitter() as never,
+ pendingTaskResults: new ResultStore<PendingTaskEntry>(60_000, entry => entry.storedAt),
+ getModel: () => 'vision-model',
+ sanitizeAttachments: (items: IncomingMessage['attachments']) => items,
+ }
+ const dispatch = (input: IncomingMessage) =>
+ new IncomingMessageHandler(input, deps).executeAsync()
+ const prepare = vi.fn(async (input: IncomingMessage): Promise<MessageResponse> => {
+ const selected = await applySessionModelSelection(
+ {
+ modelCfg: { provider: 'openai', name: 'vision-model' },
+ convManager: conversations,
+ allowlistView: {
+ allowlistAvailable: () => true,
+ allowedModels: () => new Map([['openai', [{ model: 'vision-model' }]]]),
+ },
+ },
+ input.sender,
+ input.channelId,
+ input.threadId,
+ input.model!,
+ input.modelSelectionRevision
+ )
+ if (!selected.ok)
+ return {
+ success: false,
+ error: {
+ code: selected.reason,
+ message: selected.reason,
+ retryable: false,
+ provider: 'openai',
+ },
+ }
+ return dispatch(input)
+ })
+ const coordinator = new IncomingDelivery()
+ return {
+ queue,
+ lifecycle,
+ prepare,
+ dispatch,
+ run: (input = message) =>
+ coordinator.run(
+ input,
+ queue,
+ () => prepare(input),
+ () => dispatch(input)
+ ),
+ }
+}
+
+describe('model CAS and delivery replay', () => {
+ it('replays an admitted delivery instead of applying its stale CAS again', async () => {
+ const f = fixture()
+ const original = await f.run()
+ expect(original.success).toBe(true)
+ expect(await f.run({ ...message })).toMatchObject({ success: true, taskId: original.taskId })
+ expect(f.prepare).toHaveBeenCalledTimes(1)
+ expect(f.queue.dequeue()?.id).toBe(original.taskId)
+ expect(f.queue.dequeue()).toBeNull()
+ })
+
+ it('coalesces two deliveries while the first selection write has not admitted a task yet', async () => {
+ const f = fixture()
+ const [a, b] = await Promise.all([f.run(), f.run({ ...message })])
+ expect(a.success).toBe(true)
+ expect(b).toEqual(a)
+ expect(f.prepare).toHaveBeenCalledTimes(1)
+ expect(f.queue.dequeue()?.id).toBe(a.taskId)
+ expect(f.queue.dequeue()).toBeNull()
+ })
+
+ it('uses the existing terminal replay after the original task completes', async () => {
+ const f = fixture()
+ const first = await f.run()
+ const task = f.queue.dequeue()!
+ task.result = { response: 'original answer', model: 'vision-model' }
+ f.queue.completeTask(task)
+ expect(await f.run()).toMatchObject({
+ success: true,
+ taskId: first.taskId,
+ response: 'original answer',
+ })
+ expect(f.prepare).toHaveBeenCalledTimes(1)
+ })
+
+ it('does not cache admission failures or suppress a distinct delivery', async () => {
+ const f = fixture()
+ expect((await f.run({ ...message, modelSelectionRevision: 9 })).success).toBe(false)
+ expect((await f.run(message)).success).toBe(true)
+ expect(
+ (await f.run({ ...message, messageId: 'second', modelSelectionRevision: 1 })).success
+ ).toBe(true)
+ expect(f.prepare).toHaveBeenCalledTimes(3)
+ })
+
+ it('does not coalesce delivery identities belonging to different senders', async () => {
+ const f = fixture()
+ const [a, b] = await Promise.all([f.run(), f.run({ ...message, sender: 'another-owner' })])
+ expect(a.success).toBe(true)
+ expect(b.success).toBe(true)
+ expect(a.taskId).not.toBe(b.taskId)
+ expect(f.prepare).toHaveBeenCalledTimes(2)
+ })
+
+ it('demonstrates the original failure when CAS is called before duplicate admission', async () => {
+ const f = fixture()
+ expect((await f.prepare(message)).success).toBe(true)
+ expect(await f.prepare(message)).toMatchObject({
+ success: false,
+ error: { code: 'model_selection_conflict' },
+ })
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts b/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts
new file mode 100644
index 000000000..d48d0b16c
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest'
+import {
+ INCOMING_IMAGE_MAX_COUNT,
+ validateIncomingImageAttachments,
+} from '../incomingImageAttachments'
+
+const limits = { maxCount: 2, maxBytes: 10 }
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])
+// Bytes exercise the ingress encoding/size contract and the declared-type
+// check; they are still not a decodable image.
+const image = {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: PNG_SIGNATURE.toString('base64'),
+}
+
+describe('visual input validation', () => {
+ it('preserves text-only messages and valid image bytes', () => {
+ expect(validateIncomingImageAttachments(undefined, limits)).toEqual({
+ ok: true,
+ attachments: undefined,
+ })
+ expect(validateIncomingImageAttachments([image], limits)).toEqual({
+ ok: true,
+ attachments: [image],
+ })
+ const jpeg = {
+ ...image,
+ mimeType: 'image/jpeg',
+ dataBase64: JPEG_SIGNATURE.toString('base64'),
+ }
+ expect(validateIncomingImageAttachments([jpeg], limits)).toEqual({
+ ok: true,
+ attachments: [jpeg],
+ })
+ })
+ it.each([
+ 'not-a-list',
+ [null],
+ [{ ...image, mimeType: 'image/gif' }],
+ [{ ...image, dataBase64: '' }],
+ [{ ...image, dataBase64: 'YQ=' }],
+ [{ ...image, dataBase64: 'YR==' }],
+ [image, image, image],
+ [image, { ...image, encoding: 'url' }],
+ ])('rejects the whole message for invalid input %#', raw => {
+ const result = validateIncomingImageAttachments(raw, limits)
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result).not.toHaveProperty('attachments')
+ })
+ describe('size limit (maxBytes = 10)', () => {
+ // A well-formed PNG of exactly `size` bytes, so a rejection can only come
+ // from the size checks: the shape, re-encoding and signature checks pass.
+ const pngOfSize = (size: number) =>
+ Buffer.concat([PNG_SIGNATURE, Buffer.alloc(size - PNG_SIGNATURE.length)]).toString('base64')
+ // The pre-decode bound on the base64 length for maxBytes = 10.
+ const encodedBound = Math.ceil(limits.maxBytes / 3) * 4
+ const SIZE_MESSAGE = 'An image exceeds the attachment size limit.'
+
+ it('accepts a PNG of exactly maxBytes (control)', () => {
+ const dataBase64 = pngOfSize(10)
+ expect(validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)).toEqual({
+ ok: true,
+ attachments: [{ ...image, dataBase64 }],
+ })
+ })
+
+ it.each([11, 12])(
+ 'rejects a %i-byte PNG on its decoded size (its base64 fits the pre-decode bound)',
+ size => {
+ const dataBase64 = pngOfSize(size)
+ // Precondition: only the decoded-size check can reject this input.
+ expect(dataBase64.length).toBeLessThanOrEqual(encodedBound)
+ const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
+ expect(result).toEqual({
+ ok: false,
+ error: {
+ code: 'LLM_INVALID_ATTACHMENT',
+ message: SIZE_MESSAGE,
+ retryable: false,
+ provider: 'unknown',
+ },
+ })
+ }
+ )
+
+ it('rejects a 13-byte PNG whose base64 already exceeds the pre-decode bound', () => {
+ const dataBase64 = pngOfSize(13)
+ expect(dataBase64.length).toBeGreaterThan(encodedBound)
+ const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
+ expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
+ })
+
+ it('rejects oversized input before decoding it', () => {
+ // Too long for the bound AND not canonical base64 (length is not a
+ // multiple of 4). Only the pre-decode length check can answer with the
+ // size message; without it the shape check answers "invalid base64".
+ const dataBase64 = 'A'.repeat(encodedBound + 5)
+ const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
+ expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
+ })
+ })
+
+ it('does not trust caller-supplied attachment metadata', () => {
+ expect(
+ validateIncomingImageAttachments(
+ [{ ...image, sourceTool: 'workflow_result', extra: true }],
+ limits
+ )
+ ).toEqual({ ok: true, attachments: [image] })
+ })
+
+ it('accepts a valid image whose base64 exceeds the old regex stack limit', () => {
+ // The grouped-quantifier base64 regex allocates one V8 backtrack frame per
+ // 4-character group and throws RangeError above ~4.47M characters. 3.5 MiB
+ // of image is ~4.67M characters, so this input reproduces that crash.
+ const bytes = Buffer.alloc(3_500_000)
+ PNG_SIGNATURE.copy(bytes, 0)
+ const dataBase64 = bytes.toString('base64')
+ expect(dataBase64.length).toBeGreaterThan(4_470_000)
+ const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], {
+ maxCount: 2,
+ maxBytes: 4_000_000,
+ })
+ expect(result.ok).toBe(true)
+ expect(result.ok && result.attachments?.[0]?.dataBase64.length).toBe(dataBase64.length)
+ })
+
+ it.each(['AAA', 'AAAA=AAA', 'A===', 'AA=A'])(
+ 'rejects the non-canonical base64 shape %s without decoding',
+ dataBase64 => {
+ const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], {
+ maxCount: 2,
+ maxBytes: 4_000_000,
+ })
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result.ok === false && result.error.message).toContain('invalid base64 data')
+ }
+ )
+
+ it('rejects bytes whose signature does not match the declared mime', () => {
+ const result = validateIncomingImageAttachments(
+ [{ ...image, mimeType: 'image/jpeg', dataBase64: PNG_SIGNATURE.toString('base64') }],
+ limits
+ )
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result.ok === false && result.error.message).toContain(
+ 'does not match its declared type'
+ )
+ })
+
+ it('admits 20 images per message and rejects the 21st', () => {
+ expect(INCOMING_IMAGE_MAX_COUNT).toBe(20)
+ const hostLimits = { maxCount: INCOMING_IMAGE_MAX_COUNT, maxBytes: 10 }
+ const batch = (count: number) =>
+ Array.from({ length: count }, (_, index) => ({ ...image, id: `image-${index + 1}` }))
+
+ const admitted = validateIncomingImageAttachments(batch(20), hostLimits)
+ expect(admitted.ok && admitted.attachments?.length).toBe(20)
+
+ const rejected = validateIncomingImageAttachments(batch(21), hostLimits)
+ expect(rejected).toMatchObject({ ok: false, error: { code: 'LLM_INVALID_ATTACHMENT' } })
+ expect(rejected.ok === false && rejected.error.message).toContain('Too many image attachments')
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/sessionModelSelection.test.ts b/mcp-host/src/agent/__tests__/sessionModelSelection.test.ts
index 5fe3894d3..44bc7cb09 100644
--- a/mcp-host/src/agent/__tests__/sessionModelSelection.test.ts
+++ b/mcp-host/src/agent/__tests__/sessionModelSelection.test.ts
@@ -75,7 +75,12 @@ describe('applySessionModelSelection (R2 shared core)', () => {
'claude-haiku-4-5'
)
- expect(result).toEqual({ ok: true, provider: 'claude', model: 'claude-haiku-4-5' })
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ modelSelectionRevision: 1,
+ })
// The selection landed on the exact row the next task reads.
const conv = await cm.getOrCreate(sessionKey)
@@ -173,7 +178,12 @@ describe('applySessionModelSelection (R2 shared core)', () => {
// The host-offered model still persists through the same subset view.
const ok = await applySessionModelSelection(deps, USER, HOST, CHAT, 'claude-opus-4-8')
- expect(ok).toEqual({ ok: true, provider: 'claude', model: 'claude-opus-4-8' })
+ expect(ok).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ modelSelectionRevision: 1,
+ })
})
it('applies under a threadless (default) session key, matching resolveTaskSessionKey', async () => {
@@ -198,3 +208,235 @@ describe('applySessionModelSelection (R2 shared core)', () => {
expect(conv.modelSelections).toEqual({ claude: 'claude-haiku-4-5' })
})
})
+
+describe('applySessionModelSelection — skipWriteWhenEffective (M3, message admission only)', () => {
+ const SKIP = { skipWriteWhenEffective: true }
+ let cm: ConversationManager
+
+ beforeEach(() => {
+ cm = new ConversationManager()
+ })
+
+ async function seedSelection(model: string): Promise<void> {
+ const conv = await cm.getOrCreate(sessionKey, {
+ userId: USER,
+ channelType: 'rpc',
+ channelId: HOST,
+ threadId: CHAT,
+ source: 'rpc',
+ })
+ const outcome = await cm.setModelSelection(conv, 'claude', model)
+ expect(outcome).toMatchObject({ applied: true, modelSelectionRevision: 1 })
+ }
+
+ it('admits the Host default without pinning it when the session has no selection', async () => {
+ const write = vi.spyOn(cm, 'setModelSelection')
+ const read = vi.spyOn(cm, 'getOrCreate')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-opus-4-8',
+ 0,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ modelSelectionRevision: 0,
+ })
+ // Witness: the session WAS read to make the decision.
+ expect(read).toHaveBeenCalledTimes(1)
+ expect(write).not.toHaveBeenCalled()
+ const conv = await cm.getOrCreate(sessionKey)
+ expect(conv.modelSelections ?? {}).toEqual({})
+ expect(conv.modelSelectionRevision).toBe(0)
+ })
+
+ it('admits the Host default without a revision too', async () => {
+ const write = vi.spyOn(cm, 'setModelSelection')
+ const read = vi.spyOn(cm, 'getOrCreate')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-opus-4-8',
+ undefined,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ modelSelectionRevision: 0,
+ })
+ expect(read).toHaveBeenCalledTimes(1)
+ expect(write).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ['without a revision', undefined],
+ ['with the current revision', 0],
+ ])(
+ 'without the option (POST /v1/runtime/model) an explicit pick of the Host default %s writes and pins it',
+ async (_label, expectedRevision) => {
+ const write = vi.spyOn(cm, 'setModelSelection')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-opus-4-8',
+ expectedRevision
+ )
+
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ modelSelectionRevision: 1,
+ })
+ expect(write).toHaveBeenCalledTimes(1)
+ const conv = await cm.getOrCreate(sessionKey)
+ // Pinned: a later Host default change does not move this chat.
+ expect(conv.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+ expect(conv.modelSelectionRevision).toBe(1)
+ }
+ )
+
+ it('without the option, re-picking the current explicit selection still bumps', async () => {
+ await seedSelection('claude-haiku-4-5')
+ const write = vi.spyOn(cm, 'setModelSelection')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-haiku-4-5',
+ 1
+ )
+
+ expect(result).toMatchObject({ ok: true, modelSelectionRevision: 2 })
+ expect(write).toHaveBeenCalledTimes(1)
+ })
+
+ it('admits the current explicit selection without a write', async () => {
+ await seedSelection('claude-haiku-4-5')
+ const write = vi.spyOn(cm, 'setModelSelection')
+ const read = vi.spyOn(cm, 'getOrCreate')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-haiku-4-5',
+ 1,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ modelSelectionRevision: 1,
+ })
+ expect(read).toHaveBeenCalledTimes(1)
+ expect(write).not.toHaveBeenCalled()
+ const conv = await cm.getOrCreate(sessionKey)
+ expect(conv.modelSelections).toEqual({ claude: 'claude-haiku-4-5' })
+ expect(conv.modelSelectionRevision).toBe(1)
+ })
+
+ it('still refuses a stale revision for the effective model, with the current revision', async () => {
+ await seedSelection('claude-haiku-4-5')
+ const write = vi.spyOn(cm, 'setModelSelection')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-haiku-4-5',
+ 0,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: false,
+ reason: 'model_selection_conflict',
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ modelSelectionRevision: 1,
+ })
+ expect(write).not.toHaveBeenCalled()
+ })
+
+ it('writes and bumps when the Host default is requested over a different explicit selection', async () => {
+ await seedSelection('claude-haiku-4-5')
+ const write = vi.spyOn(cm, 'setModelSelection')
+
+ const result = await applySessionModelSelection(
+ makeDeps(cm),
+ USER,
+ HOST,
+ CHAT,
+ 'claude-opus-4-8',
+ 1,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: true,
+ provider: 'claude',
+ model: 'claude-opus-4-8',
+ modelSelectionRevision: 2,
+ })
+ expect(write).toHaveBeenCalledTimes(1)
+ const conv = await cm.getOrCreate(sessionKey)
+ expect(conv.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+ })
+
+ it('keeps the allowlist check on the no-write path', async () => {
+ await seedSelection('claude-haiku-4-5')
+ const write = vi.spyOn(cm, 'setModelSelection')
+ const read = vi.spyOn(cm, 'getOrCreate')
+ // The operator narrowed the host subset: haiku is no longer selectable, even
+ // though it is the session's saved selection.
+ const deps: SessionModelSelectionDeps = {
+ ...makeDeps(cm),
+ allowlistView: hostSubsetAllowlistView(makeAllowlistView(), [
+ { provider: 'claude', model: 'claude-opus-4-8' },
+ ]),
+ }
+
+ const result = await applySessionModelSelection(
+ deps,
+ USER,
+ HOST,
+ CHAT,
+ 'claude-haiku-4-5',
+ 1,
+ SKIP
+ )
+
+ expect(result).toEqual({
+ ok: false,
+ reason: 'model_not_allowed',
+ provider: 'claude',
+ model: 'claude-haiku-4-5',
+ })
+ // The allowlist refuses before the session is even read.
+ expect(read).not.toHaveBeenCalled()
+ expect(write).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/stateMachine.imageSelection.test.ts b/mcp-host/src/agent/__tests__/stateMachine.imageSelection.test.ts
new file mode 100644
index 000000000..d3b6d2928
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/stateMachine.imageSelection.test.ts
@@ -0,0 +1,200 @@
+/**
+ * Issue #654 — a visual send is PINNED to the (provider, model) the user's UI
+ * validated. `IncomingMessage.imageModel` is server-owned; when it is present
+ * the task must run on exactly that pair or fail, never silently run the image
+ * under another model and never silently fall back to the Host default.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { runToolUseLoop } from '../../core/orchestration/toolUseLoop'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { MessageQueue } from '../../queue/messageQueue'
+import type { Task, TaskError } from '../../queue/types'
+import { AgentStateMachine } from '../stateMachine'
+import type { ResolvedTaskModel } from '../types'
+
+vi.mock('../../config', () => ({
+ config: {
+ devMode: true,
+ enableApproval: false,
+ enableNudge: false,
+ nudgeMaxIterations: 3,
+ devModelName: 'test-model',
+ devModelProvider: 'openai',
+ contextMaxTokens: 100000,
+ nativeTool: {
+ workspacePath: '/tmp',
+ shellTimeout: 5000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ },
+ },
+}))
+
+vi.mock('../../core/orchestration/toolUseLoop', () => ({
+ runToolUseLoop: vi.fn(),
+ validateToolLinkages: vi.fn(),
+}))
+
+function makeProvider(type: string) {
+ return {
+ completeSingleTurn: vi.fn(),
+ completeSingleTurnWithTools: vi.fn(),
+ getProviderType: vi.fn(() => type),
+ }
+}
+
+function taskFor(
+ channelId: string,
+ imageModel?: { provider: string; model: string }
+): Task & { responseCallback: ReturnType<typeof vi.fn> } {
+ const responseCallback = vi.fn(async () => {})
+ return {
+ id: `task-${channelId}-${Math.random().toString(36).slice(2, 6)}`,
+ source: 'channel',
+ sourceMessage: {
+ sender: 'user-1',
+ content: 'look at this',
+ channelType: 'rpc',
+ channelId,
+ messageId: 'msg-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'test-host',
+ ...(imageModel ? { imageModel } : {}),
+ },
+ priority: 'normal',
+ status: 'pending',
+ conversationHistory: [{ role: 'user', content: 'look at this', timestamp: new Date() }],
+ responseCallback,
+ createdAt: new Date(),
+ } as unknown as Task & { responseCallback: ReturnType<typeof vi.fn> }
+}
+
+const VISUAL = { provider: 'zai', model: 'glm-5.3-flash' }
+
+describe('#654 AgentStateMachine — visual selection pinning', () => {
+ let agent: AgentStateMachine
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ agent = new AgentStateMachine(new MessageQueue(), new TaskLifecycle(), { autoStart: false })
+ agent.setLLMProvider(makeProvider('openai') as never, 'host-default')
+ agent.setMcpManager({ getAllTools: () => [], callTool: vi.fn() } as never)
+ ;(runToolUseLoop as ReturnType<typeof vi.fn>).mockResolvedValue({
+ type: 'response',
+ content: 'ok',
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ })
+ })
+
+ it('drives the resolver with the snapshot, ignoring the session selection', async () => {
+ const provider = makeProvider('zai')
+ const resolver = vi.fn(
+ (selections: Record<string, string> | undefined): ResolvedTaskModel | null =>
+ selections?.[VISUAL.provider] === VISUAL.model
+ ? { provider: provider as never, model: VISUAL.model }
+ : null
+ )
+ agent.setTaskModelResolver(resolver)
+
+ // The session's own (older) selection must NOT be what a pinned image uses.
+ const cm = agent.getConversationManager()
+ const conv = await cm.getOrCreate('user-1:rpc:chat-visual:default')
+ cm.setModelSelection(conv, 'openai', 'gpt-4o')
+
+ await agent.executeTask(taskFor('chat-visual', VISUAL))
+
+ expect(resolver).toHaveBeenCalledWith({ [VISUAL.provider]: VISUAL.model })
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ expect(provider.getProviderType).toHaveBeenCalled()
+ })
+
+ it('runs normally when no snapshot is present (text path unchanged)', async () => {
+ const resolver = vi.fn(
+ (): ResolvedTaskModel | null => null // resolution unavailable → Host default
+ )
+ agent.setTaskModelResolver(resolver)
+
+ await agent.executeTask(taskFor('chat-text'))
+
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ })
+
+ it('fails the task when the resolver serves a DIFFERENT pair than the snapshot', async () => {
+ const other = makeProvider('openai')
+ agent.setTaskModelResolver(() => ({ provider: other as never, model: 'gpt-4o' }))
+ const task = taskFor('chat-mismatch', VISUAL)
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).not.toHaveBeenCalled()
+ expect(task.responseCallback).toHaveBeenCalledTimes(1)
+ const error = task.responseCallback.mock.calls[0][0].error as TaskError
+ expect(error.code).toBe('LLM_MODEL_NOT_AVAILABLE')
+ expect(error.retryable).toBe(false)
+ expect(error.provider).toBe('openai')
+ expect(error.message).toContain('zai/glm-5.3-flash')
+ })
+
+ it('fails closed when the pinned model cannot be resolved (no Host-default redirect)', async () => {
+ agent.setTaskModelResolver(() => null)
+ const task = taskFor('chat-unresolvable', VISUAL)
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).not.toHaveBeenCalled()
+ const error = task.responseCallback.mock.calls[0][0].error as TaskError
+ expect(error.code).toBe('LLM_MODEL_NOT_AVAILABLE')
+ expect(error.message).toContain('zai/glm-5.3-flash')
+ })
+
+ it('fails closed when the resolver THROWS for a pinned visual task', async () => {
+ agent.setTaskModelResolver(() => {
+ throw new Error('catalog unavailable')
+ })
+ const task = taskFor('chat-throw', VISUAL)
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).not.toHaveBeenCalled()
+ const error = task.responseCallback.mock.calls[0][0].error as TaskError
+ expect(error.code).toBe('LLM_MODEL_NOT_AVAILABLE')
+ expect(error.provider).toBe(VISUAL.provider)
+ })
+
+ it('keeps the existing Host-default fallback for a THROWING resolver on a text task', async () => {
+ agent.setTaskModelResolver(() => {
+ throw new Error('catalog unavailable')
+ })
+ const task = taskFor('chat-throw-text')
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ // Delivered as a normal response — the failed resolution must not surface
+ // as an error for a text-only task.
+ const delivered = task.responseCallback.mock.calls[0][0] as {
+ error?: TaskError
+ response?: string
+ }
+ expect(delivered.error).toBeUndefined()
+ expect(delivered.response).toBe('ok')
+ })
+
+ it('accepts a snapshot that matches the Host default when no resolver is wired', async () => {
+ const task = taskFor('chat-default', { provider: 'openai', model: 'host-default' })
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ })
+
+ it('ignores a malformed snapshot instead of pinning a partial pair', async () => {
+ const task = taskFor('chat-malformed')
+ ;(task.sourceMessage as { imageModel?: unknown }).imageModel = { provider: 'zai' }
+
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/taskExecutor.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
index b7a617a22..085468184 100644
--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts
+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
@@ -1,5 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { config as appConfig } from '../../config'
+import { LlmPortAdapter } from '../../core/adapters/llmPortAdapter'
import { ConversationManager } from '../../core/conversation/conversation'
import { LlmError, LlmErrorCode } from '../../core/errors'
import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
@@ -15,6 +16,9 @@ import type { Attachment, ChatMessage, MessageContentPart, TraceContextV1 } from
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
import { anthropicApiError } from '../../llm/__tests__/sdkErrorFixtures'
import { ClaudeProvider } from '../../llm/claude'
+import { FailoverEngine } from '../../llm/failover/engine'
+import type { LlmPolicy } from '../../llm/failover/types'
+import { OpenAIProvider } from '../../llm/openai'
import { PromptCache } from '../../llm/promptCache'
import { logger } from '../../logger'
import type { Task, TaskError, TaskSource } from '../../queue/types'
@@ -2073,3 +2077,165 @@ describe('adversarial review regressions', () => {
expect(runToolUseLoop).not.toHaveBeenCalled()
})
})
+
+/**
+ * #654 — the failover factory must build the SDK client with the model this
+ * attempt actually serves, and every failover attempt re-checks the image-input
+ * capability of its OWN pair before dispatching.
+ */
+describe('#654 failover identity + per-attempt image guard', () => {
+ const EVIDENCE = {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+ }
+
+ const POLICY: LlmPolicy = {
+ cooldownSeconds: 300,
+ triggerOn: ['insufficient_quota', 'auth', 'provider_unavailable', 'rate_limited'],
+ fallbacks: [{ provider: 'openai', model: 'gpt-4o' }],
+ }
+
+ function throttledProvider(type: string) {
+ return {
+ completeSingleTurn: vi.fn(),
+ completeSingleTurnWithTools: vi.fn(async () => {
+ throw new LlmError('429', type, LlmErrorCode.RateLimited, true)
+ }),
+ getProviderType: () => type,
+ classifyError: (err: unknown) => ({
+ code: err instanceof LlmError ? err.code : LlmErrorCode.ApiCallFailed,
+ retryable: true,
+ message: (err as Error).message,
+ }),
+ } as never
+ }
+
+ function conversationStub() {
+ return { id: 'conv-identity' } as never
+ }
+
+ function executorWith(overrides: Partial<TaskExecutorDeps>) {
+ const deps = createDeps(overrides)
+ return { deps, executor: new TaskExecutor(createTask(), deps) as never }
+ }
+
+ it('builds a SAME-provider fallback with the session model, and the SDK sends that model', async () => {
+ const create = vi.fn(async (_input: unknown) => ({
+ choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+ }))
+ // Mirrors `buildFallbackProvider`: the SDK model comes from `entry.model`.
+ const buildProvider = vi.fn(
+ (entry: { model: string }) =>
+ new OpenAIProvider({ chat: { completions: { create } } } as never, entry.model)
+ )
+ const { executor } = executorWith({
+ modelName: 'gpt-5.4-mini',
+ llmProvider: { getProviderType: () => 'openai' } as never,
+ failover: {
+ engine: new FailoverEngine(POLICY, { metricInc: () => {} }),
+ policy: POLICY,
+ buildProvider,
+ } as never,
+ })
+
+ // Text-only request, so the #654 image guard is a no-op here and no
+ // resolver is wired. The subject under test is the failover factory's model
+ // identity, not the guard.
+ const primaryPort = new LlmPortAdapter(throttledProvider('openai'), 'gpt-5.4-mini', 'openai')
+ const wrapped = (
+ executor as unknown as {
+ wrapFailoverPort: (
+ port: LlmPortAdapter,
+ conv: unknown
+ ) => { completeWithTools: (r: unknown) => Promise<unknown> }
+ }
+ ).wrapFailoverPort(primaryPort, conversationStub())
+
+ await wrapped.completeWithTools({ messages: [{ role: 'user', content: 'hi' }], tools: [] })
+
+ // The factory receives the EFFECTIVE entry (session model, not entry.model)…
+ expect(buildProvider).toHaveBeenCalledWith({ provider: 'openai', model: 'gpt-5.4-mini' })
+ // …and that is the model the SDK really requests (the pre-#654 bug sent 'gpt-4o').
+ expect(create).toHaveBeenCalledTimes(1)
+ expect((create.mock.calls[0]?.[0] as { model?: string }).model).toBe('gpt-5.4-mini')
+ })
+
+ it('re-checks the image capability of the FALLBACK pair before its SDK call', async () => {
+ const claudeCreate = vi.fn(async (_input: unknown) => ({
+ content: [{ type: 'text', text: 'ok' }],
+ stop_reason: 'end_turn',
+ usage: { input_tokens: 1, output_tokens: 1 },
+ }))
+ const claudeProvider = new ClaudeProvider(
+ { messages: { create: claudeCreate } } as never,
+ 'claude-haiku-4-5'
+ )
+ const buildProvider = vi.fn(() => claudeProvider)
+ const crossProviderPolicy: LlmPolicy = {
+ ...POLICY,
+ fallbacks: [{ provider: 'claude', model: 'claude-haiku-4-5' }],
+ }
+ const imageInput = vi.fn((provider: string) =>
+ provider === 'openai'
+ ? { capability: { state: 'supported', evidence: EVIDENCE } }
+ : { capability: { state: 'unsupported', evidence: EVIDENCE } }
+ )
+ const { executor } = executorWith({
+ modelName: 'gpt-5.4-mini',
+ llmProvider: { getProviderType: () => 'openai' } as never,
+ imageInput: imageInput as never,
+ failover: {
+ engine: new FailoverEngine(crossProviderPolicy, { metricInc: () => {} }),
+ policy: crossProviderPolicy,
+ buildProvider,
+ } as never,
+ })
+
+ // The primary pair MUST pass the image guard, otherwise the refusal happens
+ // before the failover engine ever considers the fallback — that is the
+ // separate "primary denial is terminal" behaviour. The primary dispatch
+ // here and the fallback adapter below read this same resolver, which is
+ // exactly what lets the test prove the fallback is re-checked.
+ const primaryPort = new LlmPortAdapter(
+ throttledProvider('openai'),
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ imageInput as never
+ )
+ const wrapped = (
+ executor as unknown as {
+ wrapFailoverPort: (
+ port: LlmPortAdapter,
+ conv: unknown
+ ) => { completeWithTools: (r: unknown) => Promise<unknown> }
+ }
+ ).wrapFailoverPort(primaryPort, conversationStub())
+
+ const imageMessage = {
+ role: 'user' as const,
+ content: 'look',
+ contentParts: [{ type: 'image' as const, mimeType: 'image/png' as const, data: 'QUJD' }],
+ }
+ let error: LlmError | undefined
+ try {
+ await wrapped.completeWithTools({ messages: [imageMessage], tools: [] })
+ } catch (err) {
+ error = err as LlmError
+ }
+
+ expect(buildProvider).toHaveBeenCalledWith({ provider: 'claude', model: 'claude-haiku-4-5' })
+ expect(error).toBeInstanceOf(LlmError)
+ expect(error?.code).toBe(LlmErrorCode.ImageInputUnsupported)
+ expect(error?.provider).toBe('claude')
+ // The incompatible fallback never reaches its SDK.
+ expect(claudeCreate).not.toHaveBeenCalled()
+ expect(imageInput).toHaveBeenCalledWith('claude', 'claude-haiku-4-5')
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/taskModelResolver.test.ts b/mcp-host/src/agent/__tests__/taskModelResolver.test.ts
index 04c7a47ef..dcc49b98f 100644
--- a/mcp-host/src/agent/__tests__/taskModelResolver.test.ts
+++ b/mcp-host/src/agent/__tests__/taskModelResolver.test.ts
@@ -103,9 +103,9 @@ describe('AgentStateMachine — per-task model resolution', () => {
// Seed two sessions on the same Host with different saved selections.
const cm = agent.getConversationManager()
const convA = await cm.getOrCreate(keyFor('chat-a'))
- cm.setModelSelection(convA, 'claude', 'model-a')
+ await cm.setModelSelection(convA, 'claude', 'model-a')
const convB = await cm.getOrCreate(keyFor('chat-b'))
- cm.setModelSelection(convB, 'claude', 'model-b')
+ await cm.setModelSelection(convB, 'claude', 'model-b')
await agent.executeTask(taskFor('chat-a'))
await agent.executeTask(taskFor('chat-b'))
@@ -131,7 +131,7 @@ describe('AgentStateMachine — per-task model resolution', () => {
const cm = agent.getConversationManager()
const conv = await cm.getOrCreate(keyFor('chat-x'))
- cm.setModelSelection(conv, 'claude', 'chosen-model')
+ await cm.setModelSelection(conv, 'claude', 'chosen-model')
// Simulate a key rotation between tasks (only mutates the default provider).
agent.setLLMProvider(makeProvider('openai') as never, 'host-default')
diff --git a/mcp-host/src/agent/incomingAdmission.ts b/mcp-host/src/agent/incomingAdmission.ts
new file mode 100644
index 000000000..62ec7224f
--- /dev/null
+++ b/mcp-host/src/agent/incomingAdmission.ts
@@ -0,0 +1,384 @@
+/**
+ * Issue #654 — the admission gate every incoming message crosses before a task
+ * exists.
+ *
+ * It lived inside `main.ts`, which runs `main()` on import and therefore cannot
+ * be loaded by a unit test. The gate decides whether a user's turn is accepted,
+ * refused, or accepted with a different model than the one that was asked for,
+ * so it is exactly the code that needs direct tests. Everything the gate reads
+ * from live process state arrives through {@link IncomingAdmissionDeps}; the
+ * decision logic here is pure.
+ */
+import { resolveImageInputCapability } from '@clerum/llm-providers'
+import { LlmErrorCode } from '../core/errors'
+import { chatTransportSupportsImageInput, imageInputDenialMessage } from '../llm/imageInput'
+import type { IncomingMessage, MessageResponse, SetModelResult } from '../server/types'
+import { serializeSessionKey } from '../session/types.js'
+import { validateIncomingImageAttachments } from './incomingImageAttachments'
+import type { SessionModelSelectionOptions } from './sessionModelSelection'
+
+/** The model a task would actually run on, as `resolveTaskModel` reports it. */
+interface AdmissionResolvedModel {
+ provider: { getProviderType: () => string }
+ model: string
+}
+
+/** What the live catalog knows about one (provider, model) pair. */
+interface AdmissionImageFacts {
+ capability?: unknown
+}
+
+/** Live process state the gate reads. Every member is injected so the gate is
+ * testable without booting the Host. */
+export interface IncomingAdmissionDeps {
+ limits: { maxCount: number; maxBytes: number }
+ /** False while the message queue is not initialized yet. */
+ queueReady: () => boolean
+ /** Non-null while the Host refuses new tasks (missing LLM key, …). */
+ degradedReason: () => { reason: string; message: string } | null | undefined
+ /** The Host's configured provider, for error envelopes that have no pair yet. */
+ hostProvider: () => string | undefined
+ getConversationByKey: (
+ key: string,
+ userId: string
+ ) => Promise<{ modelSelections?: Record<string, string> } | undefined>
+ resolveTaskModel: (
+ selections: Record<string, string> | undefined
+ ) => AdmissionResolvedModel | null | undefined
+ resolveImageInput: (provider: string, model: string) => AdmissionImageFacts | undefined
+ applySessionModelSelection: (
+ userSub: string,
+ hostRef: string,
+ chatId: string | undefined,
+ model: string,
+ expectedRevision?: number,
+ options?: SessionModelSelectionOptions
+ ) => Promise<SetModelResult>
+ dispatch: (
+ message: IncomingMessage,
+ options?: { async?: boolean }
+ ) => MessageResponse | Promise<MessageResponse>
+ logger: {
+ info: (obj: Record<string, unknown>, msg: string) => void
+ warn: (obj: Record<string, unknown>, msg: string) => void
+ }
+}
+
+export type IncomingAdmission = (
+ message: IncomingMessage,
+ options?: { async?: boolean }
+) => MessageResponse | Promise<MessageResponse>
+
+export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAdmission {
+ return function prepareIncomingMessage(
+ message: IncomingMessage,
+ options?: { async?: boolean }
+ ): MessageResponse | Promise<MessageResponse> {
+ const validated = validateIncomingImageAttachments(message.attachments, deps.limits)
+ if (!validated.ok) return { success: false, error: validated.error }
+
+ const hasAttachments = Boolean(validated.attachments?.length)
+
+ /** One structured line per refusal, so an operator can tell WHY a turn was
+ * dropped without the payload ever reaching the log. */
+ const logRefusal = (fields: {
+ provider: string
+ model: string | null
+ code: string
+ reason: string
+ }): void => {
+ deps.logger.info(
+ {
+ level: 'info',
+ event: 'message_image_refused',
+ userId: message.sender,
+ chatId: message.threadId ?? null,
+ ...fields,
+ },
+ 'Host runtime event'
+ )
+ }
+
+ if (
+ hasAttachments &&
+ message.modelSelectionRevision !== undefined &&
+ (!Number.isSafeInteger(message.modelSelectionRevision) || message.modelSelectionRevision < 0)
+ ) {
+ const provider = deps.hostProvider() ?? 'unknown'
+ logRefusal({
+ provider,
+ model: null,
+ code: LlmErrorCode.ModelSelectionConflict,
+ reason: 'invalid_revision',
+ })
+ // No `modelSelectionRevision` on the response: the client cannot adopt a
+ // revision we never read, so it must re-read the current selection.
+ return {
+ success: false,
+ error: {
+ code: LlmErrorCode.ModelSelectionConflict,
+ message: 'The model selection revision is invalid. Select the model again.',
+ retryable: true,
+ provider,
+ },
+ }
+ }
+ const normalizedMessage: IncomingMessage = {
+ ...message,
+ attachments: validated.attachments,
+ // Never accept a caller-supplied visual execution identity.
+ imageModel: undefined,
+ }
+ deps.logger.info(
+ {
+ channel: normalizedMessage.channelType,
+ attachmentCount: validated.attachments?.length ?? 0,
+ },
+ 'Received message'
+ )
+ let acceptedVisualSelection: Record<string, string> | undefined
+
+ if (!deps.queueReady()) {
+ return {
+ success: false,
+ error: {
+ code: LlmErrorCode.ApiCallFailed,
+ message: 'Message queue not initialized',
+ retryable: false,
+ provider: 'unknown',
+ },
+ }
+ }
+
+ // Refuse new tasks while the Host is degraded. Operator fixes the LLM
+ // Secret and the Host returns to ready within ~1 s — no restart.
+ const degraded = deps.degradedReason()
+ if (degraded) {
+ deps.logger.warn({ reason: degraded.reason }, '[Main] Refusing message — Host is degraded:')
+ return {
+ success: false,
+ error: {
+ code: 'LLM_KEY_MISSING',
+ message: degraded.message,
+ retryable: true,
+ provider: deps.hostProvider() ?? 'unknown',
+ },
+ }
+ }
+
+ const dispatchMessage = () => deps.dispatch(normalizedMessage, options)
+
+ /** Decide whether the model a task resolved to can read this message's
+ * images. The refusal is the exact response the Desktop receives, so the
+ * pre-write check and the per-task check cannot drift apart. */
+ const admitImageModel = (
+ resolved: AdmissionResolvedModel | null | undefined
+ ):
+ | { ok: true; pair: { provider: string; model: string } }
+ | { ok: false; response: MessageResponse } => {
+ if (!resolved) {
+ logRefusal({
+ provider: deps.hostProvider() ?? 'unknown',
+ model: null,
+ code: LlmErrorCode.ImageInputUnknown,
+ reason: 'no_model',
+ })
+ return {
+ ok: false,
+ response: {
+ success: false,
+ error: {
+ code: LlmErrorCode.ImageInputUnknown,
+ message: 'The image model is unavailable. Select a verified image-capable model.',
+ retryable: false,
+ provider: 'unknown',
+ },
+ },
+ }
+ }
+ const pair = { provider: resolved.provider.getProviderType(), model: resolved.model }
+ const facts = deps.resolveImageInput(pair.provider, pair.model)
+ const decision = resolveImageInputCapability(facts?.capability, {
+ transportSupported: chatTransportSupportsImageInput(pair.provider),
+ })
+ if (decision.state !== 'supported') {
+ const code =
+ decision.state === 'unknown'
+ ? LlmErrorCode.ImageInputUnknown
+ : LlmErrorCode.ImageInputUnsupported
+ logRefusal({ provider: pair.provider, model: pair.model, code, reason: decision.reason })
+ return {
+ ok: false,
+ response: {
+ success: false,
+ error: {
+ code,
+ message: imageInputDenialMessage(decision, pair),
+ retryable: false,
+ provider: pair.provider,
+ },
+ },
+ }
+ }
+ return { ok: true, pair }
+ }
+
+ const runHandler = (): MessageResponse | Promise<MessageResponse> => {
+ if (!hasAttachments) return dispatchMessage()
+ return (async () => {
+ const key = serializeSessionKey({
+ userId: normalizedMessage.sender,
+ channelType: normalizedMessage.channelType,
+ channelId: normalizedMessage.channelId || 'default',
+ threadId: normalizedMessage.threadId,
+ })
+ const conversation = await deps.getConversationByKey(key, normalizedMessage.sender)
+ // Checked again here even after the pre-write check below: this is the
+ // pair the task will actually run on, on every path into the handler.
+ const admission = admitImageModel(
+ deps.resolveTaskModel(acceptedVisualSelection ?? conversation?.modelSelections)
+ )
+ if (!admission.ok) return admission.response
+ normalizedMessage.imageModel = admission.pair
+ return dispatchMessage()
+ })()
+ }
+
+ // R2 — piggybacked per-session model. Because a suspended Host can't serve
+ // `POST /v1/runtime/model`, the desktop rides the user's pick on the message
+ // that wakes us. Apply it to THIS session and AWAIT the write BEFORE the task
+ // is created, so the per-task resolver (`stateMachine` taskModelResolver over
+ // `conv.modelSelections`) reads the row we just wrote. Fail-OPEN on the
+ // message: a rejected/degraded selection is logged and ignored, never dropping
+ // the user's turn (fail-closed only on the selection, inside the helper).
+ const piggybackModel = typeof message.model === 'string' ? message.model.trim() : ''
+ if (piggybackModel && normalizedMessage.channelType === 'rpc') {
+ // An image the requested model cannot read is refused BEFORE the
+ // selection is written: persisting it (and bumping the revision) for a
+ // turn that is then refused would leave the session on a model the user
+ // never got an answer from. Only the pair the selection resolves to is
+ // checked here; when resolution does not honour the requested model
+ // (not in the catalog, or a boot fallback serves another pair) the write
+ // gate and the per-task check below keep their existing verdicts.
+ const hostProvider = deps.hostProvider()
+ if (hasAttachments && hostProvider) {
+ const requested = deps.resolveTaskModel({ [hostProvider]: piggybackModel })
+ if (
+ !requested ||
+ (requested.provider.getProviderType() === hostProvider &&
+ requested.model === piggybackModel)
+ ) {
+ const admission = admitImageModel(requested)
+ if (!admission.ok) return admission.response
+ }
+ }
+ return (async () => {
+ // Hoisted out of the try so the ack below can report the revision the
+ // write produced. The send IS the write; its result travels back here.
+ let applied: SetModelResult | undefined
+ try {
+ applied = await deps.applySessionModelSelection(
+ normalizedMessage.sender,
+ normalizedMessage.channelId,
+ normalizedMessage.threadId,
+ piggybackModel,
+ hasAttachments ? message.modelSelectionRevision : undefined,
+ // An image send carries the model the client displays, not a user
+ // pick: asking for the effective model must not pin it. Text-only
+ // piggybacks and `POST /v1/runtime/model` keep writing.
+ hasAttachments ? { skipWriteWhenEffective: true } : undefined
+ )
+ if (!applied.ok) {
+ if (hasAttachments) {
+ const conflict = applied.reason === 'model_selection_conflict'
+ const code = conflict
+ ? LlmErrorCode.ModelSelectionConflict
+ : LlmErrorCode.ModelNotAllowed
+ logRefusal({
+ provider: applied.provider,
+ model: applied.model,
+ code,
+ reason: applied.reason,
+ })
+ return {
+ success: false,
+ // The winning revision, so the client can adopt it and retry
+ // without a separate read against a Host that may suspend again.
+ ...(conflict && applied.modelSelectionRevision !== undefined
+ ? { modelSelectionRevision: applied.modelSelectionRevision }
+ : {}),
+ error: {
+ code,
+ message: conflict
+ ? 'The model selection changed before this message was accepted. Select the model again.'
+ : 'The selected model is no longer allowed. Select a model again before sending the image.',
+ retryable: conflict,
+ provider: applied.provider,
+ },
+ }
+ }
+ deps.logger.warn(
+ {
+ level: 'warn',
+ event: 'message_model_ignored',
+ userId: normalizedMessage.sender,
+ chatId: normalizedMessage.threadId ?? null,
+ provider: applied.provider,
+ model: piggybackModel,
+ reason: applied.reason,
+ },
+ 'Host runtime event'
+ )
+ } else if (hasAttachments) {
+ acceptedVisualSelection = { [applied.provider]: applied.model }
+ }
+ } catch (error) {
+ applied = undefined
+ if (hasAttachments) {
+ deps.logger.warn({ err: error }, 'Visual model selection could not be confirmed')
+ logRefusal({
+ provider: deps.hostProvider() ?? 'unknown',
+ model: piggybackModel,
+ code: LlmErrorCode.ApiCallFailed,
+ reason: 'apply_failed',
+ })
+ // An unreachable selection store is an internal failure, not a
+ // statement about what this model can accept: the client may retry.
+ return {
+ success: false,
+ error: {
+ code: LlmErrorCode.ApiCallFailed,
+ message:
+ 'The image model selection could not be confirmed. Select the model again.',
+ retryable: true,
+ provider: deps.hostProvider() ?? 'unknown',
+ },
+ }
+ }
+ deps.logger.warn(
+ {
+ level: 'warn',
+ event: 'message_model_ignored',
+ userId: normalizedMessage.sender,
+ chatId: normalizedMessage.threadId ?? null,
+ provider: deps.hostProvider() ?? 'unknown',
+ model: piggybackModel,
+ reason: 'apply_failed',
+ err: error,
+ },
+ 'Host runtime event'
+ )
+ }
+ const response = await runHandler()
+ // A successful ack carries the revision only when the selection was
+ // actually persisted. Its ABSENCE after a piggyback is the contract for
+ // "the Host ignored your model".
+ return applied?.ok && applied.modelSelectionRevision !== undefined
+ ? { ...response, modelSelectionRevision: applied.modelSelectionRevision }
+ : response
+ })()
+ }
+
+ return runHandler()
+ }
+}
diff --git a/mcp-host/src/agent/incomingDelivery.ts b/mcp-host/src/agent/incomingDelivery.ts
new file mode 100644
index 000000000..3a0b32925
--- /dev/null
+++ b/mcp-host/src/agent/incomingDelivery.ts
@@ -0,0 +1,31 @@
+import { MessageQueue } from '../queue/messageQueue'
+import type { IncomingMessage, MessageResponse } from '../server/types'
+
+/**
+ * Model CAS precedes queue admission. Coalesce that preparation window so two
+ * re-forwards cannot mutate the selection twice. Once admitted, the queue's
+ * existing lifecycle-backed replay remains the only source of delivery history.
+ */
+export class IncomingDelivery {
+ private readonly preparing = new Map<string, Promise<MessageResponse>>()
+
+ run(
+ message: IncomingMessage,
+ queue: MessageQueue,
+ prepareAndDispatch: () => MessageResponse | Promise<MessageResponse>,
+ replay: () => MessageResponse | Promise<MessageResponse>
+ ): MessageResponse | Promise<MessageResponse> {
+ if (queue.hasAdmittedDelivery(message)) return replay()
+ const key = MessageQueue.deliveryKeyOf(message)
+ if (!key) return prepareAndDispatch()
+ const pending = this.preparing.get(key)
+ if (pending) return pending
+ // Register before invoking preparation, including synchronous re-entry.
+ const response = Promise.resolve().then(prepareAndDispatch)
+ const settled = response.finally(() => {
+ if (this.preparing.get(key) === settled) this.preparing.delete(key)
+ })
+ this.preparing.set(key, settled)
+ return settled
+ }
+}
diff --git a/mcp-host/src/agent/incomingImageAttachments.ts b/mcp-host/src/agent/incomingImageAttachments.ts
new file mode 100644
index 000000000..76a2aed0d
--- /dev/null
+++ b/mcp-host/src/agent/incomingImageAttachments.ts
@@ -0,0 +1,96 @@
+import type { Attachment } from '../core/types'
+import {
+ type ImageAttachmentMimeType,
+ isCanonicalBase64Shape,
+ isImageAttachmentMime,
+} from '../llm/imageInput'
+import type { TaskError } from '../queue/types'
+
+/**
+ * Images accepted in one incoming message. Kept separate from
+ * `CLERUM_ATTACHMENT_MAX_COUNT`, which caps the attachments a response returns.
+ * Must match COMPOSER_MAX_IMAGE_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.
+ * The combined size is bounded by the 10 MB JSON body limit of rpc-proxy and
+ * the host server, which carry the images inline.
+ */
+export const INCOMING_IMAGE_MAX_COUNT = 20
+
+export type IncomingImageValidation =
+ | { ok: true; attachments: Attachment[] | undefined }
+ | { ok: false; error: TaskError }
+
+/**
+ * First bytes every accepted encoding must start with. The declared media type
+ * decides how the provider serializes the image, so a declaration the bytes
+ * contradict is rejected here rather than forwarded upstream (CWE-345).
+ */
+const MIME_SIGNATURES: Readonly<Record<ImageAttachmentMimeType, Buffer>> = {
+ 'image/png': Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ 'image/jpeg': Buffer.from([0xff, 0xd8, 0xff]),
+}
+
+function bytesMatchDeclaredMime(bytes: Buffer, mimeType: ImageAttachmentMimeType): boolean {
+ const signature = MIME_SIGNATURES[mimeType]
+ return bytes.length >= signature.length && bytes.subarray(0, signature.length).equals(signature)
+}
+
+/** Reject the whole visual input rather than silently sending only its text. */
+export function validateIncomingImageAttachments(
+ raw: unknown,
+ limits: { maxCount: number; maxBytes: number }
+): IncomingImageValidation {
+ const reject = (message: string): IncomingImageValidation => ({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', message, retryable: false, provider: 'unknown' },
+ })
+ if (raw == null) return { ok: true, attachments: undefined }
+ if (!Array.isArray(raw)) return reject('Image attachments must be a list.')
+ if (!raw.length) return { ok: true, attachments: undefined }
+ if (raw.length > limits.maxCount)
+ return reject('Too many image attachments. Remove an image and try again.')
+ const attachments: Attachment[] = []
+ for (const item of raw) {
+ if (
+ !item ||
+ typeof item !== 'object' ||
+ Array.isArray(item) ||
+ item.kind !== 'image' ||
+ !isImageAttachmentMime(item.mimeType) ||
+ item.encoding !== 'base64' ||
+ typeof item.dataBase64 !== 'string' ||
+ typeof item.id !== 'string' ||
+ !item.id.trim()
+ ) {
+ return reject('Only PNG or JPEG images encoded as base64 are supported.')
+ }
+ const data = item.dataBase64
+ // Check length before decoding so validation cannot allocate an oversized
+ // binary buffer. Canonical base64 avoids ambiguous/partially decoded input.
+ if (data.length > Math.ceil(limits.maxBytes / 3) * 4)
+ return reject('An image exceeds the attachment size limit.')
+ if (!isCanonicalBase64Shape(data)) {
+ return reject('An image has invalid base64 data. Attach the original file again.')
+ }
+ const bytes = Buffer.from(data, 'base64')
+ if (bytes.length > limits.maxBytes) return reject('An image exceeds the attachment size limit.')
+ if (bytes.toString('base64') !== data)
+ return reject('An image has invalid base64 data. Attach the original file again.')
+ if (!bytesMatchDeclaredMime(bytes, item.mimeType))
+ return reject('An image does not match its declared type. Attach the original file again.')
+ attachments.push({
+ id: item.id,
+ kind: 'image',
+ mimeType: item.mimeType,
+ encoding: 'base64',
+ dataBase64: data,
+ ...(typeof item.filename === 'string' ? { filename: item.filename } : {}),
+ ...(typeof item.width === 'number' && Number.isFinite(item.width) && item.width > 0
+ ? { width: item.width }
+ : {}),
+ ...(typeof item.height === 'number' && Number.isFinite(item.height) && item.height > 0
+ ? { height: item.height }
+ : {}),
+ })
+ }
+ return { ok: true, attachments }
+}
diff --git a/mcp-host/src/agent/sessionModelSelection.ts b/mcp-host/src/agent/sessionModelSelection.ts
index 13556d05f..52259e432 100644
--- a/mcp-host/src/agent/sessionModelSelection.ts
+++ b/mcp-host/src/agent/sessionModelSelection.ts
@@ -13,10 +13,23 @@
* maps to the message `threadId`, so the next task's `resolveTaskSessionKey`
* reads this exact row. `getOrCreate` makes a set-before-first-message land the
* selection on a persisted session.
+ *
+ * #654 — the write is a durable compare-and-swap, and it is AWAITED before this
+ * function resolves: `expectedRevision` is the revision the caller read, a stale
+ * one is refused with `model_selection_conflict` (the row keeps the winner), and
+ * a legacy call without it still bumps the revision so a straggler is detectable.
+ * A resolution here therefore means "the selection is on disk", not "the op was
+ * queued" — which is what the caller's ACK asserts.
+ *
+ * With `skipWriteWhenEffective` (message admission only), a request for the
+ * session's current effective model (explicit selection, or the Host default
+ * when there is none) is admitted WITHOUT a write: it returns the current
+ * revision, after the same allowlist and revision checks.
*/
import type { AllowlistView } from '../config/allowlistCheck'
import { isModelAllowed } from '../config/modelResolution'
import type { ConversationManager } from '../core/conversation/conversation'
+import { logger } from '../logger'
import type { SetModelResult } from '../server/types'
import { serializeSessionKey } from '../session'
@@ -35,26 +48,37 @@ export interface SessionModelSelectionDeps {
convManager: ConversationManager
}
+export interface SessionModelSelectionOptions {
+ /** Admit a request for the session's current effective model WITHOUT
+ * writing it. Only the message-admission piggyback sets this: an image send
+ * carries the model the client displays, which is not a user pick. An
+ * explicit pick (`POST /v1/runtime/model`) leaves it unset, so choosing the
+ * Host default pins it and the chat stays on it if the default changes. */
+ skipWriteWhenEffective?: boolean
+}
+
export async function applySessionModelSelection(
deps: SessionModelSelectionDeps,
userSub: string,
hostRef: string,
chatId: string | undefined,
- model: string
+ model: string,
+ expectedRevision?: number,
+ options: SessionModelSelectionOptions = {}
): Promise<SetModelResult> {
const { modelCfg, allowlistView, convManager } = deps
const provider = modelCfg?.provider ?? 'unknown'
if (model.length > MAX_MODEL_LEN) {
- console.info(
- JSON.stringify({
- level: 'info',
+ logger.info(
+ {
event: 'set_model_rejected',
userId: userSub,
chatId,
provider,
reason: 'model_too_long',
modelLength: model.length,
- })
+ },
+ 'set_model_rejected'
)
return {
ok: false as const,
@@ -67,15 +91,15 @@ export async function applySessionModelSelection(
return { ok: false as const, reason: 'model_not_allowed' as const, provider, model }
}
if (!isModelAllowed(allowlistView, provider, model, modelCfg.name)) {
- console.info(
- JSON.stringify({
- level: 'info',
+ logger.info(
+ {
event: 'set_model_rejected',
userId: userSub,
chatId,
provider,
model,
- })
+ },
+ 'set_model_rejected'
)
return { ok: false as const, reason: 'model_not_allowed' as const, provider, model }
}
@@ -92,16 +116,102 @@ export async function applySessionModelSelection(
threadId: chatId,
source: 'rpc',
})
- convManager.setModelSelection(conversation, provider, model)
- console.info(
- JSON.stringify({
- level: 'info',
+ // With `skipWriteWhenEffective`, asking for the model the session ALREADY
+ // runs on is not a change, so it is not written. The effective model is the
+ // explicit selection for this provider when there is one, otherwise the Host
+ // default. Without this, every image send (which carries `model` = the model
+ // the client displays, usually the Host default) would pin the default as an
+ // explicit selection and bump the revision, so a later Host default change
+ // would no longer reach the session. The revision gate still applies: a stale `expectedRevision` is a
+ // conflict here exactly as it is in the store. The reported revision is the
+ // one on this process's conversation mirror; if another writer moved the
+ // durable row past it, the caller's next real write conflicts and carries
+ // the winner.
+ const currentRevision = conversation.modelSelectionRevision ?? 0
+ const effectiveModel = conversation.modelSelections?.[provider] ?? modelCfg.name
+ if (options.skipWriteWhenEffective === true && model === effectiveModel) {
+ if (expectedRevision !== undefined && expectedRevision !== currentRevision) {
+ logger.info(
+ {
+ event: 'set_model_conflict',
+ userId: userSub,
+ chatId,
+ provider,
+ modelSelectionRevision: currentRevision,
+ },
+ 'set_model_conflict'
+ )
+ return {
+ ok: false as const,
+ reason: 'model_selection_conflict' as const,
+ provider,
+ model,
+ modelSelectionRevision: currentRevision,
+ }
+ }
+ logger.info(
+ {
+ event: 'set_model_unchanged',
+ userId: userSub,
+ chatId,
+ provider,
+ model,
+ modelSelectionRevision: currentRevision,
+ },
+ 'set_model_unchanged'
+ )
+ return {
+ ok: true as const,
+ provider,
+ model,
+ modelSelectionRevision: currentRevision,
+ }
+ }
+ // #654 — the durable CAS write is AWAITED here: this promise resolving is what
+ // lets the route (and the piggybacked `message.model` path) ACK a selection.
+ // A losing CAS leaves the row and the in-RAM map on the winner's value and is
+ // reported as `model_selection_conflict` so the caller can re-read and retry
+ // with the revision that won, instead of silently reverting to the default.
+ const outcome = await convManager.setModelSelection(
+ conversation,
+ provider,
+ model,
+ expectedRevision
+ )
+ if (!outcome.applied) {
+ logger.info(
+ {
+ event: 'set_model_conflict',
+ userId: userSub,
+ chatId,
+ provider,
+ modelSelectionRevision: outcome.modelSelectionRevision,
+ },
+ 'set_model_conflict'
+ )
+ return {
+ ok: false as const,
+ reason: 'model_selection_conflict' as const,
+ provider,
+ model,
+ modelSelectionRevision: outcome.modelSelectionRevision,
+ }
+ }
+ logger.info(
+ {
event: 'set_model',
userId: userSub,
chatId,
provider,
model,
- })
+ modelSelectionRevision: outcome.modelSelectionRevision,
+ },
+ 'set_model'
)
- return { ok: true as const, provider, model }
+ return {
+ ok: true as const,
+ provider,
+ model,
+ modelSelectionRevision: outcome.modelSelectionRevision,
+ }
}
diff --git a/mcp-host/src/agent/stateMachine.ts b/mcp-host/src/agent/stateMachine.ts
index 762d5d261..018210c48 100644
--- a/mcp-host/src/agent/stateMachine.ts
+++ b/mcp-host/src/agent/stateMachine.ts
@@ -16,6 +16,7 @@ import { maybeWrapFailover } from '../core/adapters/failoverLlmPort'
import { AdapterStaticContext, LlmPortAdapter } from '../core/adapters/llmPortAdapter'
import { ConversationManager } from '../core/conversation/conversation'
import type { ConversationStore } from '../core/conversation/conversationStore'
+import { LlmErrorCode } from '../core/errors'
// Phase 6 imports
import type { ApprovalConfig } from '../core/extensions/approvalTypes'
import { PressureContextManager } from '../core/extensions/contextManager'
@@ -39,6 +40,7 @@ import type { ReapedSession } from '../db/worker/protocol'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import { isTerminal } from '../lifecycle/types'
import { SingleTurnProvider } from '../llm'
+import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { logger } from '../logger'
import { McpManager } from '../mcp'
@@ -149,6 +151,30 @@ type ApprovalDecisionBinding = {
sessionKey?: string
}
+/** Server-validated (provider, model) pair that a visual send is pinned to. */
+interface VisualSelectionSnapshot {
+ provider: string
+ model: string
+}
+
+/**
+ * #654 — read the server-owned visual selection snapshot from a queued task.
+ *
+ * `IncomingMessage.imageModel` is written by the server lane only after the
+ * image was validated, and the client-supplied copy is removed from the
+ * normalized message, so the value is authoritative rather than caller input.
+ * Values are still validated at runtime: anything malformed or absent means
+ * "no pinned selection" rather than a partial pin.
+ */
+function readVisualSelectionSnapshot(task: Task): VisualSelectionSnapshot | undefined {
+ const raw = task.sourceMessage?.imageModel
+ if (!raw || typeof raw !== 'object') return undefined
+ const { provider, model } = raw as { provider?: unknown; model?: unknown }
+ if (typeof provider !== 'string' || !provider) return undefined
+ if (typeof model !== 'string' || !model) return undefined
+ return { provider, model }
+}
+
/**
* Agent State Machine for task processing.
*/
@@ -204,6 +230,11 @@ export class AgentStateMachine extends EventEmitter {
// Null in dev/tests → no failover (byte-identical to today).
private failoverSupportProvider: FailoverSupportProvider | null = null
+ // #654 — live-catalog image-input capability resolver (provider, model →
+ // evidence + policy admission). Null in dev/tests/unwired hosts → images
+ // fail closed with LLM_IMAGE_INPUT_UNKNOWN; text-only turns are unchanged.
+ private imageInputResolver: ImageInputResolver | null = null
+
// Persistent core event emitter (Gap 3 resolution: bridges agent-level events to SimpleEventEmitter)
private coreEvents = new SimpleEventEmitter()
@@ -315,6 +346,18 @@ export class AgentStateMachine extends EventEmitter {
logger.info({ component: 'Agent' }, 'Failover support provider set')
}
+ /**
+ * #654 — inject the image-input capability resolver (built in `main.ts` over
+ * the live model catalog). When set, every task port and the manual
+ * `/compact` port check the capability of the exact (provider, model) they
+ * are about to send before dispatching an image-bearing request. Absent →
+ * images are rejected as unknown instead of being dropped silently.
+ */
+ setImageInputResolver(resolver: ImageInputResolver): void {
+ this.imageInputResolver = resolver
+ logger.info({ component: 'Agent' }, 'Image-input capability resolver set')
+ }
+
/**
* R5 — wrap the manual `/compact` port with provider-failover, mirroring
* `TaskExecutor.wrapFailoverPort`. Fallback entries get their own adapter with
@@ -337,11 +380,12 @@ export class AgentStateMachine extends EventEmitter {
policy: support.policy,
buildFallbackPort: index => {
const entry = support.policy.fallbacks[index]
- const provider = support.buildProvider(entry)
- if (!provider) return null
// R5.7 — same-provider fallback respects the session model; cross-provider
- // serves the fixed entry model.
+ // serves the fixed entry model. #654: resolve the effective model BEFORE
+ // building so SDK, token counter, usage event and image guard agree.
const servedModel = entry.provider === primaryProviderType ? primaryModel : entry.model
+ const provider = support.buildProvider({ ...entry, model: servedModel })
+ if (!provider) return null
const counter = createTokenCounter(provider, servedModel, {
offline: appConfig.tokenizerOffline,
})
@@ -353,7 +397,8 @@ export class AgentStateMachine extends EventEmitter {
this.usageStaticContext,
undefined,
counter,
- usage => this.conversationManager.recordSessionUsage(conv, usage)
+ usage => this.conversationManager.recordSessionUsage(conv, usage),
+ this.imageInputResolver ?? undefined
)
},
})
@@ -844,7 +889,11 @@ export class AgentStateMachine extends EventEmitter {
tokenCounter,
// Operator-triggered /compact still spends LLM tokens on this session —
// count them toward the session's lifetime totals (crit #2).
- usage => this.conversationManager.recordSessionUsage(conv, usage)
+ usage => this.conversationManager.recordSessionUsage(conv, usage),
+ // #654 — the compaction summary is a real provider attempt: an image in
+ // the message history must be checked against this pair's capability
+ // instead of being dropped by a serializer that cannot carry it.
+ this.imageInputResolver ?? undefined
)
// R5 — apply provider-failover to the manual /compact port too, so an
// eligible provider error during compaction switches to a fallback and the
@@ -1338,6 +1387,13 @@ export class AgentStateMachine extends EventEmitter {
return false
}
+ // #654 — a visual send carries the (provider, model) pair the user's UI
+ // validated when the image was accepted. That pair is server-owned
+ // (`IncomingMessage.imageModel`, populated after validation with the body
+ // already stripped) and it PINS this task: a later selection change must not
+ // redirect a queued image to another model.
+ const visualSelection = readVisualSelectionSnapshot(task)
+
let effectiveProvider = this.llmProvider
let effectiveModel = this.modelName
let effectiveContextWindow: number | undefined
@@ -1345,17 +1401,70 @@ export class AgentStateMachine extends EventEmitter {
try {
const sessionKey = resolveTaskSessionKey(task)
const existing = await this.conversationManager.getSessionByKeyAsync(sessionKey)
- const resolved = this.taskModelResolver(existing?.modelSelections)
+ const resolved = this.taskModelResolver(
+ visualSelection
+ ? { [visualSelection.provider]: visualSelection.model }
+ : existing?.modelSelections
+ )
if (resolved) {
effectiveProvider = resolved.provider
effectiveModel = resolved.model
effectiveContextWindow = resolved.contextWindowTokens
}
} catch (err) {
+ // A visual send is pinned: if resolution throws we must NOT silently run
+ // on the Host default, because that would send the validated image under
+ // a model the user never approved.
+ if (visualSelection) {
+ logger.warn(
+ { taskId: task.id, err, requested: visualSelection },
+ 'visual selection snapshot could not be resolved; failing the task'
+ )
+ this.handleTaskFailure(task, {
+ code: LlmErrorCode.ModelNotAvailable,
+ message:
+ `This message carries an image validated for ${visualSelection.provider}/${visualSelection.model}, ` +
+ 'but the host could not resolve that model. Reselect the model or remove the image and send again.',
+ retryable: false,
+ provider: visualSelection.provider,
+ })
+ return false
+ }
logger.warn({ err: err }, 'per-task model resolution failed; using Host default:')
}
}
+ if (visualSelection) {
+ const effectiveProviderType = effectiveProvider.getProviderType()
+ if (
+ effectiveProviderType !== visualSelection.provider ||
+ effectiveModel !== visualSelection.model
+ ) {
+ // NOTE: this pins the TASK's resolved model, not every physical attempt.
+ // A later policy-authorized failover may still serve another pair; that
+ // attempt is independently validated by the image-input guard in
+ // `LlmPortAdapter`, which checks the capability of the pair it sends.
+ logger.warn(
+ {
+ taskId: task.id,
+ requested: visualSelection,
+ effective: { provider: effectiveProviderType, model: effectiveModel },
+ },
+ 'visual selection snapshot could not be honored; failing the task instead of redirecting the image'
+ )
+ this.handleTaskFailure(task, {
+ code: LlmErrorCode.ModelNotAvailable,
+ message:
+ `This message carries an image validated for ${visualSelection.provider}/${visualSelection.model}, ` +
+ `but the host would run it on ${effectiveProviderType}/${effectiveModel}. ` +
+ 'Reselect the model or remove the image and send again.',
+ retryable: false,
+ provider: effectiveProviderType,
+ })
+ return false
+ }
+ }
+
const executor = this.createTaskExecutor(task, {
provider: effectiveProvider,
model: effectiveModel,
@@ -1410,6 +1519,7 @@ export class AgentStateMachine extends EventEmitter {
// R5 — resolved per task (reads live policy/engine from main.ts). Absent →
// no failover.
failover: this.failoverSupportProvider?.() ?? undefined,
+ imageInput: this.imageInputResolver ?? undefined,
onApprovalNeeded: (requestId, taskId, approval) => {
this.registerApproval(requestId, taskId, task, approval)
},
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 79d2f1c2d..d4d659da5 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -88,6 +88,7 @@ import { ApprovalExpiredError } from '../core/types'
import type { UsageContext } from '../core/types'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import type { SingleTurnProvider } from '../llm'
+import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { stampStableHashGauge } from '../llm/promptCacheMetrics'
import { isLlmProvider } from '../llm/registryCore'
@@ -236,6 +237,15 @@ export interface TaskExecutorDeps {
*/
failover?: ExecutorFailoverSupport
+ /**
+ * Issue #654 — live-catalog image-input capability lookup, keyed by the
+ * (provider, model) the adapter is about to send. Threaded to the primary
+ * port AND every failover adapter so the guard checks the pair that really
+ * runs. Absent → images fail closed with `LLM_IMAGE_INPUT_UNKNOWN` and
+ * text-only turns are unchanged.
+ */
+ imageInput?: ImageInputResolver
+
// Callbacks to coordinator
onApprovalNeeded: (requestId: string, taskId: string, approval: PendingApproval) => void
onComplete: (task: Task) => void
@@ -1280,12 +1290,14 @@ export class TaskExecutor {
policy: support.policy,
buildFallbackPort: index => {
const entry = support.policy.fallbacks[index]
- const provider = support.buildProvider(entry)
- if (!provider) return null
// R5.7 — a SAME-provider fallback (other key) respects the session's
// model; a CROSS-provider fallback serves its fixed entry model
- // (ignoring the session selection). Drives usage_events + the tokenizer.
+ // (ignoring the session selection). #654: resolve the effective model
+ // BEFORE building so the provider's SDK, the token counter, the usage
+ // event and the image guard all name the model that is really sent.
const servedModel = entry.provider === primaryProvider ? primaryModel : entry.model
+ const provider = support.buildProvider({ ...entry, model: servedModel })
+ if (!provider) return null
const counter = createTokenCounter(provider, servedModel, {
offline: appConfig.tokenizerOffline,
})
@@ -1302,7 +1314,8 @@ export class TaskExecutor {
if (conversation.contextBreakdown && usage.input_tokens > 0) {
conversation.contextBreakdown.totalInputTokens = usage.input_tokens
}
- }
+ },
+ this.deps.imageInput
)
},
})
@@ -1345,7 +1358,8 @@ export class TaskExecutor {
if (conversation.contextBreakdown && usage.input_tokens > 0) {
conversation.contextBreakdown.totalInputTokens = usage.input_tokens
}
- }
+ },
+ this.deps.imageInput
)
// R5 — wrap the primary port with provider-failover when a policy is wired.
diff --git a/mcp-host/src/agent/types.ts b/mcp-host/src/agent/types.ts
index 0f8ef8679..a22d7f4c6 100644
--- a/mcp-host/src/agent/types.ts
+++ b/mcp-host/src/agent/types.ts
@@ -21,6 +21,13 @@ export interface ExecutorFailoverSupport {
/**
* Build a fresh provider instance for a fallback entry from the LIVE
* ConfigStore keys; `null` when the entry's provider/credentials are absent.
+ *
+ * #654 — the caller passes the EFFECTIVE entry: `model` is already resolved
+ * to the model this attempt will serve (the session model for a same-provider
+ * fallback, the entry's own model otherwise). Implementations must build the
+ * provider with `entry.model` and must not substitute another model, so the
+ * SDK request, the token counter, the usage event and the image-input guard
+ * all name the same pair.
*/
buildProvider: (entry: FallbackEntry) => SingleTurnProvider | null
}
diff --git a/mcp-host/src/config/__tests__/modelResolution.test.ts b/mcp-host/src/config/__tests__/modelResolution.test.ts
index 57400301d..e1e60d925 100644
--- a/mcp-host/src/config/__tests__/modelResolution.test.ts
+++ b/mcp-host/src/config/__tests__/modelResolution.test.ts
@@ -76,12 +76,40 @@ describe('resolveSessionModel', () => {
})
describe('projectModels', () => {
+ it('projects model evidence intersected with the chat transport, never a provider-wide vision flag', () => {
+ const evidence = {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-01-01T00:00:00Z',
+ }
+ const catalog = view(true, {
+ zai: [
+ { model: 'glm-5.3', imageInput: { state: 'unsupported', evidence } },
+ { model: 'glm-5.3-flash', imageInput: { state: 'supported', evidence } },
+ ],
+ 'codex-subscription': [
+ { model: 'visual-model', imageInput: { state: 'supported', evidence } },
+ ],
+ })
+ expect(projectModels(catalog, 'zai', 'glm-5.3').models.map(m => m.imageInput)).toEqual([
+ { state: 'unsupported', reason: 'model_unsupported', evidence },
+ { state: 'supported', reason: 'supported', evidence },
+ ])
+ expect(
+ projectModels(catalog, 'codex-subscription', 'visual-model').models[0].imageInput
+ ).toEqual({ state: 'unsupported', reason: 'transport_unsupported', evidence })
+ })
it('projects enabled entries with optional metadata', () => {
expect(projectModels(view(true, CLAUDE_ALLOWLIST), 'claude', 'claude-opus-4-8')).toEqual({
degraded: false,
models: [
- { name: 'claude-opus-4-8', displayName: 'Opus 4.8', contextWindowTokens: 200000 },
- { name: 'claude-haiku-4-5' },
+ {
+ name: 'claude-opus-4-8',
+ imageInput: { state: 'unknown', reason: 'model_unknown' },
+ displayName: 'Opus 4.8',
+ contextWindowTokens: 200000,
+ },
+ { name: 'claude-haiku-4-5', imageInput: { state: 'unknown', reason: 'model_unknown' } },
],
})
})
@@ -89,7 +117,9 @@ describe('projectModels', () => {
it('degraded: collapses to the Host default only', () => {
expect(projectModels(view(false), 'claude', 'claude-opus-4-8')).toEqual({
degraded: true,
- models: [{ name: 'claude-opus-4-8' }],
+ models: [
+ { name: 'claude-opus-4-8', imageInput: { state: 'unknown', reason: 'model_unknown' } },
+ ],
})
})
})
@@ -125,7 +155,14 @@ describe('hostSubsetAllowlistView', () => {
// metadata still comes from the global entry.
expect(projectModels(v, 'claude', 'claude-opus-4-8')).toEqual({
degraded: false,
- models: [{ name: 'claude-opus-4-8', displayName: 'Opus 4.8', contextWindowTokens: 200000 }],
+ models: [
+ {
+ name: 'claude-opus-4-8',
+ imageInput: { state: 'unknown', reason: 'model_unknown' },
+ displayName: 'Opus 4.8',
+ contextWindowTokens: 200000,
+ },
+ ],
})
})
@@ -159,7 +196,12 @@ describe('hostSubsetAllowlistView', () => {
{ provider: 'claude', model: 'claude-haiku-4-5' },
])
expect(projectModels(v, 'claude', 'claude-opus-4-8').models).toEqual([
- { name: 'claude-opus-4-8', displayName: 'Opus 4.8', contextWindowTokens: 200000 },
+ {
+ name: 'claude-opus-4-8',
+ imageInput: { state: 'unknown', reason: 'model_unknown' },
+ displayName: 'Opus 4.8',
+ contextWindowTokens: 200000,
+ },
])
expect(isModelAllowed(v, 'claude', 'claude-haiku-4-5', 'claude-opus-4-8')).toBe(false)
// A saved selection on the now-unavailable model is surfaced as blocked.
@@ -178,9 +220,11 @@ describe('hostSubsetAllowlistView', () => {
{ provider: 'openai', model: 'gpt-6' },
])
expect(projectModels(v, 'claude', 'claude-opus-4-8').models).toEqual([
- { name: 'claude-haiku-4-5' },
+ { name: 'claude-haiku-4-5', imageInput: { state: 'unknown', reason: 'model_unknown' } },
+ ])
+ expect(projectModels(v, 'openai', 'gpt-5.4').models).toEqual([
+ { name: 'gpt-6', imageInput: { state: 'unknown', reason: 'model_unknown' } },
])
- expect(projectModels(v, 'openai', 'gpt-5.4').models).toEqual([{ name: 'gpt-6' }])
})
it('delegates allowlistAvailable so the degraded path is preserved (host default only)', () => {
@@ -192,7 +236,9 @@ describe('hostSubsetAllowlistView', () => {
expect(v.allowlistAvailable()).toBe(false)
expect(projectModels(v, 'claude', 'claude-opus-4-8')).toEqual({
degraded: true,
- models: [{ name: 'claude-opus-4-8' }],
+ models: [
+ { name: 'claude-opus-4-8', imageInput: { state: 'unknown', reason: 'model_unknown' } },
+ ],
})
// Degraded write gate: still only the Host default is permitted.
expect(isModelAllowed(v, 'claude', 'claude-opus-4-8', 'claude-opus-4-8')).toBe(true)
diff --git a/mcp-host/src/config/configStore.test.ts b/mcp-host/src/config/configStore.test.ts
index 221ccebd0..bd5f3fd8b 100644
--- a/mcp-host/src/config/configStore.test.ts
+++ b/mcp-host/src/config/configStore.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { register } from 'prom-client'
import { ALL_PROVIDERS, descriptorFor } from '../llm/registryCore'
+import { logger } from '../logger'
import {
CATALOG_REVISION_ANNOTATION,
CONNECTION_REVISION_ANNOTATION,
@@ -519,6 +520,55 @@ describe('ConfigStore — allowlist tier (R3)', () => {
store = null
})
+ it('observes a capability-only update and keeps malformed evidence as unknown without losing the model', async () => {
+ const errorSpy = vi.spyOn(logger, 'error').mockImplementation(() => {})
+ // No imageInput at all is an uncurated row, not corrupt data: not logged.
+ const initial = { openai: JSON.stringify([{ model: 'gpt-5.4' }]) }
+ const built = build({
+ provider: 'openai',
+ allowlistConfigMapName: ALLOWLIST_CM,
+ configMaps: { [ALLOWLIST_CM]: initial },
+ })
+ store = built.store
+ const changed = vi.fn()
+ store.onChange(changed)
+ await store.start()
+ changed.mockClear()
+ const handle = built.watch.active.get(ALLOWLIST_WATCH_KEY)
+ const imageInput = {
+ state: 'supported',
+ evidence: {
+ source: 'curated',
+ reference: 'evidence:visual-contract',
+ checkedAt: '2026-01-01T00:00:00Z',
+ },
+ }
+ handle!.emit('MODIFIED', {
+ metadata: { name: ALLOWLIST_CM },
+ data: { openai: JSON.stringify([{ model: 'gpt-5.4', imageInput }]) },
+ })
+ // Witness: both the absent and the valid capability were parsed and kept.
+ expect(store.allowedModels().get('openai')?.[0].imageInput).toEqual(imageInput)
+ expect(changed).toHaveBeenCalledWith(expect.objectContaining({ allowlistChanged: true }))
+ expect(errorSpy).toHaveBeenCalledTimes(0)
+ changed.mockClear()
+ const unsupportedClaim = { state: 'supported' }
+ handle!.emit('MODIFIED', {
+ metadata: { name: ALLOWLIST_CM },
+ data: { openai: JSON.stringify([{ model: 'gpt-5.4', imageInput: unsupportedClaim }]) },
+ })
+ expect(store.allowedModels().get('openai')).toEqual([
+ { model: 'gpt-5.4', imageInput: { state: 'unknown' } },
+ ])
+ expect(changed).toHaveBeenCalledWith(expect.objectContaining({ allowlistChanged: true }))
+ expect(errorSpy).toHaveBeenCalledTimes(1)
+ expect(errorSpy).toHaveBeenCalledWith(
+ { provider: 'openai', model: 'gpt-5.4' },
+ 'Allowlist entry has malformed imageInput; treating it as unknown'
+ )
+ errorSpy.mockRestore()
+ })
+
it('is disabled (no 4th watch, unavailable) when no CM name is configured', async () => {
const built = build({
provider: 'openai',
@@ -560,9 +610,17 @@ describe('ConfigStore — allowlist tier (R3)', () => {
expect(built.watch.watch).toHaveBeenCalledTimes(4)
expect(store.allowlistAvailable()).toBe(true)
expect(store.allowedModels().get('openai')).toEqual([
- { model: 'gpt-5.4', displayName: 'GPT 5.4', contextWindowTokens: 400000, vendor: 'OpenAI' },
+ {
+ imageInput: { state: 'unknown' },
+ model: 'gpt-5.4',
+ displayName: 'GPT 5.4',
+ contextWindowTokens: 400000,
+ vendor: 'OpenAI',
+ },
+ ])
+ expect(store.allowedModels().get('claude')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'claude-opus-4-8' },
])
- expect(store.allowedModels().get('claude')).toEqual([{ model: 'claude-opus-4-8' }])
expect(store.codexPolicyBinding()).toBeNull()
})
@@ -627,7 +685,9 @@ describe('ConfigStore — allowlist tier (R3)', () => {
store.onChange(handler)
await store.start()
- expect(store.allowedModels().get('openai')).toEqual([{ model: 'gpt-5.4' }])
+ expect(store.allowedModels().get('openai')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.4' },
+ ])
const handle = built.watch.active.get(ALLOWLIST_WATCH_KEY)
expect(handle).toBeDefined()
@@ -636,7 +696,10 @@ describe('ConfigStore — allowlist tier (R3)', () => {
data: { openai: JSON.stringify([{ model: 'gpt-5.4' }, { model: 'gpt-6' }]) },
})
- expect(store.allowedModels().get('openai')).toEqual([{ model: 'gpt-5.4' }, { model: 'gpt-6' }])
+ expect(store.allowedModels().get('openai')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.4' },
+ { imageInput: { state: 'unknown' }, model: 'gpt-6' },
+ ])
expect(handler).toHaveBeenCalledWith({
llmKeyChanged: false,
envChanged: false,
@@ -720,7 +783,7 @@ describe('ConfigStore — allowlist tier (R3)', () => {
})
it('isolates a provider key with invalid JSON — other keys still parse', async () => {
- const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+ const errorSpy = vi.spyOn(logger, 'error').mockImplementation(() => {})
// A distinctive raw value that must NOT surface in the log (a V8 SyntaxError
// can embed a snippet of the offending value — see the no-log-value policy).
const badValue = '{ not valid json SECRETish-snippet'
@@ -741,11 +804,16 @@ describe('ConfigStore — allowlist tier (R3)', () => {
// The CM is delivered (available), but the bad key is dropped.
expect(store.allowlistAvailable()).toBe(true)
expect(store.allowedModels().has('openai')).toBe(false)
- expect(store.allowedModels().get('claude')).toEqual([{ model: 'claude-opus-4-8' }])
+ expect(store.allowedModels().get('claude')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'claude-opus-4-8' },
+ ])
// The corrupt-key event logs the key at ERROR but never the raw value.
- const logged = errorSpy.mock.calls.flat().join(' ')
- expect(logged).toContain("allowlist key 'openai'")
+ const logged = JSON.stringify(errorSpy.mock.calls)
+ expect(errorSpy).toHaveBeenCalledWith(
+ { provider: 'openai', errName: 'SyntaxError' },
+ 'Allowlist JSON parse failed'
+ )
expect(logged).not.toContain('SECRETish-snippet')
errorSpy.mockRestore()
})
@@ -765,7 +833,9 @@ describe('ConfigStore — allowlist tier (R3)', () => {
store = built.store
await store.start()
- expect(store.allowedModels().get('openai')).toEqual([{ model: 'gpt-5.4' }])
+ expect(store.allowedModels().get('openai')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.4' },
+ ])
// Non-array value for a key is skipped entirely.
expect(store.allowedModels().has('zai')).toBe(false)
})
@@ -831,7 +901,9 @@ describe('ConfigStore — allowlist tier (R3)', () => {
})
store = built.store
await store.start()
- expect(store.allowedModels().get('codex-subscription')).toEqual([{ model: 'gpt-5.1' }])
+ expect(store.allowedModels().get('codex-subscription')).toEqual([
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.1' },
+ ])
expect(store.codexPolicyBinding()?.connectionKey).toBe('personal-pro')
expect(store.codexPolicyBinding()?.models).toEqual(['gpt-5.1'])
})
@@ -876,7 +948,13 @@ describe('ConfigStore — allowlist tier (R3)', () => {
credentialRevision: 2,
connectionKey: 'team-grok',
})
- expect(store.allowedModels().get('grok-subscription')).toEqual([{ model: 'grok-4.6' }])
+ // The allowlist entry carries no image-input evidence, so the store stamps the
+ // fail-closed `unknown` decision on it like every other entry (#654). The point
+ // of this assertion is the intersection with the connection's `models`, which
+ // drops `grok-4.5`.
+ expect(store.allowedModels().get('grok-subscription')).toEqual([
+ { model: 'grok-4.6', imageInput: { state: 'unknown' } },
+ ])
expect(store.codexPolicyBinding()?.catalogRevision).toBe(99)
})
@@ -964,8 +1042,8 @@ describe('ConfigStore — allowlist tier (R3)', () => {
expect(store.codexPolicyBinding()?.connectionKey).toBe('deployment-default')
expect(store.codexPolicyBinding()?.models).toBeUndefined()
expect(store.allowedModels().get('codex-subscription')).toEqual([
- { model: 'gpt-5.3-codex' },
- { model: 'gpt-5.1' },
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.3-codex' },
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.1' },
])
})
@@ -992,8 +1070,8 @@ describe('ConfigStore — allowlist tier (R3)', () => {
expect(store.codexPolicyBinding()?.connectionKey).toBe('personal-pro')
expect(store.codexPolicyBinding()?.models).toBeUndefined()
expect(store.allowedModels().get('codex-subscription')).toEqual([
- { model: 'gpt-5.3-codex' },
- { model: 'gpt-5.1' },
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.3-codex' },
+ { imageInput: { state: 'unknown' }, model: 'gpt-5.1' },
])
})
diff --git a/mcp-host/src/config/configStore.ts b/mcp-host/src/config/configStore.ts
index 3d1c8281d..3c859caa5 100644
--- a/mcp-host/src/config/configStore.ts
+++ b/mcp-host/src/config/configStore.ts
@@ -38,6 +38,7 @@ import {
toGrokPolicyBinding,
toPolicyBinding,
} from '@clerum/codex-catalog-projection'
+import { type ImageInputCapability, parseImageInputCapability } from '@clerum/llm-providers'
import type { GrokPolicyBinding } from '../llm/grokPolicyBinding'
import { assignedConnectionRef } from '../llm/hostLlmBinding'
import {
@@ -47,6 +48,7 @@ import {
descriptorFor,
primarySlot,
} from '../llm/registryCore'
+import { logger } from '../logger'
import type { ProviderCredentials } from '../types'
import { llmAllowlistMissingTotal } from './allowlistMetrics'
@@ -112,6 +114,7 @@ export interface ConfigStoreChange {
*/
export interface AllowedModelEntry {
model: string
+ imageInput?: ImageInputCapability
displayName?: string
contextWindowTokens?: number
vendor?: string
@@ -532,7 +535,7 @@ export class ConfigStore {
this.hostCm = new Map(Object.entries(data))
} catch (err) {
if (errorCode(err) === 404) return
- console.warn(`[ConfigStore] readNamespacedConfigMap ${name} failed:`, err)
+ logger.warn({ name: name, err: err }, '[ConfigStore] readNamespacedConfigMap failed:')
}
}
@@ -566,7 +569,7 @@ export class ConfigStore {
if (errorCode(err) === 404) {
return this.markAllowlistMissing()
}
- console.warn(`[ConfigStore] readNamespacedConfigMap ${name} failed:`, err)
+ logger.warn({ name: name, err: err }, '[ConfigStore] readNamespacedConfigMap failed:')
return false
}
}
@@ -617,31 +620,39 @@ export class ConfigStore {
// V8 SyntaxError can embed a snippet of the offending value. Mirrors the
// deliberate no-log-value policy in WRC's modelConfigHandler parser.
const errName = err instanceof Error ? err.name : 'ParseError'
- console.error(
- `[ConfigStore] allowlist key '${provider}' has invalid JSON (${errName}) — skipping`
- )
+ logger.error({ provider, errName }, 'Allowlist JSON parse failed')
continue
}
if (!Array.isArray(parsed)) {
- console.error(`[ConfigStore] allowlist key '${provider}' is not a JSON array — skipping`)
+ logger.error({ provider }, 'Allowlist must be a JSON array; skipping provider')
continue
}
let entries: AllowedModelEntry[] = []
for (const item of parsed) {
if (!item || typeof item !== 'object') {
- console.error(
- `[ConfigStore] allowlist key '${provider}' has a non-object entry — skipping it`
- )
+ logger.error({ provider }, 'Skipping non-object allowlist entry')
continue
}
const rec = item as Record<string, unknown>
if (typeof rec.model !== 'string' || rec.model.length === 0) {
- console.error(
- `[ConfigStore] allowlist key '${provider}' has an entry without a model — skipping it`
- )
+ logger.error({ provider }, 'Skipping allowlist entry without a model')
continue
}
const entry: AllowedModelEntry = { model: rec.model }
+ // An absent imageInput is a row nobody curated; a present one that does
+ // not parse is corrupt data. Both fail closed to `unknown`, but only the
+ // second is logged — without the value, which is ConfigMap content.
+ const parsedImageInput =
+ rec.imageInput === undefined
+ ? { state: 'unknown' as const }
+ : parseImageInputCapability(rec.imageInput)
+ if (parsedImageInput === null) {
+ logger.error(
+ { provider, model: rec.model },
+ 'Allowlist entry has malformed imageInput; treating it as unknown'
+ )
+ }
+ entry.imageInput = parsedImageInput ?? { state: 'unknown' }
if (typeof rec.displayName === 'string') entry.displayName = rec.displayName
// Optional, operator-declared: accept only a positive integer; drop
// NaN/Infinity/negatives silently (it is metadata, not part of the
@@ -694,7 +705,8 @@ export class ConfigStore {
if (!this.allowlistMissingWarned) {
this.allowlistMissingWarned = true
llmAllowlistMissingTotal.inc()
- console.warn(
+ logger.warn(
+ {},
'[ConfigStore] LLM allowlist ConfigMap absent — degraded-explicit mode (only the Host-configured model is treated as permitted)'
)
}
@@ -710,7 +722,7 @@ export class ConfigStore {
return (sec.data ?? {}) as Record<string, string>
} catch (err) {
if (errorCode(err) === 404) return null
- console.warn(`[ConfigStore] readNamespacedSecret ${name} failed:`, err)
+ logger.warn({ name: name, err: err }, '[ConfigStore] readNamespacedSecret failed:')
return null
}
}
@@ -736,7 +748,10 @@ export class ConfigStore {
this.watchAborters[tier] = undefined
if (this.stopped) return
const reason = err ? err.message : 'closed'
- console.log(`[ConfigStore] watch ${tier}/${name} ended (${reason}); reconnecting`)
+ logger.info(
+ { tier: tier, name: name, reason: reason },
+ '[ConfigStore] watch / ended (); reconnecting'
+ )
this.scheduleReconnect(tier)
}
@@ -751,7 +766,7 @@ export class ConfigStore {
})
.catch((err: unknown) => {
if (this.stopped) return
- console.warn(`[ConfigStore] watch ${tier}/${name} failed to start:`, err)
+ logger.warn({ tier: tier, name: name, err: err }, '[ConfigStore] watch / failed to start:')
this.scheduleReconnect(tier)
})
}
@@ -910,7 +925,7 @@ export class ConfigStore {
try {
h(change)
} catch (err) {
- console.warn('[ConfigStore] onChange handler threw:', err)
+ logger.warn({ err: err }, '[ConfigStore] onChange handler threw:')
}
}
}
@@ -988,6 +1003,8 @@ function allowlistMapsEqual(
const y = bEntries[i]
if (
x.model !== y.model ||
+ JSON.stringify(x.imageInput ?? { state: 'unknown' }) !==
+ JSON.stringify(y.imageInput ?? { state: 'unknown' }) ||
x.displayName !== y.displayName ||
x.contextWindowTokens !== y.contextWindowTokens ||
x.vendor !== y.vendor
diff --git a/mcp-host/src/config/modelResolution.ts b/mcp-host/src/config/modelResolution.ts
index 095a18962..c154c7d98 100644
--- a/mcp-host/src/config/modelResolution.ts
+++ b/mcp-host/src/config/modelResolution.ts
@@ -11,6 +11,8 @@
* not yet delivered (`allowlistAvailable() === false`), only the Host-configured
* default model is permitted — never fail-open, never brick an existing Host.
*/
+import { type ImageInputDecision, resolveImageInputCapability } from '@clerum/llm-providers'
+import { chatTransportSupportsImageInput } from '../llm/imageInput'
import type { HostAllowedModel } from '../types'
import type { AllowlistView } from './allowlistCheck'
import type { AllowedModelEntry } from './configStore'
@@ -66,6 +68,7 @@ export function hostSubsetAllowlistView(
/** One selectable model as projected to the desktop selector. */
export interface ModelWireEntry {
name: string
+ imageInput?: ImageInputDecision
displayName?: string
contextWindowTokens?: number
}
@@ -120,10 +123,10 @@ export function projectModels(
hostDefault: string
): { degraded: boolean; models: ModelWireEntry[] } {
if (!view.allowlistAvailable()) {
- return { degraded: true, models: [{ name: hostDefault }] }
+ return { degraded: true, models: [entryToWire({ model: hostDefault }, provider)] }
}
const entries = view.allowedModels().get(provider) ?? []
- return { degraded: false, models: entries.map(entryToWire) }
+ return { degraded: false, models: entries.map(entry => entryToWire(entry, provider)) }
}
/**
@@ -139,8 +142,13 @@ export function contextWindowForModel(
return entries.find(e => e.model === model)?.contextWindowTokens
}
-function entryToWire(e: AllowedModelEntry): ModelWireEntry {
- const wire: ModelWireEntry = { name: e.model }
+function entryToWire(e: AllowedModelEntry, provider: string): ModelWireEntry {
+ const wire: ModelWireEntry = {
+ name: e.model,
+ imageInput: resolveImageInputCapability(e.imageInput, {
+ transportSupported: chatTransportSupportsImageInput(provider),
+ }),
+ }
if (e.displayName) wire.displayName = e.displayName
if (e.contextWindowTokens) wire.contextWindowTokens = e.contextWindowTokens
return wire
diff --git a/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts
new file mode 100644
index 000000000..827b28cfb
--- /dev/null
+++ b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts
@@ -0,0 +1,706 @@
+/**
+ * Issue #654 — the image guard on the physical attempt boundary.
+ *
+ * Proves, per attempt: text-only requests never touch the resolver; an
+ * image-bearing request is refused BEFORE the provider SDK is called when the
+ * intersection is not affirmative; and a refusal is never handed to
+ * `provider.classifyError` (which is what would make it retryable).
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { ImageInputResolver } from '../../../llm/imageInput'
+import type { ClassifiedError, SingleTurnProvider } from '../../../llm/types'
+import { logger } from '../../../logger'
+import { LlmError, LlmErrorCode } from '../../errors'
+import { appendToolResults } from '../../orchestration/toolUseLoopMessages'
+import type { SystemPromptParts } from '../../reasoning/systemPrompt'
+import {
+ type ChatMessage,
+ FinishReason,
+ type MessageContentPart,
+ type ToolResult,
+} from '../../types'
+import { LlmPortAdapter } from '../llmPortAdapter'
+
+const CURATED_EVIDENCE = {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+
+function allow(capability: unknown): ImageInputResolver {
+ return () => ({ capability })
+}
+
+function imageMessage(role: ChatMessage['role'] = 'user'): ChatMessage {
+ return {
+ role,
+ content: 'look',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data: 'QUJD' }],
+ }
+}
+
+function textMessage(): ChatMessage {
+ return { role: 'user', content: 'hello' }
+}
+
+function parts(): SystemPromptParts {
+ return { stable: 'stable', context: 'context', stableHash: 'h1', contextHash: 'h2' }
+}
+
+function fakeProvider(
+ providerType: string,
+ opts: { cache?: boolean; cacheTools?: boolean } = {}
+): SingleTurnProvider & {
+ completeSingleTurn: ReturnType<typeof vi.fn>
+ completeSingleTurnWithTools: ReturnType<typeof vi.fn>
+ completeSingleTurnAndCache?: ReturnType<typeof vi.fn>
+ completeSingleTurnWithToolsAndCache?: ReturnType<typeof vi.fn>
+ classifyError: ReturnType<typeof vi.fn>
+} {
+ const ok = {
+ content: 'ok',
+ tool_calls: [],
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ finish_reason: FinishReason.Stop,
+ }
+ const provider = {
+ completeSingleTurn: vi.fn(async () => ok),
+ completeSingleTurnWithTools: vi.fn(async () => ok),
+ getProviderType: () => providerType,
+ classifyError: vi.fn(
+ (err: unknown): ClassifiedError => ({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: true,
+ message: (err as Error).message,
+ })
+ ),
+ } as unknown as SingleTurnProvider & Record<string, unknown>
+ if (opts.cache) provider.completeSingleTurnAndCache = vi.fn(async () => ok)
+ if (opts.cacheTools) provider.completeSingleTurnWithToolsAndCache = vi.fn(async () => ok)
+ return provider as never
+}
+
+async function expectDenied(
+ run: () => Promise<unknown>,
+ code: LlmErrorCode,
+ reason: string
+): Promise<LlmError> {
+ try {
+ await run()
+ } catch (err) {
+ expect(err).toBeInstanceOf(LlmError)
+ const llmError = err as LlmError
+ expect(llmError.code).toBe(code)
+ expect(llmError.retryable).toBe(false)
+ expect(llmError.message).toContain(reason)
+ return llmError
+ }
+ throw new Error('expected the guard to reject this attempt')
+}
+
+describe('#654 LlmPortAdapter image guard', () => {
+ it('never consults the resolver for a text-only request', async () => {
+ const provider = fakeProvider('openai')
+ const resolver = vi.fn<ImageInputResolver>(() => undefined)
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+
+ await adapter.complete({ messages: [textMessage()] })
+ await adapter.completeWithTools({ messages: [textMessage()], tools: [] })
+
+ expect(resolver).not.toHaveBeenCalled()
+ expect(provider.completeSingleTurn).toHaveBeenCalledTimes(1)
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ })
+
+ it('fails closed with LLM_IMAGE_INPUT_UNKNOWN when no catalog resolver is wired', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(provider, 'gpt-5.4-mini', 'openai')
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage()], tools: [] }),
+ LlmErrorCode.ImageInputUnknown,
+ 'not verified'
+ )
+
+ // The refusal happens BEFORE the SDK call and is NOT reclassified by the
+ // provider (which would flip it to retryable=true and re-open retries).
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ expect(provider.classifyError).not.toHaveBeenCalled()
+ })
+
+ it('dispatches a supported tool-bearing request and keeps the image part', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await adapter.completeWithTools({ messages: [imageMessage()], tools: [] })
+
+ const [messages] = provider.completeSingleTurnWithTools.mock.calls[0]
+ expect(messages[0].contentParts).toHaveLength(1)
+ expect(messages[0].contentParts[0].type).toBe('image')
+ })
+
+ it('refuses the tool-less plain path that would drop the image (OpenAI family)', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expectDenied(
+ () => adapter.complete({ messages: [imageMessage()] }),
+ LlmErrorCode.ImageInputUnsupported,
+ 'cannot carry images'
+ )
+ expect(provider.completeSingleTurn).not.toHaveBeenCalled()
+ })
+
+ it('refuses an image on a role the family cannot carry', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage('tool')], tools: [] }),
+ LlmErrorCode.ImageInputUnsupported,
+ 'cannot carry images'
+ )
+ })
+
+ it('allows the cache-aware path where the serializer preserves images (Claude)', async () => {
+ const provider = fakeProvider('claude', { cache: true, cacheTools: true })
+ const resolver = vi.fn(allow({ state: 'supported', evidence: CURATED_EVIDENCE }))
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'claude-sonnet-4-6',
+ 'claude',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+
+ await adapter.complete({ messages: [imageMessage()], systemPromptParts: parts() })
+ await adapter.completeWithTools({
+ messages: [imageMessage()],
+ tools: [],
+ systemPromptParts: parts(),
+ })
+
+ expect(provider.completeSingleTurnAndCache).toHaveBeenCalledTimes(1)
+ expect(provider.completeSingleTurnWithToolsAndCache).toHaveBeenCalledTimes(1)
+ // The resolver is asked about the pair this adapter really sends.
+ expect(resolver).toHaveBeenCalledWith('claude', 'claude-sonnet-4-6')
+ })
+
+ it('refuses Claude plain too: that variant rebuilds role/content', async () => {
+ const provider = fakeProvider('claude', { cache: true, cacheTools: true })
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'claude-sonnet-4-6',
+ 'claude',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expectDenied(
+ () => adapter.complete({ messages: [imageMessage()] }),
+ LlmErrorCode.ImageInputUnsupported,
+ 'cannot carry images'
+ )
+ expect(provider.completeSingleTurn).not.toHaveBeenCalled()
+ })
+
+ it('reports model_unsupported for a known text-only model', async () => {
+ const provider = fakeProvider('zai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'glm-5.3',
+ 'zai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'unsupported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage()], tools: [] }),
+ LlmErrorCode.ImageInputUnsupported,
+ 'not supported by zai/glm-5.3'
+ )
+ expect(provider.classifyError).not.toHaveBeenCalled()
+ })
+
+ it('treats a pair missing from the catalog as unknown (never as allow)', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => undefined
+ )
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage()], tools: [] }),
+ LlmErrorCode.ImageInputUnknown,
+ 'not verified'
+ )
+ })
+
+ it('degrades to unknown when the catalog resolver throws, without failing text', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => {
+ throw new Error('catalog unavailable')
+ }
+ )
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage()], tools: [] }),
+ LlmErrorCode.ImageInputUnknown,
+ 'not verified'
+ )
+ // A text-only turn on the same adapter is unaffected by the broken catalog.
+ await adapter.completeWithTools({ messages: [textMessage()], tools: [] })
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ })
+
+ it('refuses Codex transport until #650 lands, even with curated evidence', async () => {
+ const provider = fakeProvider('codex-subscription')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.3-codex',
+ 'codex-subscription',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages: [imageMessage()], tools: [] }),
+ LlmErrorCode.ImageInputUnsupported,
+ 'cannot carry images'
+ )
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ })
+
+ it('refuses a malformed base64 image part with LLM_INVALID_ATTACHMENT before consulting the resolver', async () => {
+ const provider = fakeProvider('openai')
+ const resolver = vi.fn(allow({ state: 'supported', evidence: CURATED_EVIDENCE }))
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+
+ await expectDenied(
+ () =>
+ adapter.completeWithTools({
+ messages: [
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data: 'not base64!' }],
+ },
+ ],
+ tools: [],
+ }),
+ LlmErrorCode.InvalidAttachment,
+ 'unsupported image format or encoding'
+ )
+ // The shape check is the first gate: neither the catalog nor the SDK is
+ // reached, so a malformed part can never become a provider round-trip.
+ expect(resolver).toHaveBeenCalledTimes(0)
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(0)
+ })
+
+ it('refuses a non PNG/JPEG mime with LLM_INVALID_ATTACHMENT', async () => {
+ const provider = fakeProvider('openai')
+ const resolver = vi.fn(allow({ state: 'supported', evidence: CURATED_EVIDENCE }))
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+
+ await expectDenied(
+ () =>
+ adapter.completeWithTools({
+ messages: [
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'image', mimeType: 'image/gif' as never, data: 'QUJD' }],
+ },
+ ],
+ tools: [],
+ }),
+ LlmErrorCode.InvalidAttachment,
+ 'unsupported image format or encoding'
+ )
+ expect(resolver).toHaveBeenCalledTimes(0)
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(0)
+ })
+
+ it('dispatches a 5 MiB canonical image part without RangeError', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+ // Tool screenshots are not bounded by the admission limit, so the adapter
+ // sees sizes the grouped-quantifier regex could not scan.
+ const data = Buffer.alloc(5 * 1024 * 1024).toString('base64')
+ expect(data.length).toBeGreaterThan(4_470_000)
+
+ await adapter.completeWithTools({
+ messages: [
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data }],
+ },
+ ],
+ tools: [],
+ })
+
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ const [messages] = provider.completeSingleTurnWithTools.mock.calls[0]
+ expect(messages[0].contentParts[0].data).toBe(data)
+ })
+
+ it('withholds tool screenshots from an unverified model and still dispatches the text turn', async () => {
+ const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
+ try {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow(undefined)
+ )
+ const request = {
+ messages: [
+ textMessage(),
+ { role: 'tool' as const, content: 'captured', tool_call_id: 'tc_1', name: 'shot' },
+ {
+ role: 'user' as const,
+ content: 'Here are the screenshots from the tool results above.',
+ imageOrigin: 'tool_result' as const,
+ contentParts: [
+ {
+ type: 'text' as const,
+ text: 'Here are the screenshots from the tool results above.',
+ },
+ { type: 'image' as const, mimeType: 'image/png' as const, data: 'QUJD' },
+ ],
+ },
+ ],
+ tools: [],
+ }
+
+ await adapter.completeWithTools(request)
+
+ // Witness: the turn was dispatched. An unverified model must not turn a
+ // screenshot tool call into a task failure.
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ const [messages] = provider.completeSingleTurnWithTools.mock.calls[0]
+ expect(messages[2].contentParts).toBeUndefined()
+ expect(messages[2].imageOrigin).toBeUndefined()
+ expect(messages[2].content).toContain('were not forwarded')
+ expect(messages[2].content).toContain('Here are the screenshots from the tool results above.')
+ // The text-only messages are passed through by identity.
+ expect(messages[0]).toBe(request.messages[0])
+ expect(messages[1]).toBe(request.messages[1])
+ // Immutability witness: a later failover attempt on a supported pair must
+ // still see the image, so the caller's array is never rewritten in place.
+ expect(request.messages[2].contentParts).toHaveLength(2)
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.objectContaining({ withheldImages: 1, reason: 'model_unknown' }),
+ 'tool screenshots withheld: model has no affirmative image-input evidence'
+ )
+ } finally {
+ warnSpy.mockRestore()
+ }
+ })
+
+ it('keeps refusing a user-attached image on an unverified model even when tool screenshots are present', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow(undefined)
+ )
+
+ await expectDenied(
+ () =>
+ adapter.completeWithTools({
+ messages: [
+ imageMessage(),
+ {
+ role: 'user',
+ content: 'Here are the screenshots from the tool results above.',
+ imageOrigin: 'tool_result',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data: 'QUJD' }],
+ },
+ ],
+ tools: [],
+ }),
+ LlmErrorCode.ImageInputUnknown,
+ 'not verified'
+ )
+
+ // Witness: the refusal is the typed terminal error above, raised before the
+ // SDK call. One tool-originated message never licenses a user attachment.
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ expect(provider.classifyError).not.toHaveBeenCalled()
+ })
+})
+
+describe('#669 LlmPortAdapter malformed tool screenshots', () => {
+ const LINE_WRAPPED = 'QUJD\nRUZH'
+ const DATA_URL = 'data:image/png;base64,QUJD'
+ const NOTICE_SUFFIX =
+ 'screenshot(s) returned by tool results were not forwarded: invalid image encoding]'
+
+ function screenshotResult(id: string, data: string): ToolResult {
+ return {
+ tool_call_id: `tc_${id}`,
+ name: 'take_screenshot',
+ content: `captured ${id}`,
+ is_error: false,
+ attachments: [
+ {
+ id: `shot-${id}`,
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: data,
+ },
+ ],
+ }
+ }
+
+ /** Builds the turn exactly as the tool-use loop does, via `appendToolResults`. */
+ function toolTurn(images: string[]): ChatMessage[] {
+ const messages: ChatMessage[] = [textMessage()]
+ appendToolResults(
+ messages,
+ images.map((data, index) => screenshotResult(String(index), data)),
+ []
+ )
+ return messages
+ }
+
+ function adapterFor(
+ provider: ReturnType<typeof fakeProvider>,
+ resolver: ImageInputResolver
+ ): LlmPortAdapter {
+ return new LlmPortAdapter(
+ provider,
+ 'gpt-5.4-mini',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+ }
+
+ function imageParts(messages: ChatMessage[]): MessageContentPart[] {
+ return messages.flatMap(message =>
+ (message.contentParts ?? []).filter(part => part.type === 'image')
+ )
+ }
+
+ it('dispatches a turn with malformed tool screenshots on a model with no image evidence', async () => {
+ const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
+ try {
+ const provider = fakeProvider('openai')
+ const adapter = adapterFor(provider, allow(undefined))
+ const messages = toolTurn([LINE_WRAPPED, DATA_URL])
+ // Precondition: the real builder forwards the malformed data unnormalized.
+ expect(imageParts(messages)).toHaveLength(2)
+
+ await adapter.completeWithTools({ messages, tools: [] })
+
+ // Liveness witness: the turn reached the provider exactly once.
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ const [dispatched] = provider.completeSingleTurnWithTools.mock.calls[0] as [ChatMessage[]]
+ expect(imageParts(dispatched)).toHaveLength(0)
+ const carrier = dispatched[dispatched.length - 1]
+ expect(carrier.contentParts).toBeUndefined()
+ expect(carrier.imageOrigin).toBeUndefined()
+ expect(carrier.content).toContain(`[2 ${NOTICE_SUFFIX}`)
+ expect(JSON.stringify(dispatched)).not.toContain('RUZH')
+ expect(JSON.stringify(dispatched)).not.toContain('data:image/png')
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ component: 'LlmPortAdapter',
+ method: 'completeWithTools',
+ count: 2,
+ }),
+ 'tool screenshots removed before provider dispatch: invalid image encoding'
+ )
+ expect(JSON.stringify(warnSpy.mock.calls)).not.toContain('RUZH')
+ } finally {
+ warnSpy.mockRestore()
+ }
+ })
+
+ it('drops malformed tool screenshots but forwards a canonical one on an image-capable model', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = adapterFor(provider, allow({ state: 'supported', evidence: CURATED_EVIDENCE }))
+ const messages = toolTurn([LINE_WRAPPED, 'QUJD', DATA_URL])
+
+ await adapter.completeWithTools({ messages, tools: [] })
+
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ const [dispatched] = provider.completeSingleTurnWithTools.mock.calls[0] as [ChatMessage[]]
+ expect(imageParts(dispatched)).toEqual([{ type: 'image', mimeType: 'image/png', data: 'QUJD' }])
+ const carrier = dispatched[dispatched.length - 1]
+ expect(carrier.imageOrigin).toBe('tool_result')
+ expect(carrier.content).toContain(`[2 ${NOTICE_SUFFIX}`)
+ // Providers render `contentParts` instead of `content` when parts are
+ // present, so the notice must also travel as a text part.
+ expect(carrier.contentParts?.at(-1)).toEqual({
+ type: 'text',
+ text: `[2 ${NOTICE_SUFFIX}`,
+ })
+ expect(JSON.stringify(dispatched)).not.toContain('RUZH')
+ expect(JSON.stringify(dispatched)).not.toContain('data:image/png')
+ })
+
+ it('still refuses a malformed USER image with LLM_INVALID_ATTACHMENT', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = adapterFor(provider, allow({ state: 'supported', evidence: CURATED_EVIDENCE }))
+ const messages: ChatMessage[] = [
+ ...toolTurn([DATA_URL]),
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data: LINE_WRAPPED }],
+ },
+ ]
+
+ await expectDenied(
+ () => adapter.completeWithTools({ messages, tools: [] }),
+ LlmErrorCode.InvalidAttachment,
+ 'unsupported image format or encoding'
+ )
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(0)
+ expect(provider.classifyError).not.toHaveBeenCalled()
+ })
+
+ it('leaves the caller messages untouched so a failover attempt sees the original', async () => {
+ const provider = fakeProvider('openai')
+ const adapter = adapterFor(provider, allow(undefined))
+ const messages = toolTurn([LINE_WRAPPED, 'QUJD'])
+ const snapshot = structuredClone(messages)
+ const references = [...messages]
+
+ await adapter.completeWithTools({ messages, tools: [] })
+
+ expect(provider.completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ const [dispatched] = provider.completeSingleTurnWithTools.mock.calls[0] as [ChatMessage[]]
+ expect(dispatched).not.toBe(messages)
+ expect(messages).toEqual(snapshot)
+ expect(messages).toHaveLength(references.length)
+ messages.forEach((message, index) => expect(message).toBe(references[index]))
+ expect(imageParts(messages).map(part => part.type === 'image' && part.data)).toEqual([
+ LINE_WRAPPED,
+ 'QUJD',
+ ])
+ })
+})
diff --git a/mcp-host/src/core/adapters/__tests__/llmPortAdapterDiagnostics.test.ts b/mcp-host/src/core/adapters/__tests__/llmPortAdapterDiagnostics.test.ts
index 26356b74d..322786b87 100644
--- a/mcp-host/src/core/adapters/__tests__/llmPortAdapterDiagnostics.test.ts
+++ b/mcp-host/src/core/adapters/__tests__/llmPortAdapterDiagnostics.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
import { SingleTurnProvider } from '../../../llm'
+import { logger } from '../../../logger'
import { LlmError, LlmErrorCode } from '../../errors'
import { LlmPortAdapter } from '../llmPortAdapter'
@@ -7,7 +8,7 @@ describe('LlmPortAdapter diagnostics', () => {
it('does not copy raw cause messages into provider diagnostics logs', async () => {
const cause = new Error('upstream payload included Bearer sk-live-secret')
const originalError = new Error('Connection error.', { cause })
- const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined)
+ const logSpy = vi.spyOn(logger, 'info').mockImplementation(() => undefined)
const mockProvider: SingleTurnProvider = {
completeSingleTurn: vi.fn().mockRejectedValue(originalError),
completeSingleTurnWithTools: vi.fn(),
@@ -22,7 +23,8 @@ describe('LlmPortAdapter diagnostics', () => {
await expect(adapter.complete({ messages: [] })).rejects.toBeInstanceOf(LlmError)
- const logText = logSpy.mock.calls.flat().join('\n')
+ expect(logSpy).toHaveBeenCalled()
+ const logText = JSON.stringify(logSpy.mock.calls)
expect(logText).not.toContain('sk-live-secret')
expect(logText).not.toContain('upstream payload included')
logSpy.mockRestore()
@@ -40,7 +42,7 @@ describe('LlmPortAdapter diagnostics', () => {
name: 'APIConnectionError',
code: secretishCode,
})
- const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined)
+ const logSpy = vi.spyOn(logger, 'info').mockImplementation(() => undefined)
const mockProvider: SingleTurnProvider = {
completeSingleTurn: vi.fn().mockRejectedValue(originalError),
completeSingleTurnWithTools: vi.fn(),
@@ -55,7 +57,8 @@ describe('LlmPortAdapter diagnostics', () => {
await expect(adapter.complete({ messages: [] })).rejects.toBeInstanceOf(LlmError)
- const logText = logSpy.mock.calls.flat().join('\n')
+ expect(logSpy).toHaveBeenCalled()
+ const logText = JSON.stringify(logSpy.mock.calls)
expect(logText).not.toContain(secretishCode)
expect(logText).not.toContain(secretishCauseCode)
expect(logText).toContain(`${secretPrefix}-[redacted]`)
diff --git a/mcp-host/src/core/adapters/llmPortAdapter.ts b/mcp-host/src/core/adapters/llmPortAdapter.ts
index a86f26691..92d1e61a4 100644
--- a/mcp-host/src/core/adapters/llmPortAdapter.ts
+++ b/mcp-host/src/core/adapters/llmPortAdapter.ts
@@ -1,12 +1,24 @@
+import type { ImageInputDecision } from '@clerum/llm-providers'
import { SingleTurnProvider } from '../../llm'
+import {
+ type ImageInputCapabilitySource,
+ type ImageInputResolver,
+ type ImageTransportOperation,
+ decideImageInput,
+ imageInputDenialMessage,
+ imageInputRolesFor,
+ isCanonicalBase64Shape,
+ isImageAttachmentMime,
+} from '../../llm/imageInput'
import {
clerumPromptCacheInputTokens,
clerumPromptCacheReadTokens,
clerumPromptCacheWriteTokens,
} from '../../llm/promptCacheMetrics'
+import { logger } from '../../logger'
import { LlmUsageEvent, UsageReporter, newRequestId } from '../../usage/usageReporter.js'
import type { SessionTokenUsage } from '../conversation/conversationStore'
-import { LlmError } from '../errors'
+import { LlmError, LlmErrorCode } from '../errors'
import { LlmPort } from '../interfaces'
import type { SystemPromptParts } from '../reasoning/systemPrompt'
import { redactDiagnosticField } from '../redactDiagnostics.js'
@@ -15,6 +27,7 @@ import {
ChatMessage,
CompletionRequest,
CompletionResponse,
+ MessageRole,
ToolCompletionRequest,
ToolCompletionResponse,
UsageContext,
@@ -33,6 +46,19 @@ function prependConcatSystem(parts: SystemPromptParts, messages: ChatMessage[]):
return [{ role: 'system', content }, ...messages]
}
+/**
+ * An image part the adapter may forward: PNG/JPEG mime and canonical base64
+ * string data. Line-wrapped, `data:`-prefixed, URL-safe or unpadded base64
+ * fails.
+ */
+function isWellFormedImagePart(part: { mimeType: unknown; data: unknown }): boolean {
+ return (
+ isImageAttachmentMime(part.mimeType) &&
+ typeof part.data === 'string' &&
+ isCanonicalBase64Shape(part.data)
+ )
+}
+
export type AdapterStaticContext = {
host_ref: string
context_ref: string | null
@@ -48,7 +74,7 @@ function errorField(value: unknown, field: string): string | null {
return trimmed ? redactDiagnosticField(trimmed).slice(0, 120) : null
}
-function providerErrorDiagnostics(err: unknown): string {
+function providerErrorDiagnostics(err: unknown): Record<string, string> {
const fields: Record<string, string> = {}
const name = errorField(err, 'name')
const type = errorField(err, 'type')
@@ -68,8 +94,7 @@ function providerErrorDiagnostics(err: unknown): string {
if (causeName) fields.causeName = causeName
if (causeCode) fields.causeCode = causeCode
- const entries = Object.entries(fields)
- return entries.length > 0 ? ` diagnostics=${JSON.stringify(Object.fromEntries(entries))}` : ''
+ return fields
}
/**
@@ -104,7 +129,14 @@ export class LlmPortAdapter implements LlmPort {
* Tests and legacy callers omit it (no-op). Independent of `usageReporter`:
* session persistence does not require control-api to be wired.
*/
- private readonly onUsageRecorded?: (usage: SessionTokenUsage) => void
+ private readonly onUsageRecorded?: (usage: SessionTokenUsage) => void,
+ /**
+ * Issue #654 — live-catalog lookup for the image-input capability of the
+ * (provider, model) this adapter is about to send. Absent (dev, tests,
+ * unwired host) means `unknown`: requests without images are byte-identical
+ * to today, requests carrying an image fail closed before the SDK.
+ */
+ private readonly imageInputResolver?: ImageInputResolver
) {}
/**
@@ -122,13 +154,21 @@ export class LlmPortAdapter implements LlmPort {
}
async complete(request: CompletionRequest): Promise<CompletionResponse> {
- console.log(
- `[NewCore:LlmPort] complete → model=${this.model}, messages=${request.messages.length}, cache=${request.systemPromptParts ? 'on' : 'off'}`
+ logger.info(
+ { provider: this.providerName, model: this.model, messageCount: request.messages.length },
+ 'Starting completion'
+ )
+ // Excluded from the SDK-classification catch below on purpose: a denied
+ // image must stay a typed, terminal LlmError instead of being reclassified
+ // by `provider.classifyError` (which would make it retryable).
+ const messages = this.prepareMessagesForImageInput(
+ request.messages,
+ this.dispatchMethodFor(request, false)
)
const requestId = newRequestId()
try {
- const response = await this.dispatchComplete(request)
- console.log(`[NewCore:LlmPort] ← finish_reason=${response.finish_reason}`)
+ const response = await this.dispatchComplete({ ...request, messages })
+ logger.info({ finishReason: response.finish_reason }, 'Completion returned')
this.recordUsage(requestId, request.usageContext, response.usage)
return response
} catch (err) {
@@ -137,15 +177,28 @@ export class LlmPortAdapter implements LlmPort {
}
async completeWithTools(request: ToolCompletionRequest): Promise<ToolCompletionResponse> {
- console.log(
- `[NewCore:LlmPort] completeWithTools → model=${this.model}, tools=${request.tools.length}, messages=${request.messages.length}, cache=${request.systemPromptParts ? 'on' : 'off'}`
+ logger.info(
+ {
+ provider: this.providerName,
+ model: this.model,
+ toolCount: request.tools.length,
+ messageCount: request.messages.length,
+ },
+ 'Starting tool completion'
+ )
+ // Same exclusion as `complete`: deny BEFORE the try/catch that classifies
+ // provider SDK errors.
+ const messages = this.prepareMessagesForImageInput(
+ request.messages,
+ this.dispatchMethodFor(request, true)
)
const requestId = newRequestId()
try {
- const response = await this.dispatchCompleteWithTools(request)
+ const response = await this.dispatchCompleteWithTools({ ...request, messages })
const toolCallCount = response.tool_calls?.length ?? 0
- console.log(
- `[NewCore:LlmPort] ← finish_reason=${response.finish_reason}, tool_calls=${toolCallCount}, usage=${JSON.stringify(response.usage ?? {})}`
+ logger.info(
+ { finishReason: response.finish_reason, toolCallCount },
+ 'Tool completion returned'
)
this.recordUsage(requestId, request.usageContext, response.usage)
return response
@@ -164,7 +217,11 @@ export class LlmPortAdapter implements LlmPort {
*/
private async dispatchComplete(request: CompletionRequest): Promise<CompletionResponse> {
const parts = request.systemPromptParts
- if (parts && this.provider.completeSingleTurnAndCache) {
+ if (
+ this.dispatchMethodFor(request, false) === 'completeAndCache' &&
+ parts &&
+ this.provider.completeSingleTurnAndCache
+ ) {
return this.provider.completeSingleTurnAndCache(parts, request.messages, {
max_tokens: request.max_tokens,
temperature: request.temperature,
@@ -183,7 +240,11 @@ export class LlmPortAdapter implements LlmPort {
request: ToolCompletionRequest
): Promise<ToolCompletionResponse> {
const parts = request.systemPromptParts
- if (parts && this.provider.completeSingleTurnWithToolsAndCache) {
+ if (
+ this.dispatchMethodFor(request, true) === 'completeWithToolsAndCache' &&
+ parts &&
+ this.provider.completeSingleTurnWithToolsAndCache
+ ) {
return this.provider.completeSingleTurnWithToolsAndCache(
parts,
request.messages,
@@ -205,6 +266,229 @@ export class LlmPortAdapter implements LlmPort {
})
}
+ /**
+ * Issue #654 — the single source of truth for which transport implementation
+ * a request will actually use. `dispatchComplete`/`dispatchCompleteWithTools`
+ * branch on this same method, so the image guard can never evaluate a
+ * different path than the one that runs.
+ */
+ private dispatchMethodFor(
+ request: { systemPromptParts?: SystemPromptParts },
+ withTools: boolean
+ ): ImageTransportOperation {
+ const parts = request.systemPromptParts
+ if (withTools) {
+ return parts && this.provider.completeSingleTurnWithToolsAndCache
+ ? 'completeWithToolsAndCache'
+ : 'completeWithTools'
+ }
+ return parts && this.provider.completeSingleTurnAndCache ? 'completeAndCache' : 'complete'
+ }
+
+ /**
+ * Resolve the image decision for this physical attempt. Returns `unknown`
+ * when no catalog resolver is wired or the pair is absent from it — an
+ * absent catalog entry is never an implicit allow.
+ */
+ private decideImageInputForAttempt(
+ method: ImageTransportOperation,
+ roles: readonly MessageRole[]
+ ): ImageInputDecision {
+ if (!this.imageInputResolver) return { state: 'unknown', reason: 'model_unknown' }
+ let source: ImageInputCapabilitySource | undefined
+ try {
+ source = this.imageInputResolver(this.providerName, this.model)
+ } catch (err) {
+ // A catalog read failure must not fail a text-only turn, and must not be
+ // read as support: it degrades to `unknown`, which blocks images only.
+ logger.warn(
+ {
+ component: 'LlmPortAdapter',
+ provider: this.providerName,
+ model: this.model,
+ err,
+ },
+ 'image-input capability resolver threw; treating as unknown'
+ )
+ source = undefined
+ }
+ if (!source) return { state: 'unknown', reason: 'model_unknown' }
+ return decideImageInput({
+ providerType: this.providerName,
+ method,
+ roles,
+ capability: source.capability,
+ })
+ }
+
+ /**
+ * Fail closed when this attempt carries a USER image and the intersection of
+ * model evidence, transport implementation and role is not
+ * affirmative. Text-only requests return immediately (no resolver call).
+ *
+ * #654 — images the agent's own tools produced are withheld rather than
+ * fatal: the turn is dispatched without them and `content` records how many
+ * were dropped and why. A model with no image evidence must still be able to
+ * finish a text task that happens to call a screenshot tool; refusing there
+ * would turn a capability gap into a task failure the user never asked for.
+ *
+ * Encoding is validated before any capability decision. A malformed USER
+ * image (mime other than PNG/JPEG, non-string data, or data that is not
+ * canonical base64) is a terminal `InvalidAttachment`. A malformed image in a
+ * `tool_result` message came from an external MCP server, not the user, so it
+ * is removed instead: the message keeps its other parts and `content` records
+ * how many were dropped for invalid encoding. It is never forwarded, even to
+ * an image-capable model. A message left with no image part stops being an
+ * image carrier; valid tool images continue through the capability decision.
+ *
+ * Returns the message array to dispatch. The input array is never mutated,
+ * so a later failover attempt on a supported pair still sees the images.
+ */
+ private prepareMessagesForImageInput(
+ input: ChatMessage[],
+ method: ImageTransportOperation
+ ): ChatMessage[] {
+ const messages = this.removeMalformedToolImages(input, method)
+ for (const message of messages) {
+ if (message.contentParts === undefined) continue
+ if (
+ !Array.isArray(message.contentParts) ||
+ message.contentParts.some(
+ part =>
+ !part ||
+ (part.type !== 'text' && part.type !== 'image') ||
+ (part.type === 'image' && !isWellFormedImagePart(part))
+ )
+ ) {
+ throw new LlmError(
+ 'The request contains an unsupported image format or encoding.',
+ this.providerName,
+ LlmErrorCode.InvalidAttachment,
+ false
+ )
+ }
+ }
+ const roles = imageInputRolesFor(messages)
+ if (roles.length === 0) return messages
+ const decision = this.decideImageInputForAttempt(method, roles)
+ if (decision.state === 'supported') return messages
+
+ const carriesImages = (message: ChatMessage): boolean =>
+ message.contentParts?.some(part => part.type === 'image') === true
+ const userImages = messages.some(
+ message => carriesImages(message) && message.imageOrigin !== 'tool_result'
+ )
+ if (userImages) {
+ logger.warn(
+ {
+ component: 'LlmPortAdapter',
+ provider: this.providerName,
+ model: this.model,
+ method,
+ roles,
+ reason: decision.reason,
+ validUntil: decision.validUntil,
+ },
+ 'image input denied before provider dispatch'
+ )
+ throw new LlmError(
+ imageInputDenialMessage(decision, { provider: this.providerName, model: this.model }),
+ this.providerName,
+ decision.state === 'unsupported'
+ ? LlmErrorCode.ImageInputUnsupported
+ : LlmErrorCode.ImageInputUnknown,
+ false
+ )
+ }
+
+ const withheld = messages.filter(
+ message => message.imageOrigin === 'tool_result' && carriesImages(message)
+ )
+ const count = withheld.reduce(
+ (total, message) =>
+ total + message.contentParts!.filter(part => part.type === 'image').length,
+ 0
+ )
+ logger.warn(
+ {
+ component: 'LlmPortAdapter',
+ provider: this.providerName,
+ model: this.model,
+ method,
+ reason: decision.reason,
+ withheldImages: count,
+ },
+ 'tool screenshots withheld: model has no affirmative image-input evidence'
+ )
+ const notice = `[${count} screenshot(s) returned by tool results were not forwarded: ${imageInputDenialMessage(
+ decision,
+ { provider: this.providerName, model: this.model }
+ )}]`
+ // The rewritten message drops `contentParts` and `imageOrigin` and keeps
+ // everything else the wire needs. `toolUseLoopMessages` builds this message
+ // with only `role`/`content`/`contentParts`, so `tool_calls` and
+ // `spillover_ref` are never set on it; `tool_call_id`/`name` are carried
+ // anyway so the rewrite stays correct if another producer marks a message
+ // `tool_result` in the future.
+ return messages.map(message =>
+ withheld.includes(message)
+ ? {
+ role: message.role,
+ content: `${message.content}\n${notice}`,
+ ...(message.tool_call_id ? { tool_call_id: message.tool_call_id } : {}),
+ ...(message.name ? { name: message.name } : {}),
+ }
+ : message
+ )
+ }
+
+ /**
+ * Remove image parts with an invalid encoding from `tool_result` messages.
+ * Returns `messages` itself when nothing was removed; otherwise a new array
+ * in which only the affected messages are rebuilt (inputs are not mutated).
+ *
+ * Providers render `contentParts` instead of `content` when parts are
+ * present, so when valid images remain the notice is appended both to
+ * `content` and as a trailing text part. When no image remains, the message
+ * drops `contentParts` and `imageOrigin` and is sent as plain text.
+ */
+ private removeMalformedToolImages(
+ messages: ChatMessage[],
+ method: ImageTransportOperation
+ ): ChatMessage[] {
+ let removedTotal = 0
+ const sanitized = messages.map((message): ChatMessage => {
+ if (message.imageOrigin !== 'tool_result' || !Array.isArray(message.contentParts)) {
+ return message
+ }
+ const kept = message.contentParts.filter(
+ part => !(part && part.type === 'image' && !isWellFormedImagePart(part))
+ )
+ const removed = message.contentParts.length - kept.length
+ if (removed === 0) return message
+ removedTotal += removed
+ const notice = `[${removed} screenshot(s) returned by tool results were not forwarded: invalid image encoding]`
+ const content = `${message.content}\n${notice}`
+ if (kept.some(part => part && part.type === 'image')) {
+ return { ...message, content, contentParts: [...kept, { type: 'text', text: notice }] }
+ }
+ const { contentParts: _dropped, imageOrigin: _origin, ...rest } = message
+ return { ...rest, content }
+ })
+ if (removedTotal === 0) return messages
+ logger.warn(
+ {
+ component: 'LlmPortAdapter',
+ provider: this.providerName,
+ model: this.model,
+ method,
+ count: removedTotal,
+ },
+ 'tool screenshots removed before provider dispatch: invalid image encoding'
+ )
+ return sanitized
+ }
+
private recordUsage(
requestId: string,
requestUsageContext: UsageContext | undefined,
@@ -251,7 +535,7 @@ export class LlmPortAdapter implements LlmPort {
cache_write_tokens: usage.cache_write_tokens,
})
} catch (err) {
- console.error('[NewCore:LlmPort] onUsageRecorded sink threw (ignored):', err)
+ logger.error({ err }, 'Usage sink failed after completion')
}
}
if (!this.usageReporter || !this.staticContext || !usageContext || !usage) return
@@ -292,10 +576,15 @@ export class LlmPortAdapter implements LlmPort {
*/
private handleProviderError(err: unknown): never {
const classified = this.provider.classifyError(err)
- console.log(
- `[NewCore:LlmPort] ← ERROR: code=${classified.code} ` +
- `retryable=${classified.retryable} message="${classified.message}"` +
- providerErrorDiagnostics(err)
+ logger.info(
+ {
+ provider: this.providerName,
+ model: this.model,
+ code: classified.code,
+ retryable: classified.retryable,
+ diagnostics: providerErrorDiagnostics(err),
+ },
+ 'LLM provider call failed'
)
throw new LlmError(
classified.message,
diff --git a/mcp-host/src/core/conversation/conversation.ts b/mcp-host/src/core/conversation/conversation.ts
index 528d47bf5..0edf51e5b 100644
--- a/mcp-host/src/core/conversation/conversation.ts
+++ b/mcp-host/src/core/conversation/conversation.ts
@@ -1,3 +1,4 @@
+import type { ModelSelectionWriteOutcome } from '../../db/worker/protocol'
import { parseSessionKey } from '../../session/types'
import { ConversationError, ConversationErrorCode } from '../errors'
import { isMcpToolName } from '../extensions/mcpApprovalGateController'
@@ -102,6 +103,11 @@ export class ConversationManager {
auto_approved_tools: new Set(),
created_at: new Date(),
updated_at: new Date(),
+ // #654 — a freshly inserted row carries the column default, so the RAM
+ // base revision matches disk from the first write onward. Without it the
+ // projection would omit the revision and the first selection of a new chat
+ // would fall back to the legacy unconditional (no-CAS) write.
+ modelSelectionRevision: 0,
}
this.store.set(sessionKey, conv)
await Promise.resolve(this.store.persistSessionCreate(conv, opts ?? {}))
@@ -652,14 +658,29 @@ export class ConversationManager {
}
/**
- * R2 — upsert the session's model selection for a provider and write it
- * through to the durable `model_selections` column. Full-overwrite of the
- * in-RAM map (this manager owns it); the store re-serializes on persist. The
- * per-task resolver reads this map after a cold-load to honour the choice.
+ * Apply a per-provider selection atomically and await its durable outcome.
+ * Conflicts return the winning map as well as its revision so the RAM mirror
+ * and the next /models response cannot pair stale data with a fresh revision.
*/
- setModelSelection(conversation: Conversation, provider: string, model: string): void {
- conversation.modelSelections = { ...(conversation.modelSelections ?? {}), [provider]: model }
- void Promise.resolve(this.store.persistModelSelections?.(conversation))
+ async setModelSelection(
+ conversation: Conversation,
+ provider: string,
+ model: string,
+ expectedRevision?: number
+ ): Promise<ModelSelectionWriteOutcome> {
+ const outcome = await this.store.applyModelSelection(
+ conversation,
+ provider,
+ model,
+ expectedRevision
+ )
+ // Another accepted write may have completed while this reply was queued.
+ // Never move the mirror backwards; conflicts also carry the winning map.
+ if (outcome.modelSelectionRevision >= (conversation.modelSelectionRevision ?? 0)) {
+ conversation.modelSelections = outcome.modelSelections
+ conversation.modelSelectionRevision = outcome.modelSelectionRevision
+ }
+ return outcome
}
/**
diff --git a/mcp-host/src/core/conversation/conversationStore.ts b/mcp-host/src/core/conversation/conversationStore.ts
index 43146579f..ab315b2dd 100644
--- a/mcp-host/src/core/conversation/conversationStore.ts
+++ b/mcp-host/src/core/conversation/conversationStore.ts
@@ -1,4 +1,4 @@
-import type { ReapedSession } from '../../db/worker/protocol'
+import type { ModelSelectionWriteOutcome, ReapedSession } from '../../db/worker/protocol'
import {
type Conversation,
ConversationState,
@@ -316,12 +316,32 @@ export interface ConversationStore {
persistSystemPromptStableHash(conv: Conversation, stableHash: string): Promise<void> | void
/**
- * R2 — persist the per-session `{ provider → model }` selection map after a
- * `set-model`. Async (enqueued via the worker), keyed by sessionKey so it
- * lands after the session's own `insert_session`. In-memory stores no-op.
- * Optional so legacy/in-memory stores don't have to implement it.
+ * R2 / #654 — compare-and-swap write of the per-session `{ provider → model }`
+ * selection: the map plus the monotonic `model_selection_revision` that guards
+ * it, committed as ONE durable write.
+ *
+ * `expectedRevision` is the CAS base the caller read:
+ * - a number → the write lands only while the stored revision still equals
+ * it. Otherwise the row is untouched and the caller receives
+ * `applied: false` with the revision that won.
+ * - `undefined` → the legacy unconditional write (last-write-wins). It STILL
+ * increments the revision, so an accepted straggler invalidates any CAS
+ * that was armed against the previous value.
+ *
+ * Callers MUST await the outcome before ACKing a selection to the user: the
+ * write is the durability barrier this method exists to provide (the previous
+ * fire-and-forget enqueue could fail silently and leave RAM ahead of disk).
+ *
+ * The store does NOT mutate the `Conversation`: it only decides and persists.
+ * `ConversationManager` mirrors the accepted outcome into RAM, so a conflicting
+ * write can never leave RAM holding a selection the row does not contain.
*/
- persistModelSelections?(conv: Conversation): Promise<void> | void
+ applyModelSelection(
+ conv: Conversation,
+ provider: string,
+ model: string,
+ expectedRevision?: number
+ ): Promise<ModelSelectionWriteOutcome> | ModelSelectionWriteOutcome
/**
* Spec 15 Fase B — persist a user rename (`sessions.title` overwrite). Async
@@ -504,8 +524,39 @@ export class InMemoryConversationStore implements ConversationStore {
/* no-op */
}
- persistModelSelections(_conv: Conversation): void {
- /* no-op — RAM-only store keeps the selection on the Conversation object */
+ /**
+ * #654 — RAM-only equivalent of the durable CAS. The map lives on the
+ * `Conversation` object and the manager applies the accepted one, so the store
+ * only has to arbitrate on the revision. This is the real `memory`-mode
+ * contract (the dev default), NOT a silent skip: a stale CAS is refused here
+ * exactly as it is in SQLite.
+ */
+ applyModelSelection(
+ conv: Conversation,
+ provider: string,
+ model: string,
+ expectedRevision?: number
+ ): ModelSelectionWriteOutcome {
+ const current = conv.modelSelectionRevision ?? 0
+ if (!Number.isSafeInteger(current) || current < 0 || current === Number.MAX_SAFE_INTEGER) {
+ throw new Error('Invalid model selection revision')
+ }
+ if (expectedRevision !== undefined && expectedRevision !== current) {
+ return {
+ applied: false,
+ reason: 'model_selection_conflict',
+ modelSelectionRevision: current,
+ modelSelections: { ...conv.modelSelections },
+ }
+ }
+ // Memory mode arbitrates synchronously, before the manager's await yields.
+ conv.modelSelections = { ...conv.modelSelections, [provider]: model }
+ conv.modelSelectionRevision = current + 1
+ return {
+ applied: true,
+ modelSelectionRevision: current + 1,
+ modelSelections: { ...conv.modelSelections },
+ }
}
persistTitle(_conv: Conversation): void {
diff --git a/mcp-host/src/core/conversation/persistence/__tests__/modelSelections.test.ts b/mcp-host/src/core/conversation/persistence/__tests__/modelSelections.test.ts
index fbcb46864..64e2408d6 100644
--- a/mcp-host/src/core/conversation/persistence/__tests__/modelSelections.test.ts
+++ b/mcp-host/src/core/conversation/persistence/__tests__/modelSelections.test.ts
@@ -1,18 +1,51 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
import type { PersistedSession } from '../../../../db/worker/protocol'
import { ConversationManager } from '../../conversation'
+import { InMemoryConversationStore } from '../../conversationStore'
import { reconstructConversation } from '../reconstruct'
import { makeSqliteStore } from './testHelpers'
const SESSION_KEY = 'u-1:rpc:agent-x:chat-1'
+/** #654 — CAS needs two real writers over ONE database file. */
+const tempDirs: string[] = []
+function makeSharedDbPath(): string {
+ const dir = mkdtempSync(join(tmpdir(), 'model-selection-cas-'))
+ tempDirs.push(dir)
+ return join(dir, 'state.db')
+}
+
+afterEach(() => {
+ for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function revisionOf(handle: ReturnType<typeof makeSqliteStore>, sessionId: string): number {
+ const row = handle.worker.db
+ .prepare('SELECT model_selection_revision AS revision FROM sessions WHERE id = ?')
+ .get(sessionId) as { revision: number } | undefined
+ return row?.revision ?? -1
+}
+
+function selectionsOf(
+ handle: ReturnType<typeof makeSqliteStore>,
+ sessionId: string
+): Record<string, string> {
+ const row = handle.worker.db
+ .prepare('SELECT model_selections AS ms FROM sessions WHERE id = ?')
+ .get(sessionId) as { ms: string | null } | undefined
+ return row?.ms ? (JSON.parse(row.ms) as Record<string, string>) : {}
+}
+
describe('R2 — model_selections persistence', () => {
it('setModelSelection writes the map and rehydrates on cold-load', async () => {
const handle = makeSqliteStore()
try {
const manager = new ConversationManager(handle.store)
const conv = await manager.getOrCreate(SESSION_KEY)
- manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
+ await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
expect(conv.modelSelections).toEqual({ claude: 'claude-haiku-4-5' })
await handle.persistQueue.drainSessionKey(SESSION_KEY)
@@ -38,8 +71,8 @@ describe('R2 — model_selections persistence', () => {
try {
const manager = new ConversationManager(handle.store)
const conv = await manager.getOrCreate(SESSION_KEY)
- manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
- manager.setModelSelection(conv, 'claude', 'claude-opus-4-8')
+ await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
+ await manager.setModelSelection(conv, 'claude', 'claude-opus-4-8')
await handle.persistQueue.drainSessionKey(SESSION_KEY)
const row = handle.worker.db
@@ -52,6 +85,254 @@ describe('R2 — model_selections persistence', () => {
})
})
+/**
+ * #654 §4.4 — the durable CAS. These drive the REAL dispatcher over a real
+ * SQLite database (no stubbed statements, no mocked worker), because the
+ * property under test is exactly "what is on disk after both writers ran".
+ */
+describe('#654 — model selection CAS (durable revision)', () => {
+ it('arbitrates simultaneous memory-mode writes before the manager await yields', async () => {
+ const manager = new ConversationManager(new InMemoryConversationStore())
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ const [first, second] = await Promise.all([
+ manager.setModelSelection(conv, 'claude', 'claude-opus-4-8', 0),
+ manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5', 0),
+ ])
+ expect(first.applied).toBe(true)
+ expect(second.applied).toBe(false)
+ expect(conv.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+ expect(conv.modelSelectionRevision).toBe(1)
+ })
+ it('legacy writes without expectedRevision still increment the revision', async () => {
+ const handle = makeSqliteStore()
+ try {
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ expect(conv.modelSelectionRevision).toBe(0)
+
+ const first = await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
+ expect(first).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 1,
+ })
+
+ const second = await manager.setModelSelection(conv, 'claude', 'claude-opus-4-8')
+ expect(second).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 2,
+ })
+
+ expect(revisionOf(handle, conv.id)).toBe(2)
+ expect(selectionsOf(handle, conv.id)).toEqual({ claude: 'claude-opus-4-8' })
+ expect(conv.modelSelectionRevision).toBe(2)
+ } finally {
+ await handle.shutdown()
+ }
+ })
+
+ it('applies a write whose expectedRevision still matches and rehydrates it cold', async () => {
+ const handle = makeSqliteStore()
+ try {
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+
+ const outcome = await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5', 0)
+ expect(outcome).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 1,
+ })
+ expect(revisionOf(handle, conv.id)).toBe(1)
+
+ handle.store['cache'].delete(SESSION_KEY)
+ handle.store['ordinals'].clear()
+ handle.store['sessionKeyById'].clear()
+ const reloaded = await handle.store.getOrLoad(SESSION_KEY)
+ expect(reloaded?.modelSelectionRevision).toBe(1)
+ expect(reloaded?.modelSelections).toEqual({ claude: 'claude-haiku-4-5' })
+ } finally {
+ await handle.shutdown()
+ }
+ })
+
+ it('rejects a stale write and leaves the winner on disk and in RAM', async () => {
+ const handle = makeSqliteStore()
+ try {
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ await manager.setModelSelection(conv, 'claude', 'claude-opus-4-8', 0)
+
+ // A straggler armed against revision 0 (the value it read before the
+ // winner landed) must not overwrite revision 1.
+ const stale = await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5', 0)
+ expect(stale).toEqual({
+ modelSelections: expect.any(Object),
+ applied: false,
+ reason: 'model_selection_conflict',
+ modelSelectionRevision: 1,
+ })
+
+ // Disk keeps the winner; RAM never adopted the rejected value and its
+ // revision was realigned to the durable one so the retry can succeed.
+ expect(revisionOf(handle, conv.id)).toBe(1)
+ expect(selectionsOf(handle, conv.id)).toEqual({ claude: 'claude-opus-4-8' })
+ expect(conv.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+ expect(conv.modelSelectionRevision).toBe(1)
+
+ // The retry, armed with the revision that won, is accepted.
+ const retry = await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5', 1)
+ expect(retry).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 2,
+ })
+ expect(selectionsOf(handle, conv.id)).toEqual({ claude: 'claude-haiku-4-5' })
+ } finally {
+ await handle.shutdown()
+ }
+ })
+
+ it('orders two replicas on one database: the older write is refused, not queued behind', async () => {
+ const dbPath = makeSharedDbPath()
+ const replicaA = makeSqliteStore({ dbPath })
+ const replicaB = makeSqliteStore({ dbPath })
+ try {
+ const managerA = new ConversationManager(replicaA.store)
+ const managerB = new ConversationManager(replicaB.store)
+
+ // Both replicas observe revision 0 (as two devices on one chat would).
+ const convA = await managerA.getOrCreate(SESSION_KEY)
+ await replicaA.persistQueue.drainSessionKey(SESSION_KEY)
+ const convB = await managerB.getSessionByKeyAsync(SESSION_KEY)
+ expect(convB).toBeDefined()
+ expect(convB!.id).toBe(convA.id)
+ expect(convA.modelSelectionRevision).toBe(0)
+ expect(convB!.modelSelectionRevision).toBe(0)
+
+ const winner = await managerA.setModelSelection(convA, 'claude', 'claude-opus-4-8', 0)
+ expect(winner).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 1,
+ })
+
+ // B's write is a straggler even though B sends it AFTER A resolved: its
+ // base is stale, which is the whole point of the revision.
+ const loser = await managerB.setModelSelection(convB!, 'claude', 'claude-haiku-4-5', 0)
+ expect(loser).toEqual({
+ modelSelections: expect.any(Object),
+ applied: false,
+ reason: 'model_selection_conflict',
+ modelSelectionRevision: 1,
+ })
+ expect(convB!.modelSelectionRevision).toBe(1)
+ expect(convB!.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+ expect(loser.modelSelections).toEqual({ claude: 'claude-opus-4-8' })
+
+ expect(revisionOf(replicaA, convA.id)).toBe(1)
+ expect(selectionsOf(replicaA, convA.id)).toEqual({ claude: 'claude-opus-4-8' })
+
+ // A legacy (no-CAS) write from B still wins and invalidates the CAS base
+ // every client is holding.
+ const legacy = await managerB.setModelSelection(convB!, 'claude', 'claude-haiku-4-5')
+ expect(legacy).toEqual({
+ modelSelections: expect.any(Object),
+ applied: true,
+ modelSelectionRevision: 2,
+ })
+ const armedWithOldBase = await managerA.setModelSelection(
+ convA,
+ 'claude',
+ 'claude-opus-4-8',
+ 1
+ )
+ expect(armedWithOldBase).toEqual({
+ modelSelections: expect.any(Object),
+ applied: false,
+ reason: 'model_selection_conflict',
+ modelSelectionRevision: 2,
+ })
+ expect(selectionsOf(replicaA, convA.id)).toEqual({ claude: 'claude-haiku-4-5' })
+ expect(convA.modelSelections).toEqual({ claude: 'claude-haiku-4-5' })
+
+ // A stale replica's legacy update of another provider must merge the
+ // current durable map, not overwrite it with its old RAM snapshot.
+ await managerA.setModelSelection(convA, 'openai', 'gpt-5.4')
+ await managerB.setModelSelection(convB!, 'claude', 'claude-opus-4-8')
+ expect(selectionsOf(replicaA, convA.id)).toEqual({
+ claude: 'claude-opus-4-8',
+ openai: 'gpt-5.4',
+ })
+ } finally {
+ await replicaA.shutdown()
+ await replicaB.shutdown()
+ }
+ })
+
+ it('refuses to report success when the session has no durable row', async () => {
+ const handle = makeSqliteStore()
+ try {
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ // Drop the durable row behind the store's back: the cache still holds the
+ // Conversation, so the caller would otherwise be told the write landed.
+ handle.worker.db.prepare('DELETE FROM sessions WHERE id = ?').run(conv.id)
+
+ await expect(
+ manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5', 0)
+ ).rejects.toThrow(/no session row/)
+ expect(conv.modelSelections).toBeUndefined()
+ expect(conv.modelSelectionRevision).toBe(0)
+ } finally {
+ await handle.shutdown()
+ }
+ })
+
+ // A corrupt map is the one input the CAS cannot merge into: writing the one
+ // requested provider would silently drop every other provider the row claimed
+ // to hold. The dispatcher refuses instead, so an operator can still read the
+ // original bytes and repair them.
+ it.each([
+ ['malformed JSON', 'not json at all'],
+ ['a JSON array', '[1,2]'],
+ ['a non-string value', '{"claude":5}'],
+ ])(
+ 'refuses to write over %s in model_selections and leaves the row untouched',
+ async (_label, corrupt) => {
+ const handle = makeSqliteStore()
+ try {
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ await manager.setModelSelection(conv, 'claude', 'claude-haiku-4-5')
+ await handle.persistQueue.drainSessionKey(SESSION_KEY)
+ const revisionBefore = revisionOf(handle, conv.id)
+
+ // Corrupt the durable map behind the store's back, the way a partial
+ // write or a hand-edited database would.
+ handle.worker.db
+ .prepare('UPDATE sessions SET model_selections = ? WHERE id = ?')
+ .run(corrupt, conv.id)
+
+ // Witness: only the dispatcher's own parse of the stored row can raise
+ // this, so the refusal below is a decision and not an unreached branch.
+ await expect(manager.setModelSelection(conv, 'openai', 'gpt-5.4')).rejects.toThrow(
+ /Invalid persisted model selections/
+ )
+
+ const rawAfter = handle.worker.db
+ .prepare('SELECT model_selections AS ms FROM sessions WHERE id = ?')
+ .get(conv.id) as { ms: string }
+ expect(rawAfter.ms).toBe(corrupt)
+ expect(revisionOf(handle, conv.id)).toBe(revisionBefore)
+ } finally {
+ await handle.shutdown()
+ }
+ }
+ )
+})
+
describe('R2 — reconstruct.parseModelSelections tolerance', () => {
function persisted(model_selections: string | null): PersistedSession {
return {
diff --git a/mcp-host/src/core/conversation/persistence/dualConversationStore.ts b/mcp-host/src/core/conversation/persistence/dualConversationStore.ts
index 3300cdeb3..c9db342a2 100644
--- a/mcp-host/src/core/conversation/persistence/dualConversationStore.ts
+++ b/mcp-host/src/core/conversation/persistence/dualConversationStore.ts
@@ -10,7 +10,7 @@
* flip the canary to `sqlite`.
*/
import { Counter } from 'prom-client'
-import type { ReapedSession } from '../../../db/worker/protocol'
+import type { ModelSelectionWriteOutcome, ReapedSession } from '../../../db/worker/protocol'
import type { Conversation, PendingApproval, TurnToolCall } from '../../types'
import type {
ConversationSessionMessages,
@@ -192,8 +192,7 @@ export class DualConversationStore implements ConversationStore {
return memList
}
- const sqlParityPage =
- query.limit === undefined ? sqlList : sqlList.slice(0, query.limit)
+ const sqlParityPage = query.limit === undefined ? sqlList : sqlList.slice(0, query.limit)
this.recordParity('listSessionSummariesByPrefix', pagesMatch(memList, sqlParityPage))
if (query.limit !== undefined && memList.length >= query.limit) return memList
// A live memory copy is canonical even when its timestamp places it outside
@@ -320,6 +319,25 @@ export class DualConversationStore implements ConversationStore {
])
}
+ /**
+ * #654 — the CAS arbiter is the DURABLE store, and only it. In `dual` mode the
+ * memory store holds the same `Conversation` reference the manager mirrors the
+ * accepted outcome into, so its own revision counter has nothing to arbitrate:
+ * asking both would invent a second, weaker authority whose counter can drift
+ * from the row (a cold load leaves SQLite ahead) and start rejecting writes the
+ * durable store accepts. Without this method the canary mode would inherit the
+ * interface default — a silent no-op that reports success while nothing is
+ * persisted, which is exactly what `enqueueSync` above removes.
+ */
+ async applyModelSelection(
+ conv: Conversation,
+ provider: string,
+ model: string,
+ expectedRevision?: number
+ ): Promise<ModelSelectionWriteOutcome> {
+ return this.sqlite.applyModelSelection(conv, provider, model, expectedRevision)
+ }
+
async persistSessionUsage(conv: Conversation, usage: SessionTokenUsage): Promise<void> {
await Promise.all([
Promise.resolve(this.memory.persistSessionUsage?.(conv, usage)),
diff --git a/mcp-host/src/core/conversation/persistence/reconstruct.ts b/mcp-host/src/core/conversation/persistence/reconstruct.ts
index f83901d15..6bd49ff25 100644
--- a/mcp-host/src/core/conversation/persistence/reconstruct.ts
+++ b/mcp-host/src/core/conversation/persistence/reconstruct.ts
@@ -97,11 +97,30 @@ export function reconstructConversation(persisted: PersistedSession): Reconstruc
// per-task resolver honours a saved choice after a pod restart. Read-plumbing
// previously died at this store→Conversation frontier; parse it here.
modelSelections: parseModelSelections(persisted.session.model_selections),
+ // #654 (migration 015) — rehydrate the CAS base. Without it a cold-loaded
+ // session would arm its next write against `undefined` (legacy
+ // unconditional) and could overwrite a selection that landed while this
+ // replica was cold. `undefined` from a pre-migration row reads as the column
+ // default 0, so the first CAS still has a well-defined base.
+ modelSelectionRevision: normalizeModelSelectionRevision(
+ persisted.session.model_selection_revision
+ ),
}
return { conversation, highestOrdinal, highestTurnNumber }
}
+/**
+ * #654 — narrow the durable revision to a non-negative safe integer, defaulting
+ * to the column default 0 when the row predates migration 015 or carries a value
+ * SQLite could not have written. Never returns `undefined`: the CAS base is
+ * always an explicit revision so a caller cannot silently fall back to the
+ * unconditional legacy write by omission.
+ */
+function normalizeModelSelectionRevision(raw: number | null | undefined): number {
+ return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0
+}
+
/**
* Parse the persisted `model_selections` JSON into a `{ provider → model }`
* map. Tolerant: NULL / malformed / non-object JSON → undefined (no selection),
diff --git a/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts b/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
index 9b7769dda..2f4139a41 100644
--- a/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
+++ b/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
@@ -16,6 +16,7 @@
import { Counter, Gauge, Histogram } from 'prom-client'
import type {
LoadAllPendingApprovalsRow,
+ ModelSelectionWriteOutcome,
PendingApprovalRow,
PersistedSession,
PersistedSessionMessagePage,
@@ -979,20 +980,43 @@ export class SqliteConversationStore implements ConversationStore {
}
/**
- * R2 — persist the per-session `{ provider → model }` selection map. Enqueued
- * (async) and keyed by sessionKey so it chains AFTER the session's own
- * `insert_session` (a set-model on a brand-new session getOrCreates the row
- * first, enqueuing the insert on the same FIFO chain). Full-overwrite: the
- * ConversationManager owns the in-RAM map and re-serializes on every mutation.
+ * R2 / #654 — durable compare-and-swap of the per-session
+ * `{ provider → model }` selection map.
+ *
+ * `enqueueSync` (not `enqueueAsync`): the caller must not ACK a selection until
+ * the row carries it. The sync path also chains AFTER the session's own
+ * `insert_session` on the same per-sessionKey FIFO, so a set-model on a
+ * brand-new session cannot race the INSERT that creates its row.
+ *
+ * The worker merges one provider into the durable map under the CAS lock.
+ * A stale RAM map never overwrites selections made by another writer.
+ *
+ * Fails closed when the session id is not in the cache→key index: refusing is
+ * the only honest answer, because a write we cannot address is a write we
+ * cannot claim.
*/
- persistModelSelections(conv: Conversation): void {
+ async applyModelSelection(
+ conv: Conversation,
+ provider: string,
+ model: string,
+ expectedRevision?: number
+ ): Promise<ModelSelectionWriteOutcome> {
const sessionKey = this.sessionKeyById.get(conv.id)
- if (!sessionKey) return
- this.persistQueue.enqueueAsync(sessionKey, {
- kind: 'update_session_model_selections',
- sessionId: conv.id,
- modelSelections: JSON.stringify(conv.modelSelections ?? {}),
- })
+ if (!sessionKey) {
+ throw new Error(
+ `applyModelSelection: no sessionKey for conversation ${conv.id}; refusing a write with no durable target`
+ )
+ }
+ return this.persistQueue.enqueueSync<ModelSelectionWriteOutcome>(
+ {
+ kind: 'update_session_model_selections',
+ sessionId: conv.id,
+ provider,
+ model,
+ ...(expectedRevision === undefined ? {} : { expectedRevision }),
+ },
+ sessionKey
+ )
}
/**
diff --git a/mcp-host/src/core/errors.ts b/mcp-host/src/core/errors.ts
index 7e7f61e94..644b7634d 100644
--- a/mcp-host/src/core/errors.ts
+++ b/mcp-host/src/core/errors.ts
@@ -21,6 +21,7 @@ export class AgentError extends Error {
// ─── LLM Errors ─────────────────────────────────────────────
export enum LlmErrorCode {
+ InvalidAttachment = 'LLM_INVALID_ATTACHMENT',
ApiCallFailed = 'LLM_API_CALL_FAILED',
InvalidResponse = 'LLM_INVALID_RESPONSE',
ContextLengthExceeded = 'LLM_CONTEXT_LENGTH_EXCEEDED',
@@ -30,6 +31,34 @@ export enum LlmErrorCode {
RateLimited = 'LLM_RATE_LIMITED',
AuthenticationFailed = 'LLM_AUTHENTICATION_FAILED',
ModelOverloaded = 'LLM_MODEL_OVERLOADED',
+ /**
+ * Issue #654 — the selected (provider, model) is known NOT to accept the
+ * image carried by this attempt (model evidence `unsupported`, selection
+ * policy denial, or a transport path whose serializer would drop it).
+ * Terminal: never retryable, never failover-eligible
+ * (`classifyFailoverClass` returns null for it).
+ */
+ ImageInputUnsupported = 'LLM_IMAGE_INPUT_UNSUPPORTED',
+ /**
+ * Issue #654 — a required datum for the image decision is missing, stale or
+ * not yet valid (no evidence, malformed metadata, expired `validUntil`).
+ * Terminal for the same reasons as {@link LlmErrorCode.ImageInputUnsupported};
+ * text-only requests are unaffected and are never classified with this code.
+ */
+ ImageInputUnknown = 'LLM_IMAGE_INPUT_UNKNOWN',
+ /**
+ * Issue #654 — a piggybacked per-session model selection lost the
+ * compare-and-swap against the persisted revision, or carried a revision the
+ * Host cannot interpret. It says nothing about image capability: the client
+ * re-reads the current selection and sends again, so it is RETRYABLE.
+ */
+ ModelSelectionConflict = 'LLM_MODEL_SELECTION_CONFLICT',
+ /**
+ * Issue #654 — a piggybacked per-session model selection names a model this
+ * Host's allowlist no longer admits. Terminal: retrying the same pick cannot
+ * succeed, the user must choose another model.
+ */
+ ModelNotAllowed = 'LLM_MODEL_NOT_ALLOWED',
}
export class LlmError extends AgentError {
diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoopMessages.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoopMessages.test.ts
index 7423e3100..2b1096ff3 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoopMessages.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoopMessages.test.ts
@@ -218,4 +218,40 @@ describe('appendToolResults', () => {
expect(collectedAttachments).toEqual([])
})
+
+ it('marks the screenshot message as tool-originated (#654)', () => {
+ const messages: ChatMessage[] = []
+ const collectedAttachments: Attachment[] = []
+ const payloadKey = 'data' + 'Base' + '64'
+ const screenshot = (id: string, body: string): Attachment =>
+ ({
+ id,
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: ['base', '64'].join('') as Attachment['encoding'],
+ [payloadKey]: Buffer.from(body).toString(('base' + '64') as BufferEncoding),
+ sourceTool: 'browser__screenshot',
+ }) as unknown as Attachment
+
+ appendToolResults(
+ messages,
+ [
+ {
+ tool_call_id: 'tc_1',
+ name: 'browser__screenshot',
+ content: 'captured 2 viewports',
+ is_error: false,
+ attachments: [screenshot('shot-1', 'first-png'), screenshot('shot-2', 'second-png')],
+ },
+ ],
+ collectedAttachments
+ )
+
+ const screenshotMessage = messages.find(message => message.role === 'user')
+ expect(screenshotMessage).toBeDefined()
+ // The flag is what lets `LlmPortAdapter.prepareMessagesForImageInput` tell a
+ // tool screenshot (withheld) from a user attachment (refused).
+ expect(screenshotMessage).toMatchObject({ role: 'user', imageOrigin: 'tool_result' })
+ expect(screenshotMessage!.contentParts?.filter(part => part.type === 'image')).toHaveLength(2)
+ })
})
diff --git a/mcp-host/src/core/orchestration/toolUseLoopMessages.ts b/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
index 4ddf20ece..249b03452 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
@@ -1,3 +1,4 @@
+import { isImageAttachmentMime } from '../../llm/imageInput'
import {
isInternalGeneratedArtifactAttachment,
isInternalGeneratedArtifactSourceTool,
@@ -72,7 +73,7 @@ export function appendToolResults(
if (trustedAttachments.length) {
for (const att of trustedAttachments) {
if (att.kind !== 'image') continue
- if (att.mimeType !== 'image/jpeg' && att.mimeType !== 'image/png') continue
+ if (!isImageAttachmentMime(att.mimeType)) continue
pendingImages.push({
type: 'image',
mimeType: att.mimeType,
@@ -95,6 +96,10 @@ export function appendToolResults(
messages.push({
role: 'user',
content: 'Here are the screenshots from the tool results above.',
+ // #654 — the parts below came from tool results, not from the user. The
+ // adapter withholds them (and says so in `content`) when the model has no
+ // affirmative image-input evidence, instead of failing the whole turn.
+ imageOrigin: 'tool_result',
contentParts: [
{ type: 'text', text: 'Here are the screenshots from the tool results above.' },
...pendingImages,
diff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.ts
index 25fd01aac..d18460e6f 100644
--- a/mcp-host/src/core/types.ts
+++ b/mcp-host/src/core/types.ts
@@ -20,6 +20,14 @@ export interface ChatMessage {
role: MessageRole
content: string
contentParts?: MessageContentPart[] // only set when tool results have images
+ /**
+ * Issue #654 — set when the image parts were produced by a tool result, never
+ * by the user. A user who attaches an image to a model without affirmative
+ * image-input evidence gets a typed refusal; a screenshot the agent's own
+ * tool returned is withheld instead, so an unverified model can still finish
+ * a text task that happens to call a screenshot tool.
+ */
+ imageOrigin?: 'tool_result'
tool_call_id?: string
name?: string
tool_calls?: ToolCall[] | null
@@ -401,6 +409,15 @@ export interface Conversation {
* `undefined` ⇔ no selection (today's behaviour).
*/
modelSelections?: Record<string, string>
+ /**
+ * #654 (migration 015) — durable revision of `modelSelections` for this
+ * session, mirrored from `sessions.model_selection_revision` and rehydrated on
+ * cold-load. It is the compare-and-swap token of the selection write: the
+ * writer sends the revision it read, and a write whose base is already stale
+ * is rejected instead of overwriting the row that got there first. `undefined`
+ * ⇔ the row has not been read yet; the durable default is 0.
+ */
+ modelSelectionRevision?: number
}
/**
diff --git a/mcp-host/src/db/migrations/015-session-model-selection-revision.ts b/mcp-host/src/db/migrations/015-session-model-selection-revision.ts
new file mode 100644
index 000000000..7308fc19f
--- /dev/null
+++ b/mcp-host/src/db/migrations/015-session-model-selection-revision.ts
@@ -0,0 +1,50 @@
+/**
+ * Migration 015 — durable revision counter for the per-session model selection
+ * (`sessions.model_selection_revision`, issue #654 §4.4).
+ *
+ * The selection itself lives in `model_selections` (migration 007). This column
+ * is the monotonic revision of that row and exists to make the selection write a
+ * compare-and-swap: `POST /v1/runtime/model` may carry `expectedRevision`, and
+ * the write lands only while the stored revision still equals it. A write that
+ * was ordered behind a newer one — a retry after a client timeout, two replicas,
+ * a second device on the same chat — is then rejected with
+ * `model_selection_conflict` instead of silently overwriting the winner.
+ *
+ * A counter, not a hash or a timestamp: the writer only compares equality, so
+ * the value merely has to change on every accepted write. EVERY write bumps it,
+ * including the legacy unconditional path (no `expectedRevision`), which is what
+ * makes a straggler detectable by the time it arrives.
+ *
+ * `INTEGER NOT NULL DEFAULT 0` is a metadata-only change for SQLite: every
+ * existing row reads 0, which is the base revision of that session's first CAS
+ * write. No backfill and no index — the CAS reads and writes the row by primary
+ * key, so no query here filters on the revision.
+ */
+import type { Database } from 'better-sqlite3'
+
+export const name = '015-session-model-selection-revision'
+
+function hasColumn(db: Database): boolean {
+ return (db.prepare('PRAGMA table_info(sessions)').all() as Array<{ name: string }>).some(
+ row => row.name === 'model_selection_revision'
+ )
+}
+
+export function up(db: Database): void {
+ // SQLite has no `ADD COLUMN IF NOT EXISTS`; the guard keeps a re-run (a
+ // half-applied manual repair, or a test that calls `up()` twice) idempotent
+ // instead of throwing "duplicate column name".
+ if (!hasColumn(db)) {
+ db.exec(`
+ ALTER TABLE sessions ADD COLUMN model_selection_revision INTEGER NOT NULL DEFAULT 0;
+ `)
+ }
+}
+
+export function down(db: Database): void {
+ if (hasColumn(db)) {
+ // better-sqlite3 v11 ships SQLite 3.42+, where DROP COLUMN is supported.
+ // No index or trigger references model_selection_revision.
+ db.exec('ALTER TABLE sessions DROP COLUMN model_selection_revision;')
+ }
+}
diff --git a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
index f091bbced..22ce1a048 100644
--- a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
+++ b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
@@ -76,6 +76,7 @@ describe('migration 008 — active trace context', () => {
'012-session-ownership-backfill',
'013-pending-approval-connect',
'014-pending-approval-task-budget',
+ '015-session-model-selection-revision',
],
pending: [],
})
diff --git a/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts b/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts
index ba2adea50..bd9c44405 100644
--- a/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts
+++ b/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts
@@ -55,6 +55,9 @@ describe('durable task budget migration and renewal', () => {
it('atomically replaces a legacy approval, retaining old state if insertion fails', async () => {
const db = fixture()
try {
+ // The current dispatcher prepares statements against the current schema.
+ const currentIndex = migrations.findIndex(m => m.name === migration.name)
+ for (const later of migrations.slice(currentIndex + 1)) later.up(db)
const deps = createDispatcher(db)
const old = db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
const budget = { elapsedActiveMs: 0, iterationsUsed: 0, durationMs: 100, maxIterations: 3 }
diff --git a/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts b/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts
new file mode 100644
index 000000000..d4ba28335
--- /dev/null
+++ b/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import Database from 'better-sqlite3'
+import * as migration from '../015-session-model-selection-revision'
+import { migrations } from '../index'
+
+function tableColumns(db: Database.Database, table: string): string[] {
+ return (db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>).map(
+ c => c.name
+ )
+}
+
+function preMigrationDb(): Database.Database {
+ const db = new Database(':memory:')
+ for (const m of migrations) {
+ if (m.name === migration.name) break
+ m.up(db)
+ }
+ db.prepare(
+ `INSERT INTO sessions (id, session_key, source, started_at) VALUES (?, ?, 'rpc', 0)`
+ ).run('s-legacy', 'u:rpc:a:1')
+ return db
+}
+
+describe('migration 015 — sessions.model_selection_revision', () => {
+ it('appends last to the ordered migration list', () => {
+ expect(migrations[migrations.length - 1]?.name).toBe(migration.name)
+ })
+
+ it('adds a NOT NULL revision that reads 0 for every pre-existing row', () => {
+ const db = preMigrationDb()
+ try {
+ expect(tableColumns(db, 'sessions')).not.toContain('model_selection_revision')
+
+ migration.up(db)
+ expect(tableColumns(db, 'sessions')).toContain('model_selection_revision')
+
+ const row = db
+ .prepare('SELECT model_selection_revision AS revision FROM sessions WHERE id = ?')
+ .get('s-legacy') as { revision: number }
+ expect(row.revision).toBe(0)
+
+ // The default keeps applying to rows inserted without the column, which is
+ // what makes the CAS base of a brand-new session a defined 0.
+ db.prepare(
+ `INSERT INTO sessions (id, session_key, source, started_at) VALUES (?, ?, 'rpc', 0)`
+ ).run('s-new', 'u:rpc:a:2')
+ expect(
+ (
+ db
+ .prepare('SELECT model_selection_revision AS revision FROM sessions WHERE id = ?')
+ .get('s-new') as { revision: number }
+ ).revision
+ ).toBe(0)
+
+ expect(() =>
+ db
+ .prepare(
+ 'INSERT INTO sessions (id, session_key, source, started_at, model_selection_revision) VALUES (?, ?, ?, 0, ?)'
+ )
+ .run('s-bad', 'u:rpc:a:3', 'rpc', null)
+ ).toThrow()
+ } finally {
+ db.close()
+ }
+ })
+
+ it('is idempotent when re-run and drops cleanly on down()', () => {
+ const db = preMigrationDb()
+ try {
+ migration.up(db)
+ migration.up(db)
+ db.prepare('UPDATE sessions SET model_selection_revision = 7 WHERE id = ?').run('s-legacy')
+ migration.up(db)
+ expect(
+ (
+ db
+ .prepare('SELECT model_selection_revision AS revision FROM sessions WHERE id = ?')
+ .get('s-legacy') as { revision: number }
+ ).revision
+ ).toBe(7)
+
+ migration.down(db)
+ expect(tableColumns(db, 'sessions')).not.toContain('model_selection_revision')
+ migration.down(db)
+ expect(tableColumns(db, 'sessions')).not.toContain('model_selection_revision')
+ } finally {
+ db.close()
+ }
+ })
+})
diff --git a/mcp-host/src/db/migrations/index.ts b/mcp-host/src/db/migrations/index.ts
index 22fae9d0a..cdb025478 100644
--- a/mcp-host/src/db/migrations/index.ts
+++ b/mcp-host/src/db/migrations/index.ts
@@ -12,6 +12,7 @@ import * as sessionSummaryUserActivityIndex from './011-session-summary-user-act
import * as sessionOwnershipBackfill from './012-session-ownership-backfill'
import * as pendingApprovalConnect from './013-pending-approval-connect'
import * as pendingApprovalTaskBudget from './014-pending-approval-task-budget'
+import * as sessionModelSelectionRevision from './015-session-model-selection-revision'
/**
* Ordered list of migrations. New migrations append; never reorder or rename.
@@ -37,4 +38,5 @@ export const migrations: Array<{
sessionOwnershipBackfill,
pendingApprovalConnect,
pendingApprovalTaskBudget,
+ sessionModelSelectionRevision,
]
diff --git a/mcp-host/src/db/statements.ts b/mcp-host/src/db/statements.ts
index c1a70846c..6d35ced74 100644
--- a/mcp-host/src/db/statements.ts
+++ b/mcp-host/src/db/statements.ts
@@ -25,6 +25,7 @@ export interface PreparedStatements {
recomputeSessionMessageSummary: Statement
updateSessionPromptStableHash: Statement
updateSessionModelSelections: Statement
+ selectSessionModelSelectionRevision: Statement
setSessionTitleIfAbsent: Statement
updateSessionTitle: Statement
selectSessionBySessionKey: Statement
@@ -171,9 +172,24 @@ export function prepareStatements(db: Database): PreparedStatements {
// dispatcher passes the already-serialized JSON string; a full overwrite is
// correct because ConversationManager owns the in-RAM map and re-serializes
// it on every mutation.
+ //
+ // #654 — the same statement stamps the new revision, so map + revision are
+ // one atomic write inside the dispatcher's transaction. Both values come
+ // from the dispatcher, which is the only place that reads the previous
+ // revision and decides whether the CAS may proceed.
updateSessionModelSelections: db.prepare(`
UPDATE sessions
- SET model_selections = @model_selections
+ SET model_selections = @model_selections,
+ model_selection_revision = @model_selection_revision
+ WHERE id = @id
+ `),
+ // #654 — the CAS base. Read INSIDE the same IMMEDIATE transaction that
+ // writes, so a concurrent writer in another replica cannot slip between the
+ // check and the update. `changes === 0` from the paired UPDATE is not enough
+ // to classify the failure, hence the dedicated read.
+ selectSessionModelSelectionRevision: db.prepare(`
+ SELECT model_selection_revision, model_selections
+ FROM sessions
WHERE id = @id
`),
// Auto-title (spec 15) — write the derived title only if the column is still
diff --git a/mcp-host/src/db/worker/dispatcher.ts b/mcp-host/src/db/worker/dispatcher.ts
index 0c0e9ec21..cdca15711 100644
--- a/mcp-host/src/db/worker/dispatcher.ts
+++ b/mcp-host/src/db/worker/dispatcher.ts
@@ -10,6 +10,7 @@ import { PreparedStatements, prepareStatements } from '../statements'
import { withBusyRetry } from './busyRetry'
import type {
LoadAllPendingApprovalsRow,
+ ModelSelectionWriteOutcome,
PendingApprovalRow,
PersistedSession,
PersistedSessionMessagePage,
@@ -415,14 +416,70 @@ export async function dispatch(op: WorkerOp, deps: DispatcherDeps): Promise<unkn
case 'update_session_model_selections':
return withBusyRetry(() => {
- const tx = db.transaction(() => {
+ // #654 — compare-and-swap on `model_selection_revision`.
+ //
+ // Read-then-write inside ONE IMMEDIATE transaction. The worker is a
+ // single writer, but another replica may hold the same row, and
+ // `.immediate()` takes the write lock before the read, so no other
+ // process can commit between the check and the update.
+ //
+ // A missing row throws instead of acking: reporting `applied` for a
+ // selection that never reached disk would recreate exactly the
+ // fire-and-forget lie this change removes.
+ const tx = db.transaction((): ModelSelectionWriteOutcome => {
+ const row = s.selectSessionModelSelectionRevision.get({ id: op.sessionId }) as
+ | { model_selection_revision: number; model_selections: string | null }
+ | undefined
+ if (!row) {
+ const err: Error & { code?: string } = new Error(
+ `update_session_model_selections: no session row for id=${op.sessionId}`
+ )
+ err.code = 'MODEL_SELECTION_SESSION_NOT_FOUND'
+ throw err
+ }
+ const current = row.model_selection_revision
+ if (
+ !Number.isSafeInteger(current) ||
+ current < 0 ||
+ current === Number.MAX_SAFE_INTEGER
+ ) {
+ throw new Error('Invalid persisted model selection revision')
+ }
+ let modelSelections: Record<string, string>
+ try {
+ const parsed: unknown =
+ row.model_selections === null ? {} : JSON.parse(row.model_selections)
+ if (
+ !parsed ||
+ typeof parsed !== 'object' ||
+ Array.isArray(parsed) ||
+ Object.values(parsed).some(value => typeof value !== 'string')
+ )
+ throw new Error()
+ modelSelections = { ...parsed } as Record<string, string>
+ } catch {
+ throw new Error('Invalid persisted model selections')
+ }
+ if (op.expectedRevision !== undefined && op.expectedRevision !== current) {
+ return {
+ applied: false,
+ reason: 'model_selection_conflict',
+ modelSelectionRevision: current,
+ modelSelections,
+ }
+ }
+ const next = current + 1
+ // Merge the one requested provider in the durable row, never a stale
+ // full map from another replica's RAM (including legacy writes).
+ modelSelections = { ...modelSelections, [op.provider]: op.model }
s.updateSessionModelSelections.run({
id: op.sessionId,
- model_selections: op.modelSelections,
+ model_selections: JSON.stringify(modelSelections),
+ model_selection_revision: next,
})
+ return { applied: true, modelSelectionRevision: next, modelSelections }
})
- tx.immediate()
- return { ok: true }
+ return tx.immediate()
})
case 'update_session_title':
diff --git a/mcp-host/src/db/worker/protocol.ts b/mcp-host/src/db/worker/protocol.ts
index 8c75a9bfa..475701b02 100644
--- a/mcp-host/src/db/worker/protocol.ts
+++ b/mcp-host/src/db/worker/protocol.ts
@@ -27,6 +27,11 @@ export interface SessionRow {
/** R2 (migration 007) — JSON map `{ provider → model }` of the user's saved
* per-provider model selection. NULL until the first `set-model`. */
model_selections: string | null
+ /** #654 (migration 015) — durable revision of `model_selections`, the
+ * compare-and-swap token for the selection write. Optional on the in-memory
+ * shape because a row built before the first write (or by a fixture) has no
+ * value; readers normalize `undefined` to the column default 0. */
+ model_selection_revision?: number
system_prompt_stable_hash: string | null
parent_session_id: string | null
started_at: number
@@ -124,6 +129,26 @@ export interface PersistedSession {
pending_approval: PendingApprovalRow | null
}
+/**
+ * Durable outcome of one `update_session_model_selections` attempt (issue #654).
+ *
+ * - `applied: true` — the row was written and the revision is now `current + 1`.
+ * - `applied: false` — the caller's `expectedRevision` no longer matched; the row
+ * is UNCHANGED and the reply carries the revision that won, so the caller can
+ * align its in-RAM mirror and retry from the durable value.
+ *
+ * A missing session row is neither: the dispatcher throws, because a selection
+ * that was not written must never be reported as accepted.
+ */
+export type ModelSelectionWriteOutcome =
+ | { applied: true; modelSelectionRevision: number; modelSelections: Record<string, string> }
+ | {
+ applied: false
+ reason: 'model_selection_conflict'
+ modelSelectionRevision: number
+ modelSelections: Record<string, string>
+ }
+
export interface PersistedSessionSummary {
session: SessionRow
last_activity_at: number
@@ -216,11 +241,19 @@ export type WorkerOp =
| { kind: 'update_session_counters'; sessionId: string; counters: SessionCountersUpdate }
| { kind: 'update_session_prompt_stable_hash'; sessionId: string; stableHash: string }
| {
- /** R2 — persist the per-session `{ provider → model }` selection map.
- * `modelSelections` is the already-serialized JSON string. */
+ /** Update one provider in the durable per-session selection map.
+ *
+ * #654 — compare-and-swap. With `expectedRevision` the write lands only
+ * while `model_selection_revision` still equals it; `undefined` is the
+ * legacy unconditional write. BOTH paths increment the revision, so a
+ * straggler carrying an already-superseded value is rejected instead of
+ * overwriting the winner. The reply carries the durable outcome
+ * (`ModelSelectionWriteOutcome`), not just an ack. */
kind: 'update_session_model_selections'
sessionId: string
- modelSelections: string
+ provider: string
+ model: string
+ expectedRevision?: number
}
| {
/** Spec 15 Fase B — overwrite the user-set session title (rename). Unlike
diff --git a/mcp-host/src/llm/__tests__/claudeToolImageWire.test.ts b/mcp-host/src/llm/__tests__/claudeToolImageWire.test.ts
new file mode 100644
index 000000000..f5231e8ad
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/claudeToolImageWire.test.ts
@@ -0,0 +1,300 @@
+/**
+ * Issue #654 — the Claude TOOL role is the one image position that travels
+ * inside a `tool_result` block, and the only reason
+ * `transportSupportsImageInput('claude', <tool-bearing op>, 'tool')` may answer
+ * `true`. `mcp-host/src/llm/__tests__/imageInputTransport.test.ts` proves the
+ * matrix for the ORDINARY `user` role only; this suite proves the tool-role cell
+ * against the REAL `ClaudeProvider` serializer with the Anthropic SDK client
+ * intercepted, so an authorized tool-role image cannot be dropped between the
+ * guard and the wire, and a family that cannot carry it never reaches its SDK.
+ *
+ * Both tool-bearing Claude transports are covered (`completeWithTools` and the
+ * cache-aware `completeWithToolsAndCache`) because the adapter chooses between
+ * them at dispatch time and the chat loop can reach either.
+ *
+ * Coverage note: the loop's only tool-image producer (`appendToolResults` in
+ * `core/orchestration/toolUseLoopMessages.ts`) currently relays collected tool
+ * images on a separate `user` message, so this suite is what keeps the ROLE
+ * MATRIX honest — `IMAGE_ROLES_BY_FAMILY.claude` authorizes `tool`, and the
+ * serializer below really implements it — rather than a description of today's
+ * loop shape.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { LlmPortAdapter } from '../../core/adapters/llmPortAdapter'
+import { LlmError, LlmErrorCode } from '../../core/errors'
+import type { SystemPromptParts } from '../../core/reasoning/systemPrompt'
+import type { ChatMessage } from '../../core/types'
+import { ClaudeProvider } from '../claude'
+import type { ImageInputResolver } from '../imageInput'
+import { OpenAIProvider } from '../openai'
+
+const EVIDENCE = {
+ source: 'curated' as const,
+ reference: 'https://docs.anthropic.com/en/docs/build-with-claude/vision',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+
+/**
+ * Canonical base64 for the bytes `ABC`. Real image bytes are not needed: the
+ * adapter validates the encoding SHAPE, not the image, and these tests assert
+ * structure on the wire. Keeping the fixture canonical keeps the guard's own
+ * validation (which rejects non-canonical base64) out of the assertion path.
+ */
+const IMAGE_B64 = 'QUJD'
+const TOOL_TEXT = 'tool output'
+
+const allowResolver: ImageInputResolver = () => ({
+ capability: { state: 'supported', evidence: EVIDENCE },
+})
+
+function parts(): SystemPromptParts {
+ return { stable: 'stable', context: 'context', stableHash: 'h1', contextHash: 'h2' }
+}
+
+/**
+ * The real Claude tool-call sequence: the user attaches an image, the assistant
+ * asks for a tool, and the tool returns a text block plus an image. The tool
+ * result is the position under test.
+ */
+function toolImageConversation(): ChatMessage[] {
+ return [
+ {
+ role: 'user',
+ content: 'look at this',
+ contentParts: [
+ { type: 'text', text: 'look at this' },
+ { type: 'image', mimeType: 'image/png', data: IMAGE_B64 },
+ ],
+ },
+ {
+ role: 'assistant',
+ content: '',
+ tool_calls: [{ id: 'tc_1', name: 'lookup', arguments: { q: 'x' } }],
+ },
+ {
+ role: 'tool',
+ content: TOOL_TEXT,
+ tool_call_id: 'tc_1',
+ name: 'lookup',
+ contentParts: [
+ { type: 'text', text: TOOL_TEXT },
+ { type: 'image', mimeType: 'image/png', data: IMAGE_B64 },
+ ],
+ },
+ ]
+}
+
+/** The same shape with a text-only tool result (the unchanged ordinary path). */
+function toolTextConversation(): ChatMessage[] {
+ return [
+ { role: 'user', content: 'hello' },
+ {
+ role: 'assistant',
+ content: '',
+ tool_calls: [{ id: 'tc_1', name: 'lookup', arguments: { q: 'x' } }],
+ },
+ { role: 'tool', content: TOOL_TEXT, tool_call_id: 'tc_1', name: 'lookup' },
+ ]
+}
+
+const CLAUDE_OK = {
+ content: [{ type: 'text', text: 'ok' }],
+ stop_reason: 'end_turn',
+ usage: { input_tokens: 1, output_tokens: 1 },
+}
+const OPENAI_OK = {
+ choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+}
+
+type WireBlock = {
+ type: string
+ text?: string
+ tool_use_id?: string
+ content?: WireBlock[] | string
+ source?: { type?: string; media_type?: string; data?: string }
+ cache_control?: unknown
+}
+type WireMessage = { role: string; content: string | WireBlock[] }
+type WirePayload = { messages?: WireMessage[]; system?: WireBlock[] }
+
+function blocksOf(content: string | WireBlock[] | undefined): WireBlock[] | undefined {
+ return Array.isArray(content) ? content : undefined
+}
+
+function wireMessages(wire: unknown): WireMessage[] {
+ return (wire as WirePayload).messages ?? []
+}
+
+/** The `tool_result` blocks on the wire, flattened across messages. */
+function toolResultBlocks(wire: unknown): WireBlock[] {
+ const blocks: WireBlock[] = []
+ for (const message of wireMessages(wire)) {
+ for (const block of blocksOf(message.content) ?? []) {
+ if (block.type === 'tool_result') blocks.push(block)
+ }
+ }
+ return blocks
+}
+
+/** Every `image` block on the wire, at message level or nested in a tool result. */
+function imageBlocks(wire: unknown): WireBlock[] {
+ const blocks: WireBlock[] = []
+ const pushImages = (list: WireBlock[] | undefined): void => {
+ for (const block of list ?? []) if (block.type === 'image') blocks.push(block)
+ }
+ for (const message of wireMessages(wire)) {
+ const content = blocksOf(message.content)
+ pushImages(content)
+ for (const block of content ?? []) {
+ if (block.type === 'tool_result') pushImages(blocksOf(block.content))
+ }
+ }
+ return blocks
+}
+
+function claudeAdapter(
+ create: ReturnType<typeof vi.fn>,
+ model: string,
+ resolver: ImageInputResolver
+): { adapter: LlmPortAdapter; provider: ClaudeProvider } {
+ const provider = new ClaudeProvider({ messages: { create } } as never, model)
+ const adapter = new LlmPortAdapter(
+ provider,
+ model,
+ 'claude',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ resolver
+ )
+ return { adapter, provider }
+}
+
+describe('#654 Claude tool-role image serialization (real serializer)', () => {
+ it('carries the tool image inside a tool_result block through completeWithTools', async () => {
+ const create = vi.fn(async (_input: unknown) => CLAUDE_OK)
+ const resolver = vi.fn(allowResolver)
+ const { adapter } = claudeAdapter(create, 'claude-sonnet-4-6', resolver)
+
+ await adapter.completeWithTools({ messages: toolImageConversation(), tools: [] })
+
+ // The guard ran against the real pair…
+ expect(resolver).toHaveBeenCalledWith('claude', 'claude-sonnet-4-6')
+ // …the image was NOT silently removed…
+ expect(create).toHaveBeenCalledTimes(1)
+ const wire = create.mock.calls[0]?.[0]
+
+ const toolResults = toolResultBlocks(wire)
+ expect(toolResults).toHaveLength(1)
+ expect(toolResults[0].tool_use_id).toBe('tc_1')
+ // …and the tool result really is the multi-block form, not the string form.
+ expect(toolResults[0].content).toEqual([
+ { type: 'text', text: TOOL_TEXT },
+ { type: 'image', source: { type: 'base64', media_type: 'image/png', data: IMAGE_B64 } },
+ ])
+
+ // The user-role image from the same request is present too, so the
+ // assertion above is about the tool block rather than an empty request.
+ expect(imageBlocks(wire)).toHaveLength(2)
+ })
+
+ it('carries the tool image through the cache-aware tool method and keeps cache_control', async () => {
+ const create = vi.fn(async (_input: unknown) => CLAUDE_OK)
+ const { adapter, provider } = claudeAdapter(create, 'claude-sonnet-4-6', allowResolver)
+ const cacheSpy = vi.spyOn(provider, 'completeSingleTurnWithToolsAndCache')
+ const legacySpy = vi.spyOn(provider, 'completeSingleTurnWithTools')
+
+ await adapter.completeWithTools({
+ messages: toolImageConversation(),
+ tools: [],
+ systemPromptParts: parts(),
+ })
+
+ // The cache-aware arm is the one that really ran…
+ expect(cacheSpy).toHaveBeenCalledTimes(1)
+ expect(legacySpy).not.toHaveBeenCalled()
+
+ const wire = create.mock.calls[0]?.[0]
+ // …it still emits the tool_result image…
+ expect(toolResultBlocks(wire)).toHaveLength(1)
+ expect(imageBlocks(wire)).toHaveLength(2)
+ // …and it kept the cache markers that distinguish it from the legacy path.
+ const system = (wire as WirePayload).system ?? []
+ expect(system.length).toBeGreaterThan(0)
+ expect(system.every(block => block.cache_control)).toBe(true)
+ })
+
+ it('refuses a tool-role image on a family whose wire has no tool-image position', async () => {
+ const create = vi.fn(async (_input: unknown) => OPENAI_OK)
+ const provider = new OpenAIProvider({ chat: { completions: { create } } } as never, 'gpt-4o')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'gpt-4o',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allowResolver
+ )
+
+ await expect(
+ adapter.completeWithTools({ messages: toolImageConversation(), tools: [] })
+ ).rejects.toMatchObject({
+ code: LlmErrorCode.ImageInputUnsupported,
+ retryable: false,
+ provider: 'openai',
+ })
+ // Role admission is a real decision, not a label: nothing reached the SDK.
+ expect(create).not.toHaveBeenCalled()
+ })
+
+ it('keeps a text-only tool result in the plain string form (the branch images change)', async () => {
+ const create = vi.fn(async (_input: unknown) => CLAUDE_OK)
+ const { adapter } = claudeAdapter(create, 'claude-sonnet-4-6', allowResolver)
+
+ await adapter.completeWithTools({ messages: toolTextConversation(), tools: [] })
+
+ const toolResults = toolResultBlocks(create.mock.calls[0]?.[0])
+ expect(toolResults).toHaveLength(1)
+ // Without `contentParts` the serializer keeps `msg.content`, which is what
+ // makes the array form above evidence of the image path specifically.
+ expect(toolResults[0].content).toBe(TOOL_TEXT)
+ expect(imageBlocks(create.mock.calls[0]?.[0])).toHaveLength(0)
+ })
+
+ it('surfaces the denial as a typed terminal error and never classifies it', async () => {
+ // The refusal must not be handed to `classifyError`, which would make it
+ // retryable and turn one rejected image into a retry storm.
+ const create = vi.fn(async (_input: unknown) => CLAUDE_OK)
+ const provider = new ClaudeProvider({ messages: { create } } as never, 'claude-sonnet-4-6')
+ const classifyError = vi.spyOn(provider, 'classifyError')
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'claude-sonnet-4-6',
+ 'claude',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => ({ capability: { state: 'unsupported', evidence: EVIDENCE } })
+ )
+
+ let error: unknown
+ try {
+ await adapter.completeWithTools({ messages: toolImageConversation(), tools: [] })
+ } catch (err) {
+ error = err
+ }
+ expect(error).toBeInstanceOf(LlmError)
+ expect((error as LlmError).retryable).toBe(false)
+ expect((error as LlmError).code).toBe(LlmErrorCode.ImageInputUnsupported)
+ expect(classifyError).not.toHaveBeenCalled()
+ expect(create).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/imageInput.test.ts b/mcp-host/src/llm/__tests__/imageInput.test.ts
new file mode 100644
index 000000000..e914e9b33
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/imageInput.test.ts
@@ -0,0 +1,322 @@
+/**
+ * Issue #654 — host image-input helper: transport/role matrix, the pure
+ * intersection, and the operator-facing denial text.
+ */
+import { describe, expect, it } from 'vitest'
+import type { ChatMessage, MessageRole } from '../../core/types'
+import {
+ type ImageTransportOperation,
+ chatTransportSupportsImageInput,
+ decideImageInput,
+ imageInputDenialMessage,
+ imageInputRolesFor,
+ imageWireFamilyFor,
+ transportSupportsImageInput,
+} from '../imageInput'
+import { ALL_PROVIDERS, descriptorFor, isLlmProvider } from '../registryCore'
+
+const METHODS: ImageTransportOperation[] = [
+ 'complete',
+ 'completeWithTools',
+ 'completeAndCache',
+ 'completeWithToolsAndCache',
+]
+
+/** The transport baseline from plan §4.1, restated so a silent edit fails here. */
+const EXPECTED_MATRIX: Record<string, Record<ImageTransportOperation, boolean>> = {
+ openai: {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ zai: {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ azure: {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ claude: {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: true,
+ completeWithToolsAndCache: true,
+ },
+ vertex: {
+ complete: true,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ bedrock: {
+ complete: true,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ 'codex-subscription': {
+ complete: false,
+ completeWithTools: false,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+}
+
+function userImageMessage(): ChatMessage {
+ return {
+ role: 'user',
+ content: 'what is in this image?',
+ contentParts: [
+ { type: 'text', text: 'what is in this image?' },
+ { type: 'image', mimeType: 'image/png', data: 'AAAA' },
+ ],
+ }
+}
+
+const supported = {
+ state: 'supported' as const,
+ evidence: {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+ },
+}
+
+/** Role support, observed through the one public decision on the chat method. */
+function roleReason(providerType: string, role: MessageRole) {
+ return decideImageInput({
+ providerType,
+ method: 'completeWithTools',
+ roles: [role],
+ capability: supported,
+ }).reason
+}
+
+describe('#654 transport matrix', () => {
+ it('matches the documented baseline for every provider family', () => {
+ for (const [provider, expected] of Object.entries(EXPECTED_MATRIX)) {
+ for (const method of METHODS) {
+ expect(`${provider}/${method}=${transportSupportsImageInput(provider, method)}`).toBe(
+ `${provider}/${method}=${expected[method]}`
+ )
+ }
+ }
+ })
+
+ it('folds the role into the selector', () => {
+ expect(transportSupportsImageInput('openai', 'completeWithTools')).toBe(true)
+ expect(transportSupportsImageInput('openai', 'completeWithTools', 'tool')).toBe(false)
+ expect(transportSupportsImageInput('claude', 'completeWithToolsAndCache', 'tool')).toBe(true)
+ expect(transportSupportsImageInput('bedrock', 'complete', 'user')).toBe(true)
+ expect(transportSupportsImageInput('bedrock', 'complete', 'assistant')).toBe(false)
+ })
+
+ it('pins explicit factory arms and derives the data-driven arm from the descriptor', () => {
+ expect(imageWireFamilyFor('openai')).toBe('openai-compatible')
+ expect(imageWireFamilyFor('azure')).toBe('openai-compatible')
+ expect(imageWireFamilyFor('zai')).toBe('openai-compatible')
+ expect(imageWireFamilyFor('claude')).toBe('claude')
+ expect(imageWireFamilyFor('codex-subscription')).toBe('codex')
+ })
+
+ it('authorizes NO transport for an unregistered or invented provider id', () => {
+ expect(isLlmProvider('some-future-provider')).toBe(false)
+ expect(imageWireFamilyFor('some-future-provider')).toBe('unregistered')
+ for (const operation of METHODS) {
+ expect(transportSupportsImageInput('some-future-provider', operation)).toBe(false)
+ expect(transportSupportsImageInput('', operation)).toBe(false)
+ }
+ expect(chatTransportSupportsImageInput('some-future-provider')).toBe(false)
+ expect(roleReason('some-future-provider', 'user')).toBe('transport_unsupported')
+ })
+
+ it('never authorizes a registered provider that has no real factory coverage', () => {
+ // The data-driven arm requires a baseURL; without one `makeProvider` throws,
+ // so the projection must not promise images for it either.
+ for (const provider of ALL_PROVIDERS) {
+ const authorized = chatTransportSupportsImageInput(provider)
+ if (!authorized) continue
+ const hasDescriptorBaseURL = Boolean(descriptorFor(provider).baseURL)
+ const isExplicitArm = ['openai', 'azure', 'claude', 'vertex', 'bedrock'].includes(provider)
+ // `provider` is interpolated into the assertion message by the expect
+ // failure, so a future divergent provider that inherits coverage fails
+ // here with its own id.
+ expect(hasDescriptorBaseURL || isExplicitArm).toBe(true)
+ }
+ expect(chatTransportSupportsImageInput('codex-subscription')).toBe(false)
+ })
+
+ it('projects the CHAT operation as tool-bearing, never as the tool-less plain path', () => {
+ // The loop always dispatches completeWithTools (empty array included).
+ expect(chatTransportSupportsImageInput('openai')).toBe(true)
+ expect(chatTransportSupportsImageInput('claude')).toBe(true)
+ expect(chatTransportSupportsImageInput('vertex')).toBe(true)
+ expect(chatTransportSupportsImageInput('bedrock')).toBe(true)
+ // #650 not landed: Codex cannot carry images anywhere yet.
+ expect(chatTransportSupportsImageInput('codex-subscription')).toBe(false)
+ })
+
+ it('rejects assistant/system images and honors per-family role support', () => {
+ expect(roleReason('openai', 'user')).toBe('supported')
+ expect(roleReason('openai', 'tool')).toBe('transport_unsupported')
+ expect(roleReason('claude', 'tool')).toBe('supported')
+ expect(roleReason('claude', 'assistant')).toBe('transport_unsupported')
+ expect(roleReason('vertex', 'assistant')).toBe('transport_unsupported')
+ expect(roleReason('codex-subscription', 'user')).toBe('transport_unsupported')
+ })
+})
+
+describe('#654 imageInputRolesFor', () => {
+ it('returns [] for text-only requests and the unique image-bearing roles otherwise', () => {
+ expect(imageInputRolesFor([{ role: 'user', content: 'hi' }])).toEqual([])
+ expect(imageInputRolesFor([userImageMessage()])).toEqual(['user'])
+ expect(
+ imageInputRolesFor([
+ userImageMessage(),
+ {
+ role: 'user',
+ content: 'again',
+ contentParts: [{ type: 'image', mimeType: 'image/jpeg', data: 'BB' }],
+ },
+ {
+ role: 'tool',
+ content: 'x',
+ contentParts: [{ type: 'image', mimeType: 'image/png', data: 'CC' }],
+ },
+ ])
+ ).toEqual(['user', 'tool'])
+ // A text-only content part on a message is not an image.
+ expect(
+ imageInputRolesFor([
+ { role: 'user', content: 'hi', contentParts: [{ type: 'text', text: 'hi' }] },
+ ])
+ ).toEqual([])
+ })
+})
+
+describe('#654 decideImageInput intersection', () => {
+ it('is supported only when evidence, transport and role are all affirmative', () => {
+ expect(
+ decideImageInput({
+ providerType: 'openai',
+ method: 'completeWithTools',
+ roles: ['user'],
+ capability: supported,
+ })
+ ).toEqual({ state: 'supported', reason: 'supported', evidence: supported.evidence })
+ })
+
+ it('keeps `plain` unsupported even when the model evidence says supported', () => {
+ // This is the fail-closed cell: the serializer would drop the image.
+ expect(
+ decideImageInput({
+ providerType: 'openai',
+ method: 'complete',
+ roles: ['user'],
+ capability: supported,
+ })
+ ).toEqual({
+ state: 'unsupported',
+ reason: 'transport_unsupported',
+ evidence: supported.evidence,
+ })
+ })
+
+ it('rejects an image on a role the wire family cannot carry', () => {
+ expect(
+ decideImageInput({
+ providerType: 'openai',
+ method: 'completeWithTools',
+ roles: ['tool'],
+ capability: supported,
+ })
+ ).toEqual({
+ state: 'unsupported',
+ reason: 'transport_unsupported',
+ evidence: supported.evidence,
+ })
+ expect(
+ decideImageInput({
+ providerType: 'claude',
+ method: 'completeWithToolsAndCache',
+ roles: ['tool'],
+ capability: supported,
+ })
+ ).toEqual({ state: 'supported', reason: 'supported', evidence: supported.evidence })
+ })
+
+ it('treats absent or malformed evidence as unknown, never as support', () => {
+ for (const capability of [undefined, null, {}, { state: 'maybe' }, { state: 'supported' }]) {
+ expect(
+ decideImageInput({
+ providerType: 'openai',
+ method: 'completeWithTools',
+ roles: ['user'],
+ capability,
+ })
+ ).toEqual({ state: 'unknown', reason: 'model_unknown' })
+ }
+ })
+
+ it('evaluates freshness against an injected clock', () => {
+ const expiring = {
+ state: 'supported' as const,
+ evidence: {
+ source: 'discovery' as const,
+ reference: 'evidence:models-dev/glm-5.3-flash',
+ checkedAt: '2026-09-01T00:00:00Z',
+ validUntil: '2026-10-01T00:00:00Z',
+ },
+ }
+ const before = Date.parse('2026-09-16T00:00:00Z')
+ expect(
+ decideImageInput({
+ providerType: 'zai',
+ method: 'completeWithTools',
+ roles: ['user'],
+ capability: expiring,
+ now: before,
+ }).state
+ ).toBe('supported')
+ expect(
+ decideImageInput({
+ providerType: 'zai',
+ method: 'completeWithTools',
+ roles: ['user'],
+ capability: expiring,
+ now: Date.parse('2026-10-02T00:00:00Z'),
+ })
+ ).toEqual({
+ state: 'unknown',
+ reason: 'evidence_expired',
+ validUntil: '2026-10-01T00:00:00Z',
+ evidence: expiring.evidence,
+ })
+ })
+})
+
+describe('#654 denial messages', () => {
+ it('names the real pair and states that the rest of the message was not sent', () => {
+ for (const reason of [
+ 'transport_unsupported',
+ 'model_unsupported',
+ 'model_unknown',
+ 'evidence_expired',
+ 'evidence_not_yet_valid',
+ ] as const) {
+ const message = imageInputDenialMessage(
+ { state: reason === 'model_unsupported' ? 'unsupported' : 'unknown', reason },
+ { provider: 'zai', model: 'glm-5.3' }
+ )
+ expect(message).toContain('zai/glm-5.3')
+ expect(message).toContain('not sent to the provider')
+ expect(message).not.toContain('base64')
+ }
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/imageInputTransport.test.ts b/mcp-host/src/llm/__tests__/imageInputTransport.test.ts
new file mode 100644
index 000000000..c8da052ad
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/imageInputTransport.test.ts
@@ -0,0 +1,391 @@
+/**
+ * Issue #654 — cross-suite guard for the transport matrix.
+ *
+ * Uses the REAL provider implementations with their SDK clients intercepted, so
+ * every cell the guard labels image-capable is proven by the serializer that
+ * actually runs. A cell that says "supported" but drops the part on the wire, or
+ * an "unsupported" cell that silently reaches the SDK, fails here.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { LlmPortAdapter } from '../../core/adapters/llmPortAdapter'
+import { LlmError, LlmErrorCode } from '../../core/errors'
+import type { SystemPromptParts } from '../../core/reasoning/systemPrompt'
+import { type ChatMessage, FinishReason } from '../../core/types'
+import { ClaudeProvider } from '../claude'
+import { type BedrockConverseClient, BedrockConverseDriver } from '../drivers/bedrockConverse'
+import { type GeminiGenerateClient, GoogleGenerativeDriver } from '../drivers/googleGenerative'
+import type { ImageInputResolver, ImageTransportOperation } from '../imageInput'
+import { OpenAIProvider } from '../openai'
+import { OpenAICompatibleProvider } from '../openaiCompatible'
+import type { ClassifiedError, SingleTurnProvider } from '../types'
+
+const EVIDENCE = {
+ source: 'curated' as const,
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+
+const allowResolver: ImageInputResolver = () => ({
+ capability: { state: 'supported', evidence: EVIDENCE },
+})
+
+function parts(): SystemPromptParts {
+ return { stable: 'stable', context: 'context', stableHash: 'h1', contextHash: 'h2' }
+}
+
+function imageMessage(): ChatMessage {
+ return {
+ role: 'user',
+ content: 'what does this picture show?',
+ contentParts: [
+ { type: 'text', text: 'what does this picture show?' },
+ { type: 'image', mimeType: 'image/png', data: 'QUJD' },
+ ],
+ }
+}
+
+const OPENAI_OK = {
+ choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+}
+const CLAUDE_OK = {
+ content: [{ type: 'text', text: 'ok' }],
+ stop_reason: 'end_turn',
+ usage: { input_tokens: 1, output_tokens: 1 },
+}
+const GEMINI_OK = {
+ candidates: [{ content: { parts: [{ text: 'ok' }] }, finishReason: 'STOP' }],
+ usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1, totalTokenCount: 2 },
+}
+const BEDROCK_OK = {
+ output: { message: { content: [{ text: 'ok' }] } },
+ stopReason: 'end_turn',
+ usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+}
+
+type Family = 'openai-compatible' | 'claude' | 'vertex' | 'bedrock' | 'codex'
+
+interface Harness {
+ provider: SingleTurnProvider
+ /** Number of SDK calls that left the process boundary. */
+ sdkCalls: () => number
+ /** The last wire payload handed to the SDK, or undefined. */
+ wire: () => unknown
+}
+
+function buildHarness(family: Family): Harness {
+ switch (family) {
+ case 'openai-compatible': {
+ const create = vi.fn(async (_input: unknown) => OPENAI_OK)
+ const provider = new OpenAIProvider({ chat: { completions: { create } } } as never, 'gpt-4o')
+ return {
+ provider,
+ sdkCalls: () => create.mock.calls.length,
+ wire: () => create.mock.calls[0]?.[0],
+ }
+ }
+ case 'claude': {
+ const create = vi.fn(async (_input: unknown) => CLAUDE_OK)
+ const provider = new ClaudeProvider({ messages: { create } } as never, 'claude-sonnet-4-6')
+ return {
+ provider,
+ sdkCalls: () => create.mock.calls.length,
+ wire: () => create.mock.calls[0]?.[0],
+ }
+ }
+ case 'vertex': {
+ const generateContent = vi.fn(async (_input: unknown) => GEMINI_OK)
+ const client = { generateContent } as unknown as GeminiGenerateClient
+ const provider = new GoogleGenerativeDriver(client, 'gemini-2.5-pro')
+ return {
+ provider,
+ sdkCalls: () => generateContent.mock.calls.length,
+ wire: () => generateContent.mock.calls[0]?.[0],
+ }
+ }
+ case 'bedrock': {
+ const converse = vi.fn(async (_input: unknown) => BEDROCK_OK)
+ const client = { converse } as unknown as BedrockConverseClient
+ const provider = new BedrockConverseDriver(client, 'anthropic.claude-sonnet-4-6-v1:0')
+ return {
+ provider,
+ sdkCalls: () => converse.mock.calls.length,
+ wire: () => converse.mock.calls[0]?.[0],
+ }
+ }
+ case 'codex': {
+ const textOk = {
+ content: 'ok',
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ finish_reason: FinishReason.Stop,
+ }
+ const withTools = vi.fn(async () => ({ ...textOk, tool_calls: [] }))
+ const single = vi.fn(async () => textOk)
+ const provider = {
+ completeSingleTurn: single,
+ completeSingleTurnWithTools: withTools,
+ getProviderType: () => 'codex-subscription' as const,
+ classifyError: (err: unknown): ClassifiedError => ({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: true,
+ message: (err as Error).message,
+ }),
+ } as unknown as SingleTurnProvider
+ return {
+ provider,
+ sdkCalls: () => single.mock.calls.length + withTools.mock.calls.length,
+ wire: () => undefined,
+ }
+ }
+ }
+}
+
+/** Structural image-presence check per wire family. */
+function wireHasImage(family: Family, wire: unknown): boolean {
+ const payload = wire as {
+ messages?: Array<{ content?: unknown }>
+ contents?: Array<{ parts?: Array<{ inlineData?: unknown }> }>
+ }
+ switch (family) {
+ case 'openai-compatible':
+ return Boolean(
+ payload.messages?.some(
+ m =>
+ Array.isArray(m.content) &&
+ (m.content as Array<{ type?: string }>).some(p => p.type === 'image_url')
+ )
+ )
+ case 'claude':
+ return Boolean(
+ payload.messages?.some(
+ m =>
+ Array.isArray(m.content) &&
+ (m.content as Array<{ type?: string }>).some(p => p.type === 'image')
+ )
+ )
+ case 'vertex':
+ return Boolean(payload.contents?.some(c => c.parts?.some(p => p.inlineData !== undefined)))
+ case 'bedrock':
+ return Boolean(
+ payload.messages?.some(
+ m =>
+ Array.isArray(m.content) &&
+ (m.content as Array<Record<string, unknown>>).some(b => 'image' in b)
+ )
+ )
+ case 'codex':
+ return false
+ }
+}
+
+/** Representative REGISTERED provider id for each family (never a family name). */
+function providerIdFor(family: Family): string {
+ switch (family) {
+ case 'openai-compatible':
+ return 'openai'
+ case 'claude':
+ return 'claude'
+ case 'vertex':
+ return 'vertex'
+ case 'bedrock':
+ return 'bedrock'
+ case 'codex':
+ return 'codex-subscription'
+ }
+}
+
+function modelFor(family: Family): string {
+ switch (family) {
+ case 'openai-compatible':
+ return 'gpt-4o'
+ case 'claude':
+ return 'claude-sonnet-4-6'
+ case 'vertex':
+ return 'gemini-2.5-pro'
+ case 'bedrock':
+ return 'anthropic.claude-sonnet-4-6-v1:0'
+ case 'codex':
+ return 'gpt-5.3-codex'
+ }
+}
+
+function adapterFor(harness: Harness, family: Family): LlmPortAdapter {
+ return new LlmPortAdapter(
+ harness.provider,
+ modelFor(family),
+ providerIdFor(family),
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allowResolver
+ )
+}
+
+/** Dispatch the operation the way the real call sites do. */
+async function dispatch(
+ adapter: LlmPortAdapter,
+ operation: ImageTransportOperation,
+ messages: ChatMessage[]
+): Promise<void> {
+ switch (operation) {
+ case 'complete':
+ await adapter.complete({ messages })
+ return
+ case 'completeWithTools':
+ await adapter.completeWithTools({ messages, tools: [] })
+ return
+ case 'completeAndCache':
+ await adapter.complete({ messages, systemPromptParts: parts() })
+ return
+ case 'completeWithToolsAndCache':
+ await adapter.completeWithTools({ messages, tools: [], systemPromptParts: parts() })
+ }
+}
+
+/** Cells each family can really reach through the adapter. */
+const REACHABLE: Record<Family, ImageTransportOperation[]> = {
+ 'openai-compatible': ['complete', 'completeWithTools'],
+ claude: ['complete', 'completeWithTools', 'completeAndCache', 'completeWithToolsAndCache'],
+ vertex: ['complete', 'completeWithTools'],
+ bedrock: ['complete', 'completeWithTools'],
+ codex: ['complete', 'completeWithTools'],
+}
+
+/** Expected outcome, restated from plan §4.1 (not imported from the module). */
+function expectedSupported(family: Family, operation: ImageTransportOperation): boolean {
+ if (family === 'codex') return false
+ if (operation === 'complete') return family === 'vertex' || family === 'bedrock'
+ if (operation === 'completeWithTools') return true
+ return family === 'claude'
+}
+
+const FAMILIES: Family[] = ['openai-compatible', 'claude', 'vertex', 'bedrock', 'codex']
+
+describe('#654 transport cross-suite (real serializers)', () => {
+ for (const family of FAMILIES) {
+ for (const operation of REACHABLE[family]) {
+ const supported = expectedSupported(family, operation)
+ it(`${family}/${operation} → ${supported ? 'keeps the image on the wire' : 'never reaches the SDK'}`, async () => {
+ const harness = buildHarness(family)
+ const adapter = adapterFor(harness, family)
+
+ if (supported) {
+ await dispatch(adapter, operation, [imageMessage()])
+ expect(harness.sdkCalls()).toBe(1)
+ expect(wireHasImage(family, harness.wire())).toBe(true)
+ } else {
+ await expect(dispatch(adapter, operation, [imageMessage()])).rejects.toBeInstanceOf(
+ LlmError
+ )
+ expect(harness.sdkCalls()).toBe(0)
+ }
+ })
+ }
+ }
+
+ it('text-only traffic is dispatched unchanged on every family', async () => {
+ for (const family of FAMILIES) {
+ const harness = buildHarness(family)
+ const adapter = adapterFor(harness, family)
+ await adapter.completeWithTools({ messages: [{ role: 'user', content: 'hi' }], tools: [] })
+ expect(harness.sdkCalls()).toBe(1)
+ }
+ })
+
+ it('counterfactual: the tool-less path really drops the part (so the cell is not a guess)', async () => {
+ // OpenAI: completeSingleTurn rebuilds role/content and loses contentParts.
+ const openaiHarness = buildHarness('openai-compatible')
+ await openaiHarness.provider.completeSingleTurn([imageMessage()])
+ expect(openaiHarness.sdkCalls()).toBe(1)
+ expect(wireHasImage('openai-compatible', openaiHarness.wire())).toBe(false)
+
+ // Claude: the tool-less variant does the same.
+ const claudeHarness = buildHarness('claude')
+ await claudeHarness.provider.completeSingleTurn([imageMessage()])
+ expect(claudeHarness.sdkCalls()).toBe(1)
+ expect(wireHasImage('claude', claudeHarness.wire())).toBe(false)
+ })
+
+ it('counterfactual: the tool-bearing paths really preserve the part', async () => {
+ for (const family of ['openai-compatible', 'claude', 'vertex', 'bedrock'] as Family[]) {
+ const harness = buildHarness(family)
+ await harness.provider.completeSingleTurnWithTools([imageMessage()], [])
+ expect(harness.sdkCalls()).toBe(1)
+ expect(wireHasImage(family, harness.wire())).toBe(true)
+ }
+ })
+
+ it('names the pair that would have been called in the refusal', async () => {
+ const harness = buildHarness('codex')
+ const adapter = adapterFor(harness, 'codex')
+ await expect(
+ adapter.completeWithTools({ messages: [imageMessage()], tools: [] })
+ ).rejects.toMatchObject({
+ code: LlmErrorCode.ImageInputUnsupported,
+ retryable: false,
+ provider: 'codex-subscription',
+ })
+ })
+
+ it('does not leak image bytes or base64 into the refusal message', async () => {
+ const harness = buildHarness('openai-compatible')
+ const adapter = new LlmPortAdapter(
+ harness.provider,
+ 'glm-5.3',
+ 'zai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => ({
+ capability: { state: 'unsupported', evidence: EVIDENCE },
+ })
+ )
+ let error: LlmError | undefined
+ try {
+ await adapter.completeWithTools({ messages: [imageMessage()], tools: [] })
+ } catch (err) {
+ error = err as LlmError
+ }
+ expect(error).toBeInstanceOf(LlmError)
+ expect(error!.message).not.toContain('QUJD')
+ expect(error!.message).not.toContain('base64')
+ })
+
+ it('the data-driven compatible arm shares the proven serializer (real subclass, stub transport)', async () => {
+ // `OpenAICompatibleProvider` builds its own SDK client, so the client field is
+ // swapped for a stub AFTER construction: the class, its provider id and every
+ // serializer it runs are the production ones.
+ const provider = new OpenAICompatibleProvider(
+ { id: 'zai', baseURL: 'https://api.z.ai/api/coding/paas/v4', defaultModel: 'glm-5.3-flash' },
+ 'fake-key',
+ 'glm-5.3-flash'
+ )
+ const create = vi.fn(async (_input: unknown) => OPENAI_OK)
+ ;(provider as unknown as { client: unknown }).client = {
+ chat: { completions: { create } },
+ }
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'glm-5.3-flash',
+ 'zai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allowResolver
+ )
+
+ await adapter.completeWithTools({ messages: [imageMessage()], tools: [] })
+ expect(create).toHaveBeenCalledTimes(1)
+ expect(wireHasImage('openai-compatible', create.mock.calls[0]?.[0])).toBe(true)
+
+ // The tool-less path is still refused, so Flash cannot be attached for a
+ // `complete` call by accident.
+ await expect(adapter.complete({ messages: [imageMessage()] })).rejects.toBeInstanceOf(LlmError)
+ })
+})
diff --git a/mcp-host/src/llm/imageInput.ts b/mcp-host/src/llm/imageInput.ts
new file mode 100644
index 000000000..a648c04d9
--- /dev/null
+++ b/mcp-host/src/llm/imageInput.ts
@@ -0,0 +1,286 @@
+/**
+ * Issue #654 — host-side image-input enforcement.
+ *
+ * The shared package (`@clerum/llm-providers`) owns the model-evidence contract
+ * (`ImageInputCapability`) and the pure intersection
+ * (`resolveImageInputCapability`). This module owns the HOST half:
+ *
+ * 1. which transport implementation + message role can carry an image for a
+ * given provider, and
+ * 2. the injected resolver contract that lets the live catalog answer
+ * "what does the catalog say for (provider, model)?".
+ *
+ * Transport baseline (observed LOCAL serialization, not a model-capability
+ * proof and not an account authorization):
+ *
+ * family complete completeWithTools …AndCache image roles
+ * openai-compatible no yes n/a user
+ * claude no yes yes user, tool
+ * vertex yes yes n/a user
+ * bedrock yes yes n/a user
+ * codex-subscription no no n/a none
+ *
+ * `complete` is the tool-less, cache-less path (`completeSingleTurn`): OpenAI,
+ * OpenAI-compatible and Azure rebuild `role/content` and drop `contentParts`,
+ * so an image there is lost rather than rejected. `#653` owns fixing that path;
+ * until then this module reports it as not image-capable so the guard fails
+ * closed instead of silently dropping the image.
+ */
+import { type ImageInputDecision, resolveImageInputCapability } from '@clerum/llm-providers'
+import type { ChatMessage, MessageRole } from '../core/types'
+import { descriptorFor, isLlmProvider } from './registryCore'
+
+/**
+ * The only image media types the Host accepts on the wire. Both the admission
+ * boundary and the adapter guard read this list, so a new type is enabled in
+ * one place instead of two inline literals drifting apart.
+ */
+export const IMAGE_ATTACHMENT_MIME_TYPES = ['image/jpeg', 'image/png'] as const
+
+export type ImageAttachmentMimeType = (typeof IMAGE_ATTACHMENT_MIME_TYPES)[number]
+
+export function isImageAttachmentMime(value: unknown): value is ImageAttachmentMimeType {
+ return (
+ typeof value === 'string' && (IMAGE_ATTACHMENT_MIME_TYPES as readonly string[]).includes(value)
+ )
+}
+
+/**
+ * Canonical-base64 shape check that stays linear in V8.
+ *
+ * The grouped-quantifier form `(?:[A-Za-z0-9+/]{4})*` allocates one backtrack
+ * frame per group and throws `RangeError: Maximum call stack size exceeded`
+ * above ~4.47M characters — roughly a 3.2 MiB image, well inside the sizes this
+ * Host accepts. `gfs-controller/src/api/serve.ts` already carries the same fix.
+ * Length-mod-4 plus an unanchored character class decides the same shapes
+ * without backtracking; the decode round-trip at the admission boundary remains
+ * the authority on non-canonical padding bits.
+ */
+export function isCanonicalBase64Shape(data: string): boolean {
+ return data.length > 0 && data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(data)
+}
+
+/**
+ * The transport operation a request is about to use, named after the adapter
+ * dispatch path (`complete`, `completeWithTools` and their `…AndCache`
+ * variants), which maps 1:1 onto the `SingleTurnProvider` `completeSingleTurn*`
+ * methods.
+ */
+export type ImageTransportOperation =
+ | 'complete'
+ | 'completeWithTools'
+ | 'completeAndCache'
+ | 'completeWithToolsAndCache'
+
+/** Wire family — the unit that actually owns image serialization behavior. */
+export type ImageWireFamily =
+ | 'openai-compatible'
+ | 'claude'
+ | 'vertex'
+ | 'bedrock'
+ | 'codex'
+ /**
+ * No covered serializer exists for this id (unknown string, or a registered
+ * provider with no factory arm we have proven). Every capability answer is
+ * `false`, so a future divergent driver can never inherit OpenAI-compatible
+ * coverage by accident.
+ */
+ | 'unregistered'
+
+/**
+ * Providers the factory (`registry.ts:makeProvider`) builds through an EXPLICIT
+ * arm. These are the only ids whose serializer is pinned by provider id; every
+ * other registered id must carry a real `baseURL` to reach the data-driven
+ * OpenAI-compatible arm, and anything else gets no coverage at all.
+ */
+const EXPLICIT_DRIVER_FAMILY: Readonly<Record<string, ImageWireFamily>> = {
+ openai: 'openai-compatible',
+ claude: 'claude',
+ vertex: 'vertex',
+ bedrock: 'bedrock',
+ azure: 'openai-compatible',
+ 'codex-subscription': 'codex',
+}
+
+export function imageWireFamilyFor(providerType: string): ImageWireFamily {
+ const explicit = EXPLICIT_DRIVER_FAMILY[providerType]
+ if (explicit) return explicit
+ if (!isLlmProvider(providerType)) return 'unregistered'
+ // Data-driven arm: a registered provider is built as an OpenAI-compatible
+ // client only when its descriptor really carries a baseURL. Anything else
+ // makes `makeProvider` throw, so it is not authorized here either.
+ return descriptorFor(providerType).baseURL ? 'openai-compatible' : 'unregistered'
+}
+
+const TRANSPORT_SUPPORT: Readonly<
+ Record<ImageWireFamily, Readonly<Record<ImageTransportOperation, boolean>>>
+> = {
+ 'openai-compatible': {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ claude: {
+ complete: false,
+ completeWithTools: true,
+ completeAndCache: true,
+ completeWithToolsAndCache: true,
+ },
+ vertex: {
+ complete: true,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ bedrock: {
+ complete: true,
+ completeWithTools: true,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ codex: {
+ complete: false,
+ completeWithTools: false,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+ unregistered: {
+ complete: false,
+ completeWithTools: false,
+ completeAndCache: false,
+ completeWithToolsAndCache: false,
+ },
+}
+
+const IMAGE_ROLES_BY_FAMILY: Readonly<Record<ImageWireFamily, readonly MessageRole[]>> = {
+ 'openai-compatible': ['user'],
+ claude: ['user', 'tool'],
+ vertex: ['user'],
+ bedrock: ['user'],
+ codex: [],
+ unregistered: [],
+}
+
+/**
+ * True when `operation` on `providerType` preserves the image part on the wire
+ * for `role` (default `user`, the ordinary composer case).
+ *
+ * The answer is a property of the implementing serializer, never of the model
+ * name or of OpenAI compatibility, so `/models` can project it directly.
+ */
+export function transportSupportsImageInput(
+ providerType: string,
+ operation: ImageTransportOperation,
+ role: MessageRole = 'user'
+): boolean {
+ const family = imageWireFamilyFor(providerType)
+ return TRANSPORT_SUPPORT[family][operation] && IMAGE_ROLES_BY_FAMILY[family].includes(role)
+}
+
+/**
+ * Projection for the host `/models` wire: can the CHAT operation carry images?
+ *
+ * The reasoning port dispatches `completeWithTools` (`core/reasoning/port.ts`)
+ * — with an empty tool array when no tools are registered — and the adapter
+ * selects the cache-aware variant when the provider implements it. The context
+ * manager's summarisation dispatches `complete`
+ * (`core/extensions/contextManager.ts`), which the adapter checks per attempt
+ * with the real method. This helper answers the admission-time question for the
+ * chat turn only, so it takes the union of the two tool-bearing methods.
+ */
+export function chatTransportSupportsImageInput(providerType: string): boolean {
+ return (
+ transportSupportsImageInput(providerType, 'completeWithTools') ||
+ transportSupportsImageInput(providerType, 'completeWithToolsAndCache')
+ )
+}
+
+/**
+ * Transport-independent facts for one (provider, model) pair, supplied by the
+ * host's live-catalog resolver.
+ */
+export interface ImageInputCapabilitySource {
+ /**
+ * Raw or normalized capability from the catalog. Anything missing or
+ * malformed normalizes to `unknown` inside the shared resolver, never to
+ * affirmative support.
+ */
+ capability?: unknown
+}
+
+/**
+ * Host → catalog lookup for image-input capability. Returns `undefined` when
+ * the pair is not in the live catalog (treated as `unknown`, never as allow).
+ * Implementations must be cheap and must not perform network I/O per call.
+ */
+export type ImageInputResolver = (
+ provider: string,
+ model: string
+) => ImageInputCapabilitySource | undefined
+
+export interface ImageInputRequestFacts {
+ providerType: string
+ method: ImageTransportOperation
+ /** Roles that actually carry at least one image part in this request. */
+ roles: readonly MessageRole[]
+ capability: unknown
+ now?: number
+}
+
+/**
+ * Full intersection for one physical attempt: model evidence ∩ transport
+ * implementation ∩ message role. Delegates the evidence half to the shared
+ * resolver so both sides cannot drift.
+ */
+export function decideImageInput(facts: ImageInputRequestFacts): ImageInputDecision {
+ const transportSupported =
+ facts.roles.length > 0 &&
+ facts.roles.every(role => transportSupportsImageInput(facts.providerType, facts.method, role))
+ return resolveImageInputCapability(facts.capability, {
+ transportSupported,
+ now: facts.now,
+ })
+}
+
+/**
+ * Message roles carrying at least one image part, in first-seen order. An
+ * empty result means the request carries no image and the guard is a no-op.
+ */
+export function imageInputRolesFor(messages: readonly ChatMessage[]): MessageRole[] {
+ const roles: MessageRole[] = []
+ for (const message of messages) {
+ if (!message.contentParts?.some(part => part.type === 'image')) continue
+ if (!roles.includes(message.role)) roles.push(message.role)
+ }
+ return roles
+}
+
+/**
+ * Operator/Desktop-facing explanation for a denied decision. States the real
+ * (provider, model) that would have been called and the action to take; never
+ * names internal evidence references or private endpoints.
+ */
+export function imageInputDenialMessage(
+ decision: ImageInputDecision,
+ target: { provider: string; model: string }
+): string {
+ const pair = `${target.provider}/${target.model}`
+ const suffix = 'The rest of the message was not sent to the provider.'
+ switch (decision.reason) {
+ case 'transport_unsupported':
+ return `The ${target.provider} transport path used for this operation cannot carry images for ${pair}. Remove the image or retry with a model whose chat path supports images. ${suffix}`
+ case 'model_unsupported':
+ return `Image input is not supported by ${pair}. Remove the image or choose a model with verified image support. ${suffix}`
+ case 'model_unknown':
+ return `Image input support for ${pair} is not verified. Remove the image or choose a model with verified image support. ${suffix}`
+ case 'evidence_expired':
+ return `Image input support for ${pair} expired${
+ decision.validUntil ? ` on ${decision.validUntil}` : ''
+ }. Refresh the capability evidence or choose another model. ${suffix}`
+ case 'evidence_not_yet_valid':
+ return `Image input support for ${pair} is not effective yet. Refresh the capability evidence or choose another model. ${suffix}`
+ case 'supported':
+ return `Image input is allowed for ${pair}.`
+ }
+}
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index e09df9016..de5a4d44a 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -18,7 +18,13 @@ import { AgentStateMachine, CronScheduler, wireCronDispatch } from './agent'
import type { ResolvedTaskModel } from './agent'
import { agentToolEnvProvider } from './agent/agentToolEnv'
import type { PendingCronResult } from './agent/cronDispatch'
-import { applySessionModelSelection as applySessionModelSelectionCore } from './agent/sessionModelSelection'
+import { createIncomingAdmission } from './agent/incomingAdmission'
+import { IncomingDelivery } from './agent/incomingDelivery'
+import { INCOMING_IMAGE_MAX_COUNT } from './agent/incomingImageAttachments'
+import {
+ type SessionModelSelectionOptions,
+ applySessionModelSelection as applySessionModelSelectionCore,
+} from './agent/sessionModelSelection'
import { applySessionTitle as applySessionTitleCore } from './agent/sessionTitle'
import { BudgetClient } from './budget/budgetClient'
// Structured JSON logging — must be first import
@@ -69,10 +75,11 @@ import { parseLlmPolicy } from './llm/failover/policy'
import type { FailoverSwitchEvent, FallbackEntry, LlmPolicy } from './llm/failover/types'
import { setGrokPolicyBindingReader } from './llm/grokPolicyBinding'
import { hostPrimaryLlmBindingChanged } from './llm/hostLlmBinding'
+import { type ImageInputResolver } from './llm/imageInput'
import { PromptCache } from './llm/promptCache'
import { clerumPromptCacheInvalidationsTotal } from './llm/promptCacheMetrics'
import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'
-import './logger'
+import { logger } from './logger'
import {
McpManager,
type McpPrincipal,
@@ -370,18 +377,19 @@ function sanitizeAttachments(raw: Attachment[] | undefined): Attachment[] | unde
isAllowedWorkflowFileAttachment(attachment) ||
(config.enableResponseAttachments && isInternalGeneratedArtifactAttachment(attachment))
if (!supportedImage && !supportedFile) {
- console.warn(`[Main] Dropping unsupported attachment type: ${attachment.mimeType}`)
+ logger.warn({ mimeType: attachment.mimeType }, '[Main] Dropping unsupported attachment type:')
continue
}
if (attachment.encoding !== 'base64' || typeof attachment.dataBase64 !== 'string') {
- console.warn('[Main] Dropping attachment with unsupported encoding')
+ logger.warn({}, '[Main] Dropping attachment with unsupported encoding')
continue
}
const decodedBytes = approxDecodedBytes(attachment.dataBase64)
if (decodedBytes > config.attachmentMaxBytes) {
- console.warn(
- `[Main] Dropping oversized attachment (${decodedBytes} bytes > ${config.attachmentMaxBytes})`
+ logger.warn(
+ { decodedBytes: decodedBytes, attachmentMaxBytes: config.attachmentMaxBytes },
+ '[Main] Dropping oversized attachment ( bytes > )'
)
continue
}
@@ -392,37 +400,6 @@ function sanitizeAttachments(raw: Attachment[] | undefined): Attachment[] | unde
return sanitized.length > 0 ? sanitized : undefined
}
-function sanitizeIncomingAttachments(raw: Attachment[] | undefined): Attachment[] | undefined {
- if (!raw || raw.length === 0) {
- return undefined
- }
-
- const sanitized: Attachment[] = []
- for (const attachment of raw) {
- if (sanitized.length >= config.attachmentMaxCount) {
- break
- }
- const isSupportedImageMime =
- attachment.mimeType === 'image/jpeg' || attachment.mimeType === 'image/png'
- if (
- attachment.kind !== 'image' ||
- !isSupportedImageMime ||
- attachment.encoding !== 'base64' ||
- typeof attachment.dataBase64 !== 'string' ||
- !attachment.dataBase64.trim()
- ) {
- continue
- }
- const decodedBytes = approxDecodedBytes(attachment.dataBase64)
- if (decodedBytes > config.attachmentMaxBytes) {
- continue
- }
- sanitized.push(attachment)
- }
-
- return sanitized.length > 0 ? sanitized : undefined
-}
-
/**
* Project the ConfigStore's active-provider credential bag into the `ApiKeys`
* shape. ConfigStore exposes the full multi-slot credential bag (keyed by slot
@@ -440,8 +417,8 @@ function apiKeysFromConfigStore(store: ConfigStore): ApiKeys {
/** Structured WARN on every failover switch (no secrets). */
function warnOnFailoverSwitch(event: FailoverSwitchEvent): void {
- console.warn(
- JSON.stringify({
+ logger.warn(
+ {
level: 'warn',
event: 'llm_fallback_switch',
fromProvider: event.from.provider,
@@ -449,7 +426,8 @@ function warnOnFailoverSwitch(event: FailoverSwitchEvent): void {
toProvider: event.to.provider,
toModel: event.to.model,
reason: event.reason,
- })
+ },
+ 'Host runtime event'
)
}
@@ -567,6 +545,18 @@ function allowlistView(): AllowlistView {
return configStore ?? UNAVAILABLE_ALLOWLIST
}
+// Read the live global catalog for physical attempts. The selectable subset
+// remains enforced at selection admission, not expanded into a failover policy.
+const resolveImageInput: ImageInputResolver = (provider, model) => {
+ const view = allowlistView()
+ const entry = view
+ .allowedModels()
+ .get(provider)
+ ?.find(candidate => candidate.model === model)
+ if (!entry) return undefined
+ return { capability: entry.imageInput }
+}
+
/**
* T3a — the allowlist view the end-user-facing R2 model endpoints project/
* validate against: the global {@link allowlistView} narrowed to this Host's
@@ -683,7 +673,10 @@ async function ensureConfigStore(host: HostCRD): Promise<ConfigStore> {
currentKeys = keys
const next = createLLMProvider(keys, currentHost.spec.model)
if (!next) {
- console.error('[Main] LLM provider rebuild failed after key rotation — Host may be degraded')
+ logger.error(
+ {},
+ '[Main] LLM provider rebuild failed after key rotation — Host may be degraded'
+ )
return
}
currentProvider = next
@@ -696,9 +689,9 @@ async function ensureConfigStore(host: HostCRD): Promise<ConfigStore> {
failoverEngine?.clearCooldown()
if (agent) {
agent.setLLMProvider(next, currentHost.spec.model?.name)
- console.log('[Main] LLM provider rebuilt and re-attached to agent (key rotated)')
+ logger.info({}, '[Main] LLM provider rebuilt and re-attached to agent (key rotated)')
} else {
- console.log('[Main] LLM provider rebuilt (agent not ready yet, will use on init)')
+ logger.info({}, '[Main] LLM provider rebuilt (agent not ready yet, will use on init)')
}
})
@@ -724,9 +717,9 @@ async function initializeProvider(
currentHost = host
currentKeys = keys
- console.log(`[Main] Initializing provider for host: ${host.spec.host}`)
- console.log(`[Main] Model config:`, host.spec.model)
- console.log(`[Main] Context ref: ${host.spec.contextRef}`)
+ logger.info({ host: host.spec.host }, '[Main] Initializing provider for host:')
+ logger.info({ model: host.spec.model }, '[Main] Model config:')
+ logger.info({ contextRef: host.spec.contextRef }, '[Main] Context ref:')
currentProvider = createLLMProvider(keys, host.spec.model)
bootFallbackEntry = null
@@ -753,25 +746,29 @@ async function initializeProvider(
to: `${entry.provider}/${entry.model}`,
reason: 'boot',
})
- console.warn(
- JSON.stringify({
+ logger.warn(
+ {
level: 'warn',
event: 'llm_fallback_boot',
fromProvider: host.spec.model?.provider ?? null,
fromModel: host.spec.model?.name ?? null,
toProvider: entry.provider,
toModel: entry.model,
- })
+ },
+ 'Host runtime event'
)
break
}
}
if (currentProvider) {
- console.log(
- bootFallbackEntry
- ? '[Main] LLM primary inconstructible — serving via boot fallback'
- : '[Main] LLM provider initialized successfully'
+ logger.info(
+ {
+ detail: bootFallbackEntry
+ ? '[Main] LLM primary inconstructible — serving via boot fallback'
+ : '[Main] LLM provider initialized successfully',
+ },
+ 'Host runtime status'
)
// R5.10 — the primary's credentials just changed (secretRef/provider) and it
@@ -793,7 +790,7 @@ async function initializeProvider(
agent.setLLMProvider(currentProvider, effectiveModel)
}
} else {
- console.error('[Main] Failed to initialize LLM provider')
+ logger.error({}, '[Main] Failed to initialize LLM provider')
}
// Phase 6: Propagate approval config to agent
@@ -830,7 +827,10 @@ export async function admitDevelopmentMcpServers(
try {
await manager.addServer(server)
} catch (error) {
- console.error(`[Main] Dev MCP server admission failed; continuing: ${server.name}`, error)
+ logger.error(
+ { name: server.name, err: error },
+ '[Main] Dev MCP server admission failed; continuing:'
+ )
}
}
}
@@ -1018,15 +1018,16 @@ function revokeMcpAuthority(reason: string, restartPolling: boolean): void {
mcpAuthorityLastSuccessAt = 0
},
coordinator: mcpFleetCoordinator,
- onCleanupFailure: () => console.error(`[Main] MCP authority cleanup failed (reason=${reason})`),
- onRevoked: () => console.warn(`[Main] MCP authority revoked (reason=${reason})`),
+ onCleanupFailure: () =>
+ logger.error({ reason: reason }, '[Main] MCP authority cleanup failed (reason=)'),
+ onRevoked: () => logger.warn({ reason: reason }, '[Main] MCP authority revoked (reason=)'),
shouldRestartPolling: () => !isShuttingDown && !config.devMode,
startPolling: startContextMapperPolling,
})
}
async function initializeMcpServers(): Promise<void> {
- console.log('[Main] Initializing authenticated MCP server inventory')
+ logger.info({}, '[Main] Initializing authenticated MCP server inventory')
const initializationGeneration = ++mcpInitializationGeneration
const isInitializationCurrent = (): boolean =>
!isShuttingDown && mcpInitializationGeneration === initializationGeneration
@@ -1078,15 +1079,18 @@ async function initializeMcpServers(): Promise<void> {
throw new Error('MCP manager was not installed after authoritative discovery')
}
const connectedServers = mcpManager.getConnectedServers()
- console.log(
- config.devMode
- ? `[Main] Connected to ${connectedServers.length} MCP server(s)`
- : `[Main] Published the initial MCP fleet manager with ${connectedServers.length} currently connected server(s); background reconciliation may still be in progress`
+ logger.info(
+ {
+ detail: config.devMode
+ ? `[Main] Connected to ${connectedServers.length} MCP server(s)`
+ : `[Main] Published the initial MCP fleet manager with ${connectedServers.length} currently connected server(s); background reconciliation may still be in progress`,
+ },
+ 'Host runtime status'
)
if (connectedServers.length > 0) {
const tools = mcpManager.getAllTools()
- console.log(`[Main] Total tools available: ${tools.length}`)
+ logger.info({ length: tools.length }, '[Main] Total tools available:')
}
// Update agent with MCP manager
@@ -1137,10 +1141,11 @@ async function pollContextMapper(): Promise<void> {
lastSuccessAt: () => mcpAuthorityLastSuccessAt,
revoke: revokeMcpAuthority,
onCallerAuthorizationRejected: () =>
- console.warn('[Main] HCC poll rejected caller authority'),
+ logger.warn({}, '[Main] HCC poll rejected caller authority'),
onInventoryAuthorityRevoked: () =>
- console.warn('[Main] HCC inventory no longer resolves live Host authority'),
- onUnavailable: () => console.error('[Main] HCC authority poll failed (reason=unavailable)'),
+ logger.warn({}, '[Main] HCC inventory no longer resolves live Host authority'),
+ onUnavailable: () =>
+ logger.error({}, '[Main] HCC authority poll failed (reason=unavailable)'),
})
)
}
@@ -1169,7 +1174,7 @@ export function createCoalescedPollRunner(poll: () => Promise<void>): {
inFlight = true
void poll()
.catch(error => {
- console.error('[Main] Context Mapper poll runner failed:', error)
+ logger.error({ err: error }, '[Main] Context Mapper poll runner failed:')
})
.finally(() => {
inFlight = false
@@ -1198,8 +1203,9 @@ export function startContextMapperPolling(): void {
// runner would leave the previous interval dispatching into the new runner.
stopContextMapperPolling()
- console.log(
- `[Main] Starting context-mapper polling (interval: ${config.contextMapperPollInterval}ms)`
+ logger.info(
+ { contextMapperPollInterval: config.contextMapperPollInterval },
+ '[Main] Starting context-mapper polling (interval: ms)'
)
contextMapperPollRunner = createCoalescedPollRunner(() => pollContextMapper())
@@ -1218,7 +1224,7 @@ export function ensureContextMapperPolling(): void {
*/
export function stopContextMapperPolling(): void {
if (contextMapperPollTimer) {
- console.log('[Main] Stopping context-mapper polling')
+ logger.info({}, '[Main] Stopping context-mapper polling')
clearInterval(contextMapperPollTimer)
contextMapperPollTimer = null
}
@@ -1261,14 +1267,14 @@ async function runGrantRevocationSweep(manager: McpManager): Promise<void> {
if (mcpManager !== manager) return
const evicted = manager.evictRevokedPartitions(selectRevokedPartitionKeys(partitions, results))
if (evicted > 0) {
- console.log(`[Main] Grant-sweep evicted ${evicted} revoked oauth MCP partition(s)`)
+ logger.info({ evicted: evicted }, '[Main] Grant-sweep evicted revoked oauth MCP partition(s)')
}
} catch (err: unknown) {
// Fail-OPEN: a control-api/gateway blip must not tear down live sessions.
// The thrown error never carries a token (see grantExistenceClient).
- console.warn(
- '[Main] MCP grant-revocation sweep failed; conserving partitions (fail-open):',
- err instanceof Error ? err.message : String(err)
+ logger.warn(
+ { err: err },
+ '[Main] MCP grant-revocation sweep failed; conserving partitions (fail-open):'
)
} finally {
grantRevocationSweepInFlight = false
@@ -1284,15 +1290,16 @@ function startMcpStatusHeartbeat(): void {
if (mcpStatusHeartbeat) return
const interval = config.mcpStatusHeartbeatInterval
const timeoutMs = config.mcpStatusHeartbeatTimeoutMs
- console.log(
- `[Main] Starting MCP status heartbeat (interval: ${interval}ms, timeout: ${timeoutMs}ms)`
+ logger.info(
+ { interval: interval, timeoutMs: timeoutMs },
+ '[Main] Starting MCP status heartbeat (interval: ms, timeout: ms)'
)
mcpStatusHeartbeat = new McpStatusHeartbeat({
intervalMs: interval,
timeoutMs,
getRefresher: () => mcpManager,
onError: (err: unknown) => {
- console.error('[Main] MCP status heartbeat failed:', err)
+ logger.error({ err: err }, '[Main] MCP status heartbeat failed:')
},
})
mcpStatusHeartbeat.start()
@@ -1306,10 +1313,10 @@ function startMcpStatusHeartbeat(): void {
OAUTH_USER_PARTITION_MAX
)
if (evicted > 0) {
- console.log(`[Main] Evicted ${evicted} idle oauth per-user MCP partition(s)`)
+ logger.info({ evicted: evicted }, '[Main] Evicted idle oauth per-user MCP partition(s)')
}
} catch (err: unknown) {
- console.error('[Main] MCP per-user partition eviction failed:', err)
+ logger.error({ err: err }, '[Main] MCP per-user partition eviction failed:')
}
// Then the hot-revocation grant-sweep (mini-spec 13): ask control-api whether
// the live OAuth partitions still have a grant and evict the revoked ones.
@@ -1320,7 +1327,7 @@ function startMcpStatusHeartbeat(): void {
function stopMcpStatusHeartbeat(): void {
if (mcpStatusHeartbeat) {
- console.log('[Main] Stopping MCP status heartbeat')
+ logger.info({}, '[Main] Stopping MCP status heartbeat')
mcpStatusHeartbeat.stop()
mcpStatusHeartbeat = null
}
@@ -1347,14 +1354,17 @@ async function applyResolvedGuardrails(): Promise<void> {
getLlmHook,
llmHooksNamespace: config.llmHooksNamespace,
}).catch(err => {
- console.error('[Main] Guardrail hook resolution failed; running without installed hooks:', err)
+ logger.error(
+ { err: err },
+ '[Main] Guardrail hook resolution failed; running without installed hooks:'
+ )
return []
})
agent.setGuardrailsConfig(withResolvedHookDescriptors(hostGuardrails, resolved))
}
async function onHostChange(host: HostCRD): Promise<void> {
- console.log(`[Main] Host configuration changed: ${host.name}`)
+ logger.info({ name: host.name }, '[Main] Host configuration changed:')
const contextChanged =
currentHost !== null && currentHost.spec.contextRef !== host.spec.contextRef
@@ -1402,7 +1412,8 @@ async function onHostChange(host: HostCRD): Promise<void> {
connectionRefChanged ||
fallbackSlotsChanged
) {
- console.log(
+ logger.info(
+ {},
'[Main] Rebuilding ConfigStore (provider/secretRef/connectionRef/failover slots changed)'
)
await ensureConfigStore(host)
@@ -1437,9 +1448,9 @@ async function onHostChange(host: HostCRD): Promise<void> {
// so by the time onHostChange runs at runtime it is non-null; the `?.`
// is defensive for early-boot reconcile paths.
promptCache?.invalidateAll('identity_reconciled')
- console.log('[Main] Identity files reconciled from CRD')
+ logger.info({}, '[Main] Identity files reconciled from CRD')
} catch (err) {
- console.error('[Main] Failed to apply identity files:', err)
+ logger.error({ err: err }, '[Main] Failed to apply identity files:')
}
}
@@ -1453,7 +1464,7 @@ async function onHostChange(host: HostCRD): Promise<void> {
* Handle host deletion.
*/
function onHostDelete(): void {
- console.log('[Main] Host CRD deleted, shutting down')
+ logger.info({}, '[Main] Host CRD deleted, shutting down')
revokeMcpAuthority('host_deleted', false)
currentHost = null
currentProvider = null
@@ -1471,7 +1482,7 @@ function setupUsageReporting(): void {
if (!runtimeAuth) runtimeAuth = createMcpHostRuntimeAuth()
if (!runtimeAuth) {
- console.log('[Main] LLM usage reporting disabled — MCP_HOST_RUNTIME_* env not set')
+ logger.info({}, '[Main] LLM usage reporting disabled — MCP_HOST_RUNTIME_* env not set')
return
}
@@ -1509,8 +1520,9 @@ function setupUsageReporting(): void {
maxBytes: config.approvalPromptHistoryMaxBytes,
})
)
- console.log(
- `[Main] LLM usage reporting wired (host=${currentHost.name}, gateway=${auth.baseUrl})`
+ logger.info(
+ { name: currentHost.name, baseUrl: auth.baseUrl },
+ '[Main] LLM usage reporting wired (host=, gateway=)'
)
// P1 token budgets (§5.1) — reuse the SAME shared McpHostRuntimeAuth (bearer +
@@ -1536,7 +1548,7 @@ function setupUsageReporting(): void {
}
: null
)
- console.log('[Main] Token budget enforcement wired (CLERUM_BUDGETS_ENABLED=true)')
+ logger.info({}, '[Main] Token budget enforcement wired (CLERUM_BUDGETS_ENABLED=true)')
}
}
@@ -1568,15 +1580,16 @@ function resolveSessionDbPath(): string {
async function initializeConversationStore(): Promise<ConversationStoreHandle | null> {
if (!agent) return null
if (config.sessionStoreMode === 'memory') {
- console.log('[Main] Conversation store: memory (legacy fallback)')
+ logger.info({}, '[Main] Conversation store: memory (legacy fallback)')
return null
}
const dbPath = resolveSessionDbPath()
const memoryCfg = currentHost?.spec.memory || config.memory
if (!memoryCfg?.enabled) {
- console.warn(
- `[Main] SQLite state will be ephemeral — workspace memory is disabled. dbPath=${dbPath}`
+ logger.warn(
+ { dbPath: dbPath },
+ '[Main] SQLite state will be ephemeral — workspace memory is disabled. dbPath='
)
}
@@ -1596,9 +1609,13 @@ async function initializeConversationStore(): Promise<ConversationStoreHandle |
})
agent.setConversationStore(handle.store)
- console.log(
- `[Main] Conversation store mode=${handle.mode} dbPath=${dbPath} ` +
- `cacheSize=${config.conversationCacheSize} barrierMode=${barrierMode ? 'full' : 'normal'}`
+ logger.info(
+ {
+ detail:
+ `[Main] Conversation store mode=${handle.mode} dbPath=${dbPath} ` +
+ `cacheSize=${config.conversationCacheSize} barrierMode=${barrierMode ? 'full' : 'normal'}`,
+ },
+ 'Host runtime status'
)
// Wire the cold-start loader so `agent.bootstrap()` (called below) can
@@ -1609,8 +1626,9 @@ async function initializeConversationStore(): Promise<ConversationStoreHandle |
const loader = new SqliteColdStartLoader(handle.store, {
spilloverResolver,
onExpired: entry => {
- console.warn(
- `[Main] Cold-start: dropping approval ${entry.request_id} — spillover ref expired`
+ logger.warn(
+ { request_id: entry.request_id },
+ '[Main] Cold-start: dropping approval {request_id} — spillover ref expired'
)
},
})
@@ -1623,7 +1641,7 @@ async function initializeConversationStore(): Promise<ConversationStoreHandle |
* Initialize the message queue and agent.
*/
async function initializeAgent(): Promise<void> {
- console.log('[Main] Initializing message queue and agent')
+ logger.info({}, '[Main] Initializing message queue and agent')
// Create message queue
messageQueue = new MessageQueue(config.agentMaxQueueSize)
@@ -1642,8 +1660,15 @@ async function initializeAgent(): Promise<void> {
approvalTimeout: config.agentApprovalTimeout,
})
- console.log(
- `[Main] Agent config: taskDelay=${config.agentTaskDelay}ms, maxTaskDuration=${config.agentMaxTaskDuration}ms, maxToolCalls=${config.agentMaxToolCallsPerTask}, maxQueueSize=${config.agentMaxQueueSize}, approvalTimeout=${config.agentApprovalTimeout}ms`
+ logger.info(
+ {
+ agentTaskDelay: config.agentTaskDelay,
+ agentMaxTaskDuration: config.agentMaxTaskDuration,
+ agentMaxToolCallsPerTask: config.agentMaxToolCallsPerTask,
+ agentMaxQueueSize: config.agentMaxQueueSize,
+ agentApprovalTimeout: config.agentApprovalTimeout,
+ },
+ '[Main] Agent config: taskDelay=ms, maxTaskDuration=ms, maxToolCalls=, maxQueueSize=, approvalTimeout=ms'
)
// R2 — inject the per-task model resolver. Closes over the module globals
@@ -1651,6 +1676,7 @@ async function initializeAgent(): Promise<void> {
// key rotation or allowlist reload is picked up on the next task with no
// re-wiring. Set once here (the agent is created once).
agent.setTaskModelResolver(resolveTaskModel)
+ agent.setImageInputResolver(resolveImageInput)
// R5 — inject the provider-fallback support. Closes over the module globals
// (currentPolicy/failoverEngine/bootFallbackEntry + configStore) so each task
@@ -1671,8 +1697,12 @@ async function initializeAgent(): Promise<void> {
)
}
validateApprovalConfig(approvalCfg, knownNativeToolNames, config.nativeTool.httpAllowlist)
- console.log(
- `[Main] Approval system: ${config.enableApproval ? 'ENABLED' : 'DISABLED'} (policy: ${approvalCfg?.defaultPolicy || 'none/cli_only'})`
+ logger.info(
+ {
+ detail: config.enableApproval ? 'ENABLED' : 'DISABLED',
+ detail1: approvalCfg?.defaultPolicy || 'none/cli_only',
+ },
+ '[Main] Approval system: (policy: )'
)
// Shell-tool subprocesses see the ConfigStore user-env snapshot at spawn
@@ -1690,7 +1720,7 @@ async function initializeAgent(): Promise<void> {
const workspacePath = memoryCfg.workspacePath ?? config.memory.workspacePath ?? './workspace'
workspaceProvider = new ScopedWorkspaceProvider(workspacePath)
agent.setWorkspaceProvider(workspaceProvider)
- console.log(`[Main] Workspace memory enabled at: ${workspacePath}`)
+ logger.info({ workspacePath: workspacePath }, '[Main] Workspace memory enabled at:')
// Dev mode has no Host CRD watch, so apply env-sourced personalization here.
// In production, the Host watch also applies this path on every CRD update.
@@ -1706,7 +1736,7 @@ async function initializeAgent(): Promise<void> {
promptCache?.invalidateAll('identity_reconciled')
})
.catch(err => {
- console.error('[Main] Failed to apply identity files at startup:', err)
+ logger.error({ err: err }, '[Main] Failed to apply identity files at startup:')
})
}
@@ -1724,12 +1754,16 @@ async function initializeAgent(): Promise<void> {
})
// Lazy boot sweep (best-effort; failures are logged inside).
spilloverStorage.sweep().catch(err => {
- console.error('[Main] Spillover boot sweep failed (non-fatal):', err)
+ logger.error({ err: err }, '[Main] Spillover boot sweep failed (non-fatal):')
})
spilloverStorage.startGc()
agent.setSpilloverStorage(spilloverStorage)
- console.log(
- `[Main] Spillover storage enabled (threshold=${config.toolSpilloverThresholdBytes}B, ttl=${config.spilloverTtlMs}ms)`
+ logger.info(
+ {
+ toolSpilloverThresholdBytes: config.toolSpilloverThresholdBytes,
+ spilloverTtlMs: config.spilloverTtlMs,
+ },
+ '[Main] Spillover storage enabled (threshold=B, ttl=ms)'
)
}
}
@@ -1815,19 +1849,23 @@ async function initializeAgent(): Promise<void> {
// corrupt DB does not block traffic — the metric / log surfaces the issue.
sessionSearchService.sweepRetention(config.searchRetentionDays).then(
deleted => {
- console.log(
- JSON.stringify({
+ logger.info(
+ {
event: 'search_retention_sweep',
deleted_sessions: deleted,
retention_days: config.searchRetentionDays,
- })
+ },
+ 'Host runtime event'
)
},
err => {
- console.error('[Main] Session search retention sweep failed (non-fatal):', err)
+ logger.error({ err: err }, '[Main] Session search retention sweep failed (non-fatal):')
}
)
- console.log(`[Main] Session search enabled (retentionDays=${config.searchRetentionDays})`)
+ logger.info(
+ { searchRetentionDays: config.searchRetentionDays },
+ '[Main] Session search enabled (retentionDays=)'
+ )
}
// T2.2 — Process-wide system-prompt cache. Built unconditionally so the
@@ -1839,13 +1877,16 @@ async function initializeAgent(): Promise<void> {
const cache = new PromptCache({
onInvalidate: (key, reason) => {
clerumPromptCacheInvalidationsTotal.inc({ reason })
- console.log(`[PromptCache] invalidate sessionKey=${key} reason=${reason}`)
+ logger.info({ key: key, reason: reason }, '[PromptCache] invalidate sessionKey= reason=')
},
})
promptCache = cache
conversationStoreHandle?.store?.onEvict?.(sessionKey => cache.drop(sessionKey))
agent.setPromptCache(cache)
- console.log(`[Main] Prompt cache wired (flag=${config.promptCacheEnabled ? 'on' : 'off'})`)
+ logger.info(
+ { detail: config.promptCacheEnabled ? 'on' : 'off' },
+ '[Main] Prompt cache wired (flag=)'
+ )
}
// P.3 invariant #3: rehydrate pending_approvals from durable storage
@@ -1860,7 +1901,7 @@ async function initializeAgent(): Promise<void> {
agent.start()
cronScheduler.start()
- console.log('[Main] Agent and cron scheduler started')
+ logger.info({}, '[Main] Agent and cron scheduler started')
}
// R2 — thin wrapper that injects live process state (current Host model config,
@@ -1872,7 +1913,9 @@ function applySessionModelSelection(
userSub: string,
hostRef: string,
chatId: string | undefined,
- model: string
+ model: string,
+ expectedRevision?: number,
+ options?: SessionModelSelectionOptions
): Promise<SetModelResult> {
return applySessionModelSelectionCore(
{
@@ -1886,7 +1929,9 @@ function applySessionModelSelection(
userSub,
hostRef,
chatId,
- model
+ model,
+ expectedRevision,
+ options
)
}
@@ -1918,128 +1963,56 @@ function applySessionTitle(
* - Phase 2: After approval/denial, the final response is stored in pendingTaskResults
* for channel-reader to poll via GET /task/:id/result.
*/
-function handleIncomingMessage(
+const incomingDelivery = new IncomingDelivery()
+
+function dispatchIncomingMessage(
message: IncomingMessage,
options?: { async?: boolean }
): MessageResponse | Promise<MessageResponse> {
- const sanitizedIncomingAttachments = sanitizeIncomingAttachments(message.attachments)
- const normalizedMessage: IncomingMessage = {
- ...message,
- attachments: sanitizedIncomingAttachments,
- }
-
- console.log('\n' + '='.repeat(50))
- console.log('[Main] Received message')
- console.log(`[Main] Channel: ${normalizedMessage.channelType}`)
- console.log(`[Main] Channel ID: ${normalizedMessage.channelId}`)
- console.log(`[Main] Sender: ${normalizedMessage.sender}`)
- console.log(`[Main] Time: ${normalizedMessage.timestamp}`)
- console.log(`[Main] Message ID: ${normalizedMessage.messageId}`)
- console.log(
- `[Main] Content: ${normalizedMessage.content.substring(0, 100)}${normalizedMessage.content.length > 100 ? '...' : ''}`
- )
- if (normalizedMessage.attachments?.length) {
- console.log(`[Main] Attachments: ${normalizedMessage.attachments.length}`)
- }
- console.log('='.repeat(50))
-
- if (!messageQueue) {
- return {
- success: false,
- error: {
- code: 'LLM_API_CALL_FAILED',
- message: 'Message queue not initialized',
- retryable: false,
- provider: 'unknown',
- },
- }
- }
+ const handler = new IncomingMessageHandler(message, {
+ messageQueue: messageQueue!,
+ agent,
+ pendingTaskResults,
+ getModel: () => currentHost?.spec.model?.name || 'unknown',
+ sanitizeAttachments,
+ sessionProcessor: sessionProcessor ?? undefined,
+ taskLifecycle: taskLifecycle!,
+ })
- // Refuse new tasks while the Host is degraded. Operator fixes the LLM
- // Secret and the Host returns to ready within ~1 s — no restart.
- const degraded = computeDegradedReason()
- if (degraded) {
- console.warn(`[Main] Refusing message — Host is degraded: ${degraded.reason}`)
- return {
- success: false,
- error: {
- code: 'LLM_KEY_MISSING',
- message: degraded.message,
- retryable: true,
- provider: currentHost?.spec.model?.provider ?? 'unknown',
- },
- }
+ if (options?.async) {
+ return handler.executeAsync()
}
- const runHandler = (): MessageResponse | Promise<MessageResponse> => {
- const handler = new IncomingMessageHandler(normalizedMessage, {
- messageQueue: messageQueue!,
- agent,
- pendingTaskResults,
- getModel: () => currentHost?.spec.model?.name || 'unknown',
- sanitizeAttachments,
- sessionProcessor: sessionProcessor ?? undefined,
- taskLifecycle: taskLifecycle!,
- })
-
- if (options?.async) {
- return handler.executeAsync()
- }
-
- return handler.execute()
- }
-
- // R2 — piggybacked per-session model. Because a suspended Host can't serve
- // `POST /v1/runtime/model`, the desktop rides the user's pick on the message
- // that wakes us. Apply it to THIS session and AWAIT the write BEFORE the task
- // is created, so the per-task resolver (`stateMachine` taskModelResolver over
- // `conv.modelSelections`) reads the row we just wrote. Fail-OPEN on the
- // message: a rejected/degraded selection is logged and ignored, never dropping
- // the user's turn (fail-closed only on the selection, inside the helper).
- const piggybackModel = typeof message.model === 'string' ? message.model.trim() : ''
- if (piggybackModel && normalizedMessage.channelType === 'rpc') {
- return (async () => {
- try {
- const applied = await applySessionModelSelection(
- normalizedMessage.sender,
- normalizedMessage.channelId,
- normalizedMessage.threadId,
- piggybackModel
- )
- if (!applied.ok) {
- console.warn(
- JSON.stringify({
- level: 'warn',
- event: 'message_model_ignored',
- userId: normalizedMessage.sender,
- chatId: normalizedMessage.threadId ?? null,
- provider: applied.provider,
- model: piggybackModel,
- reason: applied.reason,
- })
- )
- }
- } catch (error) {
- console.warn(
- JSON.stringify({
- level: 'warn',
- event: 'message_model_ignored',
- userId: normalizedMessage.sender,
- chatId: normalizedMessage.threadId ?? null,
- provider: currentHost?.spec.model?.provider ?? 'unknown',
- model: piggybackModel,
- reason: 'apply_failed',
- error: error instanceof Error ? error.message : String(error),
- })
- )
- }
- return runHandler()
- })()
- }
+ return handler.execute()
+}
- return runHandler()
+function handleIncomingMessage(
+ message: IncomingMessage,
+ options?: { async?: boolean }
+): MessageResponse | Promise<MessageResponse> {
+ if (!messageQueue) return prepareIncomingMessage(message, options)
+ return incomingDelivery.run(
+ message,
+ messageQueue,
+ () => prepareIncomingMessage(message, options),
+ () => dispatchIncomingMessage({ ...message, imageModel: undefined }, options)
+ )
}
+const prepareIncomingMessage = createIncomingAdmission({
+ limits: { maxCount: INCOMING_IMAGE_MAX_COUNT, maxBytes: config.attachmentMaxBytes },
+ queueReady: () => Boolean(messageQueue),
+ degradedReason: computeDegradedReason,
+ hostProvider: () => currentHost?.spec.model?.provider,
+ getConversationByKey: (key, userId) =>
+ agent!.getConversationManager().getSessionByKeyForUserAsync(key, userId),
+ resolveTaskModel,
+ resolveImageInput,
+ applySessionModelSelection,
+ dispatch: dispatchIncomingMessage,
+ logger,
+})
+
function sourceMatchesRuntimeCaller(
source: { channelType?: string | null; channelId?: string | null; sender?: string | null },
caller?: RuntimeCallerContext
@@ -2063,8 +2036,8 @@ function logRuntimeOwnershipMismatch(
caller: RuntimeCallerContext,
source: { channelType?: string | null; channelId?: string | null; sender?: string | null }
): void {
- console.warn(
- JSON.stringify({
+ logger.warn(
+ {
event: 'runtime_task_ownership_mismatch',
route,
taskId,
@@ -2076,7 +2049,8 @@ function logRuntimeOwnershipMismatch(
taskChannelType: source.channelType ?? null,
taskChannelId: source.channelId ?? null,
taskSender: source.sender ?? null,
- })
+ },
+ 'Host runtime event'
)
}
@@ -2185,8 +2159,9 @@ async function handleApprovalDecision(
}
const action = decision.approved ? 'approve' : 'deny'
- console.log(
- `[Main] Processing ${action} from userId=${decision.userId} requestId=${decision.requestId}`
+ logger.info(
+ { action: action, userId: decision.userId, requestId: decision.requestId },
+ '[Main] Processing from userId= requestId='
)
const result = decision.approved
@@ -2205,9 +2180,12 @@ async function handleApprovalDecision(
)
if (!result.success) {
- console.error(`[Main] ${action} failed: ${result.error}`)
+ logger.error({ action: action, err: new Error(result.error) }, '[Main] failed:')
} else {
- console.log(`[Main] ${action} succeeded for requestId=${decision.requestId}`)
+ logger.info(
+ { action: action, requestId: decision.requestId },
+ '[Main] succeeded for requestId='
+ )
}
return result
}
@@ -2221,9 +2199,13 @@ async function handleProviderWorkflowApprovalDecision(
run?: Record<string, unknown> | null
error?: string
}> {
- console.log(
- `[Main] Processing provider workflow approval decision ${decision.decision} ` +
- `requestId=${decision.approvalRequestId} medium=${decision.providerIdentity.medium}`
+ logger.info(
+ {
+ detail:
+ `[Main] Processing provider workflow approval decision ${decision.decision} ` +
+ `requestId=${decision.approvalRequestId} medium=${decision.providerIdentity.medium}`,
+ },
+ 'Host runtime status'
)
return submitProviderWorkflowApprovalDecision(decision, runtimeAuth)
}
@@ -2287,10 +2269,9 @@ export async function handleProviderMessageAuthorization(
return { authorized: false, reason: 'error' }
} catch (error) {
const reason = classifyAuthorizationFailure(error)
- console.warn(
- `[Main] Provider message authorization failed closed (${reason}): ${
- error instanceof Error ? error.message : String(error)
- }`
+ logger.warn(
+ { reason: reason, err: error },
+ '[Main] Provider message authorization failed closed ():'
)
return { authorized: false, reason }
}
@@ -2304,9 +2285,13 @@ async function handleProviderWorkflowApprovalResolve(
| { status: 'ambiguous' }
| { status: 'error'; error: string }
> {
- console.log(
- `[Main] Resolving provider workflow approval recipe=${input.recipeName} ` +
- `medium=${input.providerIdentity.medium}`
+ logger.info(
+ {
+ detail:
+ `[Main] Resolving provider workflow approval recipe=${input.recipeName} ` +
+ `medium=${input.providerIdentity.medium}`,
+ },
+ 'Host runtime status'
)
return resolvePendingProviderWorkflowApproval(input, runtimeAuth)
}
@@ -2331,11 +2316,7 @@ async function handleProviderWorkflowResultRequest(
try {
context = await resolveProviderWorkflowCallerContext(message, key => process.env[key])
} catch (error) {
- console.warn(
- `[Main] Provider workflow result access failed closed: ${
- error instanceof Error ? error.message : String(error)
- }`
- )
+ logger.warn({ err: error }, '[Main] Provider workflow result access failed closed:')
context = null
}
if (!context?.targetUserId && !context?.targetTeamId) {
@@ -2648,6 +2629,7 @@ async function startRPCServer(): Promise<void> {
const view = hostAllowlistView()
const { degraded, models } = projectModels(view, provider, hostDefault)
let sessionModel: string | null = null
+ let modelSelectionRevision = 0
let sessionModelBlocked: string | undefined
if (chatId && modelCfg?.provider && modelCfg.name) {
const key = serializeSessionKey({
@@ -2660,6 +2642,7 @@ async function startRPCServer(): Promise<void> {
.getConversationManager()
.getSessionByKeyForUserAsync(key, userSub)
const saved = conversation?.modelSelections?.[provider]
+ modelSelectionRevision = conversation?.modelSelectionRevision ?? 0
if (saved) {
const resolution = resolveSessionModel(
view,
@@ -2673,7 +2656,15 @@ async function startRPCServer(): Promise<void> {
else sessionModel = saved
}
}
- return { provider, hostDefault, sessionModel, sessionModelBlocked, degraded, models }
+ return {
+ provider,
+ hostDefault,
+ sessionModel,
+ sessionModelBlocked,
+ modelSelectionRevision,
+ degraded,
+ models,
+ }
}
// R2 — POST /v1/runtime/model. Thin route adapter over the shared
@@ -2681,8 +2672,13 @@ async function startRPCServer(): Promise<void> {
// degraded → only the Host default; persist the per-session selection; report
// next-task effectivity). The same core also runs for a piggybacked
// `message.model` in `handleIncomingMessage`, so the two paths cannot diverge.
- const handleSetModel = (userSub: string, hostRef: string, chatId: string, model: string) =>
- applySessionModelSelection(userSub, hostRef, chatId, model)
+ const handleSetModel = (
+ userSub: string,
+ hostRef: string,
+ chatId: string,
+ model: string,
+ expectedRevision?: number
+ ) => applySessionModelSelection(userSub, hostRef, chatId, model, expectedRevision)
// Spec 15 Fase B — PATCH /v1/runtime/sessions/:agent/:chatId/name rename adapter.
const handleSetTitle = (userSub: string, agentName: string, chatId: string, title: string) =>
@@ -2751,13 +2747,14 @@ async function startRPCServer(): Promise<void> {
return { unsubscribe }
})
rpcServer.onCancel((taskId, requesterUserId) => {
- console.log(
- JSON.stringify({
+ logger.info(
+ {
event: 'cancel_requested',
taskId,
requesterUserId: requesterUserId ?? null,
origin: 'user', // HTTP-initiated cancels are always user-originated. Shutdown drain logs 'system' from stateMachine.stop().
- })
+ },
+ 'Host runtime event'
)
// Ownership check: if the record carries a submittedBy identity AND the
@@ -2772,13 +2769,14 @@ async function startRPCServer(): Promise<void> {
requesterUserId &&
existing.submittedBy !== requesterUserId
) {
- console.warn(
- JSON.stringify({
+ logger.warn(
+ {
event: 'cancel_ownership_mismatch',
taskId,
submittedBy: existing.submittedBy,
requester: requesterUserId,
- })
+ },
+ 'Host runtime event'
)
// Do NOT leak task existence to unauthorized requesters
return 'not_found'
@@ -2787,24 +2785,26 @@ async function startRPCServer(): Promise<void> {
const outcome = taskLifecycle!.transition(taskId, 'cancelled', 'user_requested')
if (outcome.kind === 'applied') {
- console.log(
- JSON.stringify({
+ logger.info(
+ {
event: 'cancel_applied',
taskId,
from_state: outcome.from,
reason: outcome.reason,
- })
+ },
+ 'Host runtime event'
)
return 'cancelled'
}
if (outcome.kind === 'already_terminal') {
- console.log(
- JSON.stringify({
+ logger.info(
+ {
event: 'already_terminal',
taskId,
current_state: outcome.state,
requested_transition: 'cancelled',
- })
+ },
+ 'Host runtime event'
)
return 'already_terminal'
}
@@ -2812,7 +2812,7 @@ async function startRPCServer(): Promise<void> {
return 'not_found'
}
// kind === 'illegal' — should never happen for cancel
- console.error('[cancel] illegal transition', outcome)
+ logger.error({ outcome: outcome }, '[cancel] illegal transition')
return 'not_found'
})
await rpcServer.start()
@@ -2939,9 +2939,13 @@ function startStatelessHeartbeat(): void {
rpcServer.setLifecycleGate(heartbeat)
heartbeat.start()
statelessHeartbeat = heartbeat
- console.log(
- `[Main] Stateless heartbeat started (interval=${config.statelessHeartbeatIntervalMs}ms, ` +
- `target=${config.mcpHostGatewayUrl})`
+ logger.info(
+ {
+ detail:
+ `[Main] Stateless heartbeat started (interval=${config.statelessHeartbeatIntervalMs}ms, ` +
+ `target=${config.mcpHostGatewayUrl})`,
+ },
+ 'Host runtime status'
)
}
@@ -2950,13 +2954,13 @@ function startStatelessHeartbeat(): void {
*/
async function shutdown(signal: string): Promise<void> {
if (isShuttingDown) {
- console.log('[Main] Shutdown already in progress...')
+ logger.info({}, '[Main] Shutdown already in progress...')
return
}
isShuttingDown = true
mcpInitializationGeneration += 1
- console.log(`[Main] Received ${signal}, shutting down`)
+ logger.info({ signal: signal }, '[Main] Received , shutting down')
// Fence MCP authority and detach live tools before any awaited shutdown
// phase. Delayed polls and in-flight connects cannot reopen a closed manager.
@@ -2994,10 +2998,7 @@ async function shutdown(signal: string): Promise<void> {
usageReporter.stop()
await usageReporter.drain()
} catch (err) {
- console.warn(
- '[Main] UsageReporter drain failed during shutdown:',
- err instanceof Error ? err.message : String(err)
- )
+ logger.warn({ err: err }, '[Main] UsageReporter drain failed during shutdown:')
}
}
if (governedRunReporter) {
@@ -3005,10 +3006,7 @@ async function shutdown(signal: string): Promise<void> {
governedRunReporter.stop()
await governedRunReporter.drain()
} catch (err) {
- console.warn(
- '[Main] GovernedRunReporter drain failed during shutdown:',
- err instanceof Error ? err.message : String(err)
- )
+ logger.warn({ err: err }, '[Main] GovernedRunReporter drain failed during shutdown:')
}
}
@@ -3025,7 +3023,7 @@ async function shutdown(signal: string): Promise<void> {
try {
await conversationStoreHandle.shutdown()
} catch (err) {
- console.warn('[Main] ConversationStore shutdown raised:', err)
+ logger.warn({ err: err }, '[Main] ConversationStore shutdown raised:')
}
}
@@ -3036,7 +3034,7 @@ async function shutdown(signal: string): Promise<void> {
* Start the MCP Host service in dev mode.
*/
async function startDevMode(): Promise<void> {
- console.log('[Main] Starting in DEV MODE')
+ logger.info({}, '[Main] Starting in DEV MODE')
// Use API keys from environment variables. Registry-driven: read each
// provider's credential slots by env var (ALL_PROVIDERS order = dev priority).
@@ -3070,7 +3068,10 @@ async function startDevMode(): Promise<void> {
...hostSpec,
model: { provider, name: defaultModel },
}
- console.log(`[Main] Auto-detected provider: ${provider} (based on available API key)`)
+ logger.info(
+ { provider: provider },
+ '[Main] Auto-detected provider: (based on available API key)'
+ )
}
// Phase 6: Attach approval config to host spec if provided via env var
@@ -3100,13 +3101,13 @@ async function startDevMode(): Promise<void> {
)
if (config.devMcpServers && config.devMcpServers.length > 0) {
- console.log(`[Main] Adding ${config.devMcpServers.length} dev MCP server(s)`)
+ logger.info({ length: config.devMcpServers.length }, '[Main] Adding dev MCP server(s)')
await admitDevelopmentMcpServers(config.devMcpServers, mcpManager)
const tools = mcpManager.getAllTools()
- console.log(`[Main] Total tools available: ${tools.length}`)
+ logger.info({ length: tools.length }, '[Main] Total tools available:')
} else {
- console.log('[Main] No MCP servers configured in dev mode')
+ logger.info({}, '[Main] No MCP servers configured in dev mode')
}
// Initialize agent (after provider and MCP manager are ready)
@@ -3121,9 +3122,9 @@ async function startDevMode(): Promise<void> {
// Stage 3 — stateless lifecycle heartbeat + reversible DRAINING fence.
startStatelessHeartbeat()
- console.log(`[Main] Approval system: ${config.enableApproval ? 'ENABLED' : 'DISABLED'}`)
- console.log('\n[Main] MCP Host running in dev mode. Press Ctrl+C to exit.')
- console.log('[Main] Waiting for messages from channel-reader...\n')
+ logger.info({ detail: config.enableApproval ? 'ENABLED' : 'DISABLED' }, '[Main] Approval system:')
+ logger.info({}, '[Main] MCP Host running in dev mode. Press Ctrl+C to exit.')
+ logger.info({}, '[Main] Waiting for messages from channel-reader...')
// Handle graceful shutdown
process.once('SIGTERM', () => shutdown('SIGTERM'))
@@ -3134,15 +3135,15 @@ async function startDevMode(): Promise<void> {
* Start the MCP Host service in production mode.
*/
async function startProductionMode(): Promise<void> {
- console.log('[Main] Starting in PRODUCTION MODE')
- console.log(`[Main] Host name: ${config.hostName}`)
- console.log(`[Main] Namespace: ${config.namespace}`)
- console.log(`[Main] Context Mapper URL: ${config.contextMapperUrl}`)
+ logger.info({}, '[Main] Starting in PRODUCTION MODE')
+ logger.info({ hostName: config.hostName }, '[Main] Host name:')
+ logger.info({ namespace: config.namespace }, '[Main] Namespace:')
+ logger.info({}, 'Context mapper configured')
const host = await getHost(config.hostName)
if (!host) {
- console.error(`[Main] Host CRD not found: ${config.hostName}`)
+ logger.error({ hostName: config.hostName }, '[Main] Host CRD not found:')
process.exit(1)
}
@@ -3177,7 +3178,7 @@ async function startProductionMode(): Promise<void> {
!!hooks &&
Object.values(hooks).some(refs => Array.isArray(refs) && refs.some(r => r?.id === name))
if (referenced) {
- console.log(`[Main] Referenced LlmHook ${name} changed — re-resolving guardrails`)
+ logger.info({ name: name }, '[Main] Referenced LlmHook changed — re-resolving guardrails')
void applyResolvedGuardrails()
}
})
@@ -3200,9 +3201,9 @@ async function startProductionMode(): Promise<void> {
afterInitialAttempt: () => ensureContextMapperPolling(),
})
- console.log(`[Main] Approval system: ${config.enableApproval ? 'ENABLED' : 'DISABLED'}`)
- console.log('[Main] MCP Host running. Press Ctrl+C to exit.')
- console.log('[Main] Waiting for messages from channel-reader...\n')
+ logger.info({ detail: config.enableApproval ? 'ENABLED' : 'DISABLED' }, '[Main] Approval system:')
+ logger.info({}, '[Main] MCP Host running. Press Ctrl+C to exit.')
+ logger.info({}, '[Main] Waiting for messages from channel-reader...')
// Handle graceful shutdown
process.once('SIGTERM', () => shutdown('SIGTERM'))
@@ -3222,7 +3223,10 @@ async function startPluginWorkloadSdkOnlyMode(): Promise<void> {
)
}
- console.log(`[Main] Starting in SDK-ONLY MODE (recipe: ${config.workflowRecipeName})`)
+ logger.info(
+ { workflowRecipeName: config.workflowRecipeName },
+ '[Main] Starting in SDK-ONLY MODE (recipe: )'
+ )
setCodexPolicyBindingReader(() => sdkOnlyBindingAsPolicy())
setGrokPolicyBindingReader(() => sdkOnlyGrokBindingAsPolicy())
@@ -3291,7 +3295,7 @@ async function startPluginWorkloadSdkOnlyMode(): Promise<void> {
throw err
}
- console.log('[Main] SDK-only mcp-host ready — waiting for WRC identity bootstrap')
+ logger.info({}, '[Main] SDK-only mcp-host ready — waiting for WRC identity bootstrap')
process.once('SIGTERM', () => shutdown('SIGTERM'))
process.once('SIGINT', () => shutdown('SIGINT'))
}
@@ -3300,15 +3304,16 @@ async function startPluginWorkloadSdkOnlyMode(): Promise<void> {
* Main entry point.
*/
async function main(): Promise<void> {
- console.log('='.repeat(50))
- console.log('MCP Host - Starting')
- console.log('='.repeat(50))
+ logger.info({ detail: '='.repeat(50) }, 'Host runtime status')
+ logger.info({}, 'MCP Host - Starting')
+ logger.info({ detail: '='.repeat(50) }, 'Host runtime status')
// M-18: Startup validation — crash-fail if auth is enabled but keys are missing.
// Silently disabling auth leaves workflow endpoints unauthenticated with no indication
// in metrics or logs that auth is off. In workflow mode this is always a misconfiguration.
if (config.enableAuth && !config.authJwtPublicKey) {
- console.error(
+ logger.error(
+ {},
'[Main] FATAL: enableAuth=true but CLERUM_AUTH_JWT_PUBLIC_KEY is not set — refusing to start'
)
process.exit(1)
@@ -3318,8 +3323,9 @@ async function main(): Promise<void> {
(config.runtimeKind === 'workflow' || config.runtimeKind === 'sdk-only') &&
!config.wrcPublicKey
) {
- console.error(
- `[Main] FATAL: enableAuth=true in ${config.runtimeKind} mode but WRC_PUBLIC_KEY_PEM is not set — refusing to start`
+ logger.error(
+ { runtimeKind: config.runtimeKind },
+ '[Main] FATAL: enableAuth=true in mode but WRC_PUBLIC_KEY_PEM is not set — refusing to start'
)
process.exit(1)
}
@@ -3338,7 +3344,7 @@ async function main(): Promise<void> {
})
} catch (err) {
if (err instanceof StatelessBootError) {
- console.error(`[Main] FATAL: ${err.message}`)
+ logger.error({ err: err }, '[Main] FATAL:')
process.exit(1)
}
throw err
@@ -3351,7 +3357,7 @@ async function main(): Promise<void> {
})
} catch (err) {
if (err instanceof StatelessCronPolicyError) {
- console.error(`[Main] FATAL: ${err.message}`)
+ logger.error({ err: err }, '[Main] FATAL:')
process.exit(1)
}
throw err
@@ -3363,7 +3369,8 @@ async function main(): Promise<void> {
// stateless Host could never report activity and would poison HCC's
// suspend decisions.
if (config.statelessLifecycle && !config.mcpHostGatewayUrl) {
- console.error(
+ logger.error(
+ {},
'[Main] FATAL: CLERUM_STATELESS_LIFECYCLE=true but MCP_HOST_GATEWAY_URL is not set — refusing to start'
)
process.exit(1)
@@ -3381,8 +3388,9 @@ async function main(): Promise<void> {
missingApprovalVars.push('MCP_HOST_WORKFLOW_CONTROL_TOKEN_FILE')
}
if (missingApprovalVars.length > 0) {
- console.error(
- `[Main] FATAL: Workflow mode enabled but runtime token vars missing: ${missingApprovalVars.join(', ')} — refusing to start`
+ logger.error(
+ { detail: missingApprovalVars.join(', ') },
+ '[Main] FATAL: Workflow mode enabled but runtime token vars missing: — refusing to start'
)
process.exit(1)
}
@@ -3393,7 +3401,10 @@ async function main(): Promise<void> {
await dispatchMcpHostRuntime(config.runtimeKind, {
sdkOnly: startPluginWorkloadSdkOnlyMode,
workflow: async () => {
- console.log(`[Main] Starting in WORKFLOW MODE (recipe: ${config.workflowRecipeName})`)
+ logger.info(
+ { workflowRecipeName: config.workflowRecipeName },
+ '[Main] Starting in WORKFLOW MODE (recipe: )'
+ )
const { WorkflowService } = await import('./workflow/workflowService')
const { McpClient, staticTokenProvider } = await import('./mcp/client')
@@ -3510,7 +3521,7 @@ async function main(): Promise<void> {
await pluginWorkloadSdkServer.start()
}
- console.log('[Main] Workflow mcp-host ready — waiting for /configure from WRC')
+ logger.info({}, '[Main] Workflow mcp-host ready — waiting for /configure from WRC')
process.once('SIGTERM', () => shutdown('SIGTERM'))
process.once('SIGINT', () => shutdown('SIGINT'))
},
@@ -3534,14 +3545,17 @@ if (require.main === module) {
// and exit non-zero for a clean k8s restart; an unhandledRejection is logged
// for triage but is not treated as fatal on its own.
process.on('uncaughtException', (err, origin) => {
- console.error(`[Main] FATAL uncaughtException (${origin}):`, err)
+ logger.error({ origin: origin, err: err }, '[Main] FATAL uncaughtException ():')
process.exit(1)
})
process.on('unhandledRejection', reason => {
- console.error('[Main] unhandledRejection:', reason)
+ logger.error(
+ { err: reason instanceof Error ? reason : new Error('Unhandled rejection') },
+ '[Main] unhandledRejection:'
+ )
})
main().catch(error => {
- console.error('[Main] Fatal error:', error)
+ logger.error({ err: error }, '[Main] Fatal error:')
process.exit(1)
})
}
diff --git a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
index adfe1c551..3e3c5fcd0 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
@@ -95,6 +95,17 @@ function makeDeps(
}
describe('PromptBridgeHandler', () => {
+ it.each([null, 42, {}, []])(
+ 'rejects non-text content %j before authorization or inference',
+ async content => {
+ const { handler, authorize, complete } = makeDeps()
+ await expect(
+ handler.handle({ ...validBody, messages: [{ role: 'user', content }] }, 'api')
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ expect(authorize).not.toHaveBeenCalled()
+ expect(complete).not.toHaveBeenCalled()
+ }
+ )
it('rejects invalid input before authorizing', async () => {
const { handler, authorize } = makeDeps()
await expect(
diff --git a/mcp-host/src/queue/__tests__/duplicateAdmission.test.ts b/mcp-host/src/queue/__tests__/duplicateAdmission.test.ts
index 87710953e..f01afcab0 100644
--- a/mcp-host/src/queue/__tests__/duplicateAdmission.test.ts
+++ b/mcp-host/src/queue/__tests__/duplicateAdmission.test.ts
@@ -14,6 +14,7 @@
*/
import { afterEach, describe, expect, it, vi } from 'vitest'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { logger } from '../../logger'
import type { IncomingMessage } from '../../server'
import { MessageQueue } from '../messageQueue'
@@ -57,7 +58,7 @@ describe('MessageQueue.admit — duplicate suppression sink', () => {
it('rejects re-admission of an already-registered task id — no second queue entry, loud log', () => {
const { queue, lifecycle } = wiredQueue()
- const warn = vi.spyOn(console, 'warn')
+ const warn = vi.spyOn(logger, 'warn')
const task = queue.createTaskFromMessage(message('m-readmit'))
expect(queue.admit(task)).toEqual({ admitted: true })
@@ -78,13 +79,13 @@ describe('MessageQueue.admit — duplicate suppression sink', () => {
expect(queue.dequeue()?.id).toBe(task.id)
expect(queue.dequeue()).toBeNull()
expect(
- warn.mock.calls.some(args => String(args[0]).includes('duplicate delivery suppressed'))
+ warn.mock.calls.some(args => String(args[1]).includes('duplicate delivery suppressed'))
).toBe(true)
})
it('rejects a duplicate delivery (same messageId, fresh uuid) while the original is still in flight', () => {
const { queue } = wiredQueue()
- const warn = vi.spyOn(console, 'warn')
+ const warn = vi.spyOn(logger, 'warn')
const first = queue.createTaskFromMessage(message('m-inflight'))
expect(queue.admit(first)).toEqual({ admitted: true })
expect(queue.dequeue()?.id).toBe(first.id) // pending → processing
@@ -104,7 +105,7 @@ describe('MessageQueue.admit — duplicate suppression sink', () => {
expect(queue.getTask(duplicate.id)).toBeNull()
expect(queue.getTask(first.id)?.id).toBe(first.id)
expect(
- warn.mock.calls.some(args => String(args[0]).includes('duplicate delivery suppressed'))
+ warn.mock.calls.some(args => String(args[1]).includes('duplicate delivery suppressed'))
).toBe(true)
})
@@ -204,7 +205,7 @@ describe('MessageQueue.admit — duplicate suppression sink', () => {
// A same-messageId wake-retry (fresh uuid) must now be deduped, NOT admitted
// as a second execution.
- const warn = vi.spyOn(console, 'warn')
+ const warn = vi.spyOn(logger, 'warn')
const retry = queue.createTaskFromMessage(message('m-overflow'))
expect(retry.id).not.toBe(overflow.id)
const retryOutcome = queue.admit(retry)
@@ -217,7 +218,7 @@ describe('MessageQueue.admit — duplicate suppression sink', () => {
// The retry never registered — no second execution path.
expect(lifecycle.getStatus(retry.id)).toBeNull()
expect(
- warn.mock.calls.some(args => String(args[0]).includes('duplicate delivery suppressed'))
+ warn.mock.calls.some(args => String(args[1]).includes('duplicate delivery suppressed'))
).toBe(true)
})
diff --git a/mcp-host/src/queue/messageQueue.ts b/mcp-host/src/queue/messageQueue.ts
index 7c928583a..45e04995a 100644
--- a/mcp-host/src/queue/messageQueue.ts
+++ b/mcp-host/src/queue/messageQueue.ts
@@ -21,6 +21,7 @@ import { v4 as uuidv4 } from 'uuid'
import type { CronJob } from '../agent/types'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import type { TransitionEvent } from '../lifecycle/types'
+import { logger } from '../logger'
import { IncomingMessage } from '../server'
import {
AdmissionOutcome,
@@ -202,14 +203,21 @@ export class MessageQueue extends EventEmitter {
* carrying a non-empty client-supplied messageId participate — tasks
* without a sourceMessage (internal) or with an empty messageId never dedupe.
*/
- private static deliveryKeyOf(task: Task): string | null {
- const msg = task.sourceMessage
+ static deliveryKeyOf(msg: IncomingMessage | undefined): string | null {
if (!msg) return null
const messageId = msg.messageId?.trim()
if (!messageId) return null
return `${msg.channelType}:${msg.channelId}:${msg.sender}:${messageId}`
}
+ /** Read-only replay check before model-selection side effects. */
+ hasAdmittedDelivery(message: IncomingMessage): boolean {
+ const key = MessageQueue.deliveryKeyOf(message)
+ if (!key || !this.lifecycle) return false
+ const id = this.deliveryIndex.get(key)
+ return id !== undefined && this.lifecycle.getStatus(id) !== null
+ }
+
/**
* Single admission sink for task execution.
*
@@ -227,13 +235,14 @@ export class MessageQueue extends EventEmitter {
* prior state — duplicates are never silently swallowed and never re-run.
*/
admit(task: Task): AdmissionOutcome {
- const deliveryKey = MessageQueue.deliveryKeyOf(task)
+ const deliveryKey = MessageQueue.deliveryKeyOf(task.sourceMessage)
if (this.lifecycle) {
const priorStatus = this.lifecycle.getStatus(task.id)
if (priorStatus !== null) {
- console.warn(
- `[Queue] duplicate delivery suppressed — task ${task.id} is already registered (status=${priorStatus}); admission rejected, no new execution`
+ logger.warn(
+ { taskId: task.id, priorStatus },
+ 'duplicate delivery suppressed: task already registered'
)
return { admitted: false, reason: 'duplicate_task_id', priorTaskId: task.id, priorStatus }
}
@@ -243,8 +252,9 @@ export class MessageQueue extends EventEmitter {
if (priorTaskId && priorTaskId !== task.id) {
const priorDeliveryStatus = this.lifecycle.getStatus(priorTaskId)
if (priorDeliveryStatus !== null) {
- console.warn(
- `[Queue] duplicate delivery suppressed — ${deliveryKey} already admitted as task ${priorTaskId} (status=${priorDeliveryStatus}); rejected duplicate task ${task.id}, no new execution`
+ logger.warn(
+ { taskId: task.id, priorTaskId, priorStatus: priorDeliveryStatus },
+ 'duplicate delivery suppressed: delivery already admitted'
)
// The duplicate Task object will never run — drop its instance-index
// entry (it has no lifecycle record, so eviction would never reap it).
@@ -265,7 +275,7 @@ export class MessageQueue extends EventEmitter {
}
if (this.pendingQueue.length >= this.maxQueueSize) {
- console.warn(`[Queue] Task ${task.id} rejected: queue full (${this.maxQueueSize})`)
+ logger.warn({ taskId: task.id, maxQueueSize: this.maxQueueSize }, 'Task rejected: queue full')
this.emitEvent('queue:full', task)
// C1: queue_full is NOT a no-op — the caller (messageHandler) still
// registers this task's lifecycle record and dispatches it via
@@ -300,9 +310,7 @@ export class MessageQueue extends EventEmitter {
this.deliveryKeyByTaskId.set(task.id, deliveryKey)
}
- console.log(
- `[Queue] Task ${task.id} added (source: ${task.source}, priority: ${task.priority})`
- )
+ logger.info({ taskId: task.id, source: task.source, priority: task.priority }, 'Task admitted')
// task:added is forwarded from lifecycle transition (null→pending) via handleLifecycleTransition.
// Emit it directly here too for callers that set up lifecycle AFTER enqueue (e.g. tests).
if (!this.lifecycle) {
@@ -333,7 +341,7 @@ export class MessageQueue extends EventEmitter {
task.startedAt = new Date()
this.lifecycle?.transition(task.id, 'processing', 'dispatched')
- console.log(`[Queue] Task ${task.id} dequeued for processing`)
+ logger.info({ taskId: task.id }, 'Task dequeued for processing')
// task:started is forwarded from lifecycle transition via handleLifecycleTransition.
if (!this.lifecycle) {
this.emitEvent('task:started', task)
@@ -358,7 +366,7 @@ export class MessageQueue extends EventEmitter {
response: task.result?.response,
})
- console.log(`[Queue] Task ${task.id} completed`)
+ logger.info({ taskId: task.id }, 'Task completed')
// task:completed forwarded via handleLifecycleTransition.
if (!this.lifecycle) {
this.emitEvent('task:completed', task)
@@ -380,7 +388,7 @@ export class MessageQueue extends EventEmitter {
task.completedAt = new Date()
this.lifecycle?.transition(task.id, 'failed', `error:${error.code}`, { error })
- console.log(`[Queue] Task ${task.id} failed: ${error.code}`)
+ logger.info({ taskId: task.id, code: error.code }, 'Task failed')
// task:failed forwarded via handleLifecycleTransition.
if (!this.lifecycle) {
this.emitEvent('task:failed', task)
diff --git a/mcp-host/src/server.ts b/mcp-host/src/server.ts
index c7039bcea..992474405 100644
--- a/mcp-host/src/server.ts
+++ b/mcp-host/src/server.ts
@@ -190,8 +190,9 @@ export class RPCServer {
})
// Image attachments are sent as base64 in /v1/runtime/messages.
- // 6mb comfortably covers the default 3mb binary limit plus JSON overhead.
- this.app.use(express.json({ limit: '6mb' }))
+ // 10mb covers the Desktop's 8 MB combined base64 image budget plus the text
+ // and JSON envelope.
+ this.app.use(express.json({ limit: '10mb' }))
this.registerRoutes()
}
diff --git a/mcp-host/src/server/__tests__/messageRoute.test.ts b/mcp-host/src/server/__tests__/messageRoute.test.ts
index 0815ac0f8..66e2750bd 100644
--- a/mcp-host/src/server/__tests__/messageRoute.test.ts
+++ b/mcp-host/src/server/__tests__/messageRoute.test.ts
@@ -41,6 +41,17 @@ function makeRes(): CapturedRes {
}
describe('handleMessageRoute — rpc sender identity invariant', () => {
+ it.each([null, undefined, 42, {}, []])(
+ 'rejects non-string content %j before dispatch',
+ async content => {
+ const messageHandler = vi.fn()
+ const req = { body: { content } } as unknown as Request
+ const captured = makeRes()
+ await handleMessageRoute(req, captured.res, makeHandlers({ messageHandler }))
+ expect(captured.statusCode).toBe(400)
+ expect(messageHandler).not.toHaveBeenCalled()
+ }
+ )
// Tests assume auth is enabled (production / minikube default).
beforeEach(() => {
;(config as { enableAuth: boolean }).enableAuth = true
@@ -194,12 +205,11 @@ describe('handleMessageRoute — rpc sender identity invariant', () => {
})
it('maps persisted ownership mismatches to a generic 403', async () => {
- const messageHandler = vi.fn().mockRejectedValue(
- new ConversationError(
- 'sensitive ownership detail',
- ConversationErrorCode.OwnershipMismatch
+ const messageHandler = vi
+ .fn()
+ .mockRejectedValue(
+ new ConversationError('sensitive ownership detail', ConversationErrorCode.OwnershipMismatch)
)
- )
const req = {
runtimeCaller: { caller: 'rpc-proxy', hostRef: 'chatllm', userId: 'legit-user' },
body: {
diff --git a/mcp-host/src/server/__tests__/modelRoutes.test.ts b/mcp-host/src/server/__tests__/modelRoutes.test.ts
index 2ca5f58e4..ea346d12d 100644
--- a/mcp-host/src/server/__tests__/modelRoutes.test.ts
+++ b/mcp-host/src/server/__tests__/modelRoutes.test.ts
@@ -127,7 +127,13 @@ describe('handleSetModelRoute (POST /v1/runtime/model)', () => {
provider: 'claude',
model: 'claude-haiku-4-5',
})
- expect(setModelHandler).toHaveBeenCalledWith('u-1', 'chatllm', 'c-9', 'claude-haiku-4-5')
+ expect(setModelHandler).toHaveBeenCalledWith(
+ 'u-1',
+ 'chatllm',
+ 'c-9',
+ 'claude-haiku-4-5',
+ undefined
+ )
})
it('returns 403 model_not_allowed when the handler rejects the model', async () => {
@@ -153,6 +159,55 @@ describe('handleSetModelRoute (POST /v1/runtime/model)', () => {
})
})
+ it('passes the revision and returns an explicit conflict without disguising it as a model denial', async () => {
+ const setModelHandler: SetModelHandler = vi.fn().mockResolvedValue({
+ ok: false,
+ reason: 'model_selection_conflict',
+ provider: 'claude',
+ model: 'chosen',
+ modelSelectionRevision: 4,
+ })
+ const captured = makeRes()
+ await handleSetModelRoute(
+ makeReq({
+ caller: 'rpc-proxy',
+ userId: 'u-1',
+ hostRef: 'chatllm',
+ body: { chatId: 'c-9', model: 'chosen', expectedRevision: 2 },
+ }),
+ captured.res,
+ makeHandlers({ setModelHandler })
+ )
+ expect(setModelHandler).toHaveBeenCalledWith('u-1', 'chatllm', 'c-9', 'chosen', 2)
+ expect(captured.statusCode).toBe(409)
+ expect(captured.jsonBody).toEqual({
+ error: 'model_selection_conflict',
+ provider: 'claude',
+ model: 'chosen',
+ modelSelectionRevision: 4,
+ })
+ })
+
+ it.each([-1, 0.5, '1', null, Number.MAX_SAFE_INTEGER + 1])(
+ 'rejects an invalid revision %s before mutation',
+ async expectedRevision => {
+ const setModelHandler: SetModelHandler = vi.fn()
+ const captured = makeRes()
+ await handleSetModelRoute(
+ makeReq({
+ caller: 'rpc-proxy',
+ userId: 'u-1',
+ hostRef: 'chatllm',
+ body: { chatId: 'c-9', model: 'chosen', expectedRevision },
+ }),
+ captured.res,
+ makeHandlers({ setModelHandler })
+ )
+ expect(captured.statusCode).toBe(400)
+ expect(setModelHandler).not.toHaveBeenCalled()
+ }
+ )
+
it('returns 400 when chatId is missing (mandatory)', async () => {
const setModelHandler: SetModelHandler = vi.fn()
const req = makeReq({
@@ -189,12 +244,11 @@ describe('handleSetModelRoute (POST /v1/runtime/model)', () => {
})
it('maps persisted ownership mismatches to a generic 403', async () => {
- const setModelHandler: SetModelHandler = vi.fn().mockRejectedValue(
- new ConversationError(
- 'sensitive ownership detail',
- ConversationErrorCode.OwnershipMismatch
+ const setModelHandler: SetModelHandler = vi
+ .fn()
+ .mockRejectedValue(
+ new ConversationError('sensitive ownership detail', ConversationErrorCode.OwnershipMismatch)
)
- )
const req = makeReq({
caller: 'rpc-proxy',
userId: 'u-1',
diff --git a/mcp-host/src/server/routes.ts b/mcp-host/src/server/routes.ts
index fb5354394..cc0eacc4a 100644
--- a/mcp-host/src/server/routes.ts
+++ b/mcp-host/src/server/routes.ts
@@ -2,6 +2,7 @@ import type { Request, Response } from 'express'
import { ConversationError, ConversationErrorCode } from '../core/errors'
import type { ApprovalDecision } from '../core/extensions/approvalTypes'
import { isTraceContextV1 } from '../core/types'
+import { logger } from '../logger'
import { getRuntimeCallerContext } from './edgeRuntimeAuth'
import { badRequest, json } from './httpUtils'
import type {
@@ -39,6 +40,12 @@ import type {
import type { RuntimeCallerContext } from './types'
import { decodeSessionsCursor, sessionsCursorScope } from './wireProjections'
+/** Narrows an untrusted body field to the CAS revision the model routes accept,
+ * so the call site needs no cast to drop `unknown`. */
+function isNonNegativeSafeInteger(value: unknown): value is number {
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+}
+
export type RouteHandlers = {
messageHandler: MessageHandler | null
statusHandler: StatusHandler | null
@@ -265,7 +272,7 @@ export async function handleCompactionRoute(
}
}
} catch (error) {
- console.error('[Server] Error during compaction:', error)
+ logger.error({ err: error }, '[Server] Error during compaction')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -284,7 +291,7 @@ export async function handleStatusRoute(
const status = await handlers.statusHandler()
json(res, 200, status)
} catch (error) {
- console.error('[Server] Error getting status:', error)
+ logger.error({ err: error }, '[Server] Error getting status')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -297,6 +304,11 @@ export async function handleMessageRoute(
try {
const message = req.body as IncomingMessage
+ if (typeof message?.content !== 'string') {
+ badRequest(res, 'content must be a string')
+ return
+ }
+
if (message?.traceContext != null && !isTraceContextV1(message.traceContext)) {
badRequest(res, 'Invalid traceContext')
return
@@ -339,7 +351,10 @@ export async function handleMessageRoute(
}
}
- console.log(`[Server] Received message from ${message.channelType}/${message.sender}`)
+ logger.info(
+ { channelType: message.channelType, sender: message.sender },
+ '[Server] Received message'
+ )
if (!handlers.messageHandler) {
json(res, 500, { success: false, error: 'No message handler configured' })
@@ -356,7 +371,7 @@ export async function handleMessageRoute(
const response = await handlers.messageHandler(message, isAsync ? { async: true } : undefined)
json(res, 200, response)
} catch (error) {
- console.error('[Server] Error processing message:', error)
+ logger.error({ err: error }, '[Server] Error processing message')
if (isSessionOwnershipError(error)) {
json(res, 403, { success: false, error: 'session access denied' })
return
@@ -389,7 +404,7 @@ export async function handleActivityRoute(
const snapshot = await handlers.activitySnapshotHandler(limit, sinceEventId)
json(res, 200, snapshot)
} catch (error) {
- console.error('[Server] Error getting activity snapshot:', error)
+ logger.error({ err: error }, '[Server] Error getting activity snapshot')
json(res, 500, { error: 'Activity unavailable' })
}
}
@@ -512,13 +527,17 @@ export async function handleApprovalRoute(
channelId,
}
- console.log(
- `[Server] ${approved ? 'Approval' : 'Denial'} from ${userId} for request ${requestId}`
+ logger.info(
+ { detail: approved ? 'Approval' : 'Denial', userId: userId, requestId: requestId },
+ '[Server] from for request'
)
const result = await handlers.approvalHandler(decision)
json(res, 200, result)
} catch (error) {
- console.error(`[Server] Error handling ${approved ? 'approval' : 'denial'}:`, error)
+ logger.error(
+ { detail: approved ? 'approval' : 'denial', err: error },
+ '[Server] Error handling approval decision'
+ )
json(res, 500, {
success: false,
error: error instanceof Error ? error.message : 'Unknown error',
@@ -608,7 +627,7 @@ export async function handleProviderMessageAuthorizationRoute(
})
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error authorizing provider message:', error)
+ logger.error({ err: error }, '[Server] Error authorizing provider message')
json(res, 500, { authorized: false, error: 'Provider authorization unavailable' })
}
}
@@ -663,7 +682,7 @@ export async function handleProviderWorkflowApprovalDecisionRoute(
})
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error handling provider workflow approval decision:', error)
+ logger.error({ err: error }, '[Server] Error handling provider workflow approval decision')
json(res, 500, {
success: false,
error: 'Provider workflow approval decision unavailable',
@@ -721,7 +740,7 @@ export async function handleProviderWorkflowApprovalResolveRoute(
}
json(res, 502, { error: result.error })
} catch (error) {
- console.error('[Server] Error resolving provider workflow approval:', error)
+ logger.error({ err: error }, '[Server] Error resolving provider workflow approval')
json(res, 500, {
error: 'Provider workflow approval resolve unavailable',
})
@@ -821,7 +840,7 @@ export async function handleProviderWorkflowResultRequestRoute(
)
json(res, result.success ? 200 : 403, result)
} catch (error) {
- console.error('[Server] Error handling provider workflow result request:', error)
+ logger.error({ err: error }, '[Server] Error handling provider workflow result request')
json(res, 500, {
success: false,
error: 'Provider workflow result request unavailable',
@@ -913,7 +932,7 @@ export async function handleWorkflowApprovalNotificationClaimRoute(
}
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error claiming workflow approval notifications:', error)
+ logger.error({ err: error }, '[Server] Error claiming workflow approval notifications')
json(res, 500, { deliveries: [], error: 'Workflow approval notifications unavailable' })
}
}
@@ -966,7 +985,7 @@ export async function handleWorkflowApprovalNotificationTerminalRoute(
}
res.status(204).end()
} catch (error) {
- console.error('[Server] Error updating workflow approval notification:', error)
+ logger.error({ err: error }, '[Server] Error updating workflow approval notification')
json(res, 500, { error: 'Workflow approval notification update unavailable' })
}
}
@@ -1020,7 +1039,7 @@ export async function handleWorkflowApprovalMediumEnrollmentRoute(
})
json(res, result.ok ? 200 : 409, result)
} catch (error) {
- console.error('[Server] Error confirming workflow approval medium enrollment:', error)
+ logger.error({ err: error }, '[Server] Error confirming workflow approval medium enrollment')
json(res, 500, { ok: false, error: 'Workflow approval medium enrollment unavailable' })
}
}
@@ -1075,7 +1094,10 @@ export async function handleTelegramWorkflowApprovalVerificationRoute(
})
json(res, result.ok ? 200 : 409, result)
} catch (error) {
- console.error('[Server] Error confirming Telegram workflow approval verification:', error)
+ logger.error(
+ { err: error },
+ '[Server] Error confirming Telegram workflow approval verification'
+ )
json(res, 500, { ok: false, error: 'Telegram workflow approval verification unavailable' })
}
}
@@ -1099,7 +1121,7 @@ export async function handleTaskResultRoute(
}
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error getting task result:', error)
+ logger.error({ err: error }, '[Server] Error getting task result')
json(res, 500, {
success: false,
error: error instanceof Error ? error.message : 'Unknown error',
@@ -1178,7 +1200,7 @@ export async function handleSessionsListRoute(
const result = await handlers.sessionsListHandler(caller.userId, { agent, limit, cursor })
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error listing sessions:', error)
+ logger.error({ err: error }, '[Server] Error listing sessions')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -1235,7 +1257,7 @@ export async function handleSessionSearchRoute(
})
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error searching sessions:', error)
+ logger.error({ err: error }, '[Server] Error searching sessions')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -1310,7 +1332,7 @@ export async function handleSessionMessagesRoute(
}
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error fetching session messages:', error)
+ logger.error({ err: error }, '[Server] Error fetching session messages')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -1348,7 +1370,7 @@ export async function handleContextBreakdownRoute(
}
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error fetching context breakdown:', error)
+ logger.error({ err: error }, '[Server] Error fetching context breakdown')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -1383,7 +1405,7 @@ export async function handleModelsListRoute(
)
json(res, 200, result)
} catch (error) {
- console.error('[Server] Error listing models:', error)
+ logger.error({ err: error }, '[Server] Error listing models')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
@@ -1420,14 +1442,39 @@ export async function handleSetModelRoute(
badRequest(res, 'model is required')
return
}
- const result = await handlers.setModelHandler(caller.userId, caller.hostRef, chatId, model)
+ const expectedRevision = body.expectedRevision
+ if (expectedRevision !== undefined && !isNonNegativeSafeInteger(expectedRevision)) {
+ badRequest(res, 'expectedRevision must be a non-negative integer')
+ return
+ }
+ const result = await handlers.setModelHandler(
+ caller.userId,
+ caller.hostRef,
+ chatId,
+ model,
+ expectedRevision
+ )
if (!result.ok) {
- json(res, 403, { error: result.reason, provider: result.provider, model: result.model })
+ json(res, result.reason === 'model_selection_conflict' ? 409 : 403, {
+ error: result.reason,
+ provider: result.provider,
+ model: result.model,
+ ...(result.modelSelectionRevision === undefined
+ ? {}
+ : { modelSelectionRevision: result.modelSelectionRevision }),
+ })
return
}
- json(res, 200, { effective: 'next-task', provider: result.provider, model: result.model })
+ json(res, 200, {
+ effective: 'next-task',
+ provider: result.provider,
+ model: result.model,
+ ...(result.modelSelectionRevision === undefined
+ ? {}
+ : { modelSelectionRevision: result.modelSelectionRevision }),
+ })
} catch (error) {
- console.error('[Server] Error setting model:', error)
+ logger.error({ err: error }, '[Server] Error setting model')
if (isSessionOwnershipError(error)) {
json(res, 403, { error: 'session access denied' })
return
@@ -1480,7 +1527,7 @@ export async function handleSetTitleRoute(
}
json(res, 200, { ok: true, title: result.title })
} catch (error) {
- console.error('[Server] Error setting session title:', error)
+ logger.error({ err: error }, '[Server] Error setting session title')
json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
}
}
diff --git a/mcp-host/src/server/types.ts b/mcp-host/src/server/types.ts
index cafb9fa5d..83fb03c71 100644
--- a/mcp-host/src/server/types.ts
+++ b/mcp-host/src/server/types.ts
@@ -50,6 +50,10 @@ export interface IncomingMessage {
* non-allowlisted value is ignored (fail-open on the message).
*/
model?: string
+ /** Optional CAS base for a visual message's explicit model selection. */
+ modelSelectionRevision?: number
+ /** Server-owned immutable visual selection; incoming callers cannot set it. */
+ imageModel?: { provider: string; model: string }
}
export type RuntimeCallerKind = 'rpc-proxy' | 'channel-reader' | 'workflow-approval-request-reader'
@@ -73,6 +77,34 @@ export interface MessageResponse {
error?: TaskError
model?: string
taskId?: string
+ /**
+ * Issue #654 — the session's model-selection revision after the Host accepted
+ * a piggybacked `model`, or the winning revision on a CAS conflict.
+ *
+ * The send IS the write, so its result must travel back on the same response:
+ * `POST /v1/runtime/model` is unreachable on a suspended Host, which is why
+ * the selection rides the message in the first place.
+ *
+ * Present when:
+ * - the piggybacked `model` was written: the new revision (the previous
+ * one + 1). A text-only message always writes, even the Host default;
+ * - an IMAGE message's `model` already WAS the effective model (the explicit
+ * selection, or the Host default when there is none): nothing is written
+ * and this is the unchanged current revision. The image carries the model
+ * the client displays, which is not a user pick, so it must not pin it;
+ * - an image message's `modelSelectionRevision` was stale: the winning
+ * revision, with `LLM_MODEL_SELECTION_CONFLICT`.
+ *
+ * Absent when the message carried no `model`, when the `modelSelectionRevision`
+ * itself was invalid, when an image message was refused because the requested
+ * model cannot read images (`LLM_IMAGE_INPUT_*`; the selection is NOT written,
+ * so the revision the client holds is still current), or when the selection
+ * was rejected. (During a boot fallback the task runs on another pair; if THAT
+ * pair refuses the image, the requested selection was already written and the
+ * refusal carries its new revision.) Absent on a successful ack after a piggyback means the Host
+ * IGNORED the selection.
+ */
+ modelSelectionRevision?: number
usage?: {
promptTokens: number
completionTokens: number
@@ -635,6 +667,7 @@ export interface ModelsListResult {
provider: string
hostDefault: string
sessionModel: string | null
+ modelSelectionRevision?: number
sessionModelBlocked?: string
degraded: boolean
models: RuntimeModelEntry[]
@@ -651,14 +684,21 @@ export type ModelsListHandler = (
* `model_not_allowed` → 403. The route owns the 400 (missing chatId/model).
*/
export type SetModelResult =
- | { ok: true; provider: string; model: string }
- | { ok: false; reason: 'model_not_allowed'; provider: string; model: string }
+ | { ok: true; provider: string; model: string; modelSelectionRevision?: number }
+ | {
+ ok: false
+ reason: 'model_not_allowed' | 'model_selection_conflict'
+ provider: string
+ model: string
+ modelSelectionRevision?: number
+ }
export type SetModelHandler = (
userSub: string,
hostRef: string,
chatId: string,
- model: string
+ model: string,
+ expectedRevision?: number
) => SetModelResult | Promise<SetModelResult>
/**
diff --git a/mcp-host/src/workflow/workflowRouter.ts b/mcp-host/src/workflow/workflowRouter.ts
index 1372a70b2..b04b114ac 100644
--- a/mcp-host/src/workflow/workflowRouter.ts
+++ b/mcp-host/src/workflow/workflowRouter.ts
@@ -115,7 +115,12 @@ export function createWorkflowRouter(service: WorkflowService): Router {
if (!validateWorkflowBinding(req, res, { expectedSub: 'coordinator' })) return
const body = req.body as ExecuteStepRequest
- if (!body.stepId || !body.instruction) {
+ if (
+ typeof body?.stepId !== 'string' ||
+ !body.stepId ||
+ typeof body.instruction !== 'string' ||
+ !body.instruction
+ ) {
res.status(400).json({ error: 'stepId and instruction are required' })
return
}
diff --git a/packages/llm-providers/imageInput.cjs b/packages/llm-providers/imageInput.cjs
new file mode 100644
index 000000000..a620595be
--- /dev/null
+++ b/packages/llm-providers/imageInput.cjs
@@ -0,0 +1,125 @@
+'use strict'
+
+// Model evidence is independent of transport implementation and authorization.
+// Invalid/legacy metadata must never become affirmative support.
+const STATES = new Set(['supported', 'unsupported', 'unknown'])
+const SOURCES = new Set(['curated', 'discovery'])
+
+function record(value) {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function onlyKeys(value, allowed) {
+ return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function validDate(value) {
+ if (
+ typeof value !== 'string' ||
+ !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+ )
+ return false
+ const date = new Date(value)
+ if (!Number.isFinite(date.getTime())) return false
+ const canonical = date.toISOString()
+ return value === canonical || value === canonical.replace('.000Z', 'Z')
+}
+
+function validReference(value) {
+ if (typeof value !== 'string' || value.length > 1024) return false
+ if (/^evidence:[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/.test(value)) return true
+ try {
+ const url = new URL(value)
+ // A DNS root dot is not part of the hostname. Policy decisions compare the
+ // normalized form so a trailing dot cannot bypass intranet rejection, while
+ // the caller's exact reference string is preserved for storage and output.
+ const hostname = url.hostname.replace(/\.+$/, '')
+ return (
+ url.protocol === 'https:' &&
+ !url.username &&
+ !url.password &&
+ !url.search &&
+ !url.hash &&
+ !/[\s\u0000-\u001f\u007f]/.test(value) &&
+ hostname !== '' &&
+ !/^(?:localhost|[\d.]+|\[)/i.test(hostname) &&
+ !/\.(?:local|internal|localhost)$/i.test(hostname) &&
+ hostname.includes('.')
+ )
+ } catch {
+ return false
+ }
+}
+
+function parseImageInputCapability(value) {
+ if (!record(value) || !onlyKeys(value, ['state', 'evidence']) || !STATES.has(value.state))
+ return null
+ if (value.evidence === undefined) return value.state === 'unknown' ? { state: 'unknown' } : null
+ const evidence = value.evidence
+ if (
+ !record(evidence) ||
+ !onlyKeys(evidence, ['source', 'reference', 'checkedAt', 'validUntil']) ||
+ !SOURCES.has(evidence.source) ||
+ !validReference(evidence.reference) ||
+ !validDate(evidence.checkedAt)
+ )
+ return null
+ if (
+ evidence.validUntil !== undefined &&
+ (!validDate(evidence.validUntil) ||
+ Date.parse(evidence.validUntil) <= Date.parse(evidence.checkedAt))
+ )
+ return null
+ // Discovery has no inherent freshness guarantee. Known support requires an
+ // explicit validity bound; merely downloading an old snapshot is not proof.
+ if (value.state !== 'unknown' && evidence.source === 'discovery' && !evidence.validUntil)
+ return null
+ return {
+ state: value.state,
+ evidence: {
+ source: evidence.source,
+ reference: evidence.reference,
+ checkedAt: evidence.checkedAt,
+ ...(evidence.validUntil === undefined ? {} : { validUntil: evidence.validUntil }),
+ },
+ }
+}
+
+function normalizeImageInputCapability(value) {
+ return parseImageInputCapability(value) ?? { state: 'unknown' }
+}
+
+function resolveImageInputCapability(value, options) {
+ const capability = normalizeImageInputCapability(value)
+ const now = options.now ?? Date.now()
+ const validity = capability.evidence?.validUntil
+ const dates = {
+ ...(capability.evidence ? { evidence: capability.evidence } : {}),
+ ...(validity ? { validUntil: validity } : {}),
+ }
+ if (options.transportSupported !== true)
+ return { state: 'unsupported', reason: 'transport_unsupported', ...dates }
+ // A non-finite clock cannot validate evidence, but it is not itself a reason
+ // to claim evidence exists: without evidence the truthful answer is
+ // `model_unknown`, reached below.
+ if (
+ capability.evidence &&
+ (!Number.isFinite(now) || Date.parse(capability.evidence.checkedAt) > now)
+ ) {
+ return { state: 'unknown', reason: 'evidence_not_yet_valid', ...dates }
+ }
+ if (validity && Date.parse(validity) <= now)
+ return { state: 'unknown', reason: 'evidence_expired', ...dates }
+ if (capability.state === 'unknown') return { state: 'unknown', reason: 'model_unknown', ...dates }
+ return {
+ state: capability.state,
+ reason: capability.state === 'supported' ? 'supported' : 'model_unsupported',
+ ...dates,
+ }
+}
+
+module.exports = {
+ parseImageInputCapability,
+ normalizeImageInputCapability,
+ resolveImageInputCapability,
+}
diff --git a/packages/llm-providers/imageInput.test.cjs b/packages/llm-providers/imageInput.test.cjs
new file mode 100644
index 000000000..379fecf91
--- /dev/null
+++ b/packages/llm-providers/imageInput.test.cjs
@@ -0,0 +1,114 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const {
+ parseImageInputCapability,
+ normalizeImageInputCapability,
+ resolveImageInputCapability,
+} = require('./index.cjs')
+
+const now = Date.parse('2026-09-16T12:00:00Z')
+const evidence = {
+ source: 'curated',
+ reference: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ checkedAt: '2026-09-16T00:00:00Z',
+}
+const supported = { state: 'supported', evidence }
+const options = { transportSupported: true, now }
+
+test('legacy and malformed evidence remain unknown, without inventing support', () => {
+ for (const value of [
+ null,
+ undefined,
+ {},
+ true,
+ { state: 'supported' },
+ { ...supported, extra: true },
+ { state: 'supported', evidence: { ...evidence, checkedAt: '2026-02-30T00:00:00Z' } },
+ { state: 'supported', evidence: { ...evidence, reference: 'https://localhost/path' } },
+ {
+ state: 'supported',
+ evidence: { ...evidence, reference: 'https://example.com/path?private=value' },
+ },
+ ]) {
+ assert.deepEqual(normalizeImageInputCapability(value), { state: 'unknown' })
+ }
+ assert.deepEqual(parseImageInputCapability({ state: 'unknown' }), { state: 'unknown' })
+})
+
+test('support is the intersection of model and transport', () => {
+ for (const state of ['supported', 'unsupported', 'unknown']) {
+ for (const transportSupported of [true, false]) {
+ const result = resolveImageInputCapability({ state, evidence }, { now, transportSupported })
+ const expected = transportSupported ? state : 'unsupported'
+ assert.equal(result.state, expected)
+ }
+ }
+})
+
+test('expiry is evaluated at dispatch, including the exact boundary and future evidence', () => {
+ const capability = { ...supported, evidence: { ...evidence, validUntil: '2026-09-16T12:00:00Z' } }
+ assert.equal(
+ resolveImageInputCapability(capability, { ...options, now: now - 1 }).state,
+ 'supported'
+ )
+ assert.equal(resolveImageInputCapability(capability, options).reason, 'evidence_expired')
+ assert.equal(
+ resolveImageInputCapability(supported, { ...options, now: 0 }).reason,
+ 'evidence_not_yet_valid'
+ )
+ // An unreadable clock is not itself evidence. Without evidence the truthful
+ // reason is `model_unknown`; with evidence the same clock still cannot
+ // validate it, which is the liveness witness that the branch stays reachable.
+ assert.equal(
+ resolveImageInputCapability({ state: 'unknown' }, { ...options, now: Number.NaN }).reason,
+ 'model_unknown'
+ )
+ assert.equal(
+ resolveImageInputCapability(supported, { ...options, now: Number.NaN }).reason,
+ 'evidence_not_yet_valid'
+ )
+})
+
+test('discovery cannot claim known support without a validity contract', () => {
+ const discovery = { ...supported, evidence: { ...evidence, source: 'discovery' } }
+ assert.equal(parseImageInputCapability(discovery), null)
+ const dated = {
+ ...discovery,
+ evidence: { ...discovery.evidence, validUntil: '2026-10-01T00:00:00Z' },
+ }
+ assert.equal(resolveImageInputCapability(dated, options).state, 'supported')
+ assert.deepEqual(parseImageInputCapability(supported), supported)
+})
+
+test('hostname policy compares the DNS root dot but preserves the exact reference', () => {
+ const original = 'https://docs.z.ai./guides/vlm/glm-5.3-flash'
+ const trailingDot = {
+ ...supported,
+ evidence: { ...evidence, reference: original },
+ }
+ // A public fully qualified hostname with the DNS root dot is still public.
+ assert.deepEqual(parseImageInputCapability(trailingDot), trailingDot)
+ assert.deepEqual(normalizeImageInputCapability(trailingDot), {
+ state: 'supported',
+ evidence: trailingDot.evidence,
+ })
+ assert.equal(resolveImageInputCapability(trailingDot, options).evidence.reference, original)
+
+ // The trailing dot cannot make an intranet, private, or single-label form
+ // pass, and old evidence stored with such a reference stays unknown.
+ for (const reference of [
+ 'https://localhost./docs',
+ 'https://10.0.0.1./docs',
+ 'https://catalog.internal./docs',
+ 'https://docs.local./docs',
+ 'https://web./docs',
+ ]) {
+ assert.deepEqual(
+ normalizeImageInputCapability({
+ ...supported,
+ evidence: { ...evidence, reference },
+ }),
+ { state: 'unknown' }
+ )
+ }
+})
diff --git a/packages/llm-providers/index.cjs b/packages/llm-providers/index.cjs
index 841ce32c0..1332a58c9 100644
--- a/packages/llm-providers/index.cjs
+++ b/packages/llm-providers/index.cjs
@@ -301,6 +301,7 @@ function requireStaticCredentialSlot(descriptor) {
}
module.exports = {
+ ...require('./imageInput.cjs'),
PROVIDER_IDS,
RUNNABLE_LLM_MODEL_ID_MAX_LENGTH,
RUNNABLE_LLM_MODEL_ID_PATTERN,
diff --git a/packages/llm-providers/index.d.ts b/packages/llm-providers/index.d.ts
index 2635874cd..06ebf238a 100644
--- a/packages/llm-providers/index.d.ts
+++ b/packages/llm-providers/index.d.ts
@@ -4,6 +4,37 @@
* DATA-ONLY leaf; runtime-only descriptor fields stay local to mcp-host.
*/
+export type ImageInputState = 'supported' | 'unsupported' | 'unknown'
+export interface ImageInputEvidence {
+ source: 'curated' | 'discovery'
+ reference: string
+ checkedAt: string
+ validUntil?: string
+}
+export interface ImageInputCapability {
+ state: ImageInputState
+ evidence?: ImageInputEvidence
+}
+export type ImageInputReason =
+ | 'supported'
+ | 'transport_unsupported'
+ | 'model_unsupported'
+ | 'model_unknown'
+ | 'evidence_expired'
+ | 'evidence_not_yet_valid'
+export interface ImageInputDecision {
+ state: ImageInputState
+ reason: ImageInputReason
+ validUntil?: string
+ evidence?: ImageInputEvidence
+}
+export declare function parseImageInputCapability(value: unknown): ImageInputCapability | null
+export declare function normalizeImageInputCapability(value: unknown): ImageInputCapability
+export declare function resolveImageInputCapability(
+ value: unknown,
+ options: { transportSupported: boolean; now?: number }
+): ImageInputDecision
+
/** Canonical provider ids, in dev auto-detection priority order. */
export declare const PROVIDER_IDS: readonly [
'openai',
diff --git a/packages/llm-providers/package.json b/packages/llm-providers/package.json
index 01a3b32e8..bc968f37a 100644
--- a/packages/llm-providers/package.json
+++ b/packages/llm-providers/package.json
@@ -14,7 +14,7 @@
},
"license": "MIT",
"scripts": {
- "test": "node --check index.cjs && node --test index.test.cjs",
- "build": "node --check index.cjs"
+ "test": "node --check index.cjs && node --test index.test.cjs imageInput.test.cjs",
+ "build": "node --check index.cjs && node --check imageInput.cjs"
}
}
diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.json
index 61f4fc42d..a8715fece 100644
--- a/rpc-proxy/package-lock.json
+++ b/rpc-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.80",
+ "version": "0.1.82",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-rpc-proxy",
- "version": "0.1.80",
+ "version": "0.1.82",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/rpc-proxy/package.json b/rpc-proxy/package.json
index 17d1d6dd8..936dba29e 100644
--- a/rpc-proxy/package.json
+++ b/rpc-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.80",
+ "version": "0.1.82",
"description": "External-facing RPC proxy for tenant-scoped MCP access",
"main": "dist/main.js",
"engines": {
diff --git a/rpc-proxy/src/__tests__/app-body-limit.test.ts b/rpc-proxy/src/__tests__/app-body-limit.test.ts
new file mode 100644
index 000000000..69ecef7fb
--- /dev/null
+++ b/rpc-proxy/src/__tests__/app-body-limit.test.ts
@@ -0,0 +1,257 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import { once } from 'node:events'
+import { type Server, request as httpRequest } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import request from 'supertest'
+import { createApp } from '../app.js'
+import { config } from '../config.js'
+import { createSandboxUiSession } from '../services/sandboxUiSession.js'
+
+const authTokenMock = vi.hoisted(() => ({
+ verifyRpcToken: vi.fn(),
+}))
+
+const serviceMock = vi.hoisted(() => ({
+ resolveHostConnectionForUser: vi.fn(),
+ forwardHostMessageToHost: vi.fn(),
+}))
+
+vi.mock('../authToken.js', () => authTokenMock)
+vi.mock('../services/mcpProxyService.js', () => serviceMock)
+
+// Desktop sends up to 8 MB of base64 images inline in the message JSON
+// (COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES); the parser must admit that plus text.
+const MIB = 1024 * 1024
+const IMAGE_BUDGET_BYTES = 8 * MIB
+const BODY_LIMIT_BYTES = 10 * MIB
+const MESSAGES_PATH = '/api/v1/rpc/hosts/chatllm/messages'
+
+const VALID_CLAIMS = {
+ sub: 'user-uuid-abc',
+ typ: 'user' as const,
+ accessScope: 'team' as const,
+ teamId: 'team-1',
+ scopes: ['host:message:invoke'],
+ hostRefs: ['chatllm'],
+ jti: 'j1',
+ iat: 1,
+ exp: 9999999999,
+}
+
+const HOST_CONNECTION = {
+ name: 'chatllm',
+ url: 'http://chatllm:8080',
+ headers: {
+ 'x-clerum-edge-caller': 'rpc-proxy',
+ 'x-clerum-edge-host-ref': 'chatllm',
+ 'x-clerum-edge-user-id': 'user-uuid-abc',
+ },
+}
+
+function messageBody(dataBase64Length: number): string {
+ return JSON.stringify({
+ content: 'describe these images',
+ attachments: [{ kind: 'image', dataBase64: 'A'.repeat(dataBase64Length) }],
+ })
+}
+
+// ~1 MB of bytes that are not valid JSON: the parser must read all of it
+// before it can fail, which is exactly the work anonymous callers must not
+// be able to trigger.
+const MALFORMED_JSON_BODY = `{"content": "${'x'.repeat(MIB)}`
+
+// How long a partially uploaded request may wait for its response. A route
+// that parses before authenticating never answers here: body-parser keeps
+// waiting for the bytes that were announced but not sent.
+const EARLY_RESPONSE_TIMEOUT_MS = 2000
+
+/**
+ * Announces MALFORMED_JSON_BODY via Content-Length but uploads only its first
+ * 16 KB, then waits for the response. A response can only arrive if the route
+ * answered without reading the body, which proves the body was never parsed.
+ * The upload is aborted once the response (or the timeout) is observed.
+ */
+function respondsBeforeBodyIsSent(
+ server: Server,
+ path: string,
+ headers: Record<string, string>
+): Promise<{ status: number; body: unknown }> {
+ const { port } = server.address() as AddressInfo
+ return new Promise((resolve, reject) => {
+ const req = httpRequest({
+ host: '127.0.0.1',
+ port,
+ method: 'POST',
+ path,
+ headers: {
+ ...headers,
+ 'content-type': 'application/json',
+ 'content-length': String(Buffer.byteLength(MALFORMED_JSON_BODY)),
+ },
+ })
+ const timer = setTimeout(() => {
+ req.destroy()
+ reject(
+ new Error(
+ `no response within ${EARLY_RESPONSE_TIMEOUT_MS} ms of a partial upload: the route waits for the body before authenticating`
+ )
+ )
+ }, EARLY_RESPONSE_TIMEOUT_MS)
+ req.on('response', res => {
+ const chunks: Buffer[] = []
+ res.on('data', (chunk: Buffer) => chunks.push(chunk))
+ res.on('end', () => {
+ clearTimeout(timer)
+ req.destroy()
+ resolve({
+ status: res.statusCode ?? 0,
+ body: JSON.parse(Buffer.concat(chunks).toString('utf8')),
+ })
+ })
+ })
+ req.on('error', err => {
+ clearTimeout(timer)
+ reject(err)
+ })
+ req.write(MALFORMED_JSON_BODY.slice(0, 16 * 1024))
+ })
+}
+
+function forwardedAttachmentLength(): number {
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ const forwarded = serviceMock.forwardHostMessageToHost.mock.calls[0][1] as {
+ attachments: Array<{ dataBase64: string }>
+ }
+ return forwarded.attachments[0].dataBase64.length
+}
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ authTokenMock.verifyRpcToken.mockReturnValue(VALID_CLAIMS)
+ serviceMock.resolveHostConnectionForUser.mockResolvedValue(HOST_CONNECTION)
+ serviceMock.forwardHostMessageToHost.mockResolvedValue({ success: true, status: 'completed' })
+})
+
+describe('rpc-proxy JSON body limit on POST /rpc/hosts/:hostRef/messages', () => {
+ it('accepts a body carrying the full 8 MB image budget and forwards it', async () => {
+ const res = await request(createApp())
+ .post(MESSAGES_PATH)
+ .set('authorization', 'Bearer token')
+ .set('content-type', 'application/json')
+ .send(messageBody(IMAGE_BUDGET_BYTES))
+
+ expect(res.status).toBe(200)
+ expect(forwardedAttachmentLength()).toBe(IMAGE_BUDGET_BYTES)
+ })
+
+ it('accepts a ~9.9 MB body just under the 10 MB limit', async () => {
+ const dataLength = Math.floor(9.9 * MIB)
+ const body = messageBody(dataLength)
+ // Above any lower limit such as 8.4 MB, below the 10 MB limit.
+ expect(body.length).toBeGreaterThan(9.8 * MIB)
+ expect(body.length).toBeLessThan(BODY_LIMIT_BYTES)
+
+ const res = await request(createApp())
+ .post(MESSAGES_PATH)
+ .set('authorization', 'Bearer token')
+ .set('content-type', 'application/json')
+ .send(body)
+
+ expect(res.status).toBe(200)
+ expect(forwardedAttachmentLength()).toBe(dataLength)
+ })
+
+ it('refuses a body over 10 MB', async () => {
+ const body = messageBody(BODY_LIMIT_BYTES)
+ expect(body.length).toBeGreaterThan(BODY_LIMIT_BYTES)
+
+ const res = await request(createApp())
+ .post(MESSAGES_PATH)
+ .set('authorization', 'Bearer token')
+ .set('content-type', 'application/json')
+ .send(body)
+
+ // The app's error handler maps every non-timeout error, including
+ // body-parser's PayloadTooLargeError, to 500.
+ expect(res.status).toBe(500)
+ expect(res.body).toEqual({
+ error: 'Internal Server Error',
+ message: 'request entity too large',
+ })
+ // Liveness witness for the negative below: the token was checked.
+ expect(authTokenMock.verifyRpcToken).toHaveBeenCalledTimes(1)
+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()
+ })
+})
+
+describe('rpc-proxy parses request bodies only after authentication (M4)', () => {
+ // A real listening server so the unauthenticated cases can upload a body
+ // partially and observe the response while the rest is still unsent.
+ let server: Server
+
+ beforeAll(async () => {
+ // Same binding as supertest's own ephemeral servers (all interfaces).
+ server = createApp().listen(0)
+ await once(server, 'listening')
+ })
+
+ afterAll(async () => {
+ server.closeAllConnections()
+ server.close()
+ await once(server, 'close')
+ })
+
+ it('rejects an unauthenticated malformed body with 401 before receiving it', async () => {
+ authTokenMock.verifyRpcToken.mockReturnValue(null)
+
+ const res = await respondsBeforeBodyIsSent(server, MESSAGES_PATH, {
+ authorization: 'Bearer forged',
+ })
+
+ expect(res.status).toBe(401)
+ expect(res.body).toEqual({ error: 'Unauthorized' })
+ // Liveness witness: the auth middleware ran and saw the token.
+ expect(authTokenMock.verifyRpcToken).toHaveBeenCalledWith('forged')
+ })
+
+ it('still parses the same malformed body once the caller is authenticated', async () => {
+ const res = await request(server)
+ .post(MESSAGES_PATH)
+ .set('authorization', 'Bearer token')
+ .set('content-type', 'application/json')
+ .send(MALFORMED_JSON_BODY)
+
+ // The parser is mounted on the route: its SyntaxError reaches the app's
+ // error handler (mapped to 500), and the handler never runs.
+ expect(res.status).toBe(500)
+ expect(res.body.error).toBe('Internal Server Error')
+ expect(res.body.message).toMatch(/JSON/)
+ expect(authTokenMock.verifyRpcToken).toHaveBeenCalledWith('token')
+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()
+ })
+
+ it('rejects the cookie-authenticated sandbox-ui oauth/token route without a cookie before receiving the body', async () => {
+ const res = await respondsBeforeBodyIsSent(
+ server,
+ '/api/v1/sandbox-ui/sandbox-recipes/r1/oauth/token',
+ {}
+ )
+
+ expect(res.status).toBe(401)
+ expect(res.body).toEqual({ error: 'sandbox_ui_session_required' })
+ })
+
+ it('parses the sandbox-ui oauth/token body once the session cookie is valid', async () => {
+ const cookie = createSandboxUiSession('user-uuid-abc', 'sandbox-recipes', 'r1')
+
+ const res = await request(server)
+ .post('/api/v1/sandbox-ui/sandbox-recipes/r1/oauth/token')
+ .set('Cookie', `${config.sandboxUiCookieName}=${cookie}`)
+ .set('content-type', 'application/json')
+ .send(MALFORMED_JSON_BODY)
+
+ expect(res.status).toBe(500)
+ expect(res.body.error).toBe('Internal Server Error')
+ expect(res.body.message).toMatch(/JSON/)
+ })
+})
diff --git a/rpc-proxy/src/__tests__/model-selection.test.ts b/rpc-proxy/src/__tests__/model-selection.test.ts
index 0c643d96c..52886365f 100644
--- a/rpc-proxy/src/__tests__/model-selection.test.ts
+++ b/rpc-proxy/src/__tests__/model-selection.test.ts
@@ -63,7 +63,19 @@ describe('GET /rpc/hosts/:hostRef/models — passthrough to mcp-host', () => {
const upstream = {
provider: 'claude',
hostDefault: 'claude-opus-4-8',
- models: [{ name: 'claude-opus-4-8', displayName: 'Opus 4.8', allowed: true }],
+ modelSelectionRevision: 3,
+ models: [
+ {
+ name: 'claude-opus-4-8',
+ displayName: 'Opus 4.8',
+ allowed: true,
+ imageInput: {
+ state: 'supported',
+ reason: 'supported',
+ validUntil: '2026-12-01T00:00:00Z',
+ },
+ },
+ ],
}
const fetchMock = vi.fn().mockResolvedValue({
status: 200,
@@ -152,7 +164,7 @@ describe('POST /rpc/hosts/:hostRef/model — set per-session model', () => {
})
it('forwards the body to mcp-host and returns the upstream response', async () => {
- const upstream = { effective: 'next-task' }
+ const upstream = { effective: 'next-task', modelSelectionRevision: 3 }
const fetchMock = vi.fn().mockResolvedValue({
status: 200,
headers: new Headers({ 'content-type': 'application/json' }),
@@ -163,7 +175,7 @@ describe('POST /rpc/hosts/:hostRef/model — set per-session model', () => {
const res = await request(makeApp())
.post('/rpc/hosts/chatllm/model')
.set('authorization', 'Bearer user-token')
- .send({ chatId: 'c1', model: 'claude-haiku-4-5' })
+ .send({ chatId: 'c1', model: 'claude-haiku-4-5', expectedRevision: 2 })
.expect(200)
expect(res.body).toEqual(upstream)
@@ -178,6 +190,7 @@ describe('POST /rpc/hosts/:hostRef/model — set per-session model', () => {
expect(JSON.parse((init as RequestInit).body as string)).toEqual({
chatId: 'c1',
model: 'claude-haiku-4-5',
+ expectedRevision: 2,
})
})
@@ -200,6 +213,24 @@ describe('POST /rpc/hosts/:hostRef/model — set per-session model', () => {
expect(res.body).toEqual({ error: 'model_not_allowed' })
})
+ it('passes an upstream model_selection_conflict rejection through verbatim', async () => {
+ // The conflict remains distinguishable from an authorization denial.
+ const fetchMock = vi.fn().mockResolvedValue({
+ status: 409,
+ headers: new Headers({ 'content-type': 'application/json' }),
+ text: async () => JSON.stringify({ error: 'model_selection_conflict' }),
+ } as unknown as Response)
+ globalThis.fetch = fetchMock as unknown as typeof fetch
+
+ const res = await request(makeApp())
+ .post('/rpc/hosts/chatllm/model')
+ .set('authorization', 'Bearer user-token')
+ .send({ chatId: 'c1', model: 'forbidden-model' })
+ .expect(409)
+
+ expect(res.body).toEqual({ error: 'model_selection_conflict' })
+ })
+
it('returns 403 when the caller lacks host:model:write', async () => {
authTokenMock.verifyRpcToken.mockReturnValue(READ_CLAIMS)
await request(makeApp())
diff --git a/rpc-proxy/src/__tests__/sender-assignment.test.ts b/rpc-proxy/src/__tests__/sender-assignment.test.ts
index 7f347e5aa..8edf0fa25 100644
--- a/rpc-proxy/src/__tests__/sender-assignment.test.ts
+++ b/rpc-proxy/src/__tests__/sender-assignment.test.ts
@@ -65,6 +65,9 @@ describe('POST /rpc/hosts/:hostRef/messages — sender assignment invariant', ()
.send({
content: 'hi',
channelType: 'slack',
+ model: 'vision-model',
+ modelSelectionRevision: 7,
+ imageModel: { provider: 'untrusted', model: 'untrusted' },
channelId: 'attacker-channel',
hostRef: 'attacker-host',
threadId: 'chat-1',
@@ -89,10 +92,13 @@ describe('POST /rpc/hosts/:hostRef/messages — sender assignment invariant', ()
// identical turns. Assert it is a non-empty string separately; every OTHER
// envelope field is still server-derived and overrides client input.
expect(typeof forwardedBody.messageId).toBe('string')
+ expect(forwardedBody).not.toHaveProperty('imageModel')
expect((forwardedBody.messageId as string).length).toBeGreaterThan(0)
expect(forwardedBody).toMatchObject({
content: 'hi',
channelType: 'rpc',
+ model: 'vision-model',
+ modelSelectionRevision: 7,
channelId: 'chatllm',
hostRef: 'chatllm',
sender: 'user-uuid-abc',
diff --git a/rpc-proxy/src/app.ts b/rpc-proxy/src/app.ts
index 5cb5bf351..161be87bc 100644
--- a/rpc-proxy/src/app.ts
+++ b/rpc-proxy/src/app.ts
@@ -20,17 +20,6 @@ export function createApp() {
credentials: true,
})
)
- // Allow chat payloads with base64 image attachments from desktop composer.
- // The sandbox-ui view proxy streams the raw request body straight to the
- // recipe's upstream via http-proxy — running body-parser there would drain
- // the stream, so the proxied request hangs waiting for a body that never
- // arrives. Skip JSON parsing for that path; every other route still needs it.
- const jsonParser = express.json({ limit: '6mb' })
- const VIEW_PROXY_PATH = /^\/api\/v1\/sandbox-ui\/[^/]+\/[^/]+\/view\//
- app.use((req, res, next) => {
- if (VIEW_PROXY_PATH.test(req.path)) return next()
- jsonParser(req, res, next)
- })
app.use(createHealthRouter())
diff --git a/rpc-proxy/src/middleware/jsonBody.ts b/rpc-proxy/src/middleware/jsonBody.ts
new file mode 100644
index 000000000..3e05a2460
--- /dev/null
+++ b/rpc-proxy/src/middleware/jsonBody.ts
@@ -0,0 +1,10 @@
+import express from 'express'
+
+// The single request body limit for every JSON route: up to 8 MB of base64
+// images from the Desktop composer (COMPOSER_MAX_TOTAL_IMAGE_BASE64_BYTES)
+// plus the message text and JSON envelope. Mount `jsonBody` on each route
+// right after its authentication middleware so unauthenticated requests are
+// never parsed.
+export const JSON_BODY_LIMIT = '10mb'
+
+export const jsonBody = express.json({ limit: JSON_BODY_LIMIT })
diff --git a/rpc-proxy/src/routes/mcpOauth.ts b/rpc-proxy/src/routes/mcpOauth.ts
index e82e0cbf7..8b1a52f21 100644
--- a/rpc-proxy/src/routes/mcpOauth.ts
+++ b/rpc-proxy/src/routes/mcpOauth.ts
@@ -1,6 +1,7 @@
import { Response, Router } from 'express'
import { config } from '../config.js'
import { AuthedRequest, requireRpcAuth, requireScope } from '../middleware/auth.js'
+import { jsonBody } from '../middleware/jsonBody.js'
/**
* POST /api/v1/mcp-oauth/:mcpServerName/authorize-url
@@ -48,6 +49,7 @@ export function createMcpOauthRouter(): Router {
'/mcp-oauth/:mcpServerName/authorize-url',
requireRpcAuth,
requireScope('mcp:server:invoke'),
+ jsonBody,
async (req: AuthedRequest, res: Response) => {
const { mcpServerName } = req.params
if (!isValidK8sName(mcpServerName)) {
@@ -143,6 +145,7 @@ export function createMcpOauthRouter(): Router {
'/mcp-oauth/:mcpServerName/grant',
requireRpcAuth,
requireScope('mcp:server:invoke'),
+ jsonBody,
async (req: AuthedRequest, res: Response) => {
const { mcpServerName } = req.params
if (!isValidK8sName(mcpServerName)) {
diff --git a/rpc-proxy/src/routes/rpc.ts b/rpc-proxy/src/routes/rpc.ts
index 7a9474a4b..3fc25914c 100644
--- a/rpc-proxy/src/routes/rpc.ts
+++ b/rpc-proxy/src/routes/rpc.ts
@@ -8,6 +8,7 @@ import {
requireRpcAuth,
requireScope,
} from '../middleware/auth.js'
+import { jsonBody } from '../middleware/jsonBody.js'
import { rpcInvocationContext } from '../rpcAccessContext.js'
import {
ControlApiConnectorsRejectedError,
@@ -270,6 +271,7 @@ export function createRpcRouter(): Router {
'/rpc/:serverName',
requireRpcAuth,
requireScope('mcp:server:invoke'),
+ jsonBody,
async (req: AuthedRequest, res, next) => {
try {
const auth = req.auth!
@@ -309,6 +311,7 @@ export function createRpcRouter(): Router {
'/rpc/hosts/:hostRef/messages',
requireRpcAuth,
requireScope('host:message:invoke'),
+ jsonBody,
async (req: AuthedRequest, res) => {
// Host runtime write path (REST-oriented):
// - separate from read-only status stream
@@ -371,6 +374,12 @@ export function createRpcRouter(): Router {
requestId,
origin: 'direct_chat',
})
+ if (body.attachments != null && !Array.isArray(body.attachments)) {
+ res
+ .status(400)
+ .json({ error: 'invalid_attachments', message: 'Image attachments must be a list.' })
+ return
+ }
const forwardedBody: HostRuntimeMessageRequest = {
content: body.content,
channelType: 'rpc',
@@ -381,6 +390,9 @@ export function createRpcRouter(): Router {
metadata: rpcInvocationContext(auth),
threadId: desktopSessionId,
attachments: Array.isArray(body.attachments) ? body.attachments : undefined,
+ ...(body.modelSelectionRevision === undefined
+ ? {}
+ : { modelSelectionRevision: body.modelSelectionRevision }),
traceContext,
// R2 "Option A": thread the optional piggybacked per-session model.
// This body is an explicit field allow-list, so an unlisted field is
@@ -572,6 +584,7 @@ export function createRpcRouter(): Router {
'/rpc/hosts/:hostRef/approvals/approve',
requireRpcAuth,
requireScope('host:approval:write'),
+ jsonBody,
async (req: AuthedRequest, res, next) => {
try {
const auth = req.auth!
@@ -638,6 +651,7 @@ export function createRpcRouter(): Router {
'/rpc/hosts/:hostRef/approvals/deny',
requireRpcAuth,
requireScope('host:approval:write'),
+ jsonBody,
async (req: AuthedRequest, res, next) => {
try {
const auth = req.auth!
@@ -974,6 +988,7 @@ export function createRpcRouter(): Router {
'/rpc/hosts/:hostRef/sessions/:agent/:chatId/name',
requireRpcAuth,
requireScope('host:session:write'),
+ jsonBody,
async (req: AuthedRequest, res, next) => {
try {
const auth = req.auth!
@@ -1110,6 +1125,7 @@ export function createRpcRouter(): Router {
'/rpc/hosts/:hostRef/model',
requireRpcAuth,
requireScope('host:model:write'),
+ jsonBody,
async (req: AuthedRequest, res, next) => {
try {
const auth = req.auth!
diff --git a/rpc-proxy/src/routes/sandboxUi.ts b/rpc-proxy/src/routes/sandboxUi.ts
index 717bde50a..dfd3e66e4 100644
--- a/rpc-proxy/src/routes/sandboxUi.ts
+++ b/rpc-proxy/src/routes/sandboxUi.ts
@@ -1,12 +1,14 @@
-import { Request, Response, Router } from 'express'
+import { NextFunction, Request, Response, Router } from 'express'
import httpProxy from 'http-proxy'
import type { ClientRequest, IncomingMessage, ServerResponse } from 'node:http'
import { config } from '../config.js'
import { AuthedRequest, requireRpcAuth, requireScope } from '../middleware/auth.js'
+import { jsonBody } from '../middleware/jsonBody.js'
import { emitSessionMint, emitViewRequest } from '../observability/sandboxUiAudit.js'
import { normalizeViewPath } from '../services/sandboxUiPath.js'
import { listSandboxUiApps, lookupSandboxUiRegistry } from '../services/sandboxUiRegistry.js'
import {
+ type SandboxUiSessionClaims,
buildSandboxUiSetCookie,
createSandboxUiSession,
verifySandboxUiSession,
@@ -197,6 +199,29 @@ sandboxUiProxy.on('error', (err, _req, res) => {
}
})
+/**
+ * Cookie authentication for the embed-side `oauth/*` routes. Verifies the
+ * per-recipe UI session cookie against the URL's (recipeNs, recipeName) and
+ * stores the claims in `res.locals.sandboxUiClaims`. Runs before `jsonBody`
+ * so requests without a valid session are rejected before any body parsing.
+ */
+function requireSandboxUiCookieSession(req: Request, res: Response, next: NextFunction): void {
+ const { recipeNs, recipeName } = req.params
+ const cookies = parseCookies(req.headers.cookie ?? '')
+ const cookieValue = cookies[config.sandboxUiCookieName]
+ if (!cookieValue) {
+ res.status(401).json({ error: 'sandbox_ui_session_required' })
+ return
+ }
+ const claims = verifySandboxUiSession(cookieValue, recipeNs, recipeName)
+ if (!claims) {
+ res.status(401).json({ error: 'sandbox_ui_session_invalid' })
+ return
+ }
+ res.locals.sandboxUiClaims = claims
+ next()
+}
+
export function createSandboxUiSessionRouter(): Router {
const router = Router()
@@ -300,6 +325,7 @@ export function createSandboxUiSessionRouter(): Router {
'/sandbox-ui/:recipeNs/:recipeName/oauth/authorize-url',
requireRpcAuth,
requireScope('sandbox:ui:view'),
+ jsonBody,
async (req: AuthedRequest, res: Response) => {
const { recipeNs, recipeName } = req.params
const userId = req.auth!.sub
@@ -359,7 +385,7 @@ export function createSandboxUiSessionRouter(): Router {
recipeNs,
recipeName,
oauthClientId,
- userId, // from req.auth.sub — never the body
+ userId, // from req.auth.sub — never the body
redirectUri,
background,
}),
@@ -425,20 +451,11 @@ export function createSandboxUiSessionRouter(): Router {
// the user's session is bad).
router.post(
'/sandbox-ui/:recipeNs/:recipeName/oauth/token',
+ requireSandboxUiCookieSession,
+ jsonBody,
async (req: Request, res: Response) => {
const { recipeNs, recipeName } = req.params
-
- const cookies = parseCookies(req.headers.cookie ?? '')
- const cookieValue = cookies[config.sandboxUiCookieName]
- if (!cookieValue) {
- res.status(401).json({ error: 'sandbox_ui_session_required' })
- return
- }
- const claims = verifySandboxUiSession(cookieValue, recipeNs, recipeName)
- if (!claims) {
- res.status(401).json({ error: 'sandbox_ui_session_invalid' })
- return
- }
+ const claims = res.locals.sandboxUiClaims as SandboxUiSessionClaims
const oauthClientId =
typeof req.body?.oauthClientId === 'string' ? String(req.body.oauthClientId).trim() : ''
@@ -523,20 +540,11 @@ export function createSandboxUiSessionRouter(): Router {
// a best-effort buildRevokeRequest adapter call before delete.
router.delete(
'/sandbox-ui/:recipeNs/:recipeName/oauth/grant',
+ requireSandboxUiCookieSession,
+ jsonBody,
async (req: Request, res: Response) => {
const { recipeNs, recipeName } = req.params
-
- const cookies = parseCookies(req.headers.cookie ?? '')
- const cookieValue = cookies[config.sandboxUiCookieName]
- if (!cookieValue) {
- res.status(401).json({ error: 'sandbox_ui_session_required' })
- return
- }
- const claims = verifySandboxUiSession(cookieValue, recipeNs, recipeName)
- if (!claims) {
- res.status(401).json({ error: 'sandbox_ui_session_invalid' })
- return
- }
+ const claims = res.locals.sandboxUiClaims as SandboxUiSessionClaims
const oauthClientId =
typeof req.body?.oauthClientId === 'string' ? String(req.body.oauthClientId).trim() : ''
diff --git a/rpc-proxy/test/routes.rpc.test.ts b/rpc-proxy/test/routes.rpc.test.ts
index 459868e5e..97352b4f4 100644
--- a/rpc-proxy/test/routes.rpc.test.ts
+++ b/rpc-proxy/test/routes.rpc.test.ts
@@ -375,6 +375,79 @@ describe('routes/rpc', () => {
expect(signal).not.toMatch(/user-1|agent2|session-1|ping|rpc-token|runId/)
})
+ describe('image attachments shape', () => {
+ beforeEach(() => {
+ authTokenMock.verifyRpcToken.mockReturnValue({
+ sub: 'user-1',
+ typ: 'user',
+ accessScope: 'team',
+ teamId: 'team-1',
+ scopes: ['host:message:invoke'],
+ hostRefs: ['agent2'],
+ jti: 'j1',
+ iat: 1,
+ exp: 9999999999,
+ })
+ serviceMock.resolveHostConnectionForUser.mockResolvedValue({
+ name: 'agent2',
+ url: 'http://agent2.mcp-host.svc.cluster.local:8080',
+ headers: {},
+ })
+ serviceMock.forwardHostMessageToHost.mockResolvedValue({ success: true, response: 'pong' })
+ })
+
+ it('returns 400 invalid_attachments when attachments is not a list', async () => {
+ await request(makeApp())
+ .post('/rpc/hosts/agent2/messages')
+ .set('authorization', 'Bearer rpc-token')
+ .send({ content: 'hi', attachments: 'nope' })
+ .expect(400)
+ .expect({ error: 'invalid_attachments', message: 'Image attachments must be a list.' })
+
+ // Witness: the request was authenticated. The shape is rejected before
+ // host resolution, so a malformed request never writes a binding.
+ expect(authTokenMock.verifyRpcToken).toHaveBeenCalledOnce()
+ expect(serviceMock.resolveHostConnectionForUser).toHaveBeenCalledTimes(0)
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(0)
+ })
+
+ it('forwards an empty attachments list', async () => {
+ await request(makeApp())
+ .post('/rpc/hosts/agent2/messages')
+ .set('authorization', 'Bearer rpc-token')
+ .send({ content: 'hi', attachments: [] })
+ .expect(200)
+
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledOnce()
+ expect(serviceMock.forwardHostMessageToHost.mock.calls[0][1]).toMatchObject({
+ content: 'hi',
+ attachments: [],
+ })
+ })
+
+ it('forwards a non-empty image attachments list unchanged', async () => {
+ const attachments = [
+ {
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: 'iVBORw0KGgo=',
+ id: 'a',
+ },
+ ]
+ await request(makeApp())
+ .post('/rpc/hosts/agent2/messages')
+ .set('authorization', 'Bearer rpc-token')
+ .send({ content: 'hi', attachments })
+ .expect(200)
+
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledOnce()
+ const forwarded = serviceMock.forwardHostMessageToHost.mock.calls[0][1]
+ expect(forwarded.content).toBe('hi')
+ expect(forwarded.attachments).toEqual(attachments)
+ })
+ })
+
// Regression: the `forwardedBody` is an explicit field allow-list, so a new
// client field is dropped unless threaded through. The R2 "Option A"
// piggybacked per-session `model` was silently omitted — assert it now
diff --git a/scripts/e2e/image-capabilities-fixture.mjs b/scripts/e2e/image-capabilities-fixture.mjs
new file mode 100644
index 000000000..dd6e97f0f
--- /dev/null
+++ b/scripts/e2e/image-capabilities-fixture.mjs
@@ -0,0 +1,794 @@
+import { spawnSync } from 'node:child_process'
+import { createHash, randomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { isDeepStrictEqual } from 'node:util'
+import {
+ openOwnedFile,
+ readOwnedFile,
+ validateRunDirectory,
+} from './prepare-codex-approved-tools.mjs'
+
+export const fixtureImage = 'clerum/image-capabilities-mcp-host:test'
+export const baseImage = 'clerum/mcp-host:test'
+export const runAnnotation = 'evenfire.ai/image-capabilities-run'
+export const fixtureConfigKeys = [
+ 'NODE_ENV',
+ 'EVENFIRE_IMAGE_CAPABILITIES_FIXTURE',
+ 'IMAGE_CAPABILITIES_RUN_ID',
+ 'IMAGE_CAPABILITIES_CREDENTIAL_SHA256',
+ 'MINIKUBE_PROFILE',
+ 'CONTROL_API_REAL_PG_CONTEXT',
+]
+
+export function proveImages(manifest, observed, head, profile) {
+ if (!/^[a-f0-9]{40}$/.test(head) || manifest.profile !== profile)
+ throw new Error('Fixture image ownership mismatch')
+ for (const ref of [baseImage, fixtureImage]) {
+ const id = manifest.images?.[ref]
+ if (
+ manifest.images?.[`docker.io/${ref}`] !== undefined &&
+ manifest.images[`docker.io/${ref}`] !== id
+ )
+ throw new Error('Conflicting image aliases')
+ if (
+ !/^sha256:[a-f0-9]{64}$/.test(id ?? '') ||
+ id !== observed[ref] ||
+ manifest.sourceRevisions?.[ref] !== head
+ )
+ throw new Error('Fixture image identity or source revision mismatch')
+ }
+ const binding = manifest.derivedFrom?.[fixtureImage]
+ if (binding?.ref !== baseImage || binding.id !== observed[baseImage])
+ throw new Error('Fixture derived-base mismatch')
+ return { head, profile, images: observed }
+}
+
+export function modelInputs(runId) {
+ if (!/^image-capabilities-[a-f0-9]{12}$/.test(runId)) throw new Error('Invalid fixture run')
+ return [
+ { model: 'glm-5.3-flash', state: 'supported' },
+ { model: 'glm-5.3', state: 'unsupported' },
+ { model: `image-fixture-unknown-${runId.slice(-12)}`, state: 'unknown' },
+ ].map(({ model, state }) => ({
+ provider: 'zai',
+ model,
+ enabled: true,
+ image_input: {
+ state,
+ evidence: {
+ source: 'curated',
+ reference: `evidence:${runId}`,
+ checkedAt: new Date().toISOString(),
+ },
+ },
+ }))
+}
+
+export function requireOwnedResource(resource, uid, runId) {
+ if (resource?.metadata?.uid !== uid || resource.metadata.annotations?.[runAnnotation] !== runId)
+ throw new Error('Fixture resource owner changed; refusing mutation')
+}
+
+export function sanitizeFixtureReport(output, privateValues) {
+ let text = String(output)
+ for (const value of privateValues) if (value) text = text.replaceAll(value, '[redacted]')
+ return text
+ .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted]')
+ .split('\n')
+ .filter(
+ line =>
+ line.length < 2000 &&
+ !/password|authorization|cookie|credential|secret|access.?token|refresh.?token/i.test(line)
+ )
+ .join('\n')
+ .slice(-128 * 1024)
+}
+
+// Restores the owned runtime when the run is interrupted. `command()` uses
+// spawnSync, so a signal is handled only once the current kubectl/npm call
+// returns and `main` reaches an await; the child receives the terminal's
+// signal itself. `main` keeps running until `restore` settles, so it must be
+// the same memoized restoration `main` awaits.
+export function installSignalRestore(target, restore, write = text => process.stderr.write(text)) {
+ let running = null
+ const onSignal = signal => {
+ if (running) return
+ write(`Image capability fixture interrupted by ${signal}; restoring the owned runtime\n`)
+ running = restore().then(
+ () => target.exit(signal === 'SIGINT' ? 130 : 143),
+ error => {
+ write(`restoration failed: ${error.message}\n`)
+ target.exit(1)
+ }
+ )
+ }
+ target.on('SIGINT', onSignal)
+ target.on('SIGTERM', onSignal)
+ return () => {
+ target.off('SIGINT', onSignal)
+ target.off('SIGTERM', onSignal)
+ }
+}
+
+function command(binary, args, { input, timeout = 60_000, env = process.env } = {}) {
+ const result = spawnSync(binary, args, {
+ input,
+ env,
+ encoding: 'utf8',
+ timeout,
+ maxBuffer: 8 * 1024 * 1024,
+ })
+ if (result.error || result.status !== 0) {
+ const operation =
+ args.find(value => ['get', 'create', 'patch', 'exec', 'delete', 'rollout'].includes(value)) ??
+ ''
+ const workload = args.find(value => /^deployment\/[a-z0-9-]+$/.test(value)) ?? ''
+ const reason = /timed out|deadline exceeded|timeout/i.test(result.stderr ?? '')
+ ? 'deadline'
+ : /not found|NotFound/.test(result.stderr ?? '')
+ ? 'missing-resource'
+ : /forbidden|Forbidden/.test(result.stderr ?? '')
+ ? 'permission'
+ : /conflict|test failed/i.test(result.stderr ?? '')
+ ? 'conflict'
+ : 'command-error'
+ // Emit only controlled labels, never child output that may contain data.
+ const error = new Error(
+ `${binary} ${operation} ${workload} failed (status ${result.status ?? 'unavailable'}; ${reason})`
+ )
+ Object.defineProperty(error, 'commandOutput', {
+ value: `${result.stdout ?? ''}\n${result.stderr ?? ''}`,
+ })
+ throw error
+ }
+ return result.stdout
+}
+
+async function main() {
+ process.umask(0o077)
+ if (!process.version.startsWith('v24.')) throw new Error('Node24 required')
+ const root = fs.realpathSync(process.cwd())
+ const profile = process.env.MINIKUBE_PROFILE
+ if (
+ !/^clerum-.+-[a-f0-9]{8}$/.test(profile ?? '') ||
+ profile !== process.env.CONTROL_API_REAL_PG_CONTEXT
+ )
+ throw new Error('Matching branch profile and context required')
+ command('bash', ['scripts/minikube/require-t2-mutation-lock.sh'])
+ const head = command('git', ['rev-parse', 'HEAD']).trim()
+ const branch = command('git', ['branch', '--show-current']).trim()
+ if (command('git', ['status', '--porcelain']).trim()) throw new Error('Clean checkout required')
+ const commonDir = command('git', [
+ 'rev-parse',
+ '--path-format=absolute',
+ '--git-common-dir',
+ ]).trim()
+ const canonical = fs.realpathSync(path.dirname(commonDir))
+ if (path.basename(canonical) !== 'evenfire')
+ throw new Error('Canonical Evenfire checkout required')
+ const branchMake = path.join(canonical, '.local-notes/minikube-profiles/branch.mk')
+ const info = command('make', ['-f', branchMake, 'branch-profile-info'])
+ if (!info.includes(`profile: ${profile}\n`) || !info.includes(`repo: ${root}\n`))
+ throw new Error('Branch helper identity mismatch')
+ const urlFor = label => {
+ const port = info.match(new RegExp(`^ ${label}:\\s+(\\d+)$`, 'm'))?.[1]
+ if (!port || Number(port) < 1024 || Number(port) > 65535) throw new Error('Missing owned port')
+ return `http://127.0.0.1:${port}`
+ }
+ command('make', ['-f', branchMake, 'branch-profile-health'])
+ const api = `${urlFor('control-api')}/api/v1`
+ const kc = (args, input) =>
+ command(
+ 'kubectl',
+ [
+ `--context=${profile}`,
+ args.includes('rollout') ? '--request-timeout=150s' : '--request-timeout=30s',
+ ...args,
+ ],
+ {
+ input,
+ timeout: 180_000,
+ }
+ )
+ const get = (namespace, kind, name) =>
+ JSON.parse(kc(['-n', namespace, 'get', kind, name, '-o', 'json']))
+ const patch = (namespace, kind, name, operations) =>
+ kc(
+ ['-n', namespace, 'patch', kind, name, '--type=json', '--patch-file=/dev/stdin'],
+ JSON.stringify(operations)
+ )
+ const stamp = resource => [
+ { op: 'test', path: '/metadata/uid', value: resource.metadata.uid },
+ { op: 'test', path: '/metadata/resourceVersion', value: resource.metadata.resourceVersion },
+ ]
+ const escape = value => value.replaceAll('~', '~0').replaceAll('/', '~1')
+ const annotate = resource => ({
+ op: 'add',
+ path: '/metadata/annotations',
+ value: { ...resource.metadata.annotations, [runAnnotation]: state.runId },
+ })
+ const unmark = { op: 'remove', path: `/metadata/annotations/${escape(runAnnotation)}` }
+ const waitHostImage = async image => {
+ const until = Date.now() + 120_000
+ while (Date.now() < until) {
+ const deployment = get('mcp-host', 'deployment', 'chatllm')
+ if (deployment.spec.template.spec.containers.some(c => c.image === image)) {
+ kc(['-n', 'mcp-host', 'rollout', 'status', 'deployment/chatllm', '--timeout=120s'])
+ return
+ }
+ await new Promise(resolve => setTimeout(resolve, 250))
+ }
+ throw new Error('HCC did not reconcile the expected Host image')
+ }
+ const action = process.argv[2] ?? 'run'
+ if (!['run', 'restore'].includes(action)) throw new Error('Expected run or restore')
+ const runRoot = path.join(canonical, '.local-notes/infra/runs')
+ fs.mkdirSync(runRoot, { recursive: true })
+ const runId = `image-capabilities-${randomBytes(6).toString('hex')}`
+ const directory =
+ action === 'restore' ? process.env.IMAGE_CAPABILITIES_RUN_DIR : path.join(runRoot, runId)
+ if (!directory) throw new Error('Restore requires IMAGE_CAPABILITIES_RUN_DIR')
+ if (action === 'run') fs.mkdirSync(directory, { mode: 0o700 })
+ const evidence = validateRunDirectory(canonical, directory)
+ let state =
+ action === 'restore'
+ ? JSON.parse(readOwnedFile(evidence, 'state.json'))
+ : {
+ runId,
+ branch,
+ profile,
+ head,
+ root,
+ rows: [],
+ changes: {},
+ restored: false,
+ }
+ if (
+ state.profile !== profile ||
+ state.root !== root ||
+ state.branch !== branch ||
+ (action === 'run' && state.head !== head)
+ )
+ throw new Error('Run state identity mismatch')
+ const save = () => {
+ const destination = path.join(evidence, 'state.json')
+ if (fs.existsSync(destination)) {
+ const previous = openOwnedFile(evidence, 'state.json')
+ fs.closeSync(previous.fd)
+ }
+ const name = `state-next-${randomBytes(6).toString('hex')}.json`
+ const file = openOwnedFile(evidence, name, { create: true, writable: true })
+ try {
+ const payload = JSON.stringify(state, null, 2)
+ fs.writeSync(file.fd, payload, 0, 'utf8')
+ fs.fsyncSync(file.fd)
+ fs.renameSync(path.join(evidence, name), destination)
+ const parent = fs.openSync(
+ evidence,
+ fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW
+ )
+ try {
+ fs.fsyncSync(parent)
+ } finally {
+ fs.closeSync(parent)
+ }
+ } finally {
+ fs.closeSync(file.fd)
+ }
+ }
+ if (action === 'run') {
+ save()
+ process.stdout.write(`IMAGE_CAPABILITIES_RUN_DIR=${evidence}\n`)
+ }
+ const authValue = command('bash', [
+ '-c',
+ 'set -euo pipefail; source "$3"; dotenv_load_canonical_root "$2" >/dev/null; source "$1"; e2e_resolve_admin_password "$2"',
+ 'image-fixture',
+ path.join(root, 'scripts/e2e/admin-credentials.sh'),
+ root,
+ path.join(root, 'scripts/e2e/load-dotenv.sh'),
+ ]).trim()
+ if (!authValue) throw new Error('Owned lane admin login is not configured')
+ const ADMIN_PASSWORD = authValue
+ const auth = await fetch(`${api}/admin/auth/login`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ username: process.env.ADMIN_USERNAME ?? 'admin',
+ password: ADMIN_PASSWORD,
+ }),
+ signal: AbortSignal.timeout(20_000),
+ })
+ if (!auth.ok) throw new Error(`Owned lane admin login failed (${auth.status})`)
+ const cookie = auth.headers
+ .getSetCookie()
+ .find(value => value.startsWith('control_ui_admin_session='))
+ ?.split(';')[0]
+ if (!cookie) throw new Error('Admin session missing')
+ const privateValues = [ADMIN_PASSWORD, cookie, cookie.slice(cookie.indexOf('=') + 1)]
+ const report = output => {
+ const file = openOwnedFile(evidence, 'playwright.log', { create: true })
+ try {
+ fs.writeFileSync(file.fd, sanitizeFixtureReport(output, privateValues))
+ } finally {
+ fs.closeSync(file.fd)
+ }
+ }
+ const admin = async (method, route, body) => {
+ const response = await fetch(`${api}/admin/${route}`, {
+ method,
+ headers: { Cookie: cookie, 'content-type': 'application/json' },
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+ signal: AbortSignal.timeout(30_000),
+ })
+ if (!response.ok) throw new Error(`Fixture admin operation failed (${response.status})`)
+ return response.status === 204 ? null : response.json()
+ }
+ const restoreRuntime = async () => {
+ if (state.restored) return
+ // Restore the model before removing its fixture-only catalog rows.
+ if (state.changes.host) {
+ const current = get('mcp-host', 'host', 'chatllm')
+ const keys = ['model', 'allowedModels', 'secretRef', 'llmPolicy']
+ const unchanged =
+ current.metadata.uid === state.host.uid &&
+ !current.metadata.annotations?.[runAnnotation] &&
+ keys.every(key => isDeepStrictEqual(current.spec[key], state.host[key]))
+ if (!unchanged) {
+ requireOwnedResource(current, state.host.uid, state.runId)
+ if (keys.some(key => !isDeepStrictEqual(current.spec[key], state.appliedHost[key])))
+ throw new Error('Fixture Host fields changed concurrently')
+ patch('mcp-host', 'host', 'chatllm', [
+ ...stamp(current),
+ ...['model', 'allowedModels', 'secretRef', 'llmPolicy']
+ .map(key =>
+ state.host[key] === undefined
+ ? current.spec[key] === undefined
+ ? null
+ : { op: 'remove', path: `/spec/${key}` }
+ : { op: 'add', path: `/spec/${key}`, value: state.host[key] }
+ )
+ .filter(Boolean),
+ unmark,
+ ])
+ }
+ state.changes.host = false
+ save()
+ }
+ if (state.changes.config) {
+ const current = get('mcp-host', 'configmap', 'mcp-host-config')
+ const unchanged =
+ current.metadata.uid === state.config.uid &&
+ !current.metadata.annotations?.[runAnnotation] &&
+ fixtureConfigKeys.every(key => current.data?.[key] === state.config.data[key])
+ if (!unchanged) {
+ requireOwnedResource(current, state.config.uid, state.runId)
+ if (fixtureConfigKeys.some(key => current.data?.[key] !== state.appliedConfig[key]))
+ throw new Error('Fixture configuration changed concurrently')
+ patch('mcp-host', 'configmap', 'mcp-host-config', [
+ ...stamp(current),
+ ...fixtureConfigKeys
+ .map(key =>
+ state.config.data[key] === undefined
+ ? current.data?.[key] === undefined
+ ? null
+ : { op: 'remove', path: `/data/${key}` }
+ : { op: 'add', path: `/data/${key}`, value: state.config.data[key] }
+ )
+ .filter(Boolean),
+ unmark,
+ ])
+ }
+ state.changes.config = false
+ save()
+ }
+ if (state.changes.hcc) {
+ const current = get('control-plane', 'deployment', 'host-context-controller')
+ const currentImage = current.spec.template.spec.containers
+ .flatMap(c => c.env ?? [])
+ .find(item => item.name === 'CONTEXT_MAPPER_HOST_IMAGE')?.value
+ const unchanged =
+ current.metadata.uid === state.hcc.uid &&
+ !current.metadata.annotations?.[runAnnotation] &&
+ currentImage === state.hcc.image
+ if (!unchanged) {
+ requireOwnedResource(current, state.hcc.uid, state.runId)
+ patch('control-plane', 'deployment', 'host-context-controller', [
+ ...stamp(current),
+ {
+ op: 'test',
+ path: state.hcc.path.replace(/value$/, 'name'),
+ value: 'CONTEXT_MAPPER_HOST_IMAGE',
+ },
+ { op: 'test', path: state.hcc.path, value: fixtureImage },
+ { op: 'replace', path: state.hcc.path, value: state.hcc.image },
+ unmark,
+ ])
+ }
+ state.changes.hcc = false
+ save()
+ kc([
+ '-n',
+ 'control-plane',
+ 'rollout',
+ 'status',
+ 'deployment/host-context-controller',
+ '--timeout=120s',
+ ])
+ }
+ for (const row of [...state.rows].reverse()) {
+ if (row.restored) continue
+ const current = (await admin('GET', 'llm-models')).rows.find(
+ item => item.provider === row.provider && item.model === row.model
+ )
+ if (!current && !row.created) throw new Error('Original catalog row disappeared')
+ const unchanged =
+ current &&
+ !row.created &&
+ current.enabled === row.original.enabled &&
+ isDeepStrictEqual(current.image_input, row.original.image_input)
+ if (current && !unchanged) {
+ if (
+ (row.id && current.id !== row.id) ||
+ current.image_input?.evidence?.reference !== `evidence:${state.runId}`
+ )
+ throw new Error('Catalog fixture owner changed')
+ if (row.created) await admin('DELETE', `llm-models/${current.id}`)
+ else await admin('PUT', `llm-models/${current.id}`, row.original)
+ }
+ row.restored = true
+ save()
+ }
+ if (state.changes.key) {
+ const metadata = kc([
+ '-n',
+ 'mcp-host',
+ 'get',
+ 'secret',
+ state.runId,
+ '--ignore-not-found',
+ '-o',
+ 'go-template={{.metadata.uid}} {{index .metadata.labels "evenfire.ai/image-capabilities-run"}}',
+ ]).trim()
+ if (metadata) {
+ const [uid, owner] = metadata.split(/\s+/)
+ if ((state.keyUid && uid !== state.keyUid) || owner !== state.runId)
+ throw new Error('Fixture key owner changed')
+ kc(
+ ['delete', '--raw', `/api/v1/namespaces/mcp-host/secrets/${state.runId}`, '-f', '-'],
+ JSON.stringify({ apiVersion: 'v1', kind: 'DeleteOptions', preconditions: { uid } })
+ )
+ }
+ state.changes.key = false
+ save()
+ }
+ if (!state.hcc) {
+ state.restored = true
+ save()
+ return
+ }
+ await waitHostImage(state.hcc.image)
+ const hostDeployment = get('mcp-host', 'deployment', 'chatllm')
+ if (!hostDeployment.spec.template.spec.containers.some(c => c.image === state.hcc.image))
+ throw new Error('Production Host image not restored')
+ const predicate = kc([
+ '-n',
+ 'mcp-host',
+ 'exec',
+ 'deployment/chatllm',
+ '--',
+ 'node',
+ '-e',
+ 'process.stdout.write(String(!process.env.EVENFIRE_IMAGE_CAPABILITIES_FIXTURE && !require("node:fs").existsSync("/tmp/image-capabilities-evidence.json")))',
+ ]).trim()
+ if (predicate !== 'true') throw new Error('Fixture state remains in Host')
+ state.restored = true
+ save()
+ }
+ // A signal and the normal exit path share one restoration run.
+ let restoring = null
+ const restore = () => (restoring ??= restoreRuntime())
+ const uninstallSignalRestore = installSignalRestore(process, restore)
+ if (action === 'restore') {
+ await restore()
+ uninstallSignalRestore()
+ return
+ }
+ let failure
+ try {
+ const manifest = JSON.parse(
+ fs.readFileSync(path.join(root, 'deploy/minikube/.image-manifest.json'), 'utf8')
+ )
+ const observed = Object.fromEntries(
+ [baseImage, fixtureImage].map(ref => [
+ ref,
+ command('minikube', [
+ '-p',
+ profile,
+ 'ssh',
+ '--',
+ 'docker',
+ 'image',
+ 'inspect',
+ ref,
+ '--format',
+ '{{.Id}}',
+ ]).trim(),
+ ])
+ )
+ state.imageProof = proveImages(manifest, observed, head, profile)
+ save()
+ const host = get('mcp-host', 'host', 'chatllm')
+ const hosts = JSON.parse(kc(['-n', 'mcp-host', 'get', 'hosts', '-o', 'json']))
+ if (hosts.items.length !== 1 || hosts.items[0].metadata.uid !== host.metadata.uid)
+ throw new Error('Fixture requires a dedicated single-Host profile')
+ const hcc = get('control-plane', 'deployment', 'host-context-controller')
+ const containerIndex = hcc.spec.template.spec.containers.findIndex(
+ c => c.name === 'host-context-controller'
+ )
+ const envIndex = hcc.spec.template.spec.containers[containerIndex]?.env?.findIndex(
+ e => e.name === 'CONTEXT_MAPPER_HOST_IMAGE'
+ )
+ if (containerIndex < 0 || envIndex < 0) throw new Error('HCC Host image configuration missing')
+ const originalImage = hcc.spec.template.spec.containers[containerIndex].env[envIndex].value
+ if (originalImage !== baseImage)
+ throw new Error('Expected the owned local production Host image')
+ const config = get('mcp-host', 'configmap', 'mcp-host-config')
+ if (
+ Object.keys(config.data ?? {}).some(
+ key =>
+ key.startsWith('IMAGE_CAPABILITIES_') || key === 'EVENFIRE_IMAGE_CAPABILITIES_FIXTURE'
+ )
+ )
+ throw new Error('Unrestored image capability fixture configuration')
+ for (const resource of [host, hcc, config])
+ if (resource.metadata.annotations?.[runAnnotation])
+ throw new Error('Unrestored fixture already owns resource')
+ state.host = {
+ uid: host.metadata.uid,
+ ...Object.fromEntries(
+ ['model', 'allowedModels', 'secretRef', 'llmPolicy'].map(key => [key, host.spec[key]])
+ ),
+ }
+ state.hcc = {
+ uid: hcc.metadata.uid,
+ image: originalImage,
+ path: `/spec/template/spec/containers/${containerIndex}/env/${envIndex}/value`,
+ }
+ state.config = {
+ uid: config.metadata.uid,
+ data: Object.fromEntries(
+ fixtureConfigKeys
+ .filter(key => key in (config.data ?? {}))
+ .map(key => [key, config.data[key]])
+ ),
+ }
+ save()
+ const models = modelInputs(state.runId)
+ const catalog = (await admin('GET', 'llm-models')).rows
+ for (const model of models) {
+ const prior = catalog.find(
+ row => row.provider === model.provider && row.model === model.model
+ )
+ const row = {
+ id: prior?.id,
+ provider: model.provider,
+ model: model.model,
+ created: !prior,
+ original: prior ? { enabled: prior.enabled, image_input: prior.image_input } : null,
+ }
+ state.rows.push(row)
+ save()
+ const saved = prior
+ ? await admin('PUT', `llm-models/${prior.id}`, model)
+ : await admin('POST', 'llm-models', model)
+ row.id = saved.id
+ save()
+ }
+ const fixtureKey = randomBytes(32).toString('hex')
+ privateValues.push(fixtureKey)
+ const keyHash = createHash('sha256').update(fixtureKey).digest('hex')
+ state.changes.key = true
+ save()
+ const created = JSON.parse(
+ kc(
+ ['-n', 'mcp-host', 'create', '-f', '-', '-o', 'json'],
+ JSON.stringify({
+ apiVersion: 'v1',
+ kind: 'Secret',
+ metadata: {
+ name: state.runId,
+ namespace: 'mcp-host',
+ labels: { [runAnnotation]: state.runId },
+ },
+ type: 'Opaque',
+ stringData: { 'zai-api-key': fixtureKey },
+ })
+ )
+ )
+ state.keyUid = created.metadata.uid
+ state.changes.key = true
+ save()
+ const data = {
+ NODE_ENV: 'test',
+ EVENFIRE_IMAGE_CAPABILITIES_FIXTURE: '1',
+ IMAGE_CAPABILITIES_RUN_ID: state.runId,
+ IMAGE_CAPABILITIES_CREDENTIAL_SHA256: keyHash,
+ MINIKUBE_PROFILE: profile,
+ CONTROL_API_REAL_PG_CONTEXT: profile,
+ }
+ state.appliedConfig = data
+ state.appliedHost = {
+ model: { provider: 'zai', name: 'glm-5.3-flash' },
+ allowedModels: models.map(({ provider, model }) => ({ provider, model })),
+ secretRef: state.runId,
+ }
+ state.changes.config = true
+ save()
+ const liveConfig = get('mcp-host', 'configmap', 'mcp-host-config')
+ if (
+ liveConfig.metadata.uid !== state.config.uid ||
+ fixtureConfigKeys.some(key => liveConfig.data?.[key] !== state.config.data[key])
+ )
+ throw new Error('Host configuration changed before fixture preparation')
+ patch('mcp-host', 'configmap', 'mcp-host-config', [
+ ...stamp(liveConfig),
+ annotate(liveConfig),
+ ...Object.entries(data).map(([key, value]) => ({ op: 'add', path: `/data/${key}`, value })),
+ ])
+ state.changes.host = true
+ save()
+ const liveHost = get('mcp-host', 'host', 'chatllm')
+ if (
+ liveHost.metadata.uid !== state.host.uid ||
+ ['model', 'allowedModels', 'secretRef', 'llmPolicy'].some(
+ key => !isDeepStrictEqual(liveHost.spec[key], state.host[key])
+ )
+ )
+ throw new Error('Host changed before fixture preparation')
+ patch('mcp-host', 'host', 'chatllm', [
+ ...stamp(liveHost),
+ annotate(liveHost),
+ { op: 'add', path: '/spec/model', value: { provider: 'zai', name: 'glm-5.3-flash' } },
+ {
+ op: 'add',
+ path: '/spec/allowedModels',
+ value: models.map(({ provider, model }) => ({ provider, model })),
+ },
+ { op: 'add', path: '/spec/secretRef', value: state.runId },
+ ...(host.spec.llmPolicy === undefined ? [] : [{ op: 'remove', path: '/spec/llmPolicy' }]),
+ ])
+ state.changes.hcc = true
+ save()
+ const liveHcc = get('control-plane', 'deployment', 'host-context-controller')
+ if (liveHcc.metadata.uid !== state.hcc.uid)
+ throw new Error('HCC replaced before fixture preparation')
+ patch('control-plane', 'deployment', 'host-context-controller', [
+ ...stamp(liveHcc),
+ annotate(liveHcc),
+ {
+ op: 'test',
+ path: state.hcc.path.replace(/value$/, 'name'),
+ value: 'CONTEXT_MAPPER_HOST_IMAGE',
+ },
+ { op: 'test', path: state.hcc.path, value: state.hcc.image },
+ { op: 'replace', path: state.hcc.path, value: fixtureImage },
+ ])
+ kc([
+ '-n',
+ 'control-plane',
+ 'rollout',
+ 'status',
+ 'deployment/host-context-controller',
+ '--timeout=120s',
+ ])
+ await waitHostImage(fixtureImage)
+ const wire = JSON.parse(
+ kc([
+ '-n',
+ 'mcp-host',
+ 'exec',
+ 'deployment/chatllm',
+ '--',
+ 'cat',
+ '/tmp/image-capabilities-evidence.json',
+ ])
+ )
+ if (wire.runId !== state.runId || wire.profile !== profile)
+ throw new Error('Fixture runtime marker mismatch')
+ const environment = {
+ ...process.env,
+ NODE_ENV: 'test',
+ IMAGE_CAPABILITIES_RUN_ID: state.runId,
+ IMAGE_CAPABILITIES_RUN_DIR: evidence,
+ E2E_HOST_REF: 'chatllm',
+ E2E_DEV_LOGIN_EMAIL: '[email protected]',
+ E2E_DESKTOP_PASSWORD: ADMIN_PASSWORD,
+ EXTERNAL_REST_API_BASE_URL: urlFor('external-rest-api'),
+ RPC_PROXY_BASE_URL: urlFor('rpc-proxy'),
+ QA_RECORDER_CONFIRM_CHAT: '1',
+ QA_RECORDER_IMAGE_MODEL_SUPPORTED: 'glm-5.3-flash',
+ QA_RECORDER_IMAGE_MODEL_UNSUPPORTED: 'glm-5.3',
+ QA_RECORDER_IMAGE_MODEL_UNKNOWN: models[2].model,
+ QA_RECORDER_ROOT: evidence,
+ }
+ command('npm', ['run', 'verify:electron', '--prefix', 'desktop-app'])
+ process.stdout.write(`Image capability fixture ready: ${state.runId}\n`)
+ const output = command(
+ 'node',
+ [
+ 'scripts/minikube/run-with-deadline.mjs',
+ '--timeout-seconds',
+ '900',
+ '--heartbeat-seconds',
+ '20',
+ '--kill-grace-seconds',
+ '5',
+ '--label',
+ 'image-capabilities-playwright',
+ '--',
+ 'node',
+ 'desktop-app/node_modules/@playwright/test/cli.js',
+ 'test',
+ '--config=desktop-app/test/e2e-playwright/playwright.image-capabilities.config.ts',
+ ],
+ { env: environment, timeout: 930_000 }
+ )
+ report(output)
+ state.playwright = 'PASS'
+ save()
+ } catch (error) {
+ failure = error
+ // Evidence I/O must never prevent restoring the owned runtime.
+ if (error.commandOutput) {
+ try {
+ report(error.commandOutput)
+ } catch {
+ /* Keep the original failure and restore. */
+ }
+ }
+ // Diagnostic failure must not prevent restoration. Inspect only this
+ // fixture's live deployment and persist fixed startup-error categories.
+ if (state.changes.hcc) {
+ try {
+ const current = get('mcp-host', 'deployment', 'chatllm')
+ if (
+ current.spec.template.spec.containers.some(container => container.image === fixtureImage)
+ ) {
+ const logs = kc(['-n', 'mcp-host', 'logs', 'deployment/chatllm', '--tail=60'])
+ state.startupDiagnostic = [
+ ['fixture-environment', /requires its isolated test environment/],
+ ['fixture-host', /Fixture requires the isolated chatllm Host/],
+ ['sdk-boundary', /SDK did not install the isolated provider boundary/],
+ ['module-missing', /Cannot find module|ERR_MODULE_NOT_FOUND/],
+ ['file-permission', /EACCES|permission denied/i],
+ ]
+ .filter(([, pattern]) => pattern.test(logs))
+ .map(([code]) => code)
+ save()
+ }
+ } catch {
+ /* The original failure is retained; restoration still runs. */
+ }
+ }
+ }
+ try {
+ await restore()
+ } catch (error) {
+ failure = new Error(
+ `${failure ? `${failure.message}; ` : ''}restoration failed: ${error.message}`
+ )
+ }
+ uninstallSignalRestore()
+ if (failure) throw failure
+ process.stdout.write(`IMAGE_CAPABILITIES_E2E_PASS evidence=${evidence}\n`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+ main().catch(error => {
+ process.stderr.write(`Image capability fixture stopped: ${error.message}\n`)
+ process.exitCode = 1
+ })
+}
diff --git a/scripts/e2e/image-capabilities-fixture.test.mjs b/scripts/e2e/image-capabilities-fixture.test.mjs
new file mode 100644
index 000000000..d702274d7
--- /dev/null
+++ b/scripts/e2e/image-capabilities-fixture.test.mjs
@@ -0,0 +1,163 @@
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import test from 'node:test'
+import {
+ baseImage,
+ fixtureImage,
+ installSignalRestore,
+ modelInputs,
+ proveImages,
+ requireOwnedResource,
+ runAnnotation,
+ sanitizeFixtureReport,
+} from './image-capabilities-fixture.mjs'
+
+const head = 'a'.repeat(40)
+const profile = 'clerum-image-fixture-12345678'
+const ids = { [baseImage]: `sha256:${'b'.repeat(64)}`, [fixtureImage]: `sha256:${'c'.repeat(64)}` }
+function manifest() {
+ return {
+ profile,
+ images: { ...ids },
+ sourceRevisions: { [baseImage]: head, [fixtureImage]: head },
+ derivedFrom: { [fixtureImage]: { ref: baseImage, id: ids[baseImage] } },
+ }
+}
+
+test('requires both exact source revisions and the live derived-base identity', () => {
+ assert.deepEqual(proveImages(manifest(), ids, head, profile), { head, profile, images: ids })
+ for (const mutate of [
+ value => {
+ value.profile = 'foreign-profile'
+ },
+ value => {
+ value.sourceRevisions[baseImage] = 'd'.repeat(40)
+ },
+ value => {
+ value.sourceRevisions[fixtureImage] = 'd'.repeat(40)
+ },
+ value => {
+ value.derivedFrom[fixtureImage].id = `sha256:${'d'.repeat(64)}`
+ },
+ value => {
+ value.images[`docker.io/${fixtureImage}`] = `sha256:${'d'.repeat(64)}`
+ },
+ ]) {
+ const changed = manifest()
+ mutate(changed)
+ assert.throws(() => proveImages(changed, ids, head, profile))
+ }
+ assert.throws(() =>
+ proveImages(manifest(), { ...ids, [fixtureImage]: `sha256:${'d'.repeat(64)}` }, head, profile)
+ )
+})
+
+test('fixture catalog declares supported, unsupported and run-scoped unknown without provider-wide inference', () => {
+ const rows = modelInputs('image-capabilities-123456abcdef')
+ assert.deepEqual(
+ rows.map(row => [row.model, row.image_input.state]),
+ [
+ ['glm-5.3-flash', 'supported'],
+ ['glm-5.3', 'unsupported'],
+ ['image-fixture-unknown-123456abcdef', 'unknown'],
+ ]
+ )
+ assert.ok(
+ rows.every(
+ row =>
+ row.provider === 'zai' &&
+ row.image_input.evidence.reference === 'evidence:image-capabilities-123456abcdef'
+ )
+ )
+ assert.throws(() => modelInputs('../foreign'))
+})
+
+test('restoration refuses recreated or foreign-owned Kubernetes resources', () => {
+ const resource = { metadata: { uid: 'original', annotations: { [runAnnotation]: 'our-run' } } }
+ requireOwnedResource(resource, 'original', 'our-run')
+ assert.throws(() => requireOwnedResource(resource, 'replaced', 'our-run'))
+ assert.throws(() => requireOwnedResource(resource, 'original', 'another-run'))
+ assert.throws(() =>
+ requireOwnedResource({ metadata: { uid: 'original' } }, 'original', 'our-run')
+ )
+})
+
+function signalTarget() {
+ const target = new EventEmitter()
+ target.exits = []
+ target.exit = code => target.exits.push(code)
+ return target
+}
+
+for (const [signal, code] of [
+ ['SIGTERM', 143],
+ ['SIGINT', 130],
+]) {
+ test(`a ${signal} runs restoration once and exits ${code}`, async () => {
+ const target = signalTarget()
+ const messages = []
+ let calls = 0
+ installSignalRestore(
+ target,
+ async () => {
+ calls += 1
+ },
+ text => messages.push(text)
+ )
+ target.emit(signal, signal)
+ target.emit(signal, signal)
+ await new Promise(resolve => setImmediate(resolve))
+ assert.equal(calls, 1)
+ assert.deepEqual(target.exits, [code])
+ assert.match(messages.join(''), new RegExp(`interrupted by ${signal}`))
+ })
+}
+
+test('a failed restoration exits 1 and reports the message', async () => {
+ const target = signalTarget()
+ const messages = []
+ installSignalRestore(
+ target,
+ async () => {
+ throw new Error('deployment/chatllm rollback timed out')
+ },
+ text => messages.push(text)
+ )
+ target.emit('SIGTERM', 'SIGTERM')
+ await new Promise(resolve => setImmediate(resolve))
+ assert.deepEqual(target.exits, [1])
+ assert.match(messages.join(''), /restoration failed: deployment\/chatllm rollback timed out/)
+})
+
+test('uninstalling removes both signal handlers', () => {
+ const target = signalTarget()
+ const uninstall = installSignalRestore(
+ target,
+ async () => {},
+ () => {}
+ )
+ assert.equal(target.listenerCount('SIGINT'), 1)
+ assert.equal(target.listenerCount('SIGTERM'), 1)
+ uninstall()
+ assert.equal(target.listenerCount('SIGINT'), 0)
+ assert.equal(target.listenerCount('SIGTERM'), 0)
+})
+
+test('the playwright log redacts the admin password, the session cookie and bearer-shaped tokens', () => {
+ const password = 'fixture-admin-password-4c1e'
+ const cookie = 'sid=9f3a7c2e1b'
+ const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.c2lnbmF0dXJl'
+ const output = [
+ `login with ${password}`,
+ `session ${cookie} established`,
+ `token ${jwt} issued`,
+ 'Authorization: Bearer opaque-bearer-value',
+ '3 passed (41.2s)',
+ ].join('\n')
+ const report = sanitizeFixtureReport(output, [password, cookie])
+ assert.ok(!report.includes(password))
+ assert.ok(!report.includes(cookie))
+ assert.ok(!report.includes(jwt))
+ assert.ok(!report.includes('opaque-bearer-value'))
+ assert.match(report, /3 passed \(41\.2s\)/)
+})
diff --git a/scripts/minikube/build-images.sh b/scripts/minikube/build-images.sh
index 0f16fed35..01cd87626 100755
--- a/scripts/minikube/build-images.sh
+++ b/scripts/minikube/build-images.sh
@@ -360,6 +360,10 @@ KNOWN_BUILD_NAMES=(
# These isolated test images are opt-in only. Their acquisition must happen
# before T2 reconciliation, never inside the final Playwright command.
+if [ "$ONLY_SVC" = image-capabilities-mcp-host ]; then
+ ALL_IMAGES+=("clerum/image-capabilities-mcp-host:test")
+ KNOWN_BUILD_NAMES+=(image-capabilities-mcp-host)
+fi
if [ "$ONLY_SVC" = codex-approved-tools-control-api-e2e ]; then
ALL_IMAGES+=("clerum/codex-approved-tools-control-api-e2e:test")
KNOWN_BUILD_NAMES+=(codex-approved-tools-control-api-e2e)
@@ -995,6 +999,10 @@ build_image() {
fi
log "Building ${tag}..."
local docker_args=(-t "$tag") derived_base=""
+ if [ "$name" = image-capabilities-mcp-host ]; then
+ docker_args+=(--build-arg MCP_HOST_IMAGE=clerum/mcp-host:test)
+ derived_base="clerum/mcp-host:test"
+ fi
if [ -n "$dockerfile" ]; then
docker_args+=(-f "$dockerfile")
fi
@@ -1221,6 +1229,12 @@ build_image "grok-llm-proxy" \
"clerum/grok-llm-proxy:test" \
"${PROJECT_DIR}/grok-llm-proxy/Dockerfile"
+if [ "$ONLY_SVC" = image-capabilities-mcp-host ]; then
+ build_image image-capabilities-mcp-host "${PROJECT_DIR}" \
+ clerum/image-capabilities-mcp-host:test \
+ "${PROJECT_DIR}/tests/e2e/fixtures/image-capabilities/Dockerfile"
+fi
+
if [ "$ONLY_SVC" = codex-approved-tools-control-api-e2e ]; then
build_image codex-approved-tools-control-api-e2e "${PROJECT_DIR}" \
clerum/codex-approved-tools-control-api-e2e:test \
@@ -1344,7 +1358,8 @@ if [ "$SKIP_PUBLIC" = false ]; then
"postgres:16-alpine"
"redis:7-alpine"
"nginx:1.30.1-alpine"
- "minio/minio:latest"
+ # MinIO is not pulled here: nothing in this distribution consumes the
+ # image; the optional sibling evenfire-registry deployment pulls its own.
"axllent/mailpit:latest"
"mongodb/mongodb-community-server:7.0-ubi8"
"mongodb/mongodb-mcp-server:latest"
diff --git a/scripts/minikube/t2-common.sh b/scripts/minikube/t2-common.sh
index ec9fc2415..9bea4a10f 100755
--- a/scripts/minikube/t2-common.sh
+++ b/scripts/minikube/t2-common.sh
@@ -797,6 +797,99 @@ t2_control_api_runtime_check() {
'/tmp/approved-tools-oauth-active.json'
}
+# An optional image-input fixture must never survive into a runtime verdict.
+# Runs without that opt-in image keep the existing probe set unchanged.
+t2_image_capability_fixture_check() {
+ # The planner and bootstrap lanes never certify the live Host baseline, so
+ # they never probe it: an absent manifest or an unready Host there is a plan,
+ # not residue. The strict final preflight is T2_PLAN_MODE=false on a
+ # bootstrapped profile.
+ [ "$T2_PLAN_MODE" != true ] && [ "$T2_BOOTSTRAP_REQUIRED" != true ] || return 0
+ local acquired configuration restored verdict
+ if [ ! -f "$T2_IMAGE_MANIFEST" ]; then
+ T2_NEXT_COMMAND="MINIKUBE_PROFILE=$T2_PROFILE make minikube-setup-local"
+ t2_fail IMAGE_MANIFEST_MISMATCH "image manifest is missing: $T2_IMAGE_MANIFEST"
+ return 1
+ fi
+ if ! acquired="$(python3 - "$T2_IMAGE_MANIFEST" 2>&1 <<'PY_IMAGE_FIXTURE'
+import json, sys
+with open(sys.argv[1]) as source:
+ images = json.load(source)["images"]
+if not isinstance(images, dict):
+ raise SystemExit("images")
+print("yes" if any(ref.removeprefix("docker.io/") == "clerum/image-capabilities-mcp-host:test" for ref in images) else "no")
+PY_IMAGE_FIXTURE
+ )"; then
+ T2_NEXT_COMMAND="MINIKUBE_PROFILE=$T2_PROFILE make minikube-setup-local"
+ # The last line of a Python traceback names the error without echoing data.
+ t2_fail IMAGE_MANIFEST_MISMATCH "image manifest is invalid or incomplete: $T2_IMAGE_MANIFEST${acquired:+: ${acquired##*$'\n'}}"
+ return 1
+ fi
+ # stderr is merged into the value, so anything other than an exact verdict
+ # (for example an interpreter warning before "yes") must fail, not skip.
+ case "$acquired" in
+ yes) ;;
+ no) return 0 ;;
+ *)
+ T2_NEXT_COMMAND="MINIKUBE_PROFILE=$T2_PROFILE make minikube-setup-local"
+ t2_fail IMAGE_MANIFEST_MISMATCH "image manifest check returned an unexpected verdict: ${acquired##*$'\n'}"
+ return 1
+ ;;
+ esac
+ if ! configuration="$(t2_kc -n mcp-host get configmap mcp-host-config -o json)"; then
+ t2_fail HOST_RUNTIME_MISMATCH 'unable to observe the mcp-host image capability configuration'
+ return 1
+ fi
+ # The check prints a verdict so that a crash (malformed input) is reported as
+ # a crash instead of being read as residue.
+ if ! verdict="$(python3 - "$1" "$configuration" 2>&1 <<'PY_IMAGE_FIXTURE'
+import json, sys
+deployments, config = (json.loads(value) for value in sys.argv[1:])
+flag = "evenfire.ai/image-capabilities-run"
+def clean(data):
+ return not any(key.startswith("IMAGE_CAPABILITIES_") or key == "EVENFIRE_IMAGE_CAPABILITIES_FIXTURE" for key in data)
+def residue():
+ print("residue")
+ raise SystemExit(0)
+if flag in config.get("metadata", {}).get("annotations", {}) or not clean(config.get("data", {})) or config.get("data", {}).get("NODE_ENV") == "test":
+ residue()
+for deployment in deployments["items"]:
+ if flag in deployment.get("metadata", {}).get("annotations", {}):
+ residue()
+ for container in deployment["spec"]["template"]["spec"]["containers"]:
+ if "image-capabilities-mcp-host" in container.get("image", ""):
+ residue()
+ for entry in container.get("env", []):
+ if not clean([entry["name"]]) or "image-capabilities-mcp-host" in entry.get("value", ""):
+ residue()
+print("clean")
+PY_IMAGE_FIXTURE
+ )"; then
+ t2_fail HOST_RUNTIME_MISMATCH "image capability residue check crashed: ${verdict##*$'\n'}"
+ return 1
+ fi
+ case "$verdict" in
+ clean) ;;
+ residue)
+ t2_fail HOST_RUNTIME_MISMATCH 'image capability fixture configuration remains installed'
+ return 1
+ ;;
+ *)
+ t2_fail HOST_RUNTIME_MISMATCH "image capability residue check returned an unexpected verdict: ${verdict##*$'\n'}"
+ return 1
+ ;;
+ esac
+ if ! restored="$(t2_kc -n mcp-host exec deployment/chatllm -- node -e \
+ 'process.stdout.write(String(process.env.NODE_ENV !== "test" && !Object.keys(process.env).some(key => key.startsWith("IMAGE_CAPABILITIES_") || key === "EVENFIRE_IMAGE_CAPABILITIES_FIXTURE") && !require("node:fs").existsSync("/tmp/image-capabilities-evidence.json")))')"; then
+ t2_fail HOST_RUNTIME_MISMATCH 'unable to observe the running Host image capability environment'
+ return 1
+ fi
+ if [ "$restored" != true ]; then
+ t2_fail HOST_RUNTIME_MISMATCH 'image capability fixture remains in the running Host'
+ return 1
+ fi
+}
+
t2_deployment_check() {
local deployment_json unready
deployment_json="$(t2_kc get deployments -A -o json 2>/dev/null || true)"
diff --git a/scripts/minikube/t2-preflight.sh b/scripts/minikube/t2-preflight.sh
index 4da2d634e..d8572a30a 100755
--- a/scripts/minikube/t2-preflight.sh
+++ b/scripts/minikube/t2-preflight.sh
@@ -53,6 +53,7 @@ main() {
t2_deployment_check
t2_proxy_runtime_check "$T2_DEPLOYMENT_JSON"
t2_control_api_runtime_check "$T2_DEPLOYMENT_JSON"
+ t2_image_capability_fixture_check "$T2_DEPLOYMENT_JSON"
t2_process_check
t2_classify_transition
t2_write_plan "$T2_PLAN_FILE"
diff --git a/scripts/tests/test-e2e-vitest-node-unit-gate.sh b/scripts/tests/test-e2e-vitest-node-unit-gate.sh
index 31a929405..46e24f5a3 100755
--- a/scripts/tests/test-e2e-vitest-node-unit-gate.sh
+++ b/scripts/tests/test-e2e-vitest-node-unit-gate.sh
@@ -15,6 +15,54 @@ require_contains() {
fi
}
+# A step name alone proves nothing: the registration is only useful when the
+# step carries the mcp-host gate and runs after the build that produces the
+# dist/ the fixture's SDK test imports. Both are asserted structurally so a
+# future edit that moves or un-gates the step turns this contract red.
+require_step_gate() {
+ local file="$1"
+ local step_name="$2"
+ local gate="$3"
+ local description="$4"
+ if ! awk -v step="${step_name}" -v gate="${gate}" '
+ $0 == " - name: " step { inblock = 1; next }
+ inblock && /^ - name: / { inblock = 0 }
+ inblock && index($0, gate) { found = 1 }
+ END { exit(found ? 0 : 1) }
+ ' "${file}"; then
+ echo "missing ${description}" >&2
+ exit 1
+ fi
+}
+
+require_step_after() {
+ local file="$1"
+ local later_step="$2"
+ local earlier_step="$3"
+ local description="$4"
+ if ! awk -v later="${later_step}" -v earlier="${earlier_step}" '
+ { line[NR] = $0 }
+ END {
+ later_line = 0
+ for (i = 1; i <= NR; i++) {
+ if (line[i] == " - name: " later) { later_line = i; break }
+ }
+ if (later_line == 0) { printf("missing step: %s\n", later) > "/dev/stderr"; exit 1 }
+ earlier_line = 0
+ for (i = 1; i < later_line; i++) {
+ if (line[i] == " - name: " earlier) earlier_line = i
+ }
+ if (earlier_line == 0) {
+ printf("step is not preceded by %s: %s\n", earlier, later) > "/dev/stderr"
+ exit 1
+ }
+ }
+ ' "${file}"; then
+ echo "expected ${description}" >&2
+ exit 1
+ fi
+}
+
require_contains "${RUNNER}" "DEFAULT_NODE_UNIT_VITEST_SUITES=(" \
"node-unit suite registry"
require_contains "${RUNNER}" "gfsUploadV2Fixtures.test.ts" \
@@ -35,5 +83,18 @@ require_contains "${WORKFLOW}" "node-version: '24'" \
"Node 24 setup"
require_contains "${WORKFLOW}" "E2E_VITEST_SUITE_GROUP=node-unit bash scripts/e2e/run-vitest-e2e.sh" \
"canonical runner invocation"
+require_contains "${WORKFLOW}" "Test image-capabilities fixtures and runner" \
+ "image-capabilities public CI step"
+require_contains "${WORKFLOW}" "scripts/e2e/image-capabilities-fixture.test.mjs" \
+ "image-capabilities fixture registration"
+require_contains "${WORKFLOW}" "tests/e2e/fixtures/image-capabilities/sdk.test.mjs" \
+ "image-capabilities sdk registration"
+require_contains "${WORKFLOW}" "tests/e2e/fixtures/image-capabilities/provider.test.mjs" \
+ "image-capabilities provider registration"
+require_step_gate "${WORKFLOW}" "Test image-capabilities fixtures and runner" \
+ "matrix.service == 'mcp-host'" \
+ "image-capabilities step mcp-host gate"
+require_step_after "${WORKFLOW}" "Test image-capabilities fixtures and runner" "Build" \
+ "image-capabilities step ordered after Build in the same job"
echo "E2E Vitest node-unit public gate contract OK"
diff --git a/scripts/tests/test-images-manifest.sh b/scripts/tests/test-images-manifest.sh
index 052acdd74..e52d5857a 100755
--- a/scripts/tests/test-images-manifest.sh
+++ b/scripts/tests/test-images-manifest.sh
@@ -209,7 +209,7 @@ assert_unpublished_images_are_exactly_the_known_fixtures() {
console.log(m.IMAGES.filter(i=>!i.published).map(i=>i.name).sort().join(",")))' 2>/dev/null)"
# Only these local E2E fixtures are unpublished. Keep the exact set explicit
# so a production image cannot silently disappear from publication.
- local want="codex-approved-tools-control-api-e2e,codex-approved-tools-mcp-e2e,codex-approved-tools-proxy-e2e,codex-approved-tools-workflow-e2e,workflow-custom-sdk-e2e,workflow-plugin-sdk-e2e"
+ local want="codex-approved-tools-control-api-e2e,codex-approved-tools-mcp-e2e,codex-approved-tools-proxy-e2e,codex-approved-tools-workflow-e2e,image-capabilities-mcp-host,workflow-custom-sdk-e2e,workflow-plugin-sdk-e2e"
if [ "$got" = "$want" ]; then
pass "the unpublished set is exactly the known fixtures"
else
diff --git a/scripts/tests/test-minikube-image-capability-fixture.sh b/scripts/tests/test-minikube-image-capability-fixture.sh
new file mode 100755
index 000000000..4a3ef5454
--- /dev/null
+++ b/scripts/tests/test-minikube-image-capability-fixture.sh
@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# Hermetic residue, phase, and manifest-integrity checks for the optional
+# image-capability fixture. No cluster, container, Docker, or Minikube call is
+# made; the temporary fixture repository proves the host checkout is untouched.
+# shellcheck disable=SC2034
+set -euo pipefail
+ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
+source "$ROOT/scripts/tests/lib/minikube-fixture-repo.sh"
+tmp="$(mktemp -d)"
+cleanup() {
+ local status=$?
+ minikube_test_assert_host_unchanged || status=1
+ rm -rf "$tmp"
+ exit "$status"
+}
+minikube_test_fixture_repo_init "$ROOT" "$tmp"
+trap cleanup EXIT
+export T2_PROJECT_DIR="$MINIKUBE_TEST_PROJECT_DIR"
+export T2_BRANCH="$MINIKUBE_TEST_BRANCH" T2_HEAD="$MINIKUBE_TEST_HEAD"
+export T2_WORKTREE_ID="$MINIKUBE_TEST_WORKTREE_ID"
+export T2_PROFILE=fake T2_CONTEXT=fake T2_LOCK_ROOT="$tmp/locks"
+
+# t2-common.sh resolves T2_IMAGE_MANIFEST from T2_PROJECT_DIR when it loads, so
+# the default manifest lives in the fixture repository. The custom override
+# below has to win over that default.
+source "$ROOT/scripts/minikube/t2-common.sh"
+DEFAULT_MANIFEST="$T2_IMAGE_MANIFEST"
+CUSTOM_MANIFEST="$tmp/custom-image-manifest.json"
+mkdir -p "$(dirname -- "$DEFAULT_MANIFEST")"
+T2_PLAN_MODE=false
+T2_BOOTSTRAP_REQUIRED=false
+t2_fail() { printf '%s: %s\n' "$1" "$2" >&2; return 1; }
+
+MANIFEST_ACQUIRED='{"generated":"fixture","imageSource":"local","imageTag":"","images":{"clerum/image-capabilities-mcp-host:test":"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}}'
+MANIFEST_EMPTY='{"generated":"fixture","imageSource":"local","imageTag":"","images":{}}'
+CONFIG_CLEAN='{"data":{},"metadata":{}}'
+DEPLOYMENTS_CLEAN='{"items":[{"metadata":{},"spec":{"template":{"spec":{"containers":[{"image":"clerum/mcp-host:test","env":[]}]}}}}]}'
+DEPLOYMENT_ANNOTATION='{"items":[{"metadata":{"annotations":{"evenfire.ai/image-capabilities-run":"1"}},"spec":{"template":{"spec":{"containers":[{"image":"clerum/mcp-host:test","env":[]}]}}}}]}'
+DEPLOYMENT_IMAGE='{"items":[{"metadata":{},"spec":{"template":{"spec":{"containers":[{"image":"clerum/image-capabilities-mcp-host:test","env":[]}]}}}}]}'
+DEPLOYMENT_ENV='{"items":[{"metadata":{},"spec":{"template":{"spec":{"containers":[{"image":"clerum/mcp-host:test","env":[{"name":"IMAGE_CAPABILITIES_FIXTURE_IMAGE","value":"clerum/image-capabilities-mcp-host:test"}]}]}}}}]}'
+RUNTIME_CLEAN=true
+PREFLIGHT_CALLS="$tmp/cluster-calls"
+: >"$PREFLIGHT_CALLS"
+
+# Every cluster interaction is replaced; an unexpected command is a test bug.
+# The caller observes commands through command substitution, so the log is a
+# file: a subshell cannot update a counter variable.
+t2_kc() {
+ printf '%s\n' "$*" >>"$PREFLIGHT_CALLS"
+ case "$*" in
+ '-n mcp-host get configmap mcp-host-config -o json')
+ [ "$HOST_UNREADY" != true ] || return 1
+ printf '%s' "$CONFIG"
+ ;;
+ '-n mcp-host exec deployment/chatllm -- node -e '*)
+ [ "$HOST_UNREADY" != true ] || return 1
+ printf '%s' "$RUNTIME"
+ ;;
+ *)
+ printf 'unexpected cluster command: %s\n' "$*" >&2
+ return 99
+ ;;
+ esac
+}
+
+CONFIG="$CONFIG_CLEAN"
+DEPLOYMENTS="$DEPLOYMENTS_CLEAN"
+RUNTIME="$RUNTIME_CLEAN"
+HOST_UNREADY=false
+
+reset_case() {
+ : >"$PREFLIGHT_CALLS"
+ CONFIG="$CONFIG_CLEAN"
+ DEPLOYMENTS="$DEPLOYMENTS_CLEAN"
+ RUNTIME="$RUNTIME_CLEAN"
+ HOST_UNREADY=false
+ T2_PLAN_MODE=false
+ T2_BOOTSTRAP_REQUIRED=false
+ T2_IMAGE_MANIFEST="$DEFAULT_MANIFEST"
+ printf '%s' "$MANIFEST_ACQUIRED" >"$DEFAULT_MANIFEST"
+}
+
+expect_pass() {
+ local label="$1"
+ if ! t2_image_capability_fixture_check "$DEPLOYMENTS" >"$tmp/out" 2>&1; then
+ printf 'FAIL: %s did not pass\n' "$label" >&2
+ cat "$tmp/out" >&2
+ exit 1
+ fi
+}
+
+expect_fail() {
+ local label="$1" expected="$2"
+ if t2_image_capability_fixture_check "$DEPLOYMENTS" >"$tmp/out" 2>&1; then
+ printf 'FAIL: %s unexpectedly passed\n' "$label" >&2
+ exit 1
+ fi
+ grep -Fq -- "$expected" "$tmp/out" || {
+ printf '%s\n' "$(cat "$tmp/out")" >&2
+ printf 'FAIL: %s did not report %s\n' "$label" "$expected" >&2
+ exit 1
+ }
+}
+
+expect_no_traceback() {
+ local label="$1"
+ if grep -Fq 'Traceback (most recent call last)' "$tmp/out"; then
+ cat "$tmp/out" >&2
+ printf 'FAIL: %s leaked a Python traceback\n' "$label" >&2
+ exit 1
+ fi
+}
+
+expect_cluster_calls() {
+ local label="$1" expected="$2" actual
+ actual="$(awk 'END { print NR + 0 }' "$PREFLIGHT_CALLS")"
+ if [ "$actual" -ne "$expected" ]; then
+ printf 'FAIL: %s made %s cluster calls, expected %s\n' "$label" "$actual" "$expected" >&2
+ exit 1
+ fi
+}
+
+expect_probe() {
+ local label="$1"
+ if [ "$(awk 'END { print NR + 0 }' "$PREFLIGHT_CALLS")" -le 0 ]; then
+ printf 'FAIL: %s skipped the cluster probe\n' "$label" >&2
+ exit 1
+ fi
+}
+
+# The strict final preflight probes the certified Host and passes when clean.
+reset_case
+expect_pass 'strict clean'
+expect_probe 'strict clean'
+
+# Runs without the opt-in image keep the probe set unchanged.
+reset_case
+printf '%s' "$MANIFEST_EMPTY" >"$DEFAULT_MANIFEST"
+expect_pass 'not acquired'
+expect_cluster_calls 'not acquired' 0
+
+# Residue in configuration, deployments, or the running Host must fail.
+reset_case
+CONFIG='{"data":{"IMAGE_CAPABILITIES_RUN_ID":"image-capabilities-123456abcdef"},"metadata":{}}'
+expect_fail 'configmap residue' HOST_RUNTIME_MISMATCH
+reset_case
+CONFIG='{"data":{"NODE_ENV":"test"},"metadata":{}}'
+expect_fail 'configmap test environment' HOST_RUNTIME_MISMATCH
+reset_case
+CONFIG='{"data":{},"metadata":{"annotations":{"evenfire.ai/image-capabilities-run":"1"}}}'
+expect_fail 'configmap annotation' HOST_RUNTIME_MISMATCH
+reset_case
+DEPLOYMENTS="$DEPLOYMENT_ANNOTATION"
+expect_fail 'deployment annotation' HOST_RUNTIME_MISMATCH
+reset_case
+DEPLOYMENTS="$DEPLOYMENT_IMAGE"
+expect_fail 'fixture image in deployment' HOST_RUNTIME_MISMATCH
+reset_case
+DEPLOYMENTS="$DEPLOYMENT_ENV"
+expect_fail 'fixture value in deployment environment' HOST_RUNTIME_MISMATCH
+reset_case
+RUNTIME=false
+expect_fail 'runtime residue' HOST_RUNTIME_MISMATCH
+
+# Malformed input is a crash, reported as one, never read as residue.
+reset_case
+DEPLOYMENTS='{"items":'
+expect_fail 'malformed deployments' 'image capability residue check crashed: '
+expect_fail 'malformed deployments' 'JSONDecodeError'
+expect_no_traceback 'malformed deployments'
+if grep -Fq 'configuration remains installed' "$tmp/out"; then
+ printf 'FAIL: malformed deployments were reported as residue\n' >&2
+ exit 1
+fi
+
+# stderr is merged into the verdict. An interpreter warning printed before the
+# manifest verdict must fail the strict check, not skip the cluster probe.
+reset_case
+python3() {
+ printf 'DeprecationWarning: interpreter notice\n' >&2
+ command python3 "$@"
+}
+expect_fail 'interpreter warning before the manifest verdict' 'unexpected verdict: yes'
+expect_cluster_calls 'interpreter warning before the manifest verdict' 0
+unset -f python3
+
+# Planning and bootstrap never certify the live Host, so they never probe it.
+reset_case
+T2_PLAN_MODE=true
+T2_BOOTSTRAP_REQUIRED=true
+rm -f "$DEFAULT_MANIFEST"
+expect_pass 'planner/bootstrap without a manifest'
+expect_no_traceback 'planner/bootstrap without a manifest'
+expect_cluster_calls 'planner/bootstrap without a manifest' 0
+
+reset_case
+T2_PLAN_MODE=true
+HOST_UNREADY=true
+expect_pass 'planner with an unready Host'
+expect_cluster_calls 'planner with an unready Host' 0
+
+reset_case
+T2_BOOTSTRAP_REQUIRED=true
+HOST_UNREADY=true
+expect_pass 'bootstrap with an unready Host'
+expect_cluster_calls 'bootstrap with an unready Host' 0
+
+# A custom manifest override is authoritative over the project default.
+reset_case
+T2_IMAGE_MANIFEST="$CUSTOM_MANIFEST"
+printf '%s' "$MANIFEST_EMPTY" >"$DEFAULT_MANIFEST"
+printf '%s' "$MANIFEST_ACQUIRED" >"$CUSTOM_MANIFEST"
+expect_pass 'custom manifest with the acquired image'
+expect_probe 'custom manifest with the acquired image'
+
+reset_case
+T2_IMAGE_MANIFEST="$CUSTOM_MANIFEST"
+printf '%s' "$MANIFEST_ACQUIRED" >"$DEFAULT_MANIFEST"
+printf '%s' "$MANIFEST_EMPTY" >"$CUSTOM_MANIFEST"
+expect_pass 'custom manifest without the acquired image'
+expect_cluster_calls 'custom manifest without the acquired image' 0
+
+# Manifest integrity is a stable strict failure, never a silent crash.
+reset_case
+rm -f "$DEFAULT_MANIFEST"
+expect_fail 'strict missing manifest' IMAGE_MANIFEST_MISMATCH
+expect_no_traceback 'strict missing manifest'
+
+reset_case
+printf '%s' '{"images":' >"$DEFAULT_MANIFEST"
+expect_fail 'strict corrupt manifest' IMAGE_MANIFEST_MISMATCH
+expect_fail 'strict corrupt manifest' 'JSONDecodeError'
+expect_no_traceback 'strict corrupt manifest'
+
+reset_case
+printf '%s' '{"images":[]}' >"$DEFAULT_MANIFEST"
+expect_fail 'strict non-object images' IMAGE_MANIFEST_MISMATCH
+expect_no_traceback 'strict non-object images'
+
+# Keep the production preflight integration under regression coverage.
+# The contract checks literal shell source, not an expanded value.
+# shellcheck disable=SC2016
+grep -Fq 't2_image_capability_fixture_check "$T2_DEPLOYMENT_JSON"' "$ROOT/scripts/minikube/t2-preflight.sh"
+
+printf 'PASS: optional image fixture cannot survive a T2 runtime verdict\n'
diff --git a/scripts/tests/test-minikube-t2-contract.sh b/scripts/tests/test-minikube-t2-contract.sh
index f84267a92..a3f0339bf 100755
--- a/scripts/tests/test-minikube-t2-contract.sh
+++ b/scripts/tests/test-minikube-t2-contract.sh
@@ -28,6 +28,7 @@ for file in "$MINIKUBE_DIR/profile-readiness.sh" "$ROOT/scripts/tests/test-minik
"$ROOT/scripts/tests/test-minikube-t2-scenarios.sh" \
"$ROOT/scripts/tests/test-minikube-t2-proxy-runtime.sh" \
"$ROOT/scripts/tests/test-minikube-t2-control-api-runtime.sh" \
+ "$ROOT/scripts/tests/test-minikube-image-capability-fixture.sh" \
"$ROOT/scripts/tests/test-minikube-settle-gfs-reader-rollout.sh" \
"$ROOT/scripts/tests/test-minikube-gfs-rollout-shim.sh" \
"$ROOT/scripts/tests/test-minikube-gfs-provision-order.sh" \
@@ -668,4 +669,5 @@ bash "$ROOT/scripts/tests/test-minikube-build-images-hardening.sh"
bash "$ROOT/scripts/tests/test-minikube-build-section-headers.sh"
bash "$ROOT/scripts/tests/test-minikube-pre-gate-shadow.sh"
+bash "$ROOT/scripts/tests/test-minikube-image-capability-fixture.sh"
printf 'PASS: local Minikube T0/T1/T2 contract checks\n'
diff --git a/tests/e2e/fixtures/image-capabilities/Dockerfile b/tests/e2e/fixtures/image-capabilities/Dockerfile
new file mode 100644
index 000000000..2a00757f3
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/Dockerfile
@@ -0,0 +1,5 @@
+ARG MCP_HOST_IMAGE
+FROM ${MCP_HOST_IMAGE}
+LABEL ai.evenfire.test-only="image-capabilities-minikube"
+COPY tests/e2e/fixtures/image-capabilities/provider.mjs tests/e2e/fixtures/image-capabilities/entrypoint.mjs /app/image-capabilities/
+CMD ["node", "--import", "/app/image-capabilities/entrypoint.mjs", "/app/mcp-host/dist/main.js"]
diff --git a/tests/e2e/fixtures/image-capabilities/README.md b/tests/e2e/fixtures/image-capabilities/README.md
new file mode 100644
index 000000000..45dc63463
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/README.md
@@ -0,0 +1,74 @@
+# Desktop image-capability fixture
+
+This optional, unpublished image derives from the reviewed MCP Host image. It
+simulates only the external ZAI chat-completions peer. Electron, sign-in, IPC,
+RPC, the catalog, model selection, persistence, the Host and its SDK serializer
+remain real. No paid inference is made by this lane.
+
+The fixture authenticates its own generated key by a SHA-256 digest. The key is
+held in a run-owned Kubernetes Secret; only the digest enters the fixture
+configuration. Responses to image requests are computed from the received PNG
+pixels. Evidence records model, image digest and counters, never bodies or
+authorization data. Other external origins are refused.
+
+The pinned OpenAI SDK uses node-fetch by default. The fixture entrypoint selects
+the SDK's web shim before starting the real CommonJS Host, and refuses startup
+unless the SDK binds to the isolated fetch boundary. `sdk.test.mjs` checks the
+compiled ZAI provider with the PNG generated by the browser journey.
+The preload runs with Node's `--import`; the production `main.js` remains the
+main program so its normal startup guard and crash handlers execute.
+
+## Local execution
+
+Use Node 24 and Bash 5, a clean development branch based on current `origin/dev`,
+and the profile/context resolved by the primary checkout's `branch.mk`. Both
+`MINIKUBE_PROFILE` and `CONTROL_API_REAL_PG_CONTEXT` must name that owned profile.
+Run runtime commands outside the native sandbox. Keep its registered UI forwards
+alive in a host session. Do not use a shared profile or a remote recorder config.
+
+```sh
+make minikube-build-image-capabilities-fixture
+make minikube-t2
+make minikube-run-image-capabilities
+```
+
+Acquisition is separate from the journey and records the exact source revision,
+image IDs and derived-base binding under the normal mutation lease. The runner
+requires those identities, the owned local ports and one isolated `chatllm` Host.
+It uses the existing admin-login resolver and the real admin API to establish
+catalog preconditions. Login and all chat interactions under test happen through
+the visible Desktop UI. Read-only IPC observations after the response correlate
+both rendered messages with the durable Host task; they never drive the flow.
+
+The runner journals restoration before mutation. It restores the original model,
+allowlist, configuration and production image, checks resource ownership, and
+removes only its own key and catalog rows. On SIGINT or SIGTERM it restores
+before exiting (after the current `kubectl`/`npm` call returns). If the process
+was killed or restoration failed, pass the printed canonical run directory to:
+
+```sh
+make minikube-restore-image-capabilities IMAGE_CAPABILITIES_RUN_DIR=<run directory>
+```
+
+After pod replacements, revalidate the registered forwards through the branch
+helper. Close runtime certification with `make minikube-t2-runtime` only when
+T0/T1 are already attested on the same HEAD. T2 refuses a remaining fixture image,
+configuration or marker. The browser result and the production-runtime verdict
+are separate evidence lanes. A paid-provider smoke remains separately opt-in.
+
+## Verification
+
+```sh
+node --test scripts/e2e/image-capabilities-fixture.test.mjs
+node --test tests/e2e/fixtures/image-capabilities/provider.test.mjs
+node --test tests/e2e/fixtures/image-capabilities/sdk.test.mjs
+bash scripts/tests/test-minikube-image-capability-fixture.sh
+```
+
+Build `mcp-host` before the SDK integration test. The browser config is
+`desktop-app/test/e2e-playwright/playwright.image-capabilities.config.ts`; it does
+not load global env files. The journey verifies unknown capability, supported
+image delivery, retention while switching to text-only, blocked Enter/send, and
+text delivery after explicit image removal. Missing pixels, a wrong model,
+duplicate visual delivery, stale evidence, or missing durable-task correlation
+cannot satisfy its positive oracle.
diff --git a/tests/e2e/fixtures/image-capabilities/entrypoint.mjs b/tests/e2e/fixtures/image-capabilities/entrypoint.mjs
new file mode 100644
index 000000000..8f18fcece
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/entrypoint.mjs
@@ -0,0 +1,33 @@
+import { renameSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { createImageFixtureFetch, validateFixtureEnvironment } from './provider.mjs'
+
+validateFixtureEnvironment(process.env)
+if (process.env.CLERUM_HOST_NAME !== 'chatllm')
+ throw new Error('Fixture requires the isolated chatllm Host')
+const runId = process.env.IMAGE_CAPABILITIES_RUN_ID
+const profile = process.env.MINIKUBE_PROFILE
+const marker = { runId, profile, pid: process.pid }
+const evidencePath = '/tmp/image-capabilities-evidence.json'
+const persist = evidence => {
+ writeFileSync(`${evidencePath}.next`, JSON.stringify({ ...marker, ...evidence }), { mode: 0o600 })
+ renameSync(`${evidencePath}.next`, evidencePath)
+}
+const fixture = createImageFixtureFetch(globalThis.fetch.bind(globalThis), {
+ runId,
+ credentialHash: process.env.IMAGE_CAPABILITIES_CREDENTIAL_SHA256,
+ onEvidence: persist,
+})
+globalThis.fetch = fixture.fetch
+// The pinned OpenAI v4 SDK defaults to node-fetch, not globalThis.fetch. Select
+// its documented web shim before the CommonJS production provider is loaded.
+// Refuse startup if that SDK no longer binds to the isolated HTTP boundary.
+const require = createRequire('/app/mcp-host/package.json')
+require('openai/shims/web')
+const { APIClient } = require('openai/core')
+const probe = new APIClient({ baseURL: 'http://127.0.0.1', maxRetries: 0, timeout: 1000 })
+if (probe.fetch !== fixture.fetch)
+ throw new Error('SDK did not install the isolated provider boundary')
+persist(fixture.getEvidence())
+// Docker starts the real Host as Node's main program after this preload. Its
+// require.main guard and crash handlers must execute exactly as in production.
diff --git a/tests/e2e/fixtures/image-capabilities/provider.mjs b/tests/e2e/fixtures/image-capabilities/provider.mjs
new file mode 100644
index 000000000..7165f2776
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/provider.mjs
@@ -0,0 +1,691 @@
+/**
+ * E2E_GUARDIAN_IPC_FLOW: transport fixture, not a browser journey. This module
+ * never drives the Electron app and has no page, route, or renderer HTTP request
+ * to await; the journey
+ * `desktop-app/test/e2e-playwright/qa-recorder-image-capabilities.spec.ts` owns
+ * the user-visible oracle, and this fixture's own contract is proven by
+ * `provider.test.mjs`.
+ *
+ * Evenfire E2E fixture: the EXTERNAL ZAI OpenAI chat-completions boundary (issue #654).
+ *
+ * Scope. This module owns exactly one external boundary and nothing else:
+ *
+ * POST https://api.z.ai/api/coding/paas/v4/chat/completions
+ *
+ * Everything else is either delegated untouched (internal cluster routes, where
+ * this fixture must never read or rewrite auth) or refused (any other external
+ * origin, so a misconfigured run can never reach a real provider from inside the
+ * fixture). A refusal is always an explicit error response, never a synthetic
+ * success.
+ *
+ * Why the answer is trustworthy. The journey's oracle is that the model names the
+ * tile colors of a 2-column x 3-row PNG, and those colors appear nowhere in the
+ * prompt or the file name. So this fixture must recover them from the actual
+ * pixels: it decodes the PNG bytes carried in the request's image part and reads
+ * the six tile centers. A run that never delivered the image cannot pass by
+ * guessing, and a request that carries no image never receives a color list.
+ *
+ * Determinism and sanitation. Responses carry a synthetic completion id derived
+ * from the run id, a fixed test usage block, `finish_reason: 'stop'`, and never a
+ * tool call. Both accepted models answer a text-only request with
+ * `IMAGE_FIXTURE_TEXT_OK`, so a legitimate title or summary call is never turned
+ * into a false failure; only a delivered image can produce a color list. Evidence
+ * is limited to the run id, counters, per-model counts, a per-call ledger
+ * (model, nullable image digest, response kind), and SHA-256 digests of the
+ * delivered image bytes. Headers, auth values, prompts, and raw image bytes are
+ * never recorded.
+ *
+ * Authentication. This fixture never holds the runner's ZAI key. It holds only
+ * the SHA-256 digest of that key, hashes the bearer token it receives, and
+ * compares the two digests. The key itself lives in the Host's own Secret, so a
+ * digest leak cannot be replayed as a credential.
+ *
+ * Injection note for the wiring. Shadowing `globalThis.fetch` is NOT sufficient
+ * for mcp-host: `[email protected]` resolves its transport from
+ * `_shims/node-runtime.mjs` (`node-fetch`) under the node export condition, and
+ * `shims.fetch !== globalThis.fetch`. The returned `fetch` is an ordinary
+ * fetch-shaped function, so the caller must install it where the OpenAI client
+ * actually reads its transport instead of assuming the global shadow is enough.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { crc32, inflateSync } from 'node:zlib'
+
+/**
+ * The environment-variable name that carries the SHA-256 digest of the runner's
+ * own ephemeral ZAI key. Only the digest is published to this process; the key
+ * stays in the Host's Secret. It is referenced symbolically, never by value.
+ */
+const FIXTURE_AUTH_ENV_KEY = 'IMAGE_CAPABILITIES_CREDENTIAL_SHA256'
+
+/** A SHA-256 digest, as 64 hexadecimal characters in either case. */
+const SHA256_HEX = /^[0-9a-f]{64}$/i
+
+const PROVIDER_ORIGIN = 'https://api.z.ai'
+const CHAT_COMPLETIONS_PATH = '/api/coding/paas/v4/chat/completions'
+
+/** The only two models this fixture answers for. Anything else fails closed. */
+const SUPPORTED_MODEL = 'glm-5.3-flash'
+const UNSUPPORTED_MODEL = 'glm-5.3'
+
+/** Text-only completion content. It names no image and no color. */
+const TEXT_ONLY_CONTENT = 'IMAGE_FIXTURE_TEXT_OK'
+
+/** Fixed OpenAI-compatible envelope values, so evidence is reproducible. */
+const FIXTURE_CREATED = 1767225600
+const FIXTURE_USAGE = { prompt_tokens: 12, completion_tokens: 8, total_tokens: 20 }
+const FIXTURE_SYSTEM_FINGERPRINT = 'fp_image_capabilities_fixture'
+const COMPLETION_ID_PREFIX = 'chatcmpl-image-fixture-'
+
+/** Bounds. Every one of these is checked before a decode or an inflate. */
+const MAX_REQUEST_BYTES = 8 * 1024 * 1024
+const MAX_PNG_BYTES = 6 * 1024 * 1024
+const MAX_CHUNK_BYTES = 2 * 1024 * 1024
+const MAX_DIMENSION = 2048
+const MIN_TILE_EDGE = 2
+
+/** The tile grid the journey's PNG helper paints. */
+const GRID_COLUMNS = 2
+const GRID_ROWS = 3
+
+const PNG_DATA_URI_PREFIX = 'data:image/png;base64,'
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/** PNG colour type 2 (truecolor RGB) with 8 bits per sample. */
+const PNG_COLOR_TYPE_TRUECOLOR = 2
+const PNG_BIT_DEPTH_8 = 8
+const PNG_BYTES_PER_PIXEL = 3
+
+/**
+ * Canonical tile palette. MUST stay identical to
+ * `desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts`
+ * (`IMAGE_FIXTURE_RGB`). Tiles are matched by exact RGB against this table and
+ * anything unmatched is refused, so palette drift fails loudly instead of
+ * producing a plausible but wrong answer.
+ */
+const TILE_PALETTE = [
+ ['red', 220, 30, 30],
+ ['blue', 30, 70, 220],
+ ['green', 30, 170, 60],
+ ['yellow', 245, 220, 25],
+ ['orange', 250, 140, 20],
+ ['purple', 135, 60, 200],
+ ['magenta', 230, 40, 190],
+ ['cyan', 30, 205, 220],
+ ['brown', 125, 80, 45],
+ ['pink', 250, 160, 200],
+ ['gray', 135, 135, 135],
+ ['lime', 175, 235, 35],
+]
+
+const TILE_COLOR_NAMES = new Map(
+ TILE_PALETTE.map(([name, red, green, blue]) => [`${red},${green},${blue}`, name])
+)
+
+/** A refusal with a stable machine-readable reason code for the evidence tally. */
+class FixtureImageError extends Error {
+ constructor(code, message) {
+ super(message)
+ this.name = 'FixtureImageError'
+ this.code = code
+ }
+}
+
+const malformedPng = message => new FixtureImageError('image-png-malformed', message)
+
+function readPngHeader(data) {
+ if (data.length !== 13) throw malformedPng('IHDR must be exactly 13 bytes')
+ const width = data.readUInt32BE(0)
+ const height = data.readUInt32BE(4)
+ const bitDepth = data[8]
+ const colorType = data[9]
+ const compression = data[10]
+ const filter = data[11]
+ const interlace = data[12]
+
+ if (width < GRID_COLUMNS * MIN_TILE_EDGE || height < GRID_ROWS * MIN_TILE_EDGE)
+ throw malformedPng(
+ `PNG ${width}x${height} is too small for the ${GRID_COLUMNS}x${GRID_ROWS} grid`
+ )
+ if (width > MAX_DIMENSION || height > MAX_DIMENSION)
+ throw malformedPng(`PNG ${width}x${height} exceeds the ${MAX_DIMENSION}px bound`)
+ if (width % GRID_COLUMNS !== 0 || height % GRID_ROWS !== 0)
+ throw new FixtureImageError(
+ 'image-tile-grid-mismatch',
+ `PNG ${width}x${height} does not divide into ${GRID_COLUMNS}x${GRID_ROWS} whole-pixel tiles`
+ )
+ if (
+ bitDepth !== PNG_BIT_DEPTH_8 ||
+ colorType !== PNG_COLOR_TYPE_TRUECOLOR ||
+ compression !== 0 ||
+ filter !== 0 ||
+ interlace !== 0
+ )
+ throw new FixtureImageError(
+ 'image-png-unsupported-form',
+ 'PNG must be 8-bit truecolor, non-interlaced, compression 0, filter 0 ' +
+ `(got bitDepth ${bitDepth}, colorType ${colorType}, compression ${compression}, ` +
+ `filter ${filter}, interlace ${interlace})`
+ )
+
+ return { width, height }
+}
+
+/**
+ * Decode the fixture PNG and return its six tile colors in reading order.
+ *
+ * Structural validation happens strictly BEFORE the IDAT stream is inflated:
+ * the signature, every chunk's length/CRC and criticality, the IHDR field set,
+ * the grid divisibility, and the inflated-length bound. A PNG in any other shape
+ * is refused rather than approximated.
+ */
+function decodeTileColors(bytes) {
+ if (bytes.length > MAX_PNG_BYTES)
+ throw malformedPng(`PNG exceeds the ${MAX_PNG_BYTES}-byte bound`)
+ if (bytes.length < PNG_SIGNATURE.length || !bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+ throw malformedPng('missing PNG signature')
+
+ let offset = PNG_SIGNATURE.length
+ let header = null
+ const idat = []
+ let idatClosed = false
+ let ended = false
+
+ while (offset < bytes.length) {
+ if (ended) throw malformedPng('trailing data after IEND')
+ if (offset + 8 > bytes.length) throw malformedPng('truncated chunk header')
+
+ const length = bytes.readUInt32BE(offset)
+ if (length > MAX_CHUNK_BYTES) throw malformedPng(`chunk length ${length} exceeds the bound`)
+ const critical = (bytes[offset + 4] & 0x20) === 0
+ const type = bytes.toString('latin1', offset + 4, offset + 8)
+ const dataStart = offset + 8
+ const dataEnd = dataStart + length
+ if (dataEnd + 4 > bytes.length)
+ throw malformedPng(`chunk ${type} runs past the end of the image`)
+
+ const declaredCrc = bytes.readUInt32BE(dataEnd)
+ const actualCrc = crc32(bytes.subarray(offset + 4, dataEnd)) >>> 0
+ if (declaredCrc !== actualCrc) throw malformedPng(`chunk ${type} failed its CRC check`)
+
+ const data = bytes.subarray(dataStart, dataEnd)
+ if (type !== 'IDAT' && idat.length > 0) idatClosed = true
+
+ if (type === 'IHDR') {
+ if (header || offset !== PNG_SIGNATURE.length)
+ throw malformedPng('IHDR must be the first and only IHDR chunk')
+ header = readPngHeader(data)
+ } else if (type === 'IDAT') {
+ if (!header) throw malformedPng('IDAT appeared before IHDR')
+ if (idatClosed) throw malformedPng('IDAT chunks must be consecutive')
+ idat.push(data)
+ } else if (type === 'IEND') {
+ if (data.length !== 0) throw malformedPng('IEND must be empty')
+ ended = true
+ } else if (critical) {
+ throw new FixtureImageError(
+ 'image-png-unsupported-form',
+ `unsupported critical chunk ${type}`
+ )
+ }
+
+ offset = dataEnd + 4
+ }
+
+ if (!header) throw malformedPng('missing IHDR')
+ if (!ended) throw malformedPng('missing IEND')
+ if (idat.length === 0) throw malformedPng('missing IDAT')
+
+ const { width, height } = header
+ const stride = width * PNG_BYTES_PER_PIXEL + 1
+ const expectedRawLength = stride * height
+
+ let raw
+ try {
+ raw = inflateSync(Buffer.concat(idat), { maxOutputLength: expectedRawLength })
+ } catch (error) {
+ throw malformedPng(
+ `IDAT did not inflate within the expected bound: ${String(error?.message ?? error)}`
+ )
+ }
+ if (raw.length !== expectedRawLength)
+ throw malformedPng(`inflated IDAT is ${raw.length} bytes, expected ${expectedRawLength}`)
+
+ for (let y = 0; y < height; y += 1) {
+ const filterByte = raw[y * stride]
+ if (filterByte !== 0)
+ throw new FixtureImageError(
+ 'image-png-unsupported-form',
+ `scanline ${y} uses PNG filter ${filterByte}; only filter 0 (None) is supported`
+ )
+ }
+
+ const tileWidth = width / GRID_COLUMNS
+ const tileHeight = height / GRID_ROWS
+ const colors = []
+ for (let row = 0; row < GRID_ROWS; row += 1) {
+ for (let column = 0; column < GRID_COLUMNS; column += 1) {
+ const x = column * tileWidth + Math.floor(tileWidth / 2)
+ const y = row * tileHeight + Math.floor(tileHeight / 2)
+ const start = y * stride + 1 + x * PNG_BYTES_PER_PIXEL
+ const red = raw[start]
+ const green = raw[start + 1]
+ const blue = raw[start + 2]
+ const name = TILE_COLOR_NAMES.get(`${red},${green},${blue}`)
+ if (!name)
+ throw new FixtureImageError(
+ 'image-pixel-not-a-tile-color',
+ `tile ${row * GRID_COLUMNS + column + 1} center is rgb(${red}, ${green}, ${blue}), ` +
+ 'which is not a canonical fixture tile color'
+ )
+ colors.push(name)
+ }
+ }
+
+ return colors
+}
+
+/**
+ * Extract the single canonical PNG data URI from an OpenAI chat message list.
+ *
+ * The fixture requires exactly the canonical form the host serializes
+ * (`data:image/png;base64,<padded standard base64>`). JPEG, URL references,
+ * multiple image parts, and unpadded or non-base64 payloads are refused.
+ */
+function extractPngBytes(messages) {
+ const imageParts = []
+ for (const message of messages) {
+ if (!message || typeof message !== 'object' || !Array.isArray(message.content)) continue
+ for (const part of message.content) {
+ if (part && typeof part === 'object' && part.type === 'image_url') imageParts.push(part)
+ }
+ }
+
+ if (imageParts.length === 0) return null
+ if (imageParts.length > 1)
+ throw new FixtureImageError(
+ 'image-part-count',
+ `exactly one image part is supported, received ${imageParts.length}`
+ )
+
+ const imageUrl = imageParts[0].image_url
+ const url = imageUrl && typeof imageUrl === 'object' ? imageUrl.url : undefined
+ if (typeof url !== 'string')
+ throw new FixtureImageError(
+ 'image-not-png-data-uri',
+ 'image part must carry image_url.url as a string'
+ )
+ if (!url.startsWith(PNG_DATA_URI_PREFIX))
+ throw new FixtureImageError(
+ 'image-not-png-data-uri',
+ `image must be a ${PNG_DATA_URI_PREFIX} data URI`
+ )
+
+ const payload = url.slice(PNG_DATA_URI_PREFIX.length)
+ if (payload.length === 0 || payload.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(payload))
+ throw new FixtureImageError(
+ 'image-not-png-data-uri',
+ 'image data URI payload is not canonical base64'
+ )
+
+ return Buffer.from(payload, 'base64')
+}
+
+const INTERNAL_HOST_SUFFIXES = [
+ '.svc.cluster.local',
+ '.svc',
+ '.cluster.local',
+ '.localhost',
+ '.local',
+]
+
+const INTERNAL_CLUSTER_NAMESPACES = new Set([
+ 'channels',
+ 'control-plane',
+ 'default',
+ 'gfs',
+ 'ingress',
+ 'kube-system',
+ 'llm-hooks',
+ 'mcp-host',
+ 'mcp-server',
+ 'profiles',
+ 'rpc-proxy',
+ 'sandbox-recipes',
+ 'sandbox-ui',
+ 'webhook-ingress',
+])
+
+function isInternalHost(hostname) {
+ const host = String(hostname).toLowerCase().replace(/\.$/, '')
+ if (!host) return false
+ if (host === 'localhost' || host === '::1' || host === '[::1]') return true
+ if (/^127(?:\.\d{1,3}){3}$/.test(host)) return true
+ // A bracketed IPv6 literal carries no dot, so it must be classified here,
+ // before the single-label rule below would accept any public address as
+ // cluster traffic. Only loopback and link-local (fe80::/10) literals are
+ // internal; every other literal is external egress.
+ if (host.startsWith('[') && host.endsWith(']')) {
+ const literal = host.slice(1, -1)
+ if (literal === '::1') return true
+ return /^fe[89ab][0-9a-f]:/.test(literal)
+ }
+ if (INTERNAL_HOST_SUFFIXES.some(suffix => host.endsWith(suffix))) return true
+ if (!host.includes('.')) return true
+ const labels = host.split('.')
+ return labels.length === 2 && INTERNAL_CLUSTER_NAMESPACES.has(labels[1])
+}
+
+function requestUrl(input) {
+ const raw =
+ typeof input === 'string'
+ ? input
+ : input instanceof URL
+ ? input.href
+ : input && typeof input === 'object' && typeof input.url === 'string'
+ ? input.url
+ : null
+ if (typeof raw !== 'string' || raw.length === 0) return null
+ try {
+ return new URL(raw)
+ } catch {
+ return null
+ }
+}
+
+function headerValue(headers, name) {
+ if (!headers) return null
+ if (typeof headers.get === 'function') return headers.get(name)
+ if (Array.isArray(headers)) {
+ for (const entry of headers) {
+ if (Array.isArray(entry) && String(entry[0]).toLowerCase() === name) return entry[1]
+ }
+ return null
+ }
+ if (typeof headers === 'object') {
+ for (const key of Object.keys(headers)) {
+ if (key.toLowerCase() === name) return headers[key]
+ }
+ }
+ return null
+}
+
+/**
+ * Match the request's presented value against the published digest.
+ *
+ * The comparison is constant time over equal-length hex digests, and the
+ * presented value is discarded immediately: only its digest is ever compared,
+ * and only the digest is held. A digest therefore cannot be replayed as a key.
+ */
+function authorize(header, expectedDigest) {
+ if (typeof header !== 'string') return false
+ const match = /^Bearer +(.+)$/i.exec(header.trim())
+ if (!match) return false
+ const received = Buffer.from(createHash('sha256').update(match[1]).digest('hex'))
+ const wanted = Buffer.from(String(expectedDigest).toLowerCase())
+ if (received.length !== wanted.length) return false
+ return timingSafeEqual(received, wanted)
+}
+
+function jsonResponse(body, status = 200) {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'content-type': 'application/json' },
+ })
+}
+
+/** Every refusal is an explicit, non-retryable error response. */
+function fixtureErrorResponse(status, code, message) {
+ return jsonResponse({ error: { message, type: 'fixture_error', param: null, code } }, status)
+}
+
+function completionBody(completionId, model, content) {
+ return {
+ id: completionId,
+ object: 'chat.completion',
+ created: FIXTURE_CREATED,
+ model,
+ choices: [
+ {
+ index: 0,
+ message: { role: 'assistant', content },
+ finish_reason: 'stop',
+ logprobs: null,
+ },
+ ],
+ usage: FIXTURE_USAGE,
+ system_fingerprint: FIXTURE_SYSTEM_FINGERPRINT,
+ }
+}
+
+function streamResponse(completionId, model, content) {
+ const chunk = (delta, finishReason, withUsage) => ({
+ id: completionId,
+ object: 'chat.completion.chunk',
+ created: FIXTURE_CREATED,
+ model,
+ system_fingerprint: FIXTURE_SYSTEM_FINGERPRINT,
+ choices: [{ index: 0, delta, finish_reason: finishReason }],
+ ...(withUsage ? { usage: FIXTURE_USAGE } : {}),
+ })
+ const body =
+ [
+ chunk({ role: 'assistant', content: '' }, null, false),
+ chunk({ content }, null, false),
+ chunk({}, 'stop', true),
+ ]
+ .map(frame => `data: ${JSON.stringify(frame)}\n\n`)
+ .join('') + 'data: [DONE]\n\n'
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+}
+
+/**
+ * Refuse to start unless this process is the isolated, branch-owned fixture.
+ *
+ * The guard covers every binding the fixture depends on: a test node process,
+ * the explicit fixture flag, this journey's run id, a valid Minikube profile
+ * that IS the real-PostgreSQL context, and the published digest of the runner's
+ * ephemeral ZAI key. A missing or malformed digest is a missing binding, never a
+ * placeholder the fixture accepts.
+ */
+export function validateFixtureEnvironment(env) {
+ if (
+ env.NODE_ENV !== 'test' ||
+ env.EVENFIRE_IMAGE_CAPABILITIES_FIXTURE !== '1' ||
+ !/^image-capabilities-[a-f0-9]{12}$/.test(env.IMAGE_CAPABILITIES_RUN_ID ?? '') ||
+ !/^[a-z0-9][a-z0-9-]{0,62}$/.test(env.MINIKUBE_PROFILE ?? '') ||
+ env.MINIKUBE_PROFILE !== env.CONTROL_API_REAL_PG_CONTEXT ||
+ typeof env[FIXTURE_AUTH_ENV_KEY] !== 'string' ||
+ !SHA256_HEX.test(env[FIXTURE_AUTH_ENV_KEY])
+ )
+ throw new Error(
+ 'image-capabilities fixture requires its isolated test environment: ' +
+ 'NODE_ENV must be test, EVENFIRE_IMAGE_CAPABILITIES_FIXTURE must be 1, ' +
+ 'IMAGE_CAPABILITIES_RUN_ID must be image-capabilities-<12 hex>, ' +
+ 'MINIKUBE_PROFILE must equal CONTROL_API_REAL_PG_CONTEXT, and ' +
+ 'IMAGE_CAPABILITIES_CREDENTIAL_SHA256 must be the runner key digest'
+ )
+}
+
+/**
+ * Wrap `delegate` with the synthetic ZAI chat-completions boundary.
+ *
+ * The options object carries the run id, the SHA-256 digest of the runner's own
+ * ephemeral ZAI key (compared against the digest of the request's authorisation
+ * header and never recorded), and an optional evidence sink invoked with a fresh
+ * snapshot after every provider-boundary decision.
+ */
+export function createImageFixtureFetch(
+ delegate,
+ { runId, credentialHash: IMAGE_CAPABILITIES_CREDENTIAL_SHA256, onEvidence } = {}
+) {
+ if (typeof delegate !== 'function')
+ throw new Error('image-capabilities fixture requires a delegate fetch')
+ if (!/^image-capabilities-[a-f0-9]{12}$/.test(runId ?? ''))
+ throw new Error('image-capabilities fixture requires its run id')
+ if (
+ typeof IMAGE_CAPABILITIES_CREDENTIAL_SHA256 !== 'string' ||
+ !SHA256_HEX.test(IMAGE_CAPABILITIES_CREDENTIAL_SHA256)
+ )
+ throw new Error('image-capabilities fixture requires the runner key digest')
+
+ const state = {
+ runId,
+ counters: {
+ totalAttempts: 0,
+ imageAttempts: 0,
+ textAttempts: 0,
+ rejectedAttempts: 0,
+ tileColorResponses: 0,
+ textOnlyResponses: 0,
+ textModelImageRefusals: 0,
+ blockedEgress: 0,
+ imageDecodeFailures: 0,
+ unauthorizedAttempts: 0,
+ },
+ attempts: [],
+ }
+ let sequence = 0
+
+ const snapshot = () => structuredClone(state)
+ const publish = () => {
+ if (onEvidence) onEvidence(snapshot())
+ }
+ /**
+ * One ledger row per provider-boundary attempt. `model` is null when the
+ * request was refused before its body was parsed, and `imageSha256` is null
+ * whenever the attempt carried no usable image.
+ */
+ const recordCall = (model, imageSha256, responseKind) => {
+ state.attempts.push({ model, imageSha256, responseKind })
+ }
+ const refuse = (model, reason, { status = 400, code = reason, imageSha256 = null } = {}) => {
+ state.counters.rejectedAttempts += 1
+ recordCall(model, imageSha256, 'rejected')
+ publish()
+ return fixtureErrorResponse(status, code, reason)
+ }
+ const answer = (model, content, responseKind, { imageSha256 = null, stream = false } = {}) => {
+ sequence += 1
+ const completionId = `${COMPLETION_ID_PREFIX}${runId.slice(-12)}-${sequence}`
+ recordCall(model, imageSha256, responseKind)
+ publish()
+ return stream
+ ? streamResponse(completionId, model, content)
+ : jsonResponse(completionBody(completionId, model, content))
+ }
+
+ const handleProviderRequest = (input, init, target) => {
+ state.counters.totalAttempts += 1
+
+ // The host calls the SDK with a URL string plus init. Any other form (a
+ // Request with a consumable body, or a different method) is refused instead
+ // of being read or forwarded to the real provider.
+ if (typeof input !== 'string')
+ return refuse(null, 'provider-request-form-unsupported', { code: 'unsupported_request_form' })
+ if (target.pathname !== CHAT_COMPLETIONS_PATH || target.search || target.hash)
+ return refuse(null, 'provider-path-not-captured', { code: 'path_not_captured' })
+ if (String(init?.method ?? '').toUpperCase() !== 'POST')
+ return refuse(null, 'provider-method-unsupported', { code: 'method_not_supported' })
+
+ if (
+ !authorize(headerValue(init?.headers, 'authorization'), IMAGE_CAPABILITIES_CREDENTIAL_SHA256)
+ ) {
+ state.counters.unauthorizedAttempts += 1
+ return refuse(null, 'provider-auth-mismatch', { status: 401, code: 'unauthorized' })
+ }
+
+ if (typeof init.body !== 'string')
+ return refuse(null, 'provider-body-unsupported', { code: 'unsupported_body' })
+ if (Buffer.byteLength(init.body) > MAX_REQUEST_BYTES)
+ return refuse(null, 'provider-body-unsupported', { code: 'body_too_large' })
+
+ let body
+ try {
+ body = JSON.parse(init.body)
+ } catch {
+ return refuse(null, 'provider-body-invalid', { code: 'invalid_json' })
+ }
+ if (!body || typeof body !== 'object' || Array.isArray(body))
+ return refuse(null, 'provider-body-invalid', { code: 'invalid_body' })
+ if (typeof body.model !== 'string' || !Array.isArray(body.messages))
+ return refuse(null, 'provider-body-invalid', { code: 'missing_model_or_messages' })
+
+ const model = body.model
+ const stream = body.stream === true
+
+ let imageBytes = null
+ try {
+ imageBytes = extractPngBytes(body.messages)
+ } catch (error) {
+ if (!(error instanceof FixtureImageError)) throw error
+ // An image part was present but unusable, so it is still an image attempt.
+ state.counters.imageAttempts += 1
+ state.counters.imageDecodeFailures += 1
+ return refuse(model, error.code, { code: error.code })
+ }
+
+ if (!imageBytes) {
+ state.counters.textAttempts += 1
+ // No image was delivered. Every accepted model answers with the text
+ // marker so a legitimate text or title request cannot fail here, and no
+ // request without pixels can ever receive a color list.
+ if (model !== UNSUPPORTED_MODEL && model !== SUPPORTED_MODEL)
+ return refuse(model, 'unsupported-model', { code: 'unsupported_model' })
+ state.counters.textOnlyResponses += 1
+ return answer(model, TEXT_ONLY_CONTENT, 'text-only', { stream })
+ }
+
+ state.counters.imageAttempts += 1
+
+ if (model === UNSUPPORTED_MODEL) {
+ // The text-only model must refuse an image on the wire. This is the
+ // fixture-side half of the journey's capability guard.
+ state.counters.textModelImageRefusals += 1
+ return refuse(model, 'text-model-image-incompatible', {
+ code: 'image_not_supported_by_model',
+ })
+ }
+ if (model !== SUPPORTED_MODEL)
+ return refuse(model, 'unsupported-model', { code: 'unsupported_model' })
+
+ let colors
+ try {
+ colors = decodeTileColors(imageBytes)
+ } catch (error) {
+ if (!(error instanceof FixtureImageError)) throw error
+ state.counters.imageDecodeFailures += 1
+ return refuse(model, error.code, { code: error.code })
+ }
+
+ const imageSha256 = createHash('sha256').update(imageBytes).digest('hex')
+ state.counters.tileColorResponses += 1
+ // The list is derived from the decoded pixels and from nothing else: the
+ // prompt, the file name, and the request body never contribute a color.
+ return answer(model, colors.join(', '), 'tile-colors', { imageSha256, stream })
+ }
+
+ return {
+ fetch: async (input, init = {}) => {
+ const target = requestUrl(input)
+ if (!target) return delegate(input, init)
+
+ if (target.origin === PROVIDER_ORIGIN) return handleProviderRequest(input, init, target)
+
+ // Non-HTTP schemes are not egress; let the delegate decide their fate.
+ if (target.protocol !== 'http:' && target.protocol !== 'https:') return delegate(input, init)
+ // Internal cluster traffic is delegated byte-for-byte, including its auth.
+ if (isInternalHost(target.hostname)) return delegate(input, init)
+
+ // Any other external origin would be real egress to a provider this
+ // fixture does not own. Refuse it loudly rather than delegating.
+ state.counters.blockedEgress += 1
+ publish()
+ return fixtureErrorResponse(
+ 403,
+ 'egress_blocked',
+ 'external-egress-blocked: this fixture only reaches the captured provider origin'
+ )
+ },
+ getEvidence: snapshot,
+ }
+}
diff --git a/tests/e2e/fixtures/image-capabilities/provider.test.mjs b/tests/e2e/fixtures/image-capabilities/provider.test.mjs
new file mode 100644
index 000000000..da0934b1a
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/provider.test.mjs
@@ -0,0 +1,699 @@
+/**
+ * E2E_GUARDIAN_IPC_FLOW: fixture test, not a browser journey. These tests drive
+ * the transport fixture directly; there is no page, route, or renderer HTTP
+ * request to await. The user-visible oracle lives in
+ * `desktop-app/test/e2e-playwright/qa-recorder-image-capabilities.spec.ts`.
+ *
+ * Tests for the image-capabilities ZAI chat-completions fixture (issue #654).
+ *
+ * These tests prove the fixture's own contract: that it reads colors from the PNG
+ * pixels rather than from the prompt, that it refuses every shape it does not
+ * understand, that it never delegates an external provider origin, and that the
+ * evidence it publishes stays sanitized. They are not the journey's E2E oracle.
+ */
+import assert from 'node:assert/strict'
+import { createHash, randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+import { crc32, deflateSync } from 'node:zlib'
+import { createImageFixtureFetch, validateFixtureEnvironment } from './provider.mjs'
+
+/**
+ * The runner's own ephemeral ZAI key for this process, generated here so no test
+ * depends on a literal. Only its digest is handed to the fixture, exactly as the
+ * real runner publishes it, and the key itself is never written to evidence.
+ */
+const IMAGE_CAPABILITIES_CREDENTIAL = randomBytes(32).toString('hex')
+const IMAGE_CAPABILITIES_CREDENTIAL_SHA256 = createHash('sha256')
+ .update(IMAGE_CAPABILITIES_CREDENTIAL)
+ .digest('hex')
+
+const FIXTURE_ENV = {
+ NODE_ENV: 'test',
+ EVENFIRE_IMAGE_CAPABILITIES_FIXTURE: '1',
+ IMAGE_CAPABILITIES_RUN_ID: 'image-capabilities-a1b2c3d4e5f6',
+ MINIKUBE_PROFILE: 'owned-image-profile',
+ CONTROL_API_REAL_PG_CONTEXT: 'owned-image-profile',
+ IMAGE_CAPABILITIES_CREDENTIAL_SHA256,
+}
+
+const PROVIDER_URL = 'https://api.z.ai/api/coding/paas/v4/chat/completions'
+const VISUAL_MODEL = 'glm-5.3-flash'
+const TEXT_MODEL = 'glm-5.3'
+const TEXT_ONLY_CONTENT = 'IMAGE_FIXTURE_TEXT_OK'
+
+const TILE_COLUMNS = 2
+const TILE_ROWS = 3
+const TILE_WIDTH = 320
+const TILE_HEIGHT = 240
+
+const helperUrl = new URL(
+ '../../../../desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts',
+ import.meta.url
+)
+
+/**
+ * Read the CANONICAL palette out of the Desktop helper the journey actually uses,
+ * so this suite fails when the fixture's own table drifts from it instead of
+ * quietly agreeing with a duplicated copy.
+ */
+function canonicalPalette() {
+ const source = readFileSync(helperUrl, 'utf8')
+ const table = source.slice(source.indexOf('IMAGE_FIXTURE_RGB'))
+ const entries = []
+ for (const match of table.matchAll(/^\s*(\w+):\s*\[(\d+),\s*(\d+),\s*(\d+)\],/gm))
+ entries.push([match[1], Number(match[2]), Number(match[3]), Number(match[4])])
+ return entries
+}
+
+function pngChunk(type, data, { corruptCrc = false } = {}) {
+ const length = Buffer.alloc(4)
+ length.writeUInt32BE(data.length, 0)
+ const typed = Buffer.concat([Buffer.from(type, 'ascii'), data])
+ const crc = Buffer.alloc(4)
+ crc.writeUInt32BE(corruptCrc ? (crc32(typed) ^ 0xffffffff) >>> 0 : crc32(typed), 0)
+ return Buffer.concat([length, typed, crc])
+}
+
+/**
+ * Dependency-free PNG encoder that mirrors the Desktop helper's shape (8-bit
+ * truecolor, filter 0, no interlace) with switches for the shapes the fixture
+ * must refuse.
+ */
+function encodePng({
+ colors,
+ tileWidth = TILE_WIDTH,
+ tileHeight = TILE_HEIGHT,
+ width: widthOverride,
+ height: heightOverride,
+ colorType = 2,
+ bitDepth = 8,
+ interlace = 0,
+ filterByte = 0,
+ corruptCrc = false,
+ truncateBytes = 0,
+ signature = true,
+} = {}) {
+ const width = widthOverride ?? tileWidth * TILE_COLUMNS
+ const height = heightOverride ?? tileHeight * TILE_ROWS
+ const channels = colorType === 6 ? 4 : 3
+ const sampleBytes = bitDepth === 16 ? 2 : 1
+ const stride = width * channels * sampleBytes + 1
+ const raw = Buffer.alloc(stride * height)
+
+ for (let y = 0; y < height; y += 1) {
+ const rowStart = y * stride
+ raw[rowStart] = filterByte
+ const row = Math.floor(y / tileHeight)
+ for (let x = 0; x < width; x += 1) {
+ const column = Math.floor(x / tileWidth)
+ const [red, green, blue] =
+ colors[Math.min(row, TILE_ROWS - 1) * TILE_COLUMNS + Math.min(column, TILE_COLUMNS - 1)]
+ let offset = rowStart + 1 + x * channels * sampleBytes
+ for (const sample of [red, green, blue]) {
+ if (sampleBytes === 2) {
+ raw[offset] = 0
+ raw[offset + 1] = sample
+ } else raw[offset] = sample
+ offset += sampleBytes
+ }
+ if (channels === 4) for (let i = 0; i < sampleBytes; i += 1) raw[offset + i] = 255
+ }
+ }
+
+ const ihdr = Buffer.alloc(13)
+ ihdr.writeUInt32BE(width, 0)
+ ihdr.writeUInt32BE(height, 4)
+ ihdr[8] = bitDepth
+ ihdr[9] = colorType
+ ihdr[10] = 0
+ ihdr[11] = 0
+ ihdr[12] = interlace
+
+ const body = Buffer.concat([
+ ...(signature ? [Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])] : []),
+ pngChunk('IHDR', ihdr),
+ pngChunk('IDAT', deflateSync(raw, { level: 9 }), { corruptCrc }),
+ pngChunk('IEND', Buffer.alloc(0)),
+ ])
+ return truncateBytes > 0 ? body.subarray(0, body.length - truncateBytes) : body
+}
+
+/** A canonical 2x3 fixture PNG built from the Desktop helper's own RGB values. */
+function palettePng(overrides = {}) {
+ const palette = canonicalPalette()
+ assert.ok(palette.length >= TILE_COLUMNS * TILE_ROWS, 'canonical palette is too small')
+ const picked = palette.slice(0, TILE_COLUMNS * TILE_ROWS)
+ return {
+ names: picked.map(entry => entry[0]),
+ png: encodePng({ colors: picked.map(entry => entry.slice(1)), ...overrides }),
+ }
+}
+
+function harness({ onEvidence } = {}) {
+ const delegated = []
+ const fixture = createImageFixtureFetch(
+ async (input, init) => {
+ delegated.push([input, init])
+ return new Response('delegated', { status: 200 })
+ },
+ {
+ runId: FIXTURE_ENV.IMAGE_CAPABILITIES_RUN_ID,
+ credentialHash: IMAGE_CAPABILITIES_CREDENTIAL_SHA256,
+ onEvidence,
+ }
+ )
+ return { ...fixture, delegated }
+}
+
+function authHeaders() {
+ return { authorization: `Bearer ${IMAGE_CAPABILITIES_CREDENTIAL}` }
+}
+
+function call(fixture, body, { url = PROVIDER_URL, method = 'POST', headers, rawBody } = {}) {
+ return fixture.fetch(url, {
+ method,
+ headers: headers ?? authHeaders(),
+ body: rawBody ?? JSON.stringify(body),
+ })
+}
+
+function chatBody(model, messages, extra = {}) {
+ return { model, messages, ...extra }
+}
+
+function textMessages(text = 'Reply with a short acknowledgement.') {
+ return [{ role: 'user', content: text }]
+}
+
+function imageMessages(png, text = 'Reply with the tile colors in reading order.') {
+ return [
+ {
+ role: 'user',
+ content: [
+ { type: 'text', text },
+ {
+ type: 'image_url',
+ image_url: { url: `data:image/png;base64,${png.toString('base64')}`, detail: 'auto' },
+ },
+ ],
+ },
+ ]
+}
+
+test('validateFixtureEnvironment accepts the isolated binding', () => {
+ validateFixtureEnvironment(FIXTURE_ENV)
+})
+
+test('validateFixtureEnvironment rejects every missing or wrong binding', () => {
+ for (const key of Object.keys(FIXTURE_ENV))
+ assert.throws(() => validateFixtureEnvironment({ ...FIXTURE_ENV, [key]: '' }), key)
+ assert.throws(() => validateFixtureEnvironment({ ...FIXTURE_ENV, NODE_ENV: 'production' }))
+ assert.throws(() =>
+ validateFixtureEnvironment({ ...FIXTURE_ENV, EVENFIRE_IMAGE_CAPABILITIES_FIXTURE: '0' })
+ )
+ assert.throws(() =>
+ validateFixtureEnvironment({ ...FIXTURE_ENV, MINIKUBE_PROFILE: 'not-the-context' })
+ )
+ assert.throws(() =>
+ validateFixtureEnvironment({ ...FIXTURE_ENV, MINIKUBE_PROFILE: 'Bad_Profile' })
+ )
+ assert.throws(() =>
+ validateFixtureEnvironment({
+ ...FIXTURE_ENV,
+ IMAGE_CAPABILITIES_RUN_ID: 'image-capabilities-zzzzzzzzzzzz',
+ })
+ )
+ assert.throws(() =>
+ validateFixtureEnvironment({
+ ...FIXTURE_ENV,
+ IMAGE_CAPABILITIES_RUN_ID: 'approved-tools-a1b2c3d4e5f6',
+ })
+ )
+ // The binding is a digest, so a short value or the key itself is not one.
+ assert.throws(() =>
+ validateFixtureEnvironment({
+ ...FIXTURE_ENV,
+ IMAGE_CAPABILITIES_CREDENTIAL_SHA256: 'a'.repeat(63),
+ })
+ )
+ assert.throws(() =>
+ validateFixtureEnvironment({
+ ...FIXTURE_ENV,
+ IMAGE_CAPABILITIES_CREDENTIAL_SHA256: IMAGE_CAPABILITIES_CREDENTIAL.slice(0, 32),
+ })
+ )
+})
+
+test('the factory refuses to build without a delegate, run id and key digest', () => {
+ const delegate = async () => new Response('delegated')
+ const runId = FIXTURE_ENV.IMAGE_CAPABILITIES_RUN_ID
+ assert.throws(() => createImageFixtureFetch(undefined, { runId }))
+ assert.throws(() =>
+ createImageFixtureFetch(delegate, { credentialHash: IMAGE_CAPABILITIES_CREDENTIAL_SHA256 })
+ )
+ assert.throws(() =>
+ createImageFixtureFetch(delegate, {
+ runId: 'nope',
+ credentialHash: IMAGE_CAPABILITIES_CREDENTIAL_SHA256,
+ })
+ )
+ assert.throws(() => createImageFixtureFetch(delegate, { runId, credentialHash: '' }))
+ assert.throws(() => createImageFixtureFetch(delegate, { runId, credentialHash: 'not-a-digest' }))
+ // A digest is exactly 64 hex characters; a longer value is not one.
+ assert.throws(() =>
+ createImageFixtureFetch(delegate, {
+ runId,
+ credentialHash: `${IMAGE_CAPABILITIES_CREDENTIAL}ff`,
+ })
+ )
+})
+
+test('reads the ordered tile colors from the delivered PNG bytes', async () => {
+ const { names, png } = palettePng()
+ const snapshots = []
+ const h = harness({ onEvidence: snapshot => snapshots.push(snapshot) })
+
+ const response = await call(h, chatBody(VISUAL_MODEL, imageMessages(png)))
+ assert.equal(response.status, 200)
+ const body = await response.json()
+
+ assert.equal(body.object, 'chat.completion')
+ assert.equal(body.model, VISUAL_MODEL)
+ assert.equal(body.id, `chatcmpl-image-fixture-a1b2c3d4e5f6-1`)
+ assert.equal(body.choices.length, 1)
+ assert.equal(body.choices[0].index, 0)
+ assert.equal(body.choices[0].finish_reason, 'stop')
+ assert.equal(body.choices[0].message.role, 'assistant')
+ assert.equal(body.choices[0].message.content, names.join(', '))
+ assert.equal('tool_calls' in body.choices[0].message, false)
+ assert.deepEqual(body.usage, { prompt_tokens: 12, completion_tokens: 8, total_tokens: 20 })
+ assert.equal(h.delegated.length, 0)
+
+ const evidence = h.getEvidence()
+ assert.equal(evidence.runId, FIXTURE_ENV.IMAGE_CAPABILITIES_RUN_ID)
+ assert.equal(evidence.counters.totalAttempts, 1)
+ assert.equal(evidence.counters.imageAttempts, 1)
+ assert.equal(evidence.counters.textAttempts, 0)
+ assert.equal(evidence.counters.rejectedAttempts, 0)
+ assert.equal(evidence.counters.tileColorResponses, 1)
+ assert.equal(evidence.counters.textOnlyResponses, 0)
+ assert.deepEqual(evidence.attempts, [
+ {
+ model: VISUAL_MODEL,
+ imageSha256: createHash('sha256').update(png).digest('hex'),
+ responseKind: 'tile-colors',
+ },
+ ])
+ assert.equal(snapshots.length, 1)
+ assert.equal(snapshots[0].counters.totalAttempts, 1)
+})
+
+test('never answers from the prompt alone, even when the prompt names the colors', async () => {
+ const { names } = palettePng()
+ const h = harness()
+
+ const response = await call(
+ h,
+ chatBody(VISUAL_MODEL, textMessages(`Reply with exactly: ${names.join(', ')}`))
+ )
+ assert.equal(response.status, 200)
+ const body = await response.json()
+
+ assert.equal(body.choices[0].message.content, TEXT_ONLY_CONTENT)
+ assert.equal(body.choices[0].message.content.includes(names[0]), false)
+
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.imageAttempts, 0)
+ assert.equal(evidence.counters.textAttempts, 1)
+ assert.equal(evidence.counters.tileColorResponses, 0)
+ assert.deepEqual(evidence.attempts, [
+ { model: VISUAL_MODEL, imageSha256: null, responseKind: 'text-only' },
+ ])
+})
+
+test('image removed: no color list and no image attempt is recorded', async () => {
+ const { names, png } = palettePng()
+ const h = harness()
+
+ // The exact same request as the success case, with only the image part removed.
+ const [textPart] = imageMessages(png)[0].content
+ const response = await call(h, chatBody(VISUAL_MODEL, [{ role: 'user', content: [textPart] }]))
+ assert.equal(response.status, 200)
+ const body = await response.json()
+
+ assert.equal(body.choices[0].message.content, TEXT_ONLY_CONTENT)
+ assert.notEqual(body.choices[0].message.content, names.join(', '))
+
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.imageAttempts, 0)
+ assert.equal(evidence.counters.tileColorResponses, 0)
+ assert.equal(evidence.attempts.length, 1)
+ assert.equal(evidence.attempts[0].imageSha256, null)
+ assert.equal(evidence.attempts[0].responseKind, 'text-only')
+})
+
+test('a text-only request answers with the marker for both accepted models', async () => {
+ for (const model of [TEXT_MODEL, VISUAL_MODEL]) {
+ const h = harness()
+ const response = await call(h, chatBody(model, textMessages()))
+ assert.equal(response.status, 200, model)
+ const body = await response.json()
+ assert.equal(body.choices[0].message.content, TEXT_ONLY_CONTENT, model)
+ assert.equal(body.choices[0].finish_reason, 'stop', model)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.textOnlyResponses, 1, model)
+ assert.equal(evidence.counters.tileColorResponses, 0, model)
+ }
+})
+
+test('the text-only model refuses an image and records the incompatible attempt', async () => {
+ const { png } = palettePng()
+ const h = harness()
+
+ const response = await call(h, chatBody(TEXT_MODEL, imageMessages(png)))
+ assert.equal(response.status, 400)
+ const body = await response.json()
+ assert.equal(body.error.type, 'fixture_error')
+ assert.equal(body.error.code, 'image_not_supported_by_model')
+
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.textModelImageRefusals, 1)
+ assert.equal(evidence.counters.imageAttempts, 1)
+ assert.equal(evidence.counters.rejectedAttempts, 1)
+ assert.equal(evidence.counters.tileColorResponses, 0)
+ assert.deepEqual(evidence.attempts, [
+ { model: TEXT_MODEL, imageSha256: null, responseKind: 'rejected' },
+ ])
+})
+
+test('an unsupported model is refused in both payload shapes', async () => {
+ const { png } = palettePng()
+ for (const messages of [textMessages(), imageMessages(png)]) {
+ const h = harness()
+ const response = await call(h, chatBody('glm-5.2', messages))
+ assert.equal(response.status, 400)
+ assert.equal((await response.json()).error.code, 'unsupported_model')
+ assert.equal(h.getEvidence().counters.rejectedAttempts, 1)
+ assert.equal(h.getEvidence().counters.tileColorResponses, 0)
+ }
+})
+
+test('more than one image part is refused', async () => {
+ const { png } = palettePng()
+ const h = harness()
+ const messages = imageMessages(png)
+ messages[0].content.push(messages[0].content[1])
+
+ const response = await call(h, chatBody(VISUAL_MODEL, messages))
+ assert.equal(response.status, 400)
+ assert.equal((await response.json()).error.code, 'image-part-count')
+ assert.equal(h.getEvidence().counters.imageAttempts, 1)
+})
+
+test('refuses image payloads that are not the canonical PNG data URI', async () => {
+ const { png } = palettePng()
+ const base64 = png.toString('base64')
+ const cases = [
+ ['jpeg data uri', `data:image/jpeg;base64,${base64}`],
+ ['unpadded base64', `data:image/png;base64,${base64.replace(/=+$/, '')}`],
+ ['non-base64 payload', 'data:image/png;base64,not*base64!'],
+ ['remote reference', 'https://example.test/visual-input.png'],
+ ['empty payload', 'data:image/png;base64,'],
+ ]
+
+ for (const [label, url] of cases) {
+ const h = harness()
+ const response = await call(
+ h,
+ chatBody(VISUAL_MODEL, [
+ { role: 'user', content: [{ type: 'image_url', image_url: { url } }] },
+ ])
+ )
+ assert.equal(response.status, 400, label)
+ assert.equal((await response.json()).error.code, 'image-not-png-data-uri', label)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.imageAttempts, 1, label)
+ assert.equal(evidence.counters.imageDecodeFailures, 1, label)
+ }
+})
+
+test('reads a proportionally downscaled grid, not just the exact helper size', async () => {
+ const palette = canonicalPalette().slice(0, TILE_COLUMNS * TILE_ROWS)
+ const png = encodePng({
+ colors: palette.map(entry => entry.slice(1)),
+ tileWidth: 8,
+ tileHeight: 9,
+ })
+ const h = harness()
+
+ const response = await call(h, chatBody(VISUAL_MODEL, imageMessages(png)))
+ assert.equal(response.status, 200)
+ const body = await response.json()
+ assert.equal(body.choices[0].message.content, palette.map(entry => entry[0]).join(', '))
+})
+
+test('refuses every PNG shape it cannot read pixel-exactly', async () => {
+ const cases = [
+ ['colour type 6', { colorType: 6 }, 'image-png-unsupported-form'],
+ ['bit depth 16', { bitDepth: 16 }, 'image-png-unsupported-form'],
+ ['interlaced', { interlace: 1 }, 'image-png-unsupported-form'],
+ ['non-zero scanline filter', { filterByte: 1 }, 'image-png-unsupported-form'],
+ ['corrupt chunk crc', { corruptCrc: true }, 'image-png-malformed'],
+ ['truncated image', { truncateBytes: 8 }, 'image-png-malformed'],
+ ['missing signature', { signature: false }, 'image-png-malformed'],
+ ['grid that does not divide', { width: 641 }, 'image-tile-grid-mismatch'],
+ ]
+
+ for (const [label, overrides, code] of cases) {
+ const { png } = palettePng(overrides)
+ const h = harness()
+ const response = await call(h, chatBody(VISUAL_MODEL, imageMessages(png)))
+ assert.equal(response.status, 400, label)
+ assert.equal((await response.json()).error.code, code, label)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.imageAttempts, 1, label)
+ assert.equal(evidence.counters.imageDecodeFailures, 1, label)
+ assert.equal(evidence.counters.tileColorResponses, 0, label)
+ assert.equal(evidence.attempts[0].responseKind, 'rejected', label)
+ }
+})
+
+test('refuses provider requests it will not read or forward', async () => {
+ const { png } = palettePng()
+ const validBody = JSON.stringify(chatBody(VISUAL_MODEL, imageMessages(png)))
+ const cases = [
+ ['GET method', { method: 'GET', body: validBody }, 'method_not_supported'],
+ [
+ 'query string',
+ { method: 'POST', body: validBody, url: `${PROVIDER_URL}?x=1` },
+ 'path_not_captured',
+ ],
+ [
+ 'wrong provider path',
+ { method: 'POST', body: validBody, url: 'https://api.z.ai/api/coding/paas/v4/models' },
+ 'path_not_captured',
+ ],
+ ['buffer body', { method: 'POST', body: Buffer.from(validBody) }, 'unsupported_body'],
+ ['oversized body', { method: 'POST', body: 'x'.repeat(8 * 1024 * 1024 + 1) }, 'body_too_large'],
+ ['invalid json', { method: 'POST', body: '{' }, 'invalid_json'],
+ [
+ 'missing model and messages',
+ { method: 'POST', body: JSON.stringify({ messages: [] }) },
+ 'missing_model_or_messages',
+ ],
+ ]
+
+ for (const [label, { method, body, url = PROVIDER_URL }, code] of cases) {
+ const h = harness()
+ const response = await h.fetch(url, { method, headers: authHeaders(), body })
+ assert.equal(response.status, 400, label)
+ assert.equal((await response.json()).error.code, code, label)
+ assert.equal(h.delegated.length, 0, label)
+ assert.equal(h.getEvidence().counters.rejectedAttempts, 1, label)
+ assert.equal(h.getEvidence().counters.totalAttempts, 1, label)
+ }
+
+ const h = harness()
+ const requestForm = await h.fetch(new Request(PROVIDER_URL, { method: 'POST', body: validBody }))
+ assert.equal(requestForm.status, 400)
+ assert.equal((await requestForm.json()).error.code, 'unsupported_request_form')
+ assert.equal(h.delegated.length, 0)
+})
+
+test('refuses every external origin it does not own and never delegates', async () => {
+ const h = harness()
+ const externals = [
+ 'https://api.openai.com/v1/chat/completions',
+ 'https://api.anthropic.com/v1/messages',
+ 'https://api.deepseek.com/chat/completions',
+ 'https://openrouter.ai/api/v1/chat/completions',
+ 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
+ 'https://example.test/anything',
+ ]
+
+ for (const url of externals) {
+ const response = await h.fetch(url, { method: 'POST', headers: authHeaders(), body: '{}' })
+ assert.equal(response.status, 403, url)
+ assert.equal((await response.json()).error.code, 'egress_blocked', url)
+ }
+
+ assert.equal(h.delegated.length, 0)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.blockedEgress, externals.length)
+ // A refused origin is not a provider attempt, so it adds no ledger row.
+ assert.equal(evidence.counters.totalAttempts, 0)
+ assert.deepEqual(evidence.attempts, [])
+})
+
+test('delegates internal routes untouched, including their auth', async () => {
+ const h = harness()
+ const internalAuth = `Bearer ${randomBytes(16).toString('hex')}`
+ const internals = [
+ 'http://control-api.control-plane.svc.cluster.local:8080/healthz',
+ 'http://chatllm.mcp-host:8080/v1/rpc',
+ 'http://agent2.mcp-host.svc:8080/status',
+ 'http://hcc.gfs:8080/ready',
+ 'http://127.0.0.1:3001/tools',
+ 'http://localhost:9000/metrics',
+ ]
+
+ for (const url of internals) {
+ const init = { method: 'POST', headers: { authorization: internalAuth }, body: '{"x":1}' }
+ const response = await h.fetch(url, init)
+ assert.equal(response.status, 200, url)
+ assert.equal(await response.text(), 'delegated', url)
+ const [input, passedInit] = h.delegated.at(-1)
+ assert.equal(input, url, url)
+ // Identical reference: nothing was cloned, rewritten or re-signed.
+ assert.equal(passedInit, init, url)
+ }
+
+ assert.equal(h.delegated.length, internals.length)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.totalAttempts, 0)
+ assert.equal(evidence.counters.blockedEgress, 0)
+ assert.deepEqual(evidence.attempts, [])
+})
+
+test('classifies bracketed IPv6 literals before the single-label internal rule', async () => {
+ const h = harness()
+ const internals = [
+ 'http://[::1]:8080/healthz',
+ 'http://[fe80::1]:8080/healthz',
+ 'http://localhost:8080/healthz',
+ 'http://127.0.0.1:8080/healthz',
+ 'http://chatllm:8080/healthz',
+ ]
+ const externals = ['https://[2606:4700::1111]/cdn-cgi/trace', 'https://example.com/anything']
+
+ for (const url of internals) {
+ const response = await h.fetch(url, { method: 'GET' })
+ assert.equal(response.status, 200, url)
+ assert.equal(await response.text(), 'delegated', url)
+ }
+
+ for (const url of externals) {
+ const response = await h.fetch(url, { method: 'GET' })
+ assert.equal(response.status, 403, url)
+ assert.equal((await response.json()).error.code, 'egress_blocked', url)
+ }
+
+ assert.equal(h.delegated.length, internals.length)
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.blockedEgress, externals.length)
+ assert.equal(evidence.counters.totalAttempts, 0)
+})
+
+test('streams SSE when the client asks for a stream', async () => {
+ const { names, png } = palettePng()
+ const h = harness()
+
+ const response = await call(h, chatBody(VISUAL_MODEL, imageMessages(png), { stream: true }))
+ assert.equal(response.status, 200)
+ assert.equal(response.headers.get('content-type'), 'text/event-stream')
+
+ const text = await response.text()
+ assert.match(text, /^data: /)
+ assert.match(text, /data: \[DONE\]\n\n$/)
+
+ const frames = text
+ .split('\n\n')
+ .filter(frame => frame.startsWith('data: ') && !frame.includes('[DONE]'))
+ .map(frame => JSON.parse(frame.slice('data: '.length)))
+
+ assert.equal(frames.length, 3)
+ for (const frame of frames) {
+ assert.equal(frame.object, 'chat.completion.chunk')
+ assert.equal(frame.model, VISUAL_MODEL)
+ assert.equal(frame.id, 'chatcmpl-image-fixture-a1b2c3d4e5f6-1')
+ assert.equal('tool_calls' in frame.choices[0].delta, false)
+ assert.equal(frame.choices[0].index, 0)
+ }
+ assert.equal(frames[0].choices[0].delta.role, 'assistant')
+ assert.equal(frames[1].choices[0].delta.content, names.join(', '))
+ assert.equal(frames[2].choices[0].finish_reason, 'stop')
+ assert.deepEqual(frames[2].usage, { prompt_tokens: 12, completion_tokens: 8, total_tokens: 20 })
+
+ assert.equal(h.getEvidence().counters.tileColorResponses, 1)
+ assert.equal(h.getEvidence().attempts[0].responseKind, 'tile-colors')
+})
+
+test('authenticates on the key digest and never records the key', async () => {
+ const h = harness()
+ const body = JSON.stringify(chatBody(VISUAL_MODEL, textMessages()))
+
+ assert.equal((await call(h, chatBody(VISUAL_MODEL, textMessages()))).status, 200)
+
+ const refused = [
+ ['no header', {}],
+ ['wrong scheme', { authorization: `Basic ${IMAGE_CAPABILITIES_CREDENTIAL}` }],
+ ['scheme only', { authorization: 'Bearer' }],
+ ['wrong key', { authorization: `Bearer ${IMAGE_CAPABILITIES_CREDENTIAL.slice(0, 62)}` }],
+ ['digest replayed as key', { authorization: `Bearer ${IMAGE_CAPABILITIES_CREDENTIAL_SHA256}` }],
+ ]
+ for (const [label, headers] of refused) {
+ const response = await h.fetch(PROVIDER_URL, { method: 'POST', headers, body })
+ assert.equal(response.status, 401, label)
+ assert.equal((await response.json()).error.code, 'unauthorized', label)
+ }
+
+ const evidence = h.getEvidence()
+ assert.equal(evidence.counters.unauthorizedAttempts, refused.length)
+ assert.equal(evidence.counters.totalAttempts, refused.length + 1)
+ assert.equal(evidence.counters.textOnlyResponses, 1)
+ // The accepted call is recorded first; every later refusal happened before the
+ // body was parsed, so it carries no model.
+ assert.deepEqual(
+ evidence.attempts.map(attempt => attempt.model),
+ [VISUAL_MODEL, null, null, null, null, null]
+ )
+
+ const serialized = JSON.stringify(evidence)
+ assert.equal(serialized.includes(IMAGE_CAPABILITIES_CREDENTIAL), false)
+ assert.equal(serialized.includes('authorization'), false)
+ assert.equal(serialized.includes('Bearer'), false)
+})
+
+test('getEvidence returns a private copy and onEvidence publishes snapshots', async () => {
+ const snapshots = []
+ const h = harness({ onEvidence: snapshot => snapshots.push(snapshot) })
+
+ await call(h, chatBody(VISUAL_MODEL, textMessages()))
+ await call(h, chatBody(TEXT_MODEL, textMessages()))
+
+ assert.equal(snapshots.length, 2)
+ assert.equal(snapshots[0].counters.totalAttempts, 1)
+ assert.equal(snapshots[1].counters.totalAttempts, 2)
+ assert.equal(snapshots[0].attempts.length, 1)
+ assert.notEqual(snapshots[0], snapshots[1])
+
+ const first = h.getEvidence()
+ first.counters.totalAttempts = 999
+ first.attempts.length = 0
+
+ const second = h.getEvidence()
+ assert.equal(second.counters.totalAttempts, 2)
+ assert.equal(second.attempts.length, 2)
+ assert.notEqual(h.getEvidence(), h.getEvidence())
+})
diff --git a/tests/e2e/fixtures/image-capabilities/sdk.test.mjs b/tests/e2e/fixtures/image-capabilities/sdk.test.mjs
new file mode 100644
index 000000000..715ee7047
--- /dev/null
+++ b/tests/e2e/fixtures/image-capabilities/sdk.test.mjs
@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict'
+import { createHash, randomBytes } from 'node:crypto'
+import { createRequire } from 'node:module'
+import test from 'node:test'
+import { buildImageFixture } from '../../../../desktop-app/test/e2e-playwright/helpers/qaRecorderImageFixture.ts'
+import { createImageFixtureFetch } from './provider.mjs'
+
+// Uses the real compiled provider and pinned SDK. No outbound request is allowed.
+test('the production ZAI serializer and pinned SDK reach the pixel fixture', async () => {
+ const IMAGE_CAPABILITIES_CREDENTIAL = randomBytes(32).toString('hex')
+ const fixture = createImageFixtureFetch(
+ async () => {
+ throw new Error('Unexpected network call')
+ },
+ {
+ runId: 'image-capabilities-123456abcdef',
+ credentialHash: createHash('sha256').update(IMAGE_CAPABILITIES_CREDENTIAL).digest('hex'),
+ }
+ )
+ globalThis.fetch = fixture.fetch
+ const require = createRequire(new URL('../../../../mcp-host/package.json', import.meta.url))
+ require('openai/shims/web')
+ const { OpenAICompatibleProvider } = require('./dist/llm/openaiCompatible.js')
+ const provider = new OpenAICompatibleProvider(
+ {
+ id: 'zai',
+ baseURL: 'https://api.z.ai/api/coding/paas/v4',
+ defaultModel: 'glm-5.3-flash',
+ },
+ IMAGE_CAPABILITIES_CREDENTIAL,
+ 'glm-5.3-flash'
+ )
+ const image = buildImageFixture(654)
+ const result = await provider.completeSingleTurnWithTools(
+ [
+ {
+ role: 'user',
+ content: 'Read the six tiles',
+ contentParts: [
+ { type: 'text', text: 'Read the six tiles' },
+ { type: 'image', mimeType: 'image/png', data: image.png.toString('base64') },
+ ],
+ },
+ ],
+ []
+ )
+ assert.equal(result.content, image.orderedColors.join(', '))
+ assert.deepEqual(fixture.getEvidence().attempts, [
+ {
+ model: 'glm-5.3-flash',
+ responseKind: 'tile-colors',
+ imageSha256: createHash('sha256').update(image.png).digest('hex'),
+ },
+ ])
+})
diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.json
index 294dde8e7..a2488f81a 100644
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.81",
+ "version": "1.0.84",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.81",
+ "version": "1.0.84",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.json
index 2e65862dc..449353a44 100644
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@ -1,6 +1,6 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.81",
+ "version": "1.0.84",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",