muonroi-cli 1.8.4 → 1.9.0

package/dist/src/providers/vision-backend.js

@@ -0,0 +1,258 @@
+import { getModelInfo, getVisionProxyRouting, MODELS, SWITCH_PROVIDER_ORDER } from "../models/registry.js";
+import { apiBaseFor } from "./endpoints.js";
+import { loadKeyForProvider } from "./keychain.js";
+const REQUEST_TIMEOUT_MS = 90_000;
+const DEFAULT_VISION_PROXY = {
+    default: { provider: "zai", model_id: "glm-4.6v-flash" },
+    ocr: { provider: "zai", model_id: "glm-4.6v-flash" },
+    design: { provider: "zai", model_id: "glm-5.2" },
+    fallback_chain: [
+        { provider: "xai", model_id: "grok-4.5" },
+        { provider: "zai", model_id: "glm-5.2" },
+    ],
+};
+const OCR_INTENT_RE = /\b(ocr|transcribe|read\s+(all\s+)?text|extract\s+text|text\s+in\s+(the\s+)?image|copy\s+text|what\s+(does|do)\s+it\s+say)\b/i;
+export function looksLikeOcrIntent(text) {
+    return OCR_INTENT_RE.test(text);
+}
+export function resolveVisionChain(kind) {
+    const routing = getVisionProxyRouting() ?? DEFAULT_VISION_PROXY;
+    const chain = [];
+    const primary = routing[kind] ?? routing.default;
+    if (primary)
+        chain.push(primary);
+    for (const slot of routing.fallback_chain ?? []) {
+        if (!chain.some((s) => s.provider === slot.provider && s.model_id === slot.model_id)) {
+            chain.push(slot);
+        }
+    }
+    if (chain.length === 0 && routing.default)
+        return [routing.default];
+    return chain;
+}
+async function slotHasAvailableKey(slot) {
+    try {
+        await loadKeyForProvider(slot.provider);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Vision-proxy chain filtered to providers that currently have API keys. */
+export async function resolveAvailableVisionChain(kind = "default") {
+    const available = [];
+    for (const slot of resolveVisionChain(kind)) {
+        if (await slotHasAvailableKey(slot))
+            available.push(slot);
+    }
+    return available;
+}
+export async function isVisionBackendAvailable(kind = "default") {
+    return (await resolveAvailableVisionChain(kind)).length > 0;
+}
+async function tryNativeVisionModel(modelId, source, excludeModelId) {
+    if (excludeModelId && modelId === excludeModelId)
+        return null;
+    const info = getModelInfo(modelId);
+    if (!info?.supportsVision)
+        return null;
+    const provider = info.provider;
+    const { isModelDisabled, isProviderDisabled } = await import("../utils/settings.js");
+    if (isProviderDisabled(provider) || isModelDisabled(modelId))
+        return null;
+    if (!(await slotHasAvailableKey({ provider, model_id: modelId })))
+        return null;
+    return { modelId, provider, source };
+}
+/**
+ * When vision-proxy backends have no keys, pick a catalog vision model (with key)
+ * so images can be sent natively instead of failing on a text-only primary.
+ */
+export async function findNativeVisionFallback(opts) {
+    const exclude = opts?.excludeModelId;
+    const seen = new Set();
+    for (const kind of ["default", "ocr", "design"]) {
+        for (const slot of resolveVisionChain(kind)) {
+            if (seen.has(slot.model_id))
+                continue;
+            seen.add(slot.model_id);
+            const hit = await tryNativeVisionModel(slot.model_id, "vision_proxy_slot", exclude);
+            if (hit)
+                return hit;
+        }
+    }
+    const visionByProvider = new Map();
+    for (const m of MODELS) {
+        if (!m.supportsVision || !m.provider)
+            continue;
+        const list = visionByProvider.get(m.provider) ?? [];
+        list.push(m);
+        visionByProvider.set(m.provider, list);
+    }
+    for (const provider of SWITCH_PROVIDER_ORDER) {
+        for (const m of visionByProvider.get(provider) ?? []) {
+            if (seen.has(m.id))
+                continue;
+            seen.add(m.id);
+            const hit = await tryNativeVisionModel(m.id, "catalog_vision", exclude);
+            if (hit)
+                return hit;
+        }
+    }
+    for (const m of MODELS) {
+        if (!m.supportsVision)
+            continue;
+        if (seen.has(m.id))
+            continue;
+        const hit = await tryNativeVisionModel(m.id, "catalog_vision", exclude);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+export async function collectVisionUnavailableReasons(kind = "default") {
+    const reasons = [];
+    for (const slot of resolveVisionChain(kind)) {
+        if (await slotHasAvailableKey(slot)) {
+            reasons.push(`${slot.model_id}@${slot.provider}: API key present but backend unreachable`);
+        }
+        else {
+            reasons.push(`${slot.model_id}@${slot.provider}: no API key`);
+        }
+    }
+    reasons.push("no other vision-capable catalog model has a configured API key");
+    return reasons;
+}
+export async function callVisionBackend(chain, content, signal, responseFormat) {
+    const failureReasons = [];
+    if (chain.length === 0) {
+        return { ok: false, reason: "no vision backend available — configure ZAI_API_KEY or XAI_API_KEY" };
+    }
+    for (const slot of chain) {
+        const provider = slot.provider;
+        let apiKey;
+        try {
+            apiKey = await loadKeyForProvider(provider);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            failureReasons.push(`${slot.model_id}@${provider}: no API key (${msg})`);
+            continue;
+        }
+        const base = apiBaseFor(provider);
+        const result = await callVisionModelAt(base, slot.model_id, content, apiKey, signal, responseFormat);
+        if (result.ok) {
+            return { ok: true, text: result.text, model: slot.model_id, provider };
+        }
+        failureReasons.push(`${slot.model_id}@${provider}: ${result.reason}`);
+        console.warn(`[vision-backend] ${slot.model_id}@${provider} failed (${result.reason}), trying next...`);
+    }
+    return { ok: false, reason: failureReasons.join(" | ") || "no vision backend configured" };
+}
+async function callVisionModelAt(baseURL, model, content, apiKey, signal, responseFormat) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, REQUEST_TIMEOUT_MS);
+    if (signal) {
+        signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    const url = `${baseURL.replace(/\/$/, "")}/chat/completions`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                messages: [{ role: "user", content }],
+                max_tokens: 3072,
+                temperature: 0.1,
+                ...(responseFormat ? { response_format: responseFormat } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        if (timedOut)
+            return { ok: false, reason: `timeout after ${REQUEST_TIMEOUT_MS}ms` };
+        if (signal?.aborted)
+            throw err;
+        return { ok: false, reason: `network error: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    clearTimeout(timeout);
+    if (!res.ok) {
+        const errText = await res.text().catch(() => "");
+        return { ok: false, reason: `HTTP ${res.status} ${errText.slice(0, 200)}` };
+    }
+    const data = (await res.json().catch(() => null));
+    const text = data?.choices?.[0]?.message?.content;
+    if (!text)
+        return { ok: false, reason: "empty response body" };
+    return { ok: true, text };
+}
+/** Ask the vision model to write as direct sight for the primary (text-only) agent. */
+export function wrapAnalyzerInstructions(userPrompt, kind) {
+    const style = kind === "design"
+        ? "Output ONLY valid JSON matching the requested schema. No markdown fences."
+        : "Write in clear markdown. Use first-person present tense ('I see…', 'The screenshot shows…').";
+    return [
+        userPrompt,
+        "",
+        "IMPORTANT — output style for the primary coding agent:",
+        "- Write as a DIRECT visual observation. The reader will treat your words as its own native sight.",
+        "- Do NOT mention vision proxy, backend models, or that you are a separate model.",
+        `- ${style}`,
+        "- If something is illegible, cropped, or ambiguous, say exactly what is unclear and what would help (closer crop, higher resolution, different angle).",
+    ].join("\n");
+}
+/**
+ * Envelope injected into text-only model context — reads as native vision, not third-party analysis.
+ */
+export function formatNativeVisionObservation(observation, opts) {
+    const subject = opts.imageCount > 1 ? `these ${opts.imageCount} images` : "this image";
+    const cacheHint = opts.cachedIds && opts.cachedIds.length > 0
+        ? `- Cached as ${opts.cachedIds.join(", ")} — use ask_vision_proxy with a specific question to inspect a detail`
+        : "";
+    return [
+        "<vision-observation>",
+        `You are viewing ${subject}. Treat everything below as your direct visual observation — reason and respond as if you saw it yourself.`,
+        "",
+        observation.trim(),
+        "",
+        "If any detail is unclear, cropped, or you need another angle:",
+        "- ask_vision_proxy with a precise question (region, color, text, UI element)",
+        "- analyze_image on the file path to re-inspect or compare a fresh screenshot",
+        "- ask the user to share another image or clarify what to focus on",
+        cacheHint,
+        "</vision-observation>",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+export function formatNativeVisionUnavailable(imageCount, reasons, cachedIds) {
+    const types = imageCount > 1 ? `${imageCount} images` : "1 image";
+    const cacheHint = cachedIds && cachedIds.length > 0 ? `Cached IDs: ${cachedIds.join(", ")} — try ask_vision_proxy anyway.` : "";
+    const detail = reasons.length > 0 ? reasons.join(" | ") : "vision backend unreachable";
+    return [
+        '<vision-observation status="unavailable">',
+        `${types} could not be analyzed (${detail}).`,
+        "Do NOT guess what the image contains.",
+        "Setup: configure ZAI_API_KEY or XAI_API_KEY for vision proxy, or switch to a vision-capable default model.",
+        "- Retry with analyze_image and the file path once a vision key is configured",
+        "- Use ask_vision_proxy if a cached image exists",
+        "- Ask the user to re-share the screenshot or describe what you need to see",
+        cacheHint,
+        "</vision-observation>",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+//# sourceMappingURL=vision-backend.js.map

package/dist/src/providers/vision-proxy.d.ts

@@ -1,23 +1,36 @@
 /**
  * Vision proxy layer for text-only models (e.g. DeepSeek V4).
  *
- * When the active model does not support vision, image parts in the message
- * are extracted, sent to a cheap vision model on SiliconFlow
- * (Qwen/Qwen2.5-VL-32B-Instruct @ $0.27/M tokens), and replaced with
- * structured text descriptions before the message reaches the primary model.
+ * Image parts in messages are sent to the catalog-configured vision backend
+ * (default: Z.ai glm-4.6v-flash) and replaced with native-sight observations
+ * so the primary model reasons as if it saw the image directly.
  */
 import type { ModelMessage } from "ai";
+import { type NativeVisionFallback, type VisionTaskKind } from "./vision-backend.js";
 export interface VisionProxyResult {
     messages: ModelMessage[];
     proxied: boolean;
     imageCount: number;
 }
-/**
- * Returns true when the model cannot handle image content natively.
- */
 export declare function needsVisionProxy(modelId: string): boolean;
+export type ImageHandlingPlan = {
+    strategy: "proxy";
+} | {
+    strategy: "native_model";
+    fallback: NativeVisionFallback;
+} | {
+    strategy: "unavailable";
+    notice: string;
+};
 /**
- * Process messages through the vision proxy.
- * Only messages with image parts are modified; text-only messages pass through.
+ * Decide how to handle images when the active model is text-only:
+ * proxy backend, switch to a native vision model, or surface unavailable.
  */
+export declare function planImageHandlingForTextOnlyModel(opts: {
+    primaryModelId: string;
+    imageCount: number;
+    kind?: VisionTaskKind;
+}): Promise<ImageHandlingPlan>;
+/** True when proxy backend or a native vision model can handle images for this text-only model. */
+export declare function canHandleImagesForTextOnlyModel(modelId: string): Promise<boolean>;
 export declare function proxyVision(messages: ModelMessage[], modelId: string, signal?: AbortSignal): Promise<VisionProxyResult>;

package/dist/src/providers/vision-proxy.js

@@ -1,15 +1,13 @@
 /**
  * Vision proxy layer for text-only models (e.g. DeepSeek V4).
  *
- * When the active model does not support vision, image parts in the message
- * are extracted, sent to a cheap vision model on SiliconFlow
- * (Qwen/Qwen2.5-VL-32B-Instruct @ $0.27/M tokens), and replaced with
- * structured text descriptions before the message reaches the primary model.
+ * Image parts in messages are sent to the catalog-configured vision backend
+ * (default: Z.ai glm-4.6v-flash) and replaced with native-sight observations
+ * so the primary model reasons as if it saw the image directly.
  */
 import { getModelInfo } from "../models/registry.js";
-import { apiBaseFor } from "./endpoints.js";
-import { loadKeyForProvider } from "./keychain.js";
 import { UI_LAYOUT_SCHEMA_HINT } from "./mcp-vision-bridge.js";
+import { callVisionBackend, collectVisionUnavailableReasons, findNativeVisionFallback, formatNativeVisionObservation, formatNativeVisionUnavailable, isVisionBackendAvailable, looksLikeOcrIntent, resolveAvailableVisionChain, wrapAnalyzerInstructions, } from "./vision-backend.js";
 const DESIGN_INTENT_PATTERNS = [
     /\bredesign\b/i,
     /\bdesign\s*(system|token|spec|review)?\b/i,
@@ -26,24 +24,40 @@ function looksLikeDesignIntent(text) {
         return false;
     return DESIGN_INTENT_PATTERNS.some((re) => re.test(text));
 }
-const VISION_MODELS = [
-    "Qwen/Qwen3-VL-8B-Instruct",
-    "Qwen/Qwen3-VL-30B-A3B-Instruct",
-    "Qwen/Qwen3-VL-32B-Instruct",
-];
-const SILICONFLOW_BASE = apiBaseFor("siliconflow");
-const REQUEST_TIMEOUT_MS = 90_000;
-/**
- * Returns true when the model cannot handle image content natively.
- */
 export function needsVisionProxy(modelId) {
     const info = getModelInfo(modelId);
     return info?.supportsVision === false;
 }
 /**
- * Process messages through the vision proxy.
- * Only messages with image parts are modified; text-only messages pass through.
+ * Decide how to handle images when the active model is text-only:
+ * proxy backend, switch to a native vision model, or surface unavailable.
  */
+export async function planImageHandlingForTextOnlyModel(opts) {
+    if (!needsVisionProxy(opts.primaryModelId)) {
+        return { strategy: "proxy" };
+    }
+    const kind = opts.kind ?? "default";
+    if (await isVisionBackendAvailable(kind)) {
+        return { strategy: "proxy" };
+    }
+    const fallback = await findNativeVisionFallback({ excludeModelId: opts.primaryModelId });
+    if (fallback) {
+        return { strategy: "native_model", fallback };
+    }
+    const reasons = await collectVisionUnavailableReasons(kind);
+    return {
+        strategy: "unavailable",
+        notice: formatNativeVisionUnavailable(opts.imageCount, reasons),
+    };
+}
+/** True when proxy backend or a native vision model can handle images for this text-only model. */
+export async function canHandleImagesForTextOnlyModel(modelId) {
+    if (!needsVisionProxy(modelId))
+        return true;
+    if (await isVisionBackendAvailable())
+        return true;
+    return (await findNativeVisionFallback({ excludeModelId: modelId })) !== null;
+}
 export async function proxyVision(messages, modelId, signal) {
     if (!needsVisionProxy(modelId)) {
         return { messages, proxied: false, imageCount: 0 };
@@ -66,6 +80,7 @@ export async function proxyVision(messages, modelId, signal) {
         totalImages += imageParts.length;
         const userText = textParts.map((t) => t.text).join("\n");
         const designIntent = looksLikeDesignIntent(userText);
+        const ocrIntent = looksLikeOcrIntent(userText);
         const svgFast = trySvgFastPath(imageParts, designIntent);
         if (svgFast) {
             processed.push({
@@ -74,27 +89,22 @@ export async function proxyVision(messages, modelId, signal) {
             });
             continue;
         }
-        const descriptions = await describeImages(imageParts, textParts, signal, designIntent);
+        const kind = designIntent ? "design" : ocrIntent ? "ocr" : "default";
+        const descriptions = await describeImages(imageParts, textParts, signal, kind);
         const newContent = [...textParts, { type: "text", text: descriptions }];
         processed.push({ ...msg, content: newContent });
     }
     return { messages: processed, proxied: totalImages > 0, imageCount: totalImages };
 }
-async function describeImages(images, contextTexts, signal, designIntent = false) {
-    let apiKey;
-    try {
-        apiKey = await loadKeyForProvider("siliconflow");
-    }
-    catch {
-        return buildFallbackDescription(images, ["SILICONFLOW_API_KEY not configured"]);
-    }
+async function describeImages(images, contextTexts, signal, kind = "default") {
     const userContext = contextTexts.map((t) => t.text).join("\n");
+    const designIntent = kind === "design";
     const visionContent = [];
     visionContent.push({
         type: "text",
-        text: designIntent
+        text: wrapAnalyzerInstructions(designIntent
             ? buildDesignPrompt(userContext, images.length)
-            : buildAnalysisPrompt(userContext, images.length),
+            : buildAnalysisPrompt(userContext, images.length, kind === "ocr"), kind),
     });
     for (const img of images) {
         visionContent.push({
@@ -106,24 +116,12 @@ async function describeImages(images, contextTexts, signal, designIntent = false
         });
     }
     const responseFormat = designIntent ? { type: "json_object" } : undefined;
-    const failureReasons = [];
-    for (const model of VISION_MODELS) {
-        try {
-            const result = await callVisionModel(model, visionContent, apiKey, signal, responseFormat);
-            if (result.ok)
-                return formatVisionResult(result.text, images.length, model, designIntent);
-            failureReasons.push(`${model}: ${result.reason}`);
-            console.warn(`[vision-proxy] ${model} failed (${result.reason}), trying next...`);
-        }
-        catch (err) {
-            if (signal?.aborted)
-                throw err;
-            const msg = err instanceof Error ? err.message : String(err);
-            failureReasons.push(`${model}: ${msg}`);
-            console.warn(`[vision-proxy] ${model} threw (${msg}), trying next...`);
-        }
+    const chain = await resolveAvailableVisionChain(kind);
+    const result = await callVisionBackend(chain, visionContent, signal, responseFormat);
+    if (result.ok) {
+        return formatNativeVisionObservation(result.text, { imageCount: images.length });
     }
-    return buildFallbackDescription(images, failureReasons);
+    return formatNativeVisionUnavailable(images.length, [result.reason]);
 }
 function trySvgFastPath(images, designIntent) {
     if (images.length === 0)
@@ -142,64 +140,23 @@ function trySvgFastPath(images, designIntent) {
         return svg.length > 32_000 ? `${svg.slice(0, 32_000)}\n<!-- truncated -->` : svg;
     })
         .join("\n\n");
-    const header = `[Vision Proxy — ${images.length} SVG source(s) passed through (fast-path, no vision call)]`;
-    const guidance = designIntent
-        ? `\nThe raw SVG below IS the layout contract. Map nodes to:\n${UI_LAYOUT_SCHEMA_HINT}\n`
-        : "\nThe raw SVG below is vector text — read element attributes (x, y, width, fill, text content) directly.\n";
-    return `\n${header}${guidance}\n\`\`\`svg\n${decoded}\n\`\`\`\n[/Vision Proxy]\n`;
+    const observation = designIntent
+        ? `I see ${images.length} SVG source(s). The vector markup below is exact — use element attributes (x, y, width, fill, text) directly.\n\nMap to layout schema:\n${UI_LAYOUT_SCHEMA_HINT}\n\n\`\`\`svg\n${decoded}\n\`\`\``
+        : `I see ${images.length} SVG source(s). Vector markup (read attributes directly):\n\n\`\`\`svg\n${decoded}\n\`\`\``;
+    return formatNativeVisionObservation(observation, { imageCount: images.length });
 }
-async function callVisionModel(model, content, apiKey, signal, responseFormat) {
-    const controller = new AbortController();
-    let timedOut = false;
-    const timeout = setTimeout(() => {
-        timedOut = true;
-        controller.abort();
-    }, REQUEST_TIMEOUT_MS);
-    if (signal) {
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    }
-    let res;
-    try {
-        res = await fetch(`${SILICONFLOW_BASE}/chat/completions`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${apiKey}`,
-            },
-            body: JSON.stringify({
-                model,
-                messages: [{ role: "user", content }],
-                max_tokens: 3072,
-                temperature: 0.1,
-                ...(responseFormat ? { response_format: responseFormat } : {}),
-            }),
-            signal: controller.signal,
-        });
-    }
-    catch (err) {
-        clearTimeout(timeout);
-        if (timedOut)
-            return { ok: false, reason: `timeout after ${REQUEST_TIMEOUT_MS}ms` };
-        if (signal?.aborted)
-            throw err;
-        return { ok: false, reason: `network error: ${err instanceof Error ? err.message : String(err)}` };
-    }
-    clearTimeout(timeout);
-    if (!res.ok) {
-        const errText = await res.text().catch(() => "unknown error");
-        return { ok: false, reason: `HTTP ${res.status} ${errText.slice(0, 200)}` };
-    }
-    const data = (await res.json().catch(() => null));
-    const text = data?.choices?.[0]?.message?.content;
-    if (!text)
-        return { ok: false, reason: "empty response body" };
-    return { ok: true, text };
-}
-function buildAnalysisPrompt(userContext, imageCount) {
+function buildAnalysisPrompt(userContext, imageCount, ocrFocus) {
     const plural = imageCount > 1 ? `${imageCount} images` : "the image";
+    const ocrBlock = ocrFocus
+        ? [
+            "OCR focus: transcribe ALL visible text exactly (preserve line breaks, labels, error codes).",
+            "Note any text that is blurry or partially cut off.",
+            "",
+        ]
+        : [];
     return [
-        `You are a vision model. Analyze ${plural} for a software developer working in a coding CLI tool.`,
-        "Use your full vision capability — do NOT refuse on the basis of being text-only.",
+        `Analyze ${plural} for a software developer working in a coding CLI.`,
+        ...ocrBlock,
         "Focus on:",
         "- UI layout and component structure (if screenshot)",
         "- All visible text, labels, buttons, and form elements",
@@ -212,45 +169,19 @@ function buildAnalysisPrompt(userContext, imageCount) {
         userContext ? `\nDeveloper's context: "${userContext}"` : "",
     ].join("\n");
 }
-function formatVisionResult(description, imageCount, model, designIntent = false) {
-    const usedModel = model ?? VISION_MODELS[0];
-    const tag = designIntent ? "design contract via" : "analyzed via";
-    const single = designIntent ? "design contract via" : "analyzed via";
-    const header = imageCount > 1
-        ? `[Vision Proxy — ${imageCount} images ${tag} ${usedModel}]`
-        : `[Vision Proxy — image ${single} ${usedModel}]`;
-    return `\n${header}\n${description}\n[/Vision Proxy]\n`;
-}
 function buildDesignPrompt(userContext, imageCount) {
     const plural = imageCount > 1 ? `${imageCount} images` : "the image";
     return [
-        `Analyze ${plural} as a UI/UX design contract for a software developer who CANNOT see the image.`,
-        "Output will be consumed by another AI agent to recreate or redesign this UI, so precision matters more than prose.",
-        "",
-        "Return ONLY a single JSON object matching this exact shape (no markdown, no commentary, no code fences):",
+        `Analyze ${plural} as a UI/UX design contract for a software developer.`,
+        "Return ONLY a single JSON object matching this exact shape (no markdown, no commentary):",
         UI_LAYOUT_SCHEMA_HINT,
         "",
         "Extraction rules:",
-        "- bbox: pixel coordinates relative to the visible image (origin top-left). Estimate when unsure but never omit.",
-        "- Colors: 6-digit lowercase hex (#rrggbb). Sample dominant pixel.",
-        "- Typography sizePx: estimate from cap-height, round to nearest 2.",
-        "- spacingScalePx / radiusScalePx: distinct observed values, sorted ascending.",
-        "- components[]: every visible interactive or content element. Stable IDs like 'btn_signup'.",
-        "- children[]: component IDs nested inside this component.",
-        "- hierarchy[]: visual reading order of headings — level 1 hero, 2 section, 3 sub.",
+        "- bbox: pixel coordinates relative to the visible image (origin top-left).",
+        "- Colors: 6-digit lowercase hex (#rrggbb).",
+        "- components[]: every visible interactive or content element.",
         "- text: EXACT visible string. null only when no text (icon-only).",
-        "- notes[]: things schema cannot capture — gradients, illustrations, motion.",
-        "",
-        "If a field is genuinely not determinable, use null. Never invent values.",
         userContext ? `\nDeveloper's context: "${userContext}"` : "",
     ].join("\n");
 }
-function buildFallbackDescription(images, reasons = []) {
-    const count = images.length;
-    const types = [...new Set(images.map((i) => i.mediaType))].join(", ");
-    const detail = reasons.length > 0
-        ? `Reason(s): ${reasons.join(" | ")}`
-        : "Reason: unknown — check SILICONFLOW_API_KEY and model availability.";
-    return `\n[Vision Proxy — unavailable, ${count} image(s) (${types}) could not be analyzed. ${detail}]\n`;
-}
 //# sourceMappingURL=vision-proxy.js.map

package/dist/src/providers/warm.d.ts

@@ -0,0 +1,65 @@
+/**
+ * src/providers/warm.ts
+ *
+ * Boot-time warm-up of the provider factory registry.
+ *
+ * Root cause it addresses (measured live, 2026-07-16, session 0c6728ba1a25):
+ * an xai session POSTed model `gpt-5.4` to api.x.ai and got 404 "The model
+ * gpt-5.4 does not exist" — an openai model sent to the xai endpoint. The
+ * factory/model guard in `runtime.ts` DID spot the mismatch and tried to
+ * redirect the request to openai's own factory, but the registry had no openai
+ * entry: a session only ever built the factory for ITS OWN provider, so any
+ * sub-task that resolved a model from another provider had nothing to redirect
+ * to and fell through to the wrong endpoint.
+ *
+ * That is the actual hole. Model ids and provider factories travel as two
+ * independent values, so "borrow the session's factory" is the silent default
+ * for every sub-task (compaction, classify, sub-agents, mode switches) and only
+ * some paths remember to re-derive the provider. Warming the registry for every
+ * credentialed provider closes it at the source: the factory for a model's own
+ * provider is then always present, so `resolveModelRuntime` can derive it from
+ * the model itself instead of trusting whatever factory a caller passed.
+ *
+ * Best-effort by construction: a provider that fails to warm is simply absent
+ * (the same state as today), never a boot failure.
+ */
+import { type ProviderId } from "./types.js";
+/** Outcome of {@link warmProviderFactories}, for logging and tests. */
+export interface WarmResult {
+    /** Providers whose factory is now registered. */
+    warmed: ProviderId[];
+    /** Providers left out, with the reason (no credentials, disabled, or an error). */
+    skipped: Array<{
+        id: ProviderId;
+        reason: string;
+    }>;
+}
+/**
+ * Build and register a factory for every provider the user has credentials for.
+ *
+ * Runs providers concurrently — each is an independent credential read, and a
+ * serial loop would add every provider's latency to boot.
+ *
+ * Skips providers that already have a factory: the session builds its own with
+ * session-specific options (custom baseURL, OAuth headers), and rebuilding it
+ * from bare defaults here would silently downgrade the live session's wiring.
+ */
+/**
+ * Rebuild ONE provider's factory after its credentials changed mid-session.
+ *
+ * `createProviderFactoryAsync` reads OAuth tokens at CONSTRUCTION and bakes the
+ * resulting auth headers into the factory (runtime.ts: `loadTokensWithRefresh()`
+ * then `authHeaders(tokens)`). Boot warms openai/xai even with no tokens —
+ * `getOAuthProviderConfig` only reports that a provider SUPPORTS OAuth — so the
+ * entry built at boot is an API-key-path factory. Signing in later saved tokens
+ * that nothing re-read: the stale factory stayed registered and the provider
+ * kept failing until the next process start. That is the "OAuth only works
+ * after I restart the session" report; the same held for a key set via `K` on a
+ * provider skipped at boot for "no credentials".
+ *
+ * warmProviderFactories() cannot be reused for this: it deliberately SKIPS a
+ * provider that already has a factory. The registry is last-built-wins, so
+ * building again is what replaces the stale entry.
+ */
+export declare function rewarmProviderFactory(id: ProviderId): Promise<boolean>;
+export declare function warmProviderFactories(): Promise<WarmResult>;