@liustack/modlens 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 3.3.0 - 2026-08-07
+
+- Automatic provider failover. A run now tries every provider that is set up on this machine, in order, and the first good result wins: a provider that errors, times out, or returns a schema-violating result hands over to the next. A local image tries `antigravity-cli`, then `gemini-api`, `openai`, `anthropic`, `claude-cli`; a remote URL tries the inline API providers first and the agent last (only the inline download path runs the private-address guards, the magic-byte check, and the size cap), and `claude-cli` never joins the remote chain since it reads local files only. The result's `meta.attempts` records every provider tried with timings and failure reasons, and `meta.warnings` carries failover notices. `doctor` prints both chains. Availability (binary on PATH, required keys present) is one shared source of truth between the doctor's readiness report and the chain. The 3.2.0 remote-URL reroute is absorbed by the remote chain order.
+- Behavior change: `config set provider <name>` is now a preference, not a pin. It moves that provider to the front of its allowed region (for a remote URL an agent still stays behind the inline providers), and the rest of the chain backs it up on failure, matching modsearch's engine setting. To pin exactly one provider with no fallback, pass `-p <name>`, which keeps its original error when it fails.
+
 ## 3.2.0 - 2026-08-07
 
 - A remote image URL with no explicit `-p` now runs on `gemini-api` whenever a Gemini key is configured, even if the default provider is an agent. The inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the 25 MB cap; an agent fetching the URL on its own passes through none of those. Without a Gemini key the run stays on the configured default, a local image never reroutes, and an explicit `-p` always wins.

package/dist/main.js

@@ -28053,9 +28053,6 @@ function loadConfigFile(configPath = CONFIG_PATH) {
     );
   }
 }
-function defaultProviderName(config2) {
-  return config2.provider?.trim() || "antigravity-cli";
-}
 function resolveProviderSettings(providerName, config2, env = process.env) {
   const aliasNames = Object.entries(providerAliases()).filter(([alias, canonical]) => canonical === providerName && alias !== providerName).map(([alias]) => alias);
   const fromFile = {
@@ -28157,32 +28154,177 @@ function maskKey(key) {
   }
   return `${key.slice(0, 6)}...${key.slice(-2)}`;
 }
+const PROVIDER_DESCRIPTORS = [
+  {
+    name: "antigravity-cli",
+    kind: "subprocess",
+    bin: "agy",
+    install: "curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # sign in, then exit"
+  },
+  {
+    name: "gemini-api",
+    kind: "api",
+    required: [{ field: "apiKey", env: "GEMINI_API_KEY" }],
+    fix: "modlens config set gemini-api.apiKey <key>   # free key: https://aistudio.google.com"
+  },
+  {
+    name: "openai",
+    kind: "api",
+    required: [
+      { field: "baseUrl", env: "OPENAI_BASE_URL" },
+      { field: "apiKey", env: "OPENAI_API_KEY" },
+      { field: "model" }
+    ],
+    fix: "modlens config set openai.baseUrl <url> / openai.apiKey <key> / openai.model <name>"
+  },
+  {
+    name: "anthropic",
+    kind: "api",
+    required: [{ field: "apiKey", env: "ANTHROPIC_API_KEY" }],
+    fix: "modlens config set anthropic.apiKey <key>"
+  },
+  {
+    name: "claude-cli",
+    kind: "subprocess",
+    bin: "claude",
+    install: "install the Claude Code CLI, then run `claude` once to sign in"
+  }
+];
+function findOnPath(bin, env) {
+  const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const full = path.join(dir, bin);
+    try {
+      if (fs.statSync(full).isFile()) {
+        return full;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function providerAvailable(name, config2, env = process.env) {
+  const descriptor = PROVIDER_DESCRIPTORS.find((d) => d.name === name);
+  if (!descriptor) {
+    return false;
+  }
+  if (descriptor.kind === "subprocess") {
+    return findOnPath(descriptor.bin, env) !== null;
+  }
+  const settings = resolveProviderSettings(name, config2, env);
+  return (descriptor.required ?? []).every((req) => Boolean(settings[req.field]?.trim()));
+}
+const LOCAL_FAILOVER_ORDER = [
+  "antigravity-cli",
+  "gemini-api",
+  "openai",
+  "anthropic",
+  "claude-cli"
+];
+const REMOTE_FAILOVER_ORDER = ["gemini-api", "openai", "anthropic", "antigravity-cli"];
+function providerChain(kind, config2, env = process.env) {
+  const names = [...kind === "remote" ? REMOTE_FAILOVER_ORDER : LOCAL_FAILOVER_ORDER];
+  const preferred = config2.provider?.trim();
+  if (preferred) {
+    let canonical = null;
+    try {
+      canonical = resolveProvider(preferred).name;
+    } catch {
+      canonical = null;
+    }
+    const index = canonical ? names.indexOf(canonical) : -1;
+    if (index > 0 && canonical) {
+      const isAgent = Boolean(resolveProvider(canonical).isolateWorkdir);
+      if (kind === "local" || !isAgent) {
+        names.splice(index, 1);
+        names.unshift(canonical);
+      }
+    }
+  }
+  return names.filter((name) => providerAvailable(name, config2, env)).map((name) => resolveProvider(name));
+}
 const DEFAULT_TIMEOUT_MS = 18e4;
 const KILL_GRACE_MS = 3e4;
 const DRAIN_GRACE_MS = 500;
 const SIGKILL_GRACE_MS = 2e3;
-function chooseProviderName(requested, config2, kind, env = process.env) {
-  const name = requested || defaultProviderName(config2);
-  if (requested || kind !== "remote") {
-    return name;
-  }
-  if (!resolveProvider(name).isolateWorkdir) {
-    return name;
-  }
-  return resolveProviderSettings("gemini-api", config2, env).apiKey ? "gemini-api" : name;
-}
 async function analyzeImage(options) {
   const resolvedInput = resolveInput(options.input);
   if (resolvedInput.kind === "local") {
     validateInputFile(resolvedInput.source);
   }
   const config2 = options.config ?? loadConfigFile();
-  const provider = resolveProvider(
-    chooseProviderName(options.provider, config2, resolvedInput.kind)
+  const chain = options.provider ? [resolveProvider(options.provider)] : options.providerBin ? [resolveProvider("antigravity-cli")] : providerChain(resolvedInput.kind, config2);
+  if (chain.length === 0) {
+    throw new Error(
+      "No vision provider is set up on this machine. Install Antigravity CLI (curl -fsSL https://antigravity.google/cli/install.sh | bash, then run agy once to sign in), or configure a key: modlens config set gemini-api.apiKey <key>. Run modlens doctor for the full picture."
+    );
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const attempts = [];
+  const warnings = [];
+  let lastError;
+  for (const provider of chain) {
+    const startedAt = Date.now();
+    const model = (attempts.length === 0 ? options.model : void 0) || resolveProviderSettings(provider.name, config2).model || provider.defaultModel;
+    try {
+      const parsed = await runProvider(
+        provider,
+        model,
+        options,
+        resolvedInput,
+        timeoutMs,
+        config2
+      );
+      attempts.push({
+        provider: provider.name,
+        ok: true,
+        durationSeconds: (Date.now() - startedAt) / 1e3
+      });
+      if (attempts.length > 1) {
+        const failed = attempts.slice(0, -1);
+        warnings.push(
+          `Failed over to ${provider.name} after: ${failed.map((attempt) => `${attempt.provider} (${attempt.error})`).join("; ")}.`
+        );
+        if (options.model) {
+          warnings.push(
+            `The explicit model applied to ${failed[0].provider} only; ${provider.name} ran its own default.`
+          );
+        }
+      }
+      return {
+        image: resolvedInput.source,
+        provider: provider.name,
+        result: parsed.result,
+        meta: {
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          model,
+          conversationId: parsed.meta.conversationId,
+          durationSeconds: parsed.meta.durationSeconds,
+          usage: parsed.meta.usage,
+          attempts,
+          warnings
+        }
+      };
+    } catch (error) {
+      lastError = error;
+      const message = error instanceof Error ? error.message : String(error);
+      attempts.push({
+        provider: provider.name,
+        ok: false,
+        durationSeconds: (Date.now() - startedAt) / 1e3,
+        error: message.slice(0, 300)
+      });
+    }
+  }
+  if (chain.length === 1) {
+    throw lastError;
+  }
+  throw new Error(
+    `Every configured vision provider failed for this image. ${attempts.map((attempt) => `${attempt.provider}: ${attempt.error}`).join(" | ")}`
   );
+}
+async function runProvider(provider, model, options, resolvedInput, timeoutMs, config2) {
   const settings = resolveProviderSettings(provider.name, config2);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const model = options.model || settings.model || provider.defaultModel;
   const providerOptions = {
     imageSource: resolvedInput.source,
     imageKind: resolvedInput.kind,
@@ -28228,18 +28370,7 @@ async function analyzeImage(options) {
       `${provider.name} returned a result that does not match the vision schema (missing: ${missing.join(", ")}).`
     );
   }
-  return {
-    image: resolvedInput.source,
-    provider: provider.name,
-    result: parsed.result,
-    meta: {
-      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      model,
-      conversationId: parsed.meta.conversationId,
-      durationSeconds: parsed.meta.durationSeconds,
-      usage: parsed.meta.usage
-    }
-  };
+  return parsed;
 }
 function resolveInput(input) {
   const trimmed = input.trim();
@@ -28449,42 +28580,6 @@ function detectHarness() {
   return detectHarnessDetailed().harness;
 }
 const MIN_NODE = "22.13";
-const DESCRIPTORS = [
-  {
-    name: "antigravity-cli",
-    kind: "subprocess",
-    bin: "agy",
-    install: "curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # sign in, then exit"
-  },
-  {
-    name: "gemini-api",
-    kind: "api",
-    required: [{ field: "apiKey", env: "GEMINI_API_KEY" }],
-    fix: "modlens config set gemini-api.apiKey <key>   # free key: https://aistudio.google.com"
-  },
-  {
-    name: "openai",
-    kind: "api",
-    required: [
-      { field: "baseUrl", env: "OPENAI_BASE_URL" },
-      { field: "apiKey", env: "OPENAI_API_KEY" },
-      { field: "model" }
-    ],
-    fix: "modlens config set openai.baseUrl <url> / openai.apiKey <key> / openai.model <name>"
-  },
-  {
-    name: "anthropic",
-    kind: "api",
-    required: [{ field: "apiKey", env: "ANTHROPIC_API_KEY" }],
-    fix: "modlens config set anthropic.apiKey <key>"
-  },
-  {
-    name: "claude-cli",
-    kind: "subprocess",
-    bin: "claude",
-    install: "install the Claude Code CLI, then run `claude` once to sign in"
-  }
-];
 function versionParts(version) {
   const match = /(\d+)\.(\d+)/.exec(version.replace(/^v/, ""));
   if (!match) {
@@ -28497,19 +28592,6 @@ function meetsMinimum(version, minimum) {
   const [minMajor, minMinor] = versionParts(minimum);
   return major > minMajor || major === minMajor && minor >= minMinor;
 }
-function findOnPath(bin, env) {
-  const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
-  for (const dir of dirs) {
-    const full = path.join(dir, bin);
-    try {
-      if (fs.statSync(full).isFile()) {
-        return full;
-      }
-    } catch {
-    }
-  }
-  return null;
-}
 function checkNodeSqlite() {
   const realEmit = process.emitWarning;
   process.emitWarning = () => {
@@ -28617,8 +28699,12 @@ function buildDoctorReport(input) {
       meetsMinimum: meetsMinimum(process.version, MIN_NODE)
     },
     nodeSqlite: checkNodeSqlite(),
-    providers: DESCRIPTORS.map((d) => inspectProvider(d, input.config, env)),
+    providers: PROVIDER_DESCRIPTORS.map((d) => inspectProvider(d, input.config, env)),
     selection: resolveSelection(input.config, input.providerFlag),
+    chains: {
+      local: providerChain("local", input.config, env).map((p) => p.name),
+      remote: providerChain("remote", input.config, env).map((p) => p.name)
+    },
     harness: (() => {
       const detection = detectHarnessDetailed();
       return { detected: detection.harness, source: detection.source };
@@ -28653,6 +28739,11 @@ function renderDoctorReport(report) {
   lines.push(`  ${report.selection.provider}${canonicalNote}`);
   lines.push(`  reason: ${report.selection.reason}`);
   lines.push("");
+  lines.push("Failover chains (what a run tries, in order)");
+  const chainLine = (chain) => chain.length > 0 ? chain.join(" -> ") : "(none available)";
+  lines.push(`  local:  ${chainLine(report.chains.local)}`);
+  lines.push(`  remote: ${chainLine(report.chains.remote)}`);
+  lines.push("");
   lines.push("Harness");
   lines.push(
     report.harness.detected ? `  ${report.harness.detected} (via ${report.harness.source})` : `  none detected (${report.harness.source})`
@@ -29116,7 +29207,7 @@ function recoverPastedImages(options = {}) {
   return result;
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.2.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.3.0");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);

package/docs/security.md

@@ -22,7 +22,7 @@ The `claude-cli` provider runs with `--allowedTools Read` only, so it can read l
 
 Both subprocess providers also run in a throwaway directory created fresh per call and removed afterward. For a local image it holds a private copy of that one image and nothing else, and it is a real copy, never a hardlink, so a provider writing to its temp path cannot touch the original. For a remote image the directory is empty and the agent downloads into it. Without this, text inside an image could steer a broadly-permissioned agent into reading files next to the original, or whatever project the caller happened to be in. Passing `--workdir` opts out and runs where you point it.
 
-This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer an inline API provider (`-p gemini-api`), which hands the bytes to an HTTP endpoint and runs no local agent. Remote URLs already default there when a Gemini key is configured: the inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the size cap, none of which apply when an agent fetches the URL on its own. An explicit `-p` overrides the reroute.
+This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer an inline API provider (`-p gemini-api`), which hands the bytes to an HTTP endpoint and runs no local agent. Remote URLs already prefer that path: the failover chain for a remote URL tries the inline API providers first and the agent last, because the inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the size cap, none of which apply when an agent fetches the URL on its own. An explicit `-p` pins one provider and overrides the chain.
 
 ## Image content is untrusted input
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {

package/skills/modlens/SKILL.md

@@ -33,11 +33,11 @@ The launcher finds a working way to run modlens and forwards your arguments to i
 
 ### If you cannot run the launcher script
 
-Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.2.0):
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.3.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.2.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.2.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.2.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.3.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.3.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.3.0 <args>`.
 4. Otherwise none of these runtimes is here. Tell the user no JavaScript runtime was found and that installing Node 22.13+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the version pin, the compatibility rule, and the diagnostic fields.
@@ -56,7 +56,9 @@ modlens config show
 
 `modlens config init` writes a starter config to `~/.modlens/config.json` when none exists. Full setup recipes per provider: `references/configure.md`.
 
-One routing rule to know: a remote image URL with no explicit `-p` runs on `gemini-api` whenever a Gemini key is configured, even if the default provider is an agent. The inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the size cap; an agent fetching the URL on its own passes through none of those. Without a Gemini key the run stays on the configured default, and an explicit `-p` always wins.
+Failover is automatic: a run tries every provider that is set up on this machine, in order, and the first good result wins (a provider that errors, times out, or returns a schema-violating result hands over to the next). A local image tries `antigravity-cli` first, then `gemini-api`, `openai`, `anthropic`, `claude-cli`. A remote URL tries the inline API providers first (`gemini-api`, `openai`, `anthropic`) and the agent last, because only the inline download path runs the private-address guards, the magic-byte image check, and the size cap. A provider set with `config set provider <name>` is a preference that moves to the front of its allowed region, not a pin. An explicit `-p` pins exactly one provider with no fallback.
+
+In the result, the top-level `provider` names who actually answered, `meta.attempts` lists every provider tried with timings and failure reasons, and `meta.warnings` carries failover notices. Relay a failover warning when the answer's provider surprised the user.
 
 ## Command
 

package/skills/modlens/references/configure.md

@@ -112,6 +112,13 @@ modlens config set provider claude-cli   # make it the default if the user wants
 - Already pays for Claude: `claude-cli` (no extra key) or `anthropic` (API billing).
 - Has a favorite multimodal endpoint (qwen, GLM, ...): `openai`.
 
+Every configured provider also backs up the others: a run tries them in a
+fixed order (local images agent-first; remote URLs inline-API-first, agent
+last) and fails over on an error, a timeout, or a schema-violating result.
+`config set provider <name>` moves a provider to the front of its allowed
+region; `-p <name>` pins exactly one with no fallback. `doctor` prints the
+chains, and the result's `meta.attempts` shows what a run actually tried.
+
 ## Troubleshooting
 
 - Error names a missing env var or `config set` command: run exactly that.

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.2.0
+- Pinned CLI version: 3.3.0
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.2.0'
+$Pinned = '3.3.0'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.2.0"
+PINNED="3.3.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"