@acmecloud/core 1.0.2

package/src/config/index.ts

@@ -0,0 +1,383 @@
+import { config } from "dotenv";
+import { resolve, join } from "path";
+import { homedir } from "os";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+
+// Load environment variables from .env in project root if it exists
+config({ quiet: true });
+
+// Load environment variables from ~/.acmecode/.env if it exists
+config({ path: resolve(homedir(), ".acmecode", ".env"), quiet: true });
+
+export interface ModelConfig {
+  provider: string;
+  model: string;
+  visionProvider?: string;
+  visionModel?: string;
+}
+
+export interface ProviderSettings {
+  apiKey: string;
+  baseUrl?: string;
+  isCustom?: boolean;
+  protocol?: string;
+}
+
+export type AgentMode = "plan" | "code" | "agent" | "zen";
+export type ReasoningLevel = "low" | "medium" | "high" | "max" | "xhigh";
+
+const GLOBAL_CONFIG_DIR = resolve(homedir(), ".acmecode");
+const GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, "config.json");
+
+function getProjectConfigDir(): string {
+  return resolve(process.cwd(), ".acmecode");
+}
+
+function getProjectConfigFile(): string {
+  return join(getProjectConfigDir(), "config.json");
+}
+
+function readJsonFile(filePath: string): any {
+  try {
+    if (existsSync(filePath)) {
+      return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+  } catch {}
+  return null;
+}
+
+function writeJsonFile(filePath: string, data: any): void {
+  const dir = resolve(filePath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+/**
+ * Load model config with priority: project .acmecode/config.json > global ~/.acmecode/config.json > defaults
+ */
+export function loadModelConfig(): ModelConfig {
+  const projectConfig = readJsonFile(getProjectConfigFile());
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+
+  // Resolve with priority: project > global > defaults
+  const provider =
+    projectConfig?.provider || globalConfig?.provider || "extralink";
+  const model = projectConfig?.model || globalConfig?.model || "";
+  const visionProvider =
+    projectConfig?.visionProvider || globalConfig?.visionProvider;
+  const visionModel = projectConfig?.visionModel || globalConfig?.visionModel;
+
+  return { provider, model, visionProvider, visionModel };
+}
+
+/**
+ * Load language config with priority: project .acmecode/config.json > global ~/.acmecode/config.json > default "en"
+ */
+export function loadLangConfig(): string {
+  const projectConfig = readJsonFile(getProjectConfigFile());
+  if (projectConfig?.lang) return projectConfig.lang;
+
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  if (globalConfig?.lang) return globalConfig.lang;
+
+  return "en";
+}
+
+/**
+ * Load theme config with priority: project .acmecode/config.json > global ~/.acmecode/config.json > default "dark"
+ */
+export function loadThemeConfig(): string {
+  const projectConfig = readJsonFile(getProjectConfigFile());
+  if (projectConfig?.theme) return projectConfig.theme;
+
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  if (globalConfig?.theme) return globalConfig.theme;
+
+  return "dark";
+}
+
+/**
+ * Load reasoning level config with priority: project .acmecode/config.json > global ~/.acmecode/config.json > default "medium"
+ */
+export function loadReasoningLevel(): ReasoningLevel {
+  const projectConfig = readJsonFile(getProjectConfigFile());
+  if (projectConfig?.reasoning)
+    return projectConfig.reasoning as ReasoningLevel;
+
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  if (globalConfig?.reasoning) return globalConfig.reasoning as ReasoningLevel;
+
+  return "medium";
+}
+
+/**
+ * Load agent mode config with priority: project .acmecode/config.json > default "agent"
+ */
+export function loadAgentModeConfig(): { mode: AgentMode; planFile?: string } {
+  const projectConfig = readJsonFile(getProjectConfigFile());
+  return {
+    mode: (projectConfig?.agentMode as AgentMode) || "agent",
+    planFile: projectConfig?.activePlanFile,
+  };
+}
+
+/**
+ * Save model config to the project's .acmecode/config.json
+ */
+export function saveProjectModelConfig(
+  provider: string,
+  model: string,
+  visionProvider?: string,
+  visionModel?: string,
+): void {
+  const filePath = getProjectConfigFile();
+  const existing = readJsonFile(filePath) || {};
+  existing.provider = provider;
+  existing.model = model;
+  if (visionProvider) existing.visionProvider = visionProvider;
+  if (visionModel) existing.visionModel = visionModel;
+  writeJsonFile(filePath, existing);
+}
+
+/**
+ * Save agent mode config to the project's .acmecode/config.json
+ */
+export function saveAgentModeConfig(mode: AgentMode, planFile?: string): void {
+  const filePath = getProjectConfigFile();
+  const existing = readJsonFile(filePath) || {};
+  existing.agentMode = mode;
+  if (planFile !== undefined) {
+    existing.activePlanFile = planFile;
+  } else {
+    delete existing.activePlanFile;
+  }
+  writeJsonFile(filePath, existing);
+}
+
+/**
+ * Save model config to the global ~/.acmecode/config.json
+ */
+export function saveGlobalModelConfig(provider: string, model: string): void {
+  const existing = readJsonFile(GLOBAL_CONFIG_FILE) || {};
+  existing.provider = provider;
+  existing.model = model;
+  writeJsonFile(GLOBAL_CONFIG_FILE, existing);
+}
+
+/**
+ * Save language config to the global ~/.acmecode/config.json
+ */
+export function saveGlobalLangConfig(lang: string): void {
+  const existing = readJsonFile(GLOBAL_CONFIG_FILE) || {};
+  existing.lang = lang;
+  writeJsonFile(GLOBAL_CONFIG_FILE, existing);
+}
+
+/**
+ * Save theme config to the global ~/.acmecode/config.json
+ */
+export function saveGlobalThemeConfig(theme: string): void {
+  const existing = readJsonFile(GLOBAL_CONFIG_FILE) || {};
+  existing.theme = theme;
+  writeJsonFile(GLOBAL_CONFIG_FILE, existing);
+}
+
+/**
+ * Save reasoning level config to the global ~/.acmecode/config.json
+ */
+export function saveGlobalReasoningLevel(level: ReasoningLevel): void {
+  const existing = readJsonFile(GLOBAL_CONFIG_FILE) || {};
+  writeJsonFile(GLOBAL_CONFIG_FILE, existing);
+}
+
+/**
+ * Save provider-specific settings to ~/.acmecode/config.json
+ */
+export function saveProviderConfig(
+  provider: string,
+  config: ProviderSettings,
+): void {
+  const existing = readJsonFile(GLOBAL_CONFIG_FILE) || {};
+  if (!existing.providers) existing.providers = {};
+  existing.providers[provider] = config;
+  writeJsonFile(GLOBAL_CONFIG_FILE, existing);
+}
+
+/**
+ * Load all custom providers from global config
+ */
+export function loadCustomProviders(): Record<string, ProviderSettings> {
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  const providers = globalConfig?.providers || {};
+  const customs: Record<string, ProviderSettings> = {};
+  const officialIds = [
+    "extralink",
+    "openai",
+    "anthropic",
+    "google",
+    "xai",
+    "mistral",
+    "groq",
+    "deepinfra",
+    "openrouter",
+  ];
+
+  for (const [id, cfg] of Object.entries(providers)) {
+    if ((cfg as any).isCustom || !officialIds.includes(id)) {
+      customs[id] = cfg as ProviderSettings;
+    }
+  }
+  return customs;
+}
+
+export const getProviderKey = (provider: string) => {
+  // 1. Check saved config in ~/.acmecode/config.json
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  if (globalConfig?.providers?.[provider]?.apiKey) {
+    return globalConfig.providers[provider].apiKey;
+  }
+
+  // 2. Check environment variables
+  switch (provider) {
+    case "extralink":
+      return (
+        process.env.EXTRALINK_API_KEY ||
+        "sk-7qwFHXqvDgqTMfswYhgnMDoAWNU2zneozvFgI9DaR5Cpx49w"
+      );
+    case "openai":
+      return (
+        process.env.OPENAI_API_KEY ||
+        "sk-Plobc3VM4qzRkIUAakQjtj7hwHPedlSoU4haaPNWWNIESiya"
+      );
+    case "anthropic":
+      return process.env.ANTHROPIC_API_KEY;
+    case "google":
+      return process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+    case "xai":
+      return process.env.XAI_API_KEY;
+    case "mistral":
+      return process.env.MISTRAL_API_KEY;
+    case "groq":
+      return process.env.GROQ_API_KEY;
+    case "deepinfra":
+      return process.env.DEEPINFRA_API_KEY;
+    case "openrouter":
+      return process.env.OPENROUTER_API_KEY;
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Normalizes a base URL by removing trailing slashes and ensuring consistency.
+ */
+export const normalizeBaseUrl = (
+  url: string | undefined,
+): string | undefined => {
+  if (!url) return undefined;
+  return url.replace(/\/+$/, "");
+};
+
+/**
+ * Intelligently adapts a base URL for a given protocol if version segments are missing.
+ */
+export const getAdaptedBaseUrl = (
+  protocol: string,
+  baseUrl: string | undefined,
+): string | undefined => {
+  if (!baseUrl) return undefined;
+  const clean = baseUrl.replace(/\/+$/, "");
+
+  // Official or well-known protocols often expect version segments
+  if (protocol === "anthropic" && !clean.includes("/v1")) {
+    return `${clean}/v1`;
+  }
+  if (protocol === "google" && !clean.includes("/v1")) {
+    // google usually expects /v1 or /v1beta for the SDK
+    return `${clean}/v1beta`;
+  }
+  if (
+    protocol === "openai" &&
+    !clean.includes("/v1") &&
+    !clean.includes("/web")
+  ) {
+    // Many OpenAI relays use /v1, but some use root. We'll leave root as is
+    // but normalize to clean for now.
+  }
+
+  return clean;
+};
+
+export const getProviderBaseUrl = (provider: string) => {
+  // 1. Check saved config in ~/.acmecode/config.json
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  const saved = globalConfig?.providers?.[provider];
+  if (saved?.baseUrl) {
+    return getAdaptedBaseUrl(saved.protocol || "openai", saved.baseUrl);
+  }
+
+  // 2. Check environment variables or official defaults
+  let url: string | undefined;
+  const protocol = getProviderProtocol(provider);
+  switch (provider) {
+    case "extralink":
+      url = process.env.EXTRALINK_BASE_URL || "https://apis.extralink.net/v1";
+      break;
+    case "openai":
+      url = process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
+      break;
+    case "anthropic":
+      url = process.env.ANTHROPIC_BASE_URL || "https://api.anthropic.com/v1";
+      break;
+    case "google":
+      url =
+        process.env.GOOGLE_GENERATIVE_AI_BASE_URL ||
+        "https://generativelanguage.googleapis.com/v1beta";
+      break;
+    case "xai":
+      url = process.env.XAI_BASE_URL || "https://api.x.ai/v1";
+      break;
+    case "mistral":
+      url = process.env.MISTRAL_BASE_URL || "https://api.mistral.ai/v1";
+      break;
+    case "groq":
+      url = process.env.GROQ_BASE_URL || "https://api.groq.com/openai/v1";
+      break;
+    case "deepinfra":
+      url =
+        process.env.DEEPINFRA_BASE_URL || "https://api.deepinfra.com/v1/openai";
+      break;
+    case "openrouter":
+      url = process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1";
+      break;
+  }
+  return getAdaptedBaseUrl(protocol, url);
+};
+
+/**
+ * Get the protocol for a provider (e.g. 'openai', 'anthropic', 'google')
+ */
+export const getProviderProtocol = (provider: string): string => {
+  const globalConfig = readJsonFile(GLOBAL_CONFIG_FILE);
+  if (globalConfig?.providers?.[provider]?.protocol) {
+    return globalConfig.providers[provider].protocol;
+  }
+
+  // Default to provider ID for official ones, or 'openai' as safe fallback
+  const official = [
+    "extralink",
+    "openai",
+    "anthropic",
+    "google",
+    "xai",
+    "mistral",
+    "groq",
+    "deepinfra",
+    "openrouter",
+  ];
+  if (official.includes(provider)) return provider;
+
+  return "openai";
+};

package/src/context/index.ts

@@ -0,0 +1,34 @@
+import * as fs from 'fs/promises';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+export async function getProjectContext(): Promise<string> {
+    let context = '';
+
+    // 1. ACMECODE.md
+    try {
+        const acmecodePath = path.join(process.cwd(), 'ACMECODE.md');
+        const content = await fs.readFile(acmecodePath, 'utf8');
+        context += `\n\n[Project Instructions (ACMECODE.md)]\n${content}`;
+    } catch (e: any) {
+        // Ignore if missing
+    }
+
+    // 2. Git context
+    try {
+        const { stdout: branch } = await execAsync('git rev-parse --abbrev-ref HEAD');
+        const { stdout: status } = await execAsync('git status -s');
+        context += `\n\n[Git Status (Branch: ${branch.trim()})]\n${status.trim() || 'Clean working directory'}`;
+
+        // Let's also get the last commit message for context
+        const { stdout: log } = await execAsync('git log -1 --oneline');
+        context += `\nLast Commit: ${log.trim()}`;
+    } catch (e: any) {
+        // Ignore if not a git repo
+    }
+
+    return context;
+}

package/src/llm/provider.ts

@@ -0,0 +1,237 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createXai } from "@ai-sdk/xai";
+import { createMistral } from "@ai-sdk/mistral";
+import { createGroq } from "@ai-sdk/groq";
+import { createDeepInfra } from "@ai-sdk/deepinfra";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { LanguageModel } from "ai";
+import {
+  getProviderKey,
+  getProviderBaseUrl,
+  loadCustomProviders,
+  getProviderProtocol,
+} from "../config/index.js";
+
+// ── Supported provider types ──
+export type ProviderType =
+  | "extralink"
+  | "openai"
+  | "anthropic"
+  | "google"
+  | "xai"
+  | "mistral"
+  | "groq"
+  | "deepinfra"
+  | "openrouter";
+
+// ── Provider metadata for display ──
+export interface ProviderInfo {
+  id: ProviderType;
+  name: string;
+  envKey: string;
+}
+
+const OFFICIAL_PROVIDERS: ProviderInfo[] = [
+  {
+    id: "extralink",
+    name: "Extralink",
+    envKey: "EXTRALINK_API_KEY",
+  },
+  { id: "openai", name: "OpenAI", envKey: "OPENAI_API_KEY" },
+  { id: "anthropic", name: "Anthropic", envKey: "ANTHROPIC_API_KEY" },
+  { id: "google", name: "Google", envKey: "GOOGLE_GENERATIVE_AI_API_KEY" },
+  { id: "xai", name: "xAI (Grok)", envKey: "XAI_API_KEY" },
+  { id: "mistral", name: "Mistral", envKey: "MISTRAL_API_KEY" },
+  { id: "groq", name: "Groq", envKey: "GROQ_API_KEY" },
+  { id: "deepinfra", name: "DeepInfra", envKey: "DEEPINFRA_API_KEY" },
+  { id: "openrouter", name: "OpenRouter", envKey: "OPENROUTER_API_KEY" },
+];
+
+export function getProviders(): ProviderInfo[] {
+  const customs = loadCustomProviders();
+  const customList: ProviderInfo[] = Object.keys(customs).map((id) => ({
+    id: id as ProviderType,
+    name: id,
+    envKey: "CUSTOM",
+  }));
+
+  // Filter out custom providers that duplicate official ones
+  const officialIds = new Set(OFFICIAL_PROVIDERS.map((p) => p.id));
+  const filteredCustoms = customList.filter((c) => !officialIds.has(c.id));
+
+  return [...OFFICIAL_PROVIDERS, ...filteredCustoms];
+}
+
+// ── Dynamic provider registry ──
+// Each factory creates an AI SDK provider instance given an API key and optional base URL.
+type ProviderFactory = (
+  apiKey: string,
+  baseURL?: string,
+) => (modelName: string) => LanguageModel;
+
+const PROVIDER_REGISTRY: Record<ProviderType, ProviderFactory> = {
+  extralink: (apiKey, baseURL) => {
+    const sdk = createOpenAI({ apiKey, baseURL });
+    return (model) => sdk.chat(model) as LanguageModel;
+  },
+  openai: (apiKey, baseURL) => {
+    const sdk = createOpenAI({ apiKey, baseURL });
+    return (model) => sdk.chat(model) as LanguageModel;
+  },
+  anthropic: (apiKey, baseURL) => {
+    const sdk = createAnthropic({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  google: (apiKey, baseURL) => {
+    const sdk = createGoogleGenerativeAI({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  xai: (apiKey, baseURL) => {
+    const sdk = createXai({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  mistral: (apiKey, baseURL) => {
+    const sdk = createMistral({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  groq: (apiKey, baseURL) => {
+    const sdk = createGroq({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  deepinfra: (apiKey, baseURL) => {
+    const sdk = createDeepInfra({ apiKey, baseURL });
+    return (model) => sdk(model) as LanguageModel;
+  },
+  openrouter: (apiKey, baseURL) => {
+    const sdk = createOpenRouter({ apiKey, baseURL });
+    return (model) => sdk.chat(model) as LanguageModel;
+  },
+};
+
+/**
+ * Create a language model instance for the given provider and model name.
+ * Reads API key and optional base URL from the project/env configuration.
+ */
+export function getModel(
+  provider: ProviderType,
+  modelName: string,
+): LanguageModel {
+  const protocol = getProviderProtocol(provider) as ProviderType;
+  const factory = PROVIDER_REGISTRY[protocol];
+
+  const apiKey = getProviderKey(provider);
+  if (!apiKey) {
+    const info = getProviders().find((p) => p.id === provider);
+    throw new Error(
+      `${info?.envKey || provider.toUpperCase() + "_API_KEY"} is not set.`,
+    );
+  }
+
+  const baseURL = getProviderBaseUrl(provider);
+
+  if (!factory) {
+    // Fallback for custom providers if protocol is unknown: assume OpenAI-compatible
+    const sdk = createOpenAI({ apiKey, baseURL });
+    return sdk.chat(modelName) as LanguageModel;
+  }
+
+  const createModel = factory(apiKey, baseURL);
+  return createModel(modelName);
+}
+
+/**
+ * List all providers that have API keys configured.
+ */
+export function getAvailableProviders(): ProviderInfo[] {
+  return getProviders().filter((p) => {
+    try {
+      return !!getProviderKey(p.id);
+    } catch {
+      return false;
+    }
+  });
+}
+
+// ── Dynamic Context Size Caching ──
+let modelsDevCache: Record<string, number> | null = null;
+
+export async function fetchModelsDevCache(): Promise<void> {
+  try {
+    const res = await fetch("https://models.dev/api.json");
+    if (!res.ok) return;
+    const data = await res.json();
+    const cache: Record<string, number> = {};
+    for (const provider of Object.values(data)) {
+      const parsedProvider = provider as any;
+      if (parsedProvider?.models) {
+        for (const [modId, modData] of Object.entries(parsedProvider.models)) {
+          if ((modData as any)?.limit?.context) {
+            cache[modId] = (modData as any).limit.context;
+            cache[modId.toLowerCase()] = (modData as any).limit.context;
+          }
+        }
+      }
+    }
+    modelsDevCache = cache;
+  } catch {
+    // silently ignore fetch errors
+  }
+}
+
+/**
+ * Get the known context window size for a model.
+ */
+export function getContextWindow(modelName: string): number {
+  if (modelsDevCache) {
+    if (modelsDevCache[modelName]) return modelsDevCache[modelName]!;
+    if (modelsDevCache[modelName.toLowerCase()])
+      return modelsDevCache[modelName.toLowerCase()]!;
+    // Fuzzy match
+    for (const [key, val] of Object.entries(modelsDevCache)) {
+      if (
+        modelName.toLowerCase().includes(key) ||
+        key.includes(modelName.toLowerCase())
+      ) {
+        return val;
+      }
+    }
+  }
+
+  const lower = modelName.toLowerCase();
+
+  // ── User provided specifics from models.dev ──
+  if (lower.includes("kimi-k2.5")) return 262144;
+  if (lower.includes("llama-3.3")) return 131072;
+  if (lower.includes("phi-4")) return 32000;
+  if (lower.includes("gpt-oss")) return 65536;
+  if (lower.includes("magistral")) return 131072;
+  if (lower.includes("devstral")) return 32768;
+  if (lower.includes("voxtral")) return 32000;
+  if (lower.includes("whisper")) return 448;
+  if (lower.includes("e5-large")) return 512;
+
+  // ── Standard defaults ──
+  if (lower.includes("o1") || lower.includes("o3") || lower.includes("o4"))
+    return 128000;
+  if (lower.includes("claude-3-5")) return 200000;
+  if (lower.includes("claude-3")) return 200000;
+  if (lower.includes("gemini-1.5-pro")) return 2000000;
+  if (lower.includes("gemini-1.5-flash")) return 1000000;
+  if (lower.includes("gpt-4o")) return 128000;
+  if (lower.includes("gpt-4")) return 128000;
+  if (lower.includes("deepseek")) return 64000;
+  if (lower.includes("qwen")) return 32000;
+  return 32000; // conservative default
+}
+
+/**
+ * Heuristic to estimate token count from string content.
+ * Average 3.5 characters per token for mixed English/Chinese.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  // Basic heuristic: 1 token ≈ 3.0 characters (safer for mixed Code/Chinese which are token heavy)
+  return Math.ceil(text.length / 3.0);
+}

package/src/llm/vision.ts

@@ -0,0 +1,43 @@
+import { generateText } from 'ai';
+import { getModel } from './provider.js';
+import { ModelConfig } from '../config/index.js';
+
+/**
+ * Analyzes an image using a specialized vision model and returns a textual description.
+ * This allows non-vision primary models to "see" via delegation.
+ */
+export async function analyzeImage(
+    imageData: string, // base64
+    config: ModelConfig
+): Promise<string> {
+    if (!config.visionProvider || !config.visionModel) {
+        return "Error: Vision model not configured. Please set visionProvider and visionModel in config.";
+    }
+
+    const model = getModel(config.visionProvider as any, config.visionModel);
+
+    try {
+        const { text } = await generateText({
+            model,
+            abortSignal: AbortSignal.timeout(60000), // 60 seconds timeout
+            maxRetries: 3,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        { type: 'text', text: "Please describe this screenshot in detail. Focus on the layout, visible text, interactive elements (buttons, inputs), and any apparent errors or status messages. This description will be used by another AI to understand the state of the web application." },
+                        { type: 'image', image: imageData }
+                    ]
+                }
+            ]
+        });
+
+        return `[Vision Model Analysis (${config.visionModel})]:\n${text}`;
+    } catch (err: any) {
+        let msg = err.message;
+        if (err.name === 'TimeoutError' || err.message.includes('timeout')) {
+            msg = `Analysis timed out after 60s. The image might be too complex or the provider is slow.`;
+        }
+        return `Error during vision analysis: ${msg}`;
+    }
+}