muonroi-cli 1.3.4 → 1.4.1

package/dist/src/providers/auth/grok-oauth.js

@@ -0,0 +1,341 @@
+/**
+ * src/providers/auth/grok-oauth.ts
+ *
+ * xAI / Grok subscription OAuth — Authorization Code + PKCE with loopback
+ * redirect (SuperGrok / X Premium+). No XAI_API_KEY required: the user logs in
+ * once via accounts/auth.x.ai and the access token is used as a Bearer against
+ * the standard xAI API base (https://api.x.ai/v1), which is OpenAI-compatible
+ * and accepts the token on both /chat/completions and /responses.
+ *
+ * Flow (mirrors gemini-oauth.ts, with xAI-specific authorize params):
+ *   1. Spawn a loopback HTTP server (OS-assigned port — xAI's OAuth client
+ *      allows arbitrary 127.0.0.1 ports per RFC 8252; pi-grok confirms this
+ *      with its listen(0) fallback).
+ *   2. Open the browser at https://auth.x.ai/oauth2/authorize with PKCE S256,
+ *      plus xAI extras (`plan=generic` selects the subscription tier,
+ *      `referrer` is a free-text client tag, `nonce` for OIDC).
+ *   3. User signs in; xAI redirects back to the loopback URL with ?code&state.
+ *   4. POST /oauth2/token (grant_type=authorization_code + code_verifier) for
+ *      access/refresh tokens. Public client — no client_secret (PKCE only).
+ *
+ * client_id: a shared public xAI desktop OAuth client (NOT a secret — RFC 8252
+ * native clients embed it in public bundles by design). Same interoperability
+ * pattern as the published Codex CLI client_id used in openai-oauth.ts. Sourced
+ * from the MIT-licensed pi-grok OSS project and cross-checked against the live
+ * xAI OIDC discovery document; override via MUONROI_XAI_CLIENT_ID.
+ */
+import { exec } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import * as readline from "node:readline";
+import { startOAuthCallbackServer } from "../../mcp/oauth-callback.js";
+import { exchangeBrowserCode, generatePKCE, refreshBrowserTokens } from "./browser-flow.js";
+import { OAuthLoginError, OAuthRefreshError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const XAI_ISSUER = "https://auth.x.ai";
+/**
+ * Shared public xAI desktop OAuth client_id (see file header). Override via
+ * MUONROI_XAI_CLIENT_ID. Rotate when xAI rotates the shared client.
+ */
+const XAI_CLIENT_ID = process.env.MUONROI_XAI_CLIENT_ID ?? "b1a00492-073a-47ea-816f-4c329264a828";
+/**
+ * Scopes accepted by xAI's OAuth client (every entry is in the live discovery
+ * `scopes_supported`): `grok-cli:access` + `api:access` grant API access on the
+ * subscription, `offline_access` yields a refresh token.
+ */
+const XAI_SCOPES = ["openid", "profile", "email", "offline_access", "grok-cli:access", "api:access"];
+/** Selects xAI's generic OAuth plan tier (subscription-tier selection param). */
+const XAI_PLAN = "generic";
+/** Free-text client identifier sent on the authorize request (not auth-significant). */
+const XAI_REFERRER = "muonroi-cli";
+// Pre-emptive refresh window: refresh when the token expires within 60 seconds.
+const REFRESH_WINDOW_MS = 60_000;
+// Loopback callback timeout: 5 minutes for the user to complete browser login.
+const CALLBACK_TIMEOUT_MS = 5 * 60_000;
+function defaultOpenBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    if (platform === "win32") {
+        cmd = `start "" "${url}"`;
+    }
+    else if (platform === "darwin") {
+        cmd = `open "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, () => {
+        // fire-and-forget — errors non-fatal (user can open the URL manually)
+    });
+}
+// ---------------------------------------------------------------------------
+// Mutex — prevents double-refresh under concurrent requests
+// ---------------------------------------------------------------------------
+class Mutex {
+    _locked = false;
+    _queue = [];
+    async acquire() {
+        if (!this._locked) {
+            this._locked = true;
+            return () => this._release();
+        }
+        return new Promise((resolve) => {
+            this._queue.push(() => {
+                this._locked = true;
+                resolve(() => this._release());
+            });
+        });
+    }
+    _release() {
+        const next = this._queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._locked = false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// GrokOAuthProvider
+// ---------------------------------------------------------------------------
+export class GrokOAuthProvider {
+    providerId = "xai";
+    issuer;
+    clientId;
+    fetchFn;
+    callbackServerFn;
+    openBrowserFn;
+    mutex = new Mutex();
+    constructor(opts = {}) {
+        this.issuer = opts.issuer ?? XAI_ISSUER;
+        this.clientId = opts.clientId ?? XAI_CLIENT_ID;
+        this.fetchFn = opts.fetchFn ?? globalThis.fetch.bind(globalThis);
+        this.callbackServerFn = opts.callbackServerFn ?? startOAuthCallbackServer;
+        this.openBrowserFn = opts.openBrowserFn ?? defaultOpenBrowser;
+    }
+    // -------------------------------------------------------------------------
+    // login
+    // -------------------------------------------------------------------------
+    async login(opts = {}) {
+        const { codeVerifier, codeChallenge } = generatePKCE();
+        const state = randomBytes(16).toString("base64url");
+        const nonce = randomBytes(16).toString("base64url");
+        let callbackServer;
+        let authCode;
+        let receivedState = "";
+        try {
+            // We race the normal loopback HTTP callback against a manual code paste.
+            // xAI's current auth page for this client_id sometimes shows a "Could not
+            // establish connection" screen + a code to copy (instead of redirecting
+            // to the loopback URI). Supporting manual paste makes the flow robust.
+            const httpCodePromise = new Promise((resolve, reject) => {
+                const loginTimeout = setTimeout(() => {
+                    reject(new Error("OAuth browser callback timed out"));
+                }, CALLBACK_TIMEOUT_MS);
+                this.callbackServerFn({
+                    onCode: (code, s) => {
+                        receivedState = s;
+                        clearTimeout(loginTimeout);
+                        resolve(code);
+                    },
+                    timeoutMs: CALLBACK_TIMEOUT_MS,
+                })
+                    .then((server) => {
+                    callbackServer = server;
+                    const authorizeUrl = buildXAIAuthorizeUrl({
+                        authEndpoint: `${this.issuer}/oauth2/authorize`,
+                        clientId: this.clientId,
+                        redirectUri: server.url,
+                        scopes: XAI_SCOPES,
+                        codeChallenge,
+                        state,
+                        nonce,
+                    });
+                    opts.onUserCode?.(authorizeUrl, authorizeUrl);
+                    this.openBrowserFn(authorizeUrl);
+                    // Simple manual token/code input fallback (when redirect fails and xAI page shows a code)
+                    if (process.stdin.isTTY) {
+                        const rl = readline.createInterface({ input: process.stdin });
+                        console.log('  If the xAI page shows a code ("Could not establish connection") instead of redirecting,');
+                        console.log("  copy the code and paste it here then press Enter:");
+                        rl.on("line", (line) => {
+                            const c = line.trim();
+                            if (c.length > 30) {
+                                rl.close();
+                                clearTimeout(loginTimeout);
+                                resolve(c);
+                            }
+                        });
+                    }
+                })
+                    .catch((err) => {
+                    clearTimeout(loginTimeout);
+                    reject(err);
+                });
+            });
+            authCode = await httpCodePromise;
+        }
+        catch (err) {
+            callbackServer?.close();
+            throw new OAuthLoginError("xai", String(err));
+        }
+        finally {
+            callbackServer?.close();
+        }
+        if (receivedState && receivedState !== state) {
+            throw new OAuthLoginError("xai", "OAuth state mismatch — possible CSRF, aborting.");
+        }
+        let tokenResponse;
+        try {
+            tokenResponse = await exchangeBrowserCode({
+                tokenEndpoint: `${this.issuer}/oauth2/token`,
+                clientId: this.clientId,
+                redirectUri: callbackServer?.url ?? "",
+                code: authCode,
+                codeVerifier,
+                fetchFn: this.fetchFn,
+            });
+        }
+        catch (err) {
+            throw new OAuthLoginError("xai", String(err));
+        }
+        const expiresAt = Date.now() + (tokenResponse.expires_in ?? 3600) * 1000;
+        const email = extractIdTokenClaim(tokenResponse.id_token, "email");
+        return {
+            accessToken: tokenResponse.access_token,
+            refreshToken: tokenResponse.refresh_token ?? "",
+            idToken: tokenResponse.id_token,
+            expiresAt,
+            email,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // refresh
+    // -------------------------------------------------------------------------
+    async refresh(tokens) {
+        const release = await this.mutex.acquire();
+        try {
+            if (tokens.expiresAt - Date.now() > REFRESH_WINDOW_MS) {
+                return tokens;
+            }
+            let data;
+            try {
+                data = await refreshBrowserTokens({
+                    tokenEndpoint: `${this.issuer}/oauth2/token`,
+                    clientId: this.clientId,
+                    refreshToken: tokens.refreshToken,
+                    fetchFn: this.fetchFn,
+                });
+            }
+            catch (err) {
+                throw new OAuthRefreshError("xai", String(err));
+            }
+            const expiresAt = Date.now() + (data.expires_in ?? 3600) * 1000;
+            return {
+                accessToken: data.access_token,
+                // xAI may not rotate refresh tokens — fall back to the existing one.
+                refreshToken: data.refresh_token ?? tokens.refreshToken,
+                idToken: data.id_token ?? tokens.idToken,
+                expiresAt,
+                email: tokens.email,
+            };
+        }
+        finally {
+            release();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // revoke
+    // -------------------------------------------------------------------------
+    async revoke(tokens) {
+        try {
+            const token = tokens.refreshToken || tokens.accessToken;
+            const body = new URLSearchParams({ client_id: this.clientId, token });
+            await this.fetchFn(`${this.issuer}/oauth2/revoke`, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: body.toString(),
+            });
+        }
+        catch {
+            // best-effort — caller deletes local tokens regardless
+        }
+    }
+    // -------------------------------------------------------------------------
+    // authHeaders
+    // -------------------------------------------------------------------------
+    authHeaders(tokens) {
+        // xAI uses a plain Bearer token — no account-id header (unlike OpenAI's
+        // ChatGPT-Account-ID).
+        return { Authorization: `Bearer ${tokens.accessToken}` };
+    }
+}
+function buildXAIAuthorizeUrl(opts) {
+    // Build the query string by hand — the generic buildAuthorizeUrl() injects
+    // Google-specific params (access_type=offline, prompt=consent) that xAI's
+    // auth backend does not expect.
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: opts.clientId,
+        redirect_uri: opts.redirectUri,
+        scope: opts.scopes.join(" "),
+        code_challenge: opts.codeChallenge,
+        code_challenge_method: "S256",
+        state: opts.state,
+        nonce: opts.nonce,
+        plan: XAI_PLAN,
+        referrer: XAI_REFERRER,
+    });
+    return `${opts.authEndpoint}?${params.toString()}`;
+}
+/**
+ * Decode the JWT payload (middle segment) and return a top-level claim.
+ * Returns undefined for malformed / missing tokens — email is best-effort and
+ * the login flow does not fail without it.
+ */
+function extractIdTokenClaim(idToken, key) {
+    if (!idToken)
+        return undefined;
+    const parts = idToken.split(".");
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const payload = Buffer.from(parts[1] ?? "", "base64url").toString("utf8");
+        return JSON.parse(payload)[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+/** Default Grok OAuth provider singleton (uses live xAI endpoints). */
+export const grokOAuth = new GrokOAuthProvider();
+// ---------------------------------------------------------------------------
+// Convenience: load + auto-refresh tokens
+// ---------------------------------------------------------------------------
+/**
+ * Load stored xAI OAuth tokens and auto-refresh if within the expiry window.
+ * Returns null if no tokens are stored.
+ */
+export async function loadGrokTokensWithRefresh(oauthProvider) {
+    const { loadTokens, saveTokens } = await import("./token-store.js");
+    let tokens = await loadTokens("xai");
+    if (!tokens)
+        return null;
+    const impl = oauthProvider ?? grokOAuth;
+    if (Date.now() >= tokens.expiresAt - REFRESH_WINDOW_MS) {
+        try {
+            tokens = await impl.refresh(tokens);
+            await saveTokens("xai", tokens);
+        }
+        catch {
+            // Return stale tokens — the adapter will get a 401 on the real request.
+        }
+    }
+    return tokens;
+}
+//# sourceMappingURL=grok-oauth.js.map

package/dist/src/providers/auth/registry.js

@@ -62,6 +62,23 @@ export async function loadOAuthRegistry() {
     catch {
         /* gemini-oauth unavailable */
     }
+    try {
+        const { grokOAuth, loadGrokTokensWithRefresh } = await import("./grok-oauth.js");
+        r.xai = {
+            provider: grokOAuth,
+            displayName: "xAI (Grok)",
+            // xAI subscription (SuperGrok / X Premium+) OAuth tokens hit the SAME
+            // api.x.ai/v1 host as API-key auth (unlike OpenAI, whose subscription
+            // tokens require a separate ChatGPT backend). baseURL is therefore left
+            // undefined so the api-key endpoint from endpoints.ts flows through; the
+            // strategy injects the Bearer header on the OpenAI-compatible path.
+            useResponsesApi: true,
+            loadTokensWithRefresh: () => loadGrokTokensWithRefresh(),
+        };
+    }
+    catch {
+        /* grok-oauth unavailable */
+    }
     _registry = r;
     return r;
 }

package/dist/src/providers/auth/token-store.js

@@ -21,7 +21,7 @@ function oauthAccount(provider) {
  * Override for tests — set process.env.MUONROI_AUTH_DIR to point at a temp dir.
  */
 function fallbackDir() {
-    return process.env["MUONROI_AUTH_DIR"] ?? path.join(os.homedir(), ".muonroi-cli", "auth");
+    return process.env.MUONROI_AUTH_DIR ?? path.join(os.homedir(), ".muonroi-cli", "auth");
 }
 function fallbackPath(provider) {
     return path.join(fallbackDir(), `${provider}.json`);

package/dist/src/providers/capabilities.js

@@ -26,7 +26,6 @@
  */
 import { createHash } from "node:crypto";
 import { consoleUrlFor } from "./endpoints.js";
-import { stripReasoningForSiliconflow } from "./siliconflow-history.js";
 /**
  * Default capability set — the "reliable provider" answers. Subclasses
  * override individual methods when the provider has a known quirk.
@@ -163,6 +162,10 @@ class XAIProviderCapabilities extends ReliableProviderCapabilities {
  * malformed bodies before the model fell back to free-form text.
  */
 class DeepSeekProviderCapabilities extends ReliableProviderCapabilities {
+    /** Namespace used for openai-compatible providerOptions merge. Overridden by SiliconFlow. */
+    providerNamespace() {
+        return "deepseek";
+    }
     supportsResponseTool(taskType) {
         if (taskType === "general")
             return false;
@@ -176,24 +179,15 @@ class DeepSeekProviderCapabilities extends ReliableProviderCapabilities {
         // in src/cli/cost-forensics.ts).
         return { readField: "promptCacheHitTokens", creationSupported: false };
     }
-    // DeepSeek docs (Reasoning Model guide): "Previous reasoning content is
-    // deliberately excluded from subsequent message contexts — only final
-    // answers (content) are retained in conversation history." Stripping
-    // reasoning parts on the way out matches the documented expectation and
-    // also no-ops on non-reasoning turns (identity returned by reference).
-    sanitizeHistory(messages) {
-        return stripReasoningForSiliconflow(messages);
-    }
 }
 /**
- * SiliconFlow shares DeepSeek's tool-call quirk and inherits the
- * reasoning-strip from DeepSeek. The strip was originally added here when
- * SiliconFlow returned HTTP 400 code 20015 ("reasoning_content must be
- * passed back") — see siliconflow-history.ts for wire evidence — but the
- * DeepSeek native endpoint behaves the same way per docs, so the override
- * now lives on the DeepSeek base class.
+ * SiliconFlow shares DeepSeek's `<｜DSML｜>` tool-call quirk; everything else
+ * (cache metric layout, signup URL pointer) differs only by namespace.
  */
 class SiliconflowProviderCapabilities extends DeepSeekProviderCapabilities {
+    providerNamespace() {
+        return "siliconflow";
+    }
     consoleSignupURL() {
         return consoleUrlFor("siliconflow");
     }

package/dist/src/providers/keychain.js

@@ -74,8 +74,20 @@ export async function setKeyForProvider(provider, key) {
     if (!kt?.setPassword)
         return false;
     redactor.enrollSecret(key);
-    await kt.setPassword(KEYCHAIN_SERVICE, ACCOUNT_BY_PROVIDER[provider], key);
-    return true;
+    try {
+        await kt.setPassword(KEYCHAIN_SERVICE, ACCOUNT_BY_PROVIDER[provider], key);
+        return true;
+    }
+    catch (err) {
+        // Runtime backend failure is common on Linux when libsecret / secret service
+        // (gnome-keyring, kwallet/ksecretd, etc.) is not installed, the collection is
+        // locked, or no D-Bus session/keyring is active for this user.
+        // The caller (e.g. keys import-bw / keys set) will print the friendly message.
+        if (process.env.DEBUG || process.env.MUONROI_DEBUG_KEYCHAIN) {
+            console.error(`[keychain] setPassword backend error for ${provider}:`, err?.message || err);
+        }
+        return false;
+    }
 }
 /**
  * Delete a stored key. Returns true if a key was deleted, false if none was

package/dist/src/providers/mcp-vision-bridge.js

@@ -48,27 +48,27 @@ const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bm
  * Downstream agents consume this JSON directly instead of re-parsing markdown.
  * Kept embedded in the prompt (not strict JSON-schema mode) for cross-provider portability.
  */
-export const UI_LAYOUT_SCHEMA_HINT = `{
-  "viewport": { "width": number, "height": number, "deviceClass": "mobile" | "tablet" | "desktop" },
-  "tokens": {
-    "colors": [{ "name": string, "hex": string, "role": "primary" | "secondary" | "accent" | "bg" | "fg" | "border" | "muted" }],
-    "typography": [{ "role": "heading" | "body" | "caption" | "label", "fontFamily": string, "sizePx": number, "weight": number }],
-    "spacingScalePx": number[],
-    "radiusScalePx": number[]
-  },
-  "layout": { "type": "stack" | "grid" | "flex" | "absolute", "direction": "row" | "column", "gapPx": number, "columns": number | null },
-  "components": [{
-    "id": string,
-    "role": "button" | "input" | "card" | "nav" | "header" | "footer" | "image" | "icon" | "text" | "list" | "modal" | "tabs" | "table" | "chart" | "container" | "other",
-    "label": string,
-    "text": string | null,
-    "bbox": { "x": number, "y": number, "w": number, "h": number },
-    "style": { "bgHex": string | null, "fgHex": string | null, "borderHex": string | null, "radiusPx": number | null, "shadow": string | null },
-    "state": "default" | "hover" | "active" | "disabled" | "focus" | "error",
-    "children": string[]
-  }],
-  "hierarchy": [{ "level": 1 | 2 | 3, "text": string, "componentId": string }],
-  "notes": string[]
+export const UI_LAYOUT_SCHEMA_HINT = `{
+  "viewport": { "width": number, "height": number, "deviceClass": "mobile" | "tablet" | "desktop" },
+  "tokens": {
+    "colors": [{ "name": string, "hex": string, "role": "primary" | "secondary" | "accent" | "bg" | "fg" | "border" | "muted" }],
+    "typography": [{ "role": "heading" | "body" | "caption" | "label", "fontFamily": string, "sizePx": number, "weight": number }],
+    "spacingScalePx": number[],
+    "radiusScalePx": number[]
+  },
+  "layout": { "type": "stack" | "grid" | "flex" | "absolute", "direction": "row" | "column", "gapPx": number, "columns": number | null },
+  "components": [{
+    "id": string,
+    "role": "button" | "input" | "card" | "nav" | "header" | "footer" | "image" | "icon" | "text" | "list" | "modal" | "tabs" | "table" | "chart" | "container" | "other",
+    "label": string,
+    "text": string | null,
+    "bbox": { "x": number, "y": number, "w": number, "h": number },
+    "style": { "bgHex": string | null, "fgHex": string | null, "borderHex": string | null, "radiusPx": number | null, "shadow": string | null },
+    "state": "default" | "hover" | "active" | "disabled" | "focus" | "error",
+    "children": string[]
+  }],
+  "hierarchy": [{ "level": 1 | 2 | 3, "text": string, "componentId": string }],
+  "notes": string[]
 }`;
 const MIME_MAP = {
     ".png": "image/png",
@@ -319,33 +319,33 @@ export async function askVisionProxy(question, imageIdOrPath, cwd, signal) {
 export function getVisionGuidanceForTextOnly(modelId) {
     if (!needsVisionProxy(modelId))
         return "";
-    return `
-VISION PROXY (text-only model):
-You cannot see images directly. You have vision proxy tools to work with ANY image:
-
-TOOLS:
-- analyze_image: Proactively analyze an image from a file path, URL, or base64. Use this FIRST when you encounter or need to work with an image.
-- ask_vision_proxy: Ask a specific follow-up question about any cached image (or provide a file path for a new image).
-- list_vision_cache: See all cached images available for querying.
-
-WHEN TO USE (be PROACTIVE, not passive):
-- User mentions an image file → analyze_image immediately
-- User pastes or references a screenshot → it's auto-analyzed, use ask_vision_proxy for details
-- Working with UI/web pages → prefer browser_snapshot (text-based), use screenshot + ask_vision_proxy when visual details matter
-- Reviewing design mockups, diagrams, charts → analyze_image the file
-- Debugging visual issues (CSS, layout, colors) → take screenshot, then ask_vision_proxy specific questions
-- Comparing before/after → analyze both images, ask about differences
-- Reading text from images (OCR) → analyze_image with a question like "transcribe all text"
-- Any file with image extension (.png, .jpg, .gif, .webp, .svg, etc.) → analyze_image
-
-WORKFLOW:
-1. Encounter image → analyze_image (or it's auto-analyzed from tool results)
-2. Need more detail → ask_vision_proxy with specific question
-3. Need to verify changes → take new screenshot/analyze new image → compare
-
-Images are cached (up to ${IMAGE_CACHE_MAX}, ${IMAGE_CACHE_TTL_MS / 60000}min TTL). You can reference them by ID for follow-ups.
-
-IMPORTANT: Do NOT guess what an image contains. Always use the proxy to get accurate information.
+    return `
+VISION PROXY (text-only model):
+You cannot see images directly. You have vision proxy tools to work with ANY image:
+
+TOOLS:
+- analyze_image: Proactively analyze an image from a file path, URL, or base64. Use this FIRST when you encounter or need to work with an image.
+- ask_vision_proxy: Ask a specific follow-up question about any cached image (or provide a file path for a new image).
+- list_vision_cache: See all cached images available for querying.
+
+WHEN TO USE (be PROACTIVE, not passive):
+- User mentions an image file → analyze_image immediately
+- User pastes or references a screenshot → it's auto-analyzed, use ask_vision_proxy for details
+- Working with UI/web pages → prefer browser_snapshot (text-based), use screenshot + ask_vision_proxy when visual details matter
+- Reviewing design mockups, diagrams, charts → analyze_image the file
+- Debugging visual issues (CSS, layout, colors) → take screenshot, then ask_vision_proxy specific questions
+- Comparing before/after → analyze both images, ask about differences
+- Reading text from images (OCR) → analyze_image with a question like "transcribe all text"
+- Any file with image extension (.png, .jpg, .gif, .webp, .svg, etc.) → analyze_image
+
+WORKFLOW:
+1. Encounter image → analyze_image (or it's auto-analyzed from tool results)
+2. Need more detail → ask_vision_proxy with specific question
+3. Need to verify changes → take new screenshot/analyze new image → compare
+
+Images are cached (up to ${IMAGE_CACHE_MAX}, ${IMAGE_CACHE_TTL_MS / 60000}min TTL). You can reference them by ID for follow-ups.
+
+IMPORTANT: Do NOT guess what an image contains. Always use the proxy to get accurate information.
 `;
 }
 // Keep backward compat export
@@ -539,7 +539,7 @@ function buildContextualPrompt(imageCount, context) {
             const hint = context.hint ? `\nContext: ${context.hint}` : "";
             return (base +
                 [
-                    "Provide a comprehensive analysis:" + hint,
+                    `Provide a comprehensive analysis:${hint}`,
                     "- Describe what the image shows overall",
                     "- Transcribe any visible text exactly",
                     "- Note colors, layout, and important visual details",