dsh-tool-vision 0.8.0 → 0.9.0

package/index.js

@@ -19,9 +19,20 @@
  *      event at a time, on the first pre-step of the session.
  *
  *    The bridged hint points at an exported local copy of the image, which
- *    the agent hands to `inspect_image`. Models listed in
- *    `multimodalModels` (or whose resolved `inputModalities` include
- *    "image") receive image blocks directly and are never bridged.
+ *    the agent hands to `inspect_image`. Which models skip the bridge
+ *    (v0.9.0) is decided by two independent inputs:
+ *
+ *    - `multimodalModels` — a user-owned list whose meaning is set by
+ *      `multimodalListMode`: `whitelist` (listed models receive image blocks
+ *      directly; the historical meaning and the default), `blacklist`
+ *      (listed models are forced through the bridge), or `off` (list
+ *      ignored). Entries match the full model id, its bare id after the last
+ *      `/`, or `provider/id`, and may contain `*` / `?` globs.
+ *    - `autoDetectMultimodal` — when on, the route's own declared
+ *      `inputModalities` forms the base set that the list then adds to
+ *      (whitelist) or subtracts from (blacklist). The declaration is always
+ *      read from the *unwrapped* `resolveModelInfo`, because the admission
+ *      wrap below rewrites it for every model.
  *
  * 3. Bridge image preview (v0.4.0, contributed by xing666173 from
  *    dsh-bridge-preview, MIT © 2026 xing666173) — the browser half renders
@@ -43,6 +54,7 @@ import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { registerVisionTools, CONTENT_FILTER_RE } from "./lib/vision-tools.js";
 import { sessionHeaders } from "./lib/session-header.js";
+import { probeModelCapability, PROBE_MAX_TOKENS, PROBE_TIMEOUT_MS } from "./lib/model-probe.js";
 
 /** Cordis plugin name. */
 const name = "tool-vision";
@@ -60,6 +72,16 @@ const BRIDGE_MARKER = "\u200b[bridge]";
 
 /** Loopback route serving bridged images to the same-origin page. */
 const BRIDGE_PREVIEW_ROUTE = "/plugins/dsh-tool-vision/image";
+/**
+ * Loopback JSON route the settings panel reads the configured model catalog
+ * from (autocomplete for `multimodalModels` and the current-route readout).
+ * Registered on the plugin's own fiber, so it stays up while the master
+ * switch is off — a section you cannot configure until you switch it on would
+ * be useless.
+ */
+const MODEL_CATALOG_ROUTE = "/plugins/dsh-tool-vision/models";
+/** Per-provider cap on catalog entries returned to the panel. */
+const MODEL_CATALOG_MAX_PER_PROVIDER = 500;
 /** Hard cap for a single served image (defense in depth; export is bounded). */
 const BRIDGE_PREVIEW_MAX_BYTES = 20 * 1024 * 1024;
 /** Extensions the preview route serves (svg/ico intentionally excluded). */
@@ -78,7 +100,7 @@ const DEFAULT_DESCRIPTION =
   "Provide the path to a local image file (absolute, or relative to the current workspace) or an http(s) URL, " +
   "optionally with a specific question. Returns the vision model's textual description or answer. " +
   "Use this whenever you need to read, describe, or extract information from image content, " +
-  "since the main model is text-only.";
+  "including an image that reached you as a bridged text hint.";
 
 /** Runtime schema for the tool-vision row. */
 const Config = z.object({
@@ -111,8 +133,63 @@ const Config = z.object({
   bridgeTextOnly: z.boolean().default(true),
   /** Export directory for bridged images; empty = system temp. */
   bridgeExportDir: z.string().default(""),
-  /** Model ids that receive image blocks directly (never bridged). */
+  /**
+   * Model ids the list below refers to (v0.9.0). Each entry is matched
+   * case-insensitively against the full model id (`xiaomi/mimo-v2.5`), its
+   * bare id after the last `/` (`mimo-v2.5`), and `provider/id`
+   * (`commandcode/xiaomi/mimo-v2.5`), and may use `*` / `?` globs
+   * (`*vl*`, `deepseek/*`). A bare id therefore keeps working however the
+   * route happens to spell it.
+   */
   multimodalModels: z.array(z.string()).default([]),
+  /**
+   * How `multimodalModels` is read (v0.9.0):
+   *
+   *  - `whitelist` (default): a listed model receives image blocks directly
+   *    and is never bridged — the meaning the list always had, so an
+   *    existing configuration keeps behaving exactly as before.
+   *  - `blacklist`: a listed model is forced through the bridge even when its
+   *    route declares image input. This is the correction layer for a model
+   *    that claims image support its endpoint does not really have.
+   *  - `off`: the list is ignored entirely; nothing is forced either way.
+   *
+   * An unknown value falls back to `whitelist`.
+   */
+  multimodalListMode: z.string().default("whitelist"),
+  /**
+   * Let the current route's own declared `inputModalities` drive the bridge
+   * decision, so only the models that cannot see images get bridged (v0.9.0,
+   * **on by default**). This and `multimodalModels` are one decision, not two:
+   * the declaration forms the base set, and the list unions with it
+   * (whitelist) or subtracts from it (blacklist).
+   *
+   * The declaration is only whatever the profile — or the installed catalog —
+   * says, and it CAN be wrong: profiles sometimes declare
+   * `input: [text, image]` just to pass the host admission gate, and a wrong
+   * "yes" sends the image straight to an endpoint that may reject it. The
+   * harness's own text-model projection is disabled by `bridgeAutoImage`, so
+   * nothing underneath catches that. Two things bound the damage: the first
+   * promotion of a route logs a notice naming the escape hatch
+   * ({@link warnAutoPromotion}), and naming that route in `multimodalModels`
+   * under `blacklist` mode forces the bridge back on. Set this to false to
+   * bridge everything the list does not name.
+   *
+   * The value is always read from the *unwrapped* `resolveModelInfo`, so the
+   * admission wrap can never feed its own claim back in as evidence.
+   */
+  autoDetectMultimodal: z.boolean().default(true),
+  /**
+   * Measured image capability per route (v0.9.0), keyed `"provider/model"` with
+   * the value `"yes"` or `"no"`. Written by the `vision_probe_model` tool,
+   * never by hand — the only entry in this schema that records what a route
+   * DOES rather than what it says.
+   *
+   * It outranks the route's own declaration, because a probe is a real request
+   * and a declaration is only a claim. It does NOT outrank `multimodalModels`:
+   * that list is explicit human intent, and a person who names a model
+   * deserves the last word over an automated measurement.
+   */
+  probeResults: z.dict(z.string()).default({}),
   /** Inline preview for bridged images: thumbnail above the hint text in the user bubble (click to zoom). */
   bridgePreview: z.boolean().default(true),
   /** Fallback scan interval for the preview scanner in ms; 0 disables the periodic fallback. */
@@ -288,7 +365,10 @@ function installAutoImageAdmission(llm, logger) {
     return { ...info, inputModalities: [...(mods ?? []), "image"] };
   };
   let installed = false;
-  llm[LLM_RESOLVE_WRAP_MARK] = true;
+  // The marker carries BOTH functions: the wrapped one proves ownership for
+  // dispose, and `original` is the only honest source of a route's real
+  // modalities once the wrap is in place (`unwrappedResolveModelInfo`).
+  llm[LLM_RESOLVE_WRAP_MARK] = { original, wrapped };
   llm.resolveModelInfo = wrapped;
   installed = true;
   logger?.debug?.("[tool-vision] automatic image admission installed (resolveModelInfo wrapped)");
@@ -372,22 +452,379 @@ function registerBridgePreviewRoute(ctx, exportDir, logger) {
   }), "dsh-tool-vision: bridge preview route");
 }
 
+/**
+ * Register the loopback JSON route the settings panel reads:
+ *
+ *   { current: {provider, model, direct, source, mode}, providers: [...] }
+ *
+ * `providers` comes from `llm.listProviders()` + `llm.listModels(provider)` —
+ * the routes the harness actually has configured, which is exactly the set a
+ * `multimodalModels` entry may name. `listModels` is a different seam from
+ * `resolveModelInfo`, so these declared modalities are the profile's own and
+ * are NOT contaminated by the admission wrap (a model the wrap advertises as
+ * image-capable still reports its real declaration here).
+ *
+ * Same confinement as the image route: loopback Host only, read-only,
+ * `no-store`, and no credentials or endpoints in the payload — provider ids,
+ * model ids/names and one boolean each.
+ */
+function registerModelCatalogRoute(ctx, logger, getConfig) {
+  const webServer = ctx.get("webServer");
+  if (webServer === undefined) {
+    logger?.warn?.("[tool-vision] webServer unavailable; model catalog route not registered");
+    return;
+  }
+  ctx.effect(() => webServer.register({
+    kind: "exact",
+    path: MODEL_CATALOG_ROUTE,
+    async handler(req, res) {
+      const send = (status, payload) => {
+        res.writeHead(status, {
+          "Content-Type": "application/json; charset=utf-8",
+          "Cache-Control": "no-store",
+        });
+        res.end(JSON.stringify(payload));
+      };
+      const host = String(req.headers?.host ?? "");
+      if (host !== "" && !/^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/.test(host)) {
+        send(403, { error: "forbidden" });
+        return;
+      }
+      const llm = ctx.get("llm");
+      if (llm === undefined) {
+        send(503, { error: "llm service unavailable" });
+        return;
+      }
+      // `listed` is computed HERE, with the same matcher the bridge itself
+      // uses, so the panel never reimplements the rule (and can never
+      // disagree with the decision it is describing).
+      const cfg = typeof getConfig === "function" ? getConfig() : undefined;
+      const list = Array.isArray(cfg?.multimodalModels) ? cfg.multimodalModels : [];
+      const listMode = normalizeListMode(cfg?.multimodalListMode);
+      let routes = [];
+      try {
+        routes = llm.listProviders() ?? [];
+      } catch (error) {
+        logger?.debug?.(`[tool-vision] listProviders failed: ${String(error)}`);
+      }
+      const providers = [];
+      for (const entry of routes) {
+        const id = entry?.id;
+        if (typeof id !== "string" || id.length === 0) continue;
+        const record = {
+          id,
+          name: typeof entry?.name === "string" && entry.name.length > 0 ? entry.name : id,
+          models: [],
+        };
+        try {
+          const models = await llm.listModels(id);
+          record.models = (models ?? []).slice(0, MODEL_CATALOG_MAX_PER_PROVIDER).map((model) => {
+            const modelId = String(model.id);
+            const matchedEntries = modelListMatchEntries(list, id, modelId);
+            return {
+              id: modelId,
+              name: typeof model.name === "string" && model.name.length > 0 ? model.name : modelId,
+              image: Array.isArray(model.inputModalities) && model.inputModalities.includes("image"),
+              listed: matchedEntries.length > 0,
+              matchedEntries,
+              // What the route was MEASURED doing, when anyone has probed it.
+              // `null` means "not probed", which the panel must render
+              // differently from a probe that came back negative.
+              probe: probeVerdict(cfg, id, modelId) ?? null,
+            };
+          });
+        } catch (error) {
+          // One broken route must never blank the whole panel: report it and
+          // keep going, so the other providers still list.
+          record.error = String(error?.message ?? error);
+        }
+        providers.push(record);
+      }
+      send(200, {
+        current: { ...lastModelDecision },
+        list,
+        listMode,
+        probeResults: typeof getConfig === "function" ? { ...(getConfig()?.probeResults ?? {}) } : {},
+        providers,
+      });
+    },
+  }), "dsh-tool-vision: model catalog route");
+}
+
+/** Accepted `multimodalListMode` values; anything else falls back to whitelist. */
+const MULTIMODAL_LIST_MODES = ["off", "whitelist", "blacklist"];
+const DEFAULT_MULTIMODAL_LIST_MODE = "whitelist";
+
+/**
+ * Normalize a configured list mode. The settings section only ever writes one
+ * of {@link MULTIMODAL_LIST_MODES}, but the value can also arrive from a
+ * hand-edited `settings.yaml`, so an unknown string is clamped rather than
+ * treated as "no mode" (which would silently bridge everything).
+ */
+function normalizeListMode(value) {
+  return MULTIMODAL_LIST_MODES.includes(value) ? value : DEFAULT_MULTIMODAL_LIST_MODE;
+}
+
+const listEntryCache = new Map();
+/**
+ * Compile one list entry into an anchored, case-insensitive regexp. A literal
+ * entry is just an exact match; `*` and `?` are the only metacharacters, so a
+ * model id containing `.` or `+` still matches itself.
+ */
+function listEntryRegExp(entry) {
+  const cached = listEntryCache.get(entry);
+  if (cached !== undefined) return cached;
+  const source = entry
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  const compiled = new RegExp(`^${source}$`, "i");
+  listEntryCache.set(entry, compiled);
+  return compiled;
+}
+
+/**
+ * Whether any entry in `patterns` names this route. Each entry is tested
+ * against the full model id, its bare id after the last `/`, and
+ * `provider/id` — so `mimo-v2.5`, `xiaomi/mimo-v2.5` and
+ * `commandcode/xiaomi/mimo-v2.5` all address the same route, and `*vl*`
+ * addresses every variant of one family. Exported for unit testing.
+ */
+function modelListMatches(patterns, provider, model) {
+  return modelListMatchEntries(patterns, provider, model).length > 0;
+}
+
+/**
+ * The list entries that address this route. The panel needs *which* entry hit
+ * so that unchecking a model removes exactly the entry responsible — matching
+ * `mimo-v2.5` against `xiaomi/mimo-v2.5` must not leave an orphan behind, and
+ * must not delete an unrelated entry either. Exported for unit testing.
+ */
+function modelListMatchEntries(patterns, provider, model) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return [];
+  if (typeof model !== "string" || model.length === 0) return [];
+  const slash = model.lastIndexOf("/");
+  const candidates = [model, slash === -1 ? model : model.slice(slash + 1)];
+  if (typeof provider === "string" && provider.length > 0) candidates.push(`${provider}/${model}`);
+  const hits = [];
+  for (const raw of patterns) {
+    if (raw === undefined || raw === null) continue;
+    const entry = String(raw).trim();
+    if (entry.length === 0) continue;
+    const re = listEntryRegExp(entry);
+    if (candidates.some((candidate) => re.test(candidate))) hits.push(String(raw));
+  }
+  return hits;
+}
+
+/**
+ * The route the session is on: the logged request header first, then the
+ * agent's own options. `provider` is optional (older logs may lack it).
+ */
+function currentRoute(agent) {
+  const header = agent?.session?.requestHeader?.();
+  return {
+    provider: header?.config?.provider ?? agent?.options?.provider,
+    model: header?.config?.model ?? agent?.options?.model,
+  };
+}
+
+/**
+ * The last decision `currentModelAcceptsImage` made, for the settings panel's
+ * "current route" readout (served over {@link MODEL_CATALOG_ROUTE}). A plain
+ * mutable record — the panel only ever reads it.
+ */
+const lastModelDecision = {
+  provider: undefined,
+  model: undefined,
+  direct: false,
+  source: "none",
+  mode: DEFAULT_MULTIMODAL_LIST_MODE,
+};
+
+/**
+ * `resolveModelInfo` as it was before {@link installAutoImageAdmission}
+ * wrapped it. Auto-detection MUST read through this: the wrap reports image
+ * support for *every* model, so reading the wrapped method would make the
+ * plugin's own claim the evidence for itself.
+ */
+function unwrappedResolveModelInfo(llm) {
+  const marker = llm?.[LLM_RESOLVE_WRAP_MARK];
+  const fn = marker?.original ?? llm?.resolveModelInfo;
+  return typeof fn === "function" ? fn.bind(llm) : undefined;
+}
+
+/**
+ * Whether the route declares `image` input, read before the admission wrap.
+ * `false` and `undefined` are the same answer to the caller ("not known to be
+ * multimodal"): a route nobody could resolve is bridged, never guessed.
+ */
+async function routeDeclaresImage(llm, provider, model) {
+  const resolve = unwrappedResolveModelInfo(llm);
+  if (resolve === undefined || typeof provider !== "string" || typeof model !== "string") {
+    return false;
+  }
+  try {
+    const info = await resolve(provider, model);
+    return info?.inputModalities?.includes("image") === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Routes already warned about, so the notice appears once per route. */
+const autoPromotionWarned = new Set();
+
+/** Registry key for one measured route. Provider-qualified: the same model id
+ * can be served by two gateways with different real capabilities. */
+function probeKey(provider, model) {
+  return `${typeof provider === "string" ? provider : ""}/${model}`;
+}
+
+/**
+ * The measured verdict for a route, or `undefined` when it was never probed.
+ * Anything other than the two recorded values (a hand-edited settings.yaml, a
+ * future format) reads as "not probed" rather than as a guess.
+ */
+function probeVerdict(config, provider, model) {
+  const results = config?.probeResults;
+  if (results === undefined || results === null || typeof model !== "string" || model.length === 0) {
+    return undefined;
+  }
+  const value = results[probeKey(provider, model)];
+  return value === "yes" || value === "no" ? value : undefined;
+}
+
+/**
+ * Resolve the endpoint and credential a route actually sends to, so a probe
+ * talks to the same place the model does instead of a copy of it.
+ *
+ * The pieces come from two seams that a plugin is allowed to read:
+ *  - `llm.listConfigurableProviders()` names the settings namespace and the
+ *    path a provider's profile lives at;
+ *  - `settings.get(ns)` resolves that profile (`baseURL`, `apiKeyEnv`, `api`);
+ *  - `credentials.resolve(ref)` turns `apiKeyEnv` into the secret itself
+ *    (`.value`), the same way `dsh-llm-pi-ai` does it for a real call.
+ *
+ * Read-only, and the secret never leaves this function's caller: the probe
+ * result records a verdict, never an endpoint or a key.
+ *
+ * @throws {Error} with a caller-facing reason when the route is unprobeable.
+ */
+async function resolveProbeTarget(ctx, provider, model) {
+  const llm = ctx.get("llm");
+  const settings = ctx.get("settings");
+  const credentials = ctx.get("credentials");
+  if (settings === undefined) {
+    throw new Error("the settings service is unavailable, so the route's endpoint cannot be read");
+  }
+  let entry;
+  try {
+    entry = (llm?.listConfigurableProviders?.() ?? []).find((candidate) => candidate?.provider === provider);
+  } catch {
+    /* an adapter that cannot describe its providers simply has no entry */
+  }
+  const settingsNs = entry?.settingsNs;
+  if (typeof settingsNs !== "string" || settingsNs.length === 0) {
+    throw new Error(
+      `provider "${provider}" does not publish a settings namespace, so its endpoint cannot be resolved for probing`,
+    );
+  }
+  let profile = settings.get(settingsNs);
+  const path = Array.isArray(entry.settingsPath) && entry.settingsPath.length > 0 ? entry.settingsPath : [provider];
+  for (const segment of path) profile = profile?.[segment];
+  if (profile === undefined || profile === null || typeof profile !== "object") {
+    throw new Error(`no stored profile for provider "${provider}" under "${settingsNs}"`);
+  }
+  const baseURL = typeof profile.baseURL === "string" && profile.baseURL.length > 0 ? profile.baseURL : undefined;
+  if (baseURL === undefined) {
+    throw new Error(`provider "${provider}" has no baseURL, so its endpoint cannot be probed`);
+  }
+  let apiKey;
+  const ref = profile.apiKeyEnv;
+  if (typeof ref === "string" && ref.length > 0) {
+    try {
+      const record = await credentials?.resolve?.(ref);
+      apiKey = typeof record?.value === "string" ? record.value : undefined;
+    } catch (error) {
+      throw new Error(`stored credential "${ref}" could not be read: ${String(error?.message ?? error)}`);
+    }
+  }
+  return { baseURL, apiKey, api: profile.api, model };
+}
+
+/**
+ * One-time notice when a route receives images directly *only* because of its
+ * own declaration (source `auto`). This is the one failure auto-detection
+ * cannot rule out: if the declaration is wrong, the endpoint rejects the image
+ * after the message is already durable, and the error alone does not say what
+ * to change. Naming the escape hatch the first time it happens turns a
+ * confusing 400 into a one-line fix — and now names the probe too, which
+ * settles the question instead of asking the user to guess.
+ * Read {@link lastModelDecision}; never throws.
+ */
+function warnAutoPromotion(logger) {
+  const { provider, model, direct, source } = lastModelDecision;
+  if (direct !== true || source !== "auto" || typeof model !== "string" || model.length === 0) return;
+  const key = `${typeof provider === "string" ? provider : ""}\u0000${model}`;
+  if (autoPromotionWarned.has(key)) return;
+  autoPromotionWarned.add(key);
+  logger?.warn?.(
+    `[tool-vision] "${model}" receives images directly because its route declares image input, ` +
+    `which is unverified; run vision_probe_model to measure it, or list it in multimodalModels ` +
+    `under multimodalListMode: blacklist to force the bridge`,
+  );
+}
+
 /**
  * Whether the session's current model may receive image blocks directly.
- * Uses the last logged request header first, then the agent's own options,
- * and consults ONLY the `multimodalModels` whitelist — never the model's
- * declared `inputModalities`, because profiles routinely declare
- * `input: [text, image]` on text-only models to pass the harness's prompt
- * admission check (that declaration says nothing about whether the upstream
- * endpoint really accepts `image_url` parts).
+ *
+ * Two inputs, deliberately independent:
+ *
+ *  - the base set — the route's own declared `inputModalities`, and only when
+ *    `autoDetectMultimodal` is on. It is read through
+ *    {@link unwrappedResolveModelInfo}, never through the admission wrap.
+ *  - the list — `multimodalModels` under `multimodalListMode`, and the list is
+ *    always explicit user intent, so it outranks the declaration: whitelist
+ *    adds to the base set, blacklist subtracts from it.
+ *
  * Returns true when bridging is disabled (nothing would be bridged anyway).
  */
-async function currentModelAcceptsImage(agent, config) {
-  if (!config.bridgeTextOnly) return true;
-  const header = agent?.session?.requestHeader?.();
-  const model = header?.config?.model ?? agent?.options?.model;
-  if (!model) return false;
-  return config.multimodalModels.includes(model);
+async function currentModelAcceptsImage(agent, config, llm) {
+  const mode = normalizeListMode(config.multimodalListMode);
+  if (!config.bridgeTextOnly) {
+    Object.assign(lastModelDecision, { ...currentRoute(agent), direct: true, source: "bridge-off", mode });
+    return true;
+  }
+  const { provider, model } = currentRoute(agent);
+  if (!model) {
+    Object.assign(lastModelDecision, { provider, model, direct: false, source: "no-route", mode });
+    return false;
+  }
+  const base = config.autoDetectMultimodal
+    ? await routeDeclaresImage(llm, provider, model)
+    : false;
+  let direct = base;
+  let source = base ? "auto" : "default";
+  // A measured verdict outranks the route's own claim: a probe is a real
+  // request, a declaration is only a statement. Both directions count, so a
+  // route that says "image" and answered without reading the pixels goes back
+  // to the bridge without anyone hunting for the right list entry.
+  const probed = probeVerdict(config, provider, model);
+  if (probed !== undefined) {
+    direct = probed === "yes";
+    source = probed === "yes" ? "probe-yes" : "probe-no";
+  }
+  // `off` means the list carries no opinion at all — it is not "empty list
+  // under whitelist", it is "no list semantics", so nothing is forced. The
+  // human list keeps the last word over both other signals.
+  const listed = mode !== "off" && modelListMatches(config.multimodalModels, provider, model);
+  if (listed) {
+    direct = mode !== "blacklist";
+    source = mode === "blacklist" ? "blacklist" : "whitelist";
+  }
+  Object.assign(lastModelDecision, { provider, model, direct, source, mode });
+  return direct;
 }
 
 /**
@@ -443,7 +880,8 @@ function attachPreStepBridge(ctx, getConfig, exportDir) {
     const agent = payload?.agent;
     if (!agent?.session) return decision;
     try {
-      const acceptsImage = await currentModelAcceptsImage(agent, getConfig());
+      const acceptsImage = await currentModelAcceptsImage(agent, getConfig(), ctx.get("llm"));
+      warnAutoPromotion(ctx.logger);
       if (!acceptsImage) {
         let repaired = repairedBySession.get(agent.session.id);
         if (!repaired) {
@@ -570,6 +1008,11 @@ function apply(ctx, config) {
   let current = config;
   let sourceGetter = null;
   const getConfig = () => (sourceGetter ? sourceGetter() : current);
+  // The registered settings scope, kept so tools can PERSIST what they measure.
+  // Null whenever no settings provider is mounted (composition-entry-only runs),
+  // in which case a probe still reports its verdict but cannot record it.
+  let settingsScope = null;
+  const getSettingsScope = () => settingsScope;
 
   // ── master switch: a child fiber owns every registration ──────────────────
   // `ctx.tools.register`, `ctx.effect` and `ctx.on` are all effects on the fiber
@@ -671,6 +1114,124 @@ function apply(ctx, config) {
         // (baseURL/apiKey/model). No provider chain, no local models, no extra
         // settings: everything comes from the existing tool-vision configuration.
               registerVisionTools(inner, getConfig);
+
+        // ── ground-truth capability probe (v0.9.0) ───────────────────────────
+        // Everything else decides from what a route SAYS; this measures what it
+        // DOES, and records the answer so the bridge decision stops guessing.
+        inner.tools.register(defineTool({
+          name: "vision_probe_model",
+          description:
+            "Measure whether a model's endpoint can actually read images, by sending it a real " +
+            "solid-color image and checking the answer. Use this when a model's declared image " +
+            "support is doubtful (it claims `image` but the provider may reject it, or it declares " +
+            "text-only yet the endpoint may accept images). Runs a text-only control request plus " +
+            "two different colors, so a model that merely guesses cannot pass. The verdict is " +
+            "recorded and from then on decides whether that route's images are sent directly or " +
+            "bridged. Costs a few requests against the model's own endpoint.",
+          parameters: {
+            model: {
+              type: "string",
+              required: true,
+              description: "Model id to probe, e.g. xiaomi/mimo-v2.5. Use the id exactly as dsh has it configured.",
+            },
+            provider: {
+              type: "string",
+              description:
+                "Provider route serving the model (e.g. commandcode). Omit to use the current " +
+                "session's route, or to auto-select when exactly one provider offers the model.",
+            },
+          },
+          output: {
+            schema: { type: "string" },
+            render: (_args, value) => [{ type: "text", text: value }],
+          },
+          async execute(args, exec) {
+            const cfg = getConfig();
+            const requested = String(args.model ?? "").trim();
+            if (requested.length === 0) throw new Error("vision_probe_model: model is required");
+            const llm = inner.get("llm");
+
+            // Resolve which routes offer this model, so an omitted `provider`
+            // is still an exact choice rather than a guess.
+            let candidates = [];
+            try {
+              for (const entry of llm?.listProviders?.() ?? []) {
+                const id = entry?.id;
+                if (typeof id !== "string") continue;
+                const models = await llm.listModels(id).catch(() => []);
+                if ((models ?? []).some((model) => String(model?.id) === requested)) candidates.push(id);
+              }
+            } catch {
+              /* fall through to the route/argument fallbacks below */
+            }
+            let provider = typeof args.provider === "string" && args.provider.length > 0 ? args.provider : undefined;
+            if (provider === undefined) {
+              const here = currentRoute(exec?.agent);
+              if (candidates.length === 1) provider = candidates[0];
+              else if (here.model === requested && typeof here.provider === "string") provider = here.provider;
+              else if (candidates.length > 1) {
+                throw new Error(
+                  `vision_probe_model: "${requested}" is served by ${candidates.join(", ")}; pass provider explicitly`,
+                );
+              } else {
+                provider = here.provider;
+              }
+            }
+            if (typeof provider !== "string" || provider.length === 0) {
+              throw new Error(
+                `vision_probe_model: cannot tell which provider serves "${requested}"; pass provider explicitly`,
+              );
+            }
+
+            const target = await resolveProbeTarget(inner, provider, requested);
+            const outcome = await probeModelCapability(
+              {
+                baseURL: target.baseURL,
+                apiKey: target.apiKey,
+                api: target.api,
+                model: requested,
+                maxTokens: PROBE_MAX_TOKENS,
+                timeoutMs: Math.max(PROBE_TIMEOUT_MS, Number(cfg.timeoutMs) || 0),
+                headers: sessionHeaders(cfg, exec),
+              },
+              exec.signal,
+            );
+
+            const key = probeKey(provider, requested);
+            let recorded = "not recorded (no settings provider)";
+            if (outcome.support === "yes" || outcome.support === "no") {
+              const scope = getSettingsScope();
+              if (scope !== null) {
+                try {
+                  await scope.update({ probeResults: { ...(cfg.probeResults ?? {}), [key]: outcome.support } });
+                  recorded = `recorded as "${outcome.support}"`;
+                } catch (error) {
+                  recorded = `could not be recorded: ${String(error?.message ?? error)}`;
+                }
+              }
+            }
+
+            const verdictText = outcome.support === "yes"
+              ? "SUPPORTS images"
+              : outcome.support === "no"
+                ? "does NOT read images"
+                : "INCONCLUSIVE (the route could not be probed)";
+            const effect = outcome.support === "yes"
+              ? "images will be sent to it directly"
+              : outcome.support === "no"
+                ? "images will be bridged to inspect_image hints"
+                : "the existing list/declaration rules still apply";
+            const evidence = Object.entries(outcome.evidence ?? {})
+              .map(([name, value]) => `  ${name}: ${value}`)
+              .join("\n");
+            return [
+              `${provider}/${requested}: ${verdictText}`,
+              `  ${outcome.detail}`,
+              `  ${recorded}; ${effect}`,
+              evidence ? `  evidence:\n${evidence}` : "",
+            ].filter(Boolean).join("\n");
+          },
+        }));
       },
     });
   }
@@ -704,8 +1265,10 @@ function apply(ctx, config) {
   ctx.inject(["settings"], (sctx) => {
     const scope = sctx.settings.register(NS, Config, { base: config });
     sourceGetter = () => scope.get();
+    settingsScope = scope;
     sctx.effect(() => () => {
       sourceGetter = null;
+      settingsScope = null;
     });
     // Hot-apply: `enabled` switches the child fiber, and any field that gates a
     // registration re-installs it, so none of them needs a dsh restart anymore.
@@ -716,6 +1279,14 @@ function apply(ctx, config) {
     syncFeatures();
   });
 
+  // ── model catalog route: settings support, so it lives on THIS fiber ───────
+  // The master switch disposes the feature fiber on purpose (tools, bridge,
+  // preview route), while the settings section itself deliberately stays
+  // mounted — and a section whose list field cannot autocomplete is a section
+  // you cannot configure before switching the plugin on. Registered here so it
+  // outlives `enabled: false`; read-only and secret-free by construction.
+  registerModelCatalogRoute(ctx, ctx.logger, getConfig);
+
   // No settings provider: the composition entry is the whole configuration.
   syncFeatures();
 }
@@ -727,18 +1298,35 @@ export {
   BRIDGE_PREVIEW_ROUTE,
   Config,
   DEFAULT_DESCRIPTION,
+  DEFAULT_MULTIMODAL_LIST_MODE,
   EXT_BY_MEDIA,
+  MODEL_CATALOG_MAX_PER_PROVIDER,
+  MODEL_CATALOG_ROUTE,
+  MULTIMODAL_LIST_MODES,
   apply,
   attachPreStepBridge,
+  autoPromotionWarned,
   bridgeMessages,
   currentModelAcceptsImage,
+  currentRoute,
   deepFreeze,
   exportImage,
   hasImageBlock,
   inject,
   installAutoImageAdmission,
+  lastModelDecision,
+  modelListMatches,
+  modelListMatchEntries,
   name,
+  normalizeListMode,
   parseQuery,
+  probeKey,
+  probeVerdict,
   registerBridgePreviewRoute,
+  registerModelCatalogRoute,
   repairLoggedImages,
+  resolveProbeTarget,
+  routeDeclaresImage,
+  unwrappedResolveModelInfo,
+  warnAutoPromotion,
 };