@liustack/modlens 3.16.5 → 3.16.7

package/dsh/index.js

@@ -11,7 +11,9 @@
 // package.json `dsh.bundle` manifest). Providers, reuse grants, and guard
 // rules keep living in ~/.modlens/config.json, shared with every harness.
 import { spawn } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
@@ -59,14 +61,29 @@ export function apply(ctx, config = {}) {
   // optional-inject form, so the route rides a scoped ctx.inject: the closure
   // runs when the service appears and never runs where it does not (headless
   // stays untouched, and the plugin itself never waits on it).
-  if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
+  if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (scope) => {
-      try {
-        // scope carries webServer; the plugin's own ctx carries llm for the
-        // takeover verdicts.
-        registerPasteRoute(scope, ctx, ownProviders)
-      } catch (error) {
-        console.error(`[modlens] paste-to-path route skipped: ${error}`)
+      if (config.pasteToPath !== false) {
+        try {
+          // scope carries webServer; the plugin's own ctx carries llm for the
+          // takeover verdicts.
+          registerPasteRoute(scope, ctx, ownProviders)
+        } catch (error) {
+          console.error(`[modlens] paste-to-path route skipped: ${error}`)
+        }
+      }
+      // Same web server, a separate switch: turning paste-to-path off is a
+      // statement about how images enter, not about whether the engine can
+      // be configured. dsh's own settings surface renders a hardcoded set of
+      // cards and does not enumerate namespaces, so the card the browser half
+      // contributes talks to this route rather than to a settings schema
+      // (issue #39).
+      if (config.settingsCard !== false) {
+        try {
+          registerConfigRoute(scope)
+        } catch (error) {
+          console.error(`[modlens] settings card route skipped: ${error}`)
+        }
       }
     })
   }
@@ -850,3 +867,354 @@ function renderEvidence(value) {
   }
   return lines.join('\n')
 }
+
+// The engines a user can pick in the settings card, in the order the docs
+// introduce them. Kept to the names modlens itself uses so the card and
+// `modlens doctor` say the same words.
+const ENGINES = ['antigravity-cli', 'gemini-api', 'openai', 'anthropic', 'claude-cli']
+// The two CLI engines sign in through their own tool, so a key or an endpoint
+// would be a field with nothing behind it. Both still take a model.
+const KEYLESS_ENGINES = ['antigravity-cli', 'claude-cli']
+// Every accepted spelling, mirroring src/providers/index.ts. Settings saved
+// under an alias are the same engine's settings, and a provider pinned by an
+// alias is pinned to that engine: showing either as something else would put
+// the card at odds with what actually reads the images.
+const ENGINE_ALIASES = {
+  antigravity: 'antigravity-cli',
+  agy: 'antigravity-cli',
+  gemini: 'gemini-api',
+  'openai-compat': 'openai',
+  claude: 'anthropic',
+  'claude-code': 'claude-cli',
+}
+
+/** The canonical engine a stored name means, or '' when it names none. */
+function canonicalEngine(name) {
+  if (typeof name !== 'string') return ''
+  const trimmed = name.trim().toLowerCase()
+  if (ENGINES.includes(trimmed)) return trimmed
+  return ENGINE_ALIASES[trimmed] ?? ''
+}
+
+/** The config keys holding one engine's settings: its own, plus its aliases. */
+function settingsKeysFor(engine) {
+  const aliases = Object.keys(ENGINE_ALIASES).filter((alias) => ENGINE_ALIASES[alias] === engine)
+  return [...aliases, engine]
+}
+// Auto mode: the local harnesses whose logins a read may borrow. `claude`
+// absent counts as granted, since claude-cli predates the grant model.
+const REUSE_HARNESSES = ['claude', 'codex', 'opencode', 'pi', 'grok']
+
+/** ~/.modlens/config.json, the one file every harness shares. */
+function modlensConfigPath() {
+  return join(homedir(), '.modlens', 'config.json')
+}
+
+/**
+ * The shared config, or a thrown error. Only a missing file reads as empty:
+ * a file that exists but cannot be parsed or read is somebody's configuration,
+ * and a settings card that treated it as empty would overwrite it on the next
+ * save. The card shows the error instead.
+ */
+function readModlensConfig() {
+  let raw
+  try {
+    raw = readFileSync(modlensConfigPath(), 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    throw new Error(`cannot read ${modlensConfigPath()}: ${error?.message ?? error}`)
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${modlensConfigPath()} is not valid JSON: ${error?.message ?? error}`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${modlensConfigPath()} does not hold a JSON object`)
+  }
+  return parsed
+}
+
+/**
+ * What the card is allowed to know. Every engine's endpoint and model, plus
+ * whether a key is stored, and never the key itself: a browser that cannot
+ * read a secret cannot leak one, and cannot write it back either.
+ */
+function engineSummary(config = readModlensConfig()) {
+  const engines = {}
+  for (const name of ENGINES) {
+    // Alias first, canonical last: the canonical key wins on conflict, the
+    // same order resolveProviderSettings uses.
+    const settings = Object.assign({}, ...settingsKeysFor(name).map((key) => config.providers?.[key] ?? {}))
+    engines[name] = {
+      baseUrl: typeof settings.baseUrl === 'string' ? settings.baseUrl : '',
+      model: typeof settings.model === 'string' ? settings.model : '',
+      hasKey: typeof settings.apiKey === 'string' && settings.apiKey !== '',
+    }
+  }
+  const reuse = {}
+  for (const harness of REUSE_HARNESSES) {
+    const granted = config.reuse?.[harness]
+    reuse[harness] = typeof granted === 'boolean' ? granted : harness === 'claude'
+  }
+  // Three states, kept apart: pinned to an engine, pinned by one of its
+  // aliases (reported canonically), or not pinned at all, which is its own
+  // answer and means the failover chain decides. Collapsing the third into
+  // the first pins an engine the user never chose.
+  return {
+    provider: canonicalEngine(config.provider),
+    engines,
+    keyless: KEYLESS_ENGINES,
+    reuse,
+  }
+}
+
+/**
+ * Apply one card submission to the shared file. Only the named engine's own
+ * three fields are touched, so switching engines in the card cannot copy one
+ * engine's endpoint onto another. An absent or empty `apiKey` leaves the
+ * stored one alone: the card never receives a key, so it must never be able
+ * to clear one by submitting the blank field it was shown.
+ */
+function applyEngineSettings(patch) {
+  const config = readModlensConfig()
+  // The pin moves only when the card says it moved. A save that carried the
+  // currently displayed engine regardless turned "not pinned" into a pin on
+  // whatever happened to be shown, changing which engine reads every later
+  // image without the user asking for it.
+  if (patch?.provider !== undefined) {
+    if (patch.provider === '') {
+      delete config.provider
+    } else if (ENGINES.includes(patch.provider)) {
+      config.provider = patch.provider
+    } else {
+      throw new Error(`unknown engine: ${patch.provider}`)
+    }
+  }
+  // Engine fields are edited one engine at a time, named by `engine`. Absent
+  // means this save touched no engine settings, which is what a reuse-only
+  // save looks like.
+  const engine = patch?.engine
+  if (engine !== undefined) {
+    if (!ENGINES.includes(engine)) {
+      throw new Error(`unknown engine: ${engine}`)
+    }
+    config.providers = { ...config.providers }
+    // Write where this engine's settings already live, so a key saved under
+    // an alias is updated rather than shadowed by a second copy.
+    // Write where the read takes effect. settingsKeysFor merges aliases
+    // first and the canonical key last, so the canonical value wins; picking
+    // the first existing key instead wrote a new value underneath an older
+    // canonical one, which saved successfully and changed nothing. Both CLI
+    // spellings existing at once is ordinary: `config set gemini.apiKey`
+    // then `config set gemini-api.apiKey` leaves exactly that.
+    const holders = settingsKeysFor(engine).filter((key) => config.providers[key] !== undefined)
+    const target = holders.length > 0 ? holders[holders.length - 1] : engine
+    const settings = { ...config.providers[target] }
+    for (const field of ['baseUrl', 'model']) {
+      const value = typeof patch[field] === 'string' ? patch[field].trim() : ''
+      if (value === '') {
+        delete settings[field]
+      } else {
+        settings[field] = value
+      }
+    }
+    const apiKey = typeof patch.apiKey === 'string' ? patch.apiKey.trim() : ''
+    if (apiKey !== '') {
+      settings.apiKey = apiKey
+    }
+    config.providers[target] = settings
+  }
+  // Auto mode, when the card sent it: only the harnesses this build knows,
+  // only booleans, so an unexpected key cannot land in the shared file.
+  if (patch?.reuse !== null && typeof patch?.reuse === 'object') {
+    config.reuse = { ...config.reuse }
+    for (const harness of REUSE_HARNESSES) {
+      const granted = patch.reuse[harness]
+      if (typeof granted === 'boolean') {
+        config.reuse[harness] = granted
+      }
+    }
+  }
+  const file = modlensConfigPath()
+  // A symlink here would write through to wherever it points, so it is
+  // refused rather than followed: the CLI writes a real file, and anything
+  // else is a setup this card should not silently honor.
+  try {
+    if (lstatSync(file).isSymbolicLink()) {
+      throw new Error(`${file} is a symlink; edit the file it points at instead`)
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  try {
+    chmodSync(file, 0o600)
+  } catch {
+    // Windows has no POSIX bits; the mode on the write above is all there is.
+  }
+}
+
+/**
+ * GET /modlens/config: the engine summary above. POST: one submission.
+ *
+ * The dsh web server listens on loopback, but a page in the same browser can
+ * still reach it, so a write requires a same-origin request: a cross-site POST
+ * could otherwise repoint someone's engine at an endpoint of its choosing.
+ * A read is refused the same way for symmetry, though it carries no secret.
+ */
+/**
+ * The self-check behind the card's auto-mode section: which local harnesses
+ * exist to be borrowed at all. `doctor --json` already probes them without
+ * network or quota, so the route spawns the CLI this package ships and lifts
+ * its reuse section. Cached briefly, since one probe can take a second and
+ * re-expanding the card should not re-pay it.
+ */
+const DISCOVERY_TTL_MS = 60_000
+let discoveryCache = null
+async function discoverReuse() {
+  if (discoveryCache !== null && Date.now() - discoveryCache.at < DISCOVERY_TTL_MS) {
+    return discoveryCache.value
+  }
+  try {
+    const { stdout, code } = await run(process.execPath, [CLI_PATH, 'doctor', '--json'], AbortSignal.timeout(30_000))
+    if (code !== 0) return null
+    const reuse = JSON.parse(stdout)?.reuse
+    if (!reuse || !Array.isArray(reuse.probes)) return null
+    // doctor names the harness claude-code; the grant key is claude.
+    const probes = reuse.probes.map((probe) => ({
+      harness: probe.harness === 'claude-code' ? 'claude' : probe.harness,
+      cliFound: probe.cliFound === true,
+      loggedIn: probe.loggedIn,
+      cliPath: typeof probe.cliPath === 'string' ? probe.cliPath : '',
+    }))
+    discoveryCache = { at: Date.now(), value: probes }
+    return probes
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Open the shared config file in whatever the OS considers its editor. The
+ * card's "open config file" link lands here: the path never has to be
+ * explained to the user, they just get the file. Created empty first when
+ * missing, so the editor has something to open.
+ */
+function openConfigFile() {
+  const file = modlensConfigPath()
+  try {
+    lstatSync(file)
+  } catch {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, '{}\n', { mode: 0o600 })
+  }
+  const [command, args] =
+    process.platform === 'darwin'
+      ? ['open', [file]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', file]]
+        : ['xdg-open', [file]]
+  spawn(command, args, { detached: true, stdio: 'ignore' }).unref()
+}
+
+/** localhost, ::1, or anything in 127/8, matching dsh's own /api fence. */
+function isLoopbackHost(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return (
+    parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+  )
+}
+
+/**
+ * The same fence dsh puts in front of its own /api, for the same two
+ * confused-deputy paths. Host is the header DNS rebinding cannot forge, so it
+ * must name a loopback authority: a rebound page reaches this socket carrying
+ * its own domain there. Origin and Sec-Fetch-Site then rule out a cross-site
+ * page on the machine itself. A dsh serving a LAN address configures
+ * trustedHosts for /api; this route stays loopback-only, since nothing about
+ * editing an API key wants a wider door.
+ */
+function isTrustedRequest(req) {
+  const host = req.headers?.host
+  if (typeof host !== 'string' || host === '') return false
+  let hostUrl
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHost(hostUrl.hostname)) return false
+  if (req.headers?.['sec-fetch-site'] === 'cross-site') return false
+  const origin = req.headers?.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+function registerConfigRoute(ctx) {
+  ctx.webServer.register({
+    name: 'modlens-config',
+    kind: 'exact',
+    path: '/modlens/config',
+    handler: async (req, res) => {
+      const send = (status, body) => {
+        res.writeHead(status, { 'content-type': 'application/json' })
+        res.end(JSON.stringify(body))
+      }
+      if (!isTrustedRequest(req)) {
+        send(403, { error: 'request refused: this route answers same-origin loopback only' })
+        return
+      }
+      if (req.method === 'GET') {
+        try {
+          const summary = engineSummary()
+          const wantsDiscovery = new URL(req.url, 'http://localhost').searchParams.has('discover')
+          if (wantsDiscovery) {
+            // null when the probe failed: the card then falls back to the
+            // plain grant list rather than showing nothing.
+            summary.discovery = await discoverReuse()
+          }
+          send(200, summary)
+        } catch (error) {
+          send(409, { error: String(error?.message ?? error) })
+        }
+        return
+      }
+      if (req.method !== 'POST') {
+        res.writeHead(405).end()
+        return
+      }
+      try {
+        const chunks = []
+        let total = 0
+        for await (const chunk of req) {
+          total += chunk.length
+          if (total > 64 * 1024) {
+            send(413, { error: 'config payload too large' })
+            req.destroy()
+            return
+          }
+          chunks.push(chunk)
+        }
+        const patch = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        // The card's "open config file" link: an action, not a setting.
+        if (patch?.open === true) {
+          openConfigFile()
+          send(200, { opened: true })
+          return
+        }
+        applyEngineSettings(patch)
+        send(200, engineSummary())
+      } catch (error) {
+        send(400, { error: String(error?.message ?? error) })
+      }
+    },
+  })
+}

package/package.json

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

package/skills/modlens/SKILL.md

@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.5):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.7):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.5: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.5 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.5 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.7: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.7 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.7 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/configure.md

@@ -12,14 +12,14 @@ Read this when the user asks how to set up, configure, or switch ModLens provide
 modlens config init                     # write a starter config (refuses to overwrite; --force to redo)
 modlens config show                     # effective file, API keys masked
 modlens config set provider <name>      # change the default provider
-modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model, extraBody
+modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model, proxy, extraBody, structuredOutput
 ```
 
 `config set` writes the file with 0600 permissions.
 
 ## The file's exact shape
 
-Everything lives under four top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
+Everything lives under five top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
 
 ```json
 {
@@ -42,7 +42,9 @@ Everything lives under four top-level keys, all optional. This example shows eve
       "apiKey": "sk-...",
       "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
       "model": "qwen3.6-27b",
-      "extraBody": { "thinking": { "type": "disabled" } }
+      "proxy": "http://127.0.0.1:7890",
+      "extraBody": { "thinking": { "type": "disabled" } },
+      "structuredOutput": true
     },
     "anthropic": {
       "apiKey": "sk-ant-...",
@@ -57,8 +59,9 @@ Everything lives under four top-level keys, all optional. This example shows eve
 Field semantics:
 
 - `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent pins nothing: the failover chain decides, trying configured API providers before the agent CLIs.
-- `providers.<name>.<field>`: four fields exist, `apiKey`, `baseUrl`, `model`, and `extraBody`. Every provider entry is optional, and every field inside it is optional. Alias keys are read too (settings saved under `gemini` are found when `gemini-api` resolves), with the canonical key winning on conflict.
-- `providers.<name>.extraBody`: a JSON object merged into the request body of the API providers (`gemini-api`, `openai`, `anthropic`), for whatever knobs that vendor has and modlens has no flag for. Turning thinking off is the usual reason, see the section below. Nested objects merge key by key, so adding one knob leaves the rest of that block alone. The fields carrying the image, the prompt, and the schema enforcement are refused with an error naming the field. The two CLI providers take no request body, so a run on `antigravity-cli` or `claude-cli` ignores it and says so in `meta.warnings`.
+- `providers.<name>.<field>`: six fields exist, `apiKey`, `baseUrl`, `model`, `proxy`, `extraBody`, and `structuredOutput` (the openai route only). Every provider entry is optional, and every field inside it is optional. Alias keys are read too (settings saved under `gemini` are found when `gemini-api` resolves), with the canonical key winning on conflict.
+- `providers.<name>.extraBody`: a JSON object merged into the request body of the API providers (`gemini-api`, `openai`, `anthropic`), for whatever knobs that vendor has and modlens has no flag for. Turning thinking off is the usual reason, see the section below. Nested objects merge key by key, so adding one knob leaves the rest of that block alone. The fields carrying the image, the prompt, and each route's own enforcement machinery are refused with an error naming the field. `response_format` on the `openai` route is not one of them: setting it there deliberately replaces the schema modlens would otherwise send. The two CLI providers take no request body, so a run on `antigravity-cli` or `claude-cli` ignores it and says so in `meta.warnings`.
+- `providers.openai.structuredOutput`: `true` asks an OpenAI-compatible gateway to enforce the vision contract itself, as `response_format: json_schema` in the strict form those endpoints require. Off by default, since a gateway without structured-output support answers 400 for the field. A `response_format` you set in `extraBody` wins over it.
 - `guards`: the invocation guard, for people who run both text-only and vision-capable models through the same client. Both lists hold glob patterns (`*` and `?`, case-insensitive, matched against the model name and `provider/model`), set with `modlens config set guards.denyModels '["gemini-3*"]'` or `guards.allowModels` (a JSON array or a comma-separated list, empty clears). Two ways to express the same intent, pick the shorter list:
   - `denyModels` alone: everything runs the engine except the listed vision models. Right when text-only models are the majority of what you plug in.
   - `allowModels` non-empty (allowlist mode): only the listed models run the engine, every other identified model is denied. Right for the actual 2026 landscape, where text-only models are the short list. A deny pattern still wins over an allow match, so a broad allow can have its vision variants carved out, as in the example above: `glm-5.*` allows the text line while `glm-*v*` catches `glm-5v-turbo`. Anchor allow patterns tightly (`deepseek-v4-*`, not `deepseek*`) so a vendor's next multimodal generation falls off the list and steps aside until you have checked it.
@@ -90,9 +93,13 @@ Any free Google account works; no Google AI Pro needed. Sign-in cannot be automa
 
 ```bash
 modlens config set gemini-api.apiKey <key>
+# value omitted: a hidden prompt, so the key skips argv, shell history, and this chat
+modlens config set gemini-api.apiKey
 # or environment: export GEMINI_API_KEY=<key>
 ```
 
+Offer the hidden prompt first when the user is at their own terminal. Most users paste the key into the chat because it is convenient, and that works too: take it and store it. The prompt is for the ones who would rather not.
+
 Default model `gemini-3.6-flash` has vision on the free tier (about 10-15 requests/min, 1500/day). Free-tier data may be used by Google to improve products; mention this if the user handles sensitive images.
 
 ### openai (any OpenAI-compatible multimodal endpoint)
@@ -105,7 +112,15 @@ modlens config set openai.apiKey <sk-key>
 modlens config set openai.model qwen3.6-27b
 ```
 
-For official OpenAI: baseUrl `https://api.openai.com/v1`, a vision-capable model. Environment equivalents: `OPENAI_BASE_URL`, `OPENAI_API_KEY`. The model must be multimodal; text-only models will fail or hallucinate. This route has no server-side schema enforcement, so occasional shape failures are surfaced as explicit errors; retry or switch provider.
+For official OpenAI: baseUrl `https://api.openai.com/v1`, a vision-capable model. Environment equivalents: `OPENAI_BASE_URL`, `OPENAI_API_KEY`. The model must be multimodal; text-only models will fail or hallucinate.
+
+This route enforces nothing server-side by default, so a weaker model can answer with half the contract and the run fails with an explicit error. If that happens, ask the gateway to enforce it:
+
+```bash
+modlens config set openai.structuredOutput true
+```
+
+The contract goes out as `response_format: json_schema` in strict form, derived from the schema modlens checks against. Off by default because a gateway without structured-output support answers 400 for the field, so turn it back off if the endpoint refuses it. Turning thinking off (below) makes the shape failures more likely, so the two often go together.
 
 ### anthropic (Claude API key)
 

package/skills/modlens/references/configure.zh-CN.md

@@ -12,14 +12,14 @@
 modlens config init                     # 写入一份起步配置（已存在则拒绝，--force 重写）
 modlens config show                     # 生效的配置文件，API key 打码显示
 modlens config set provider <name>      # 更改默认 provider
-modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、model、extraBody
+modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、model、proxy、extraBody、structuredOutput
 ```
 
 `config set` 写文件时权限为 0600。
 
 ## 配置文件的完整形状
 
-所有内容都在四个顶层键之下，全部可选。下面的示例一次性展示了所有支持的键和字段（真实文件只需要写你用到的部分）。文件不存在就全用默认值。provider 的设置放在 `providers.<name>` 下面，不在顶层，手工编辑最常犯的就是这个错。
+所有内容都在五个顶层键之下，全部可选。下面的示例一次性展示了所有支持的键和字段（真实文件只需要写你用到的部分）。文件不存在就全用默认值。provider 的设置放在 `providers.<name>` 下面，不在顶层，手工编辑最常犯的就是这个错。
 
 ```json
 {
@@ -42,7 +42,9 @@ modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、mo
       "apiKey": "sk-...",
       "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
       "model": "qwen3.6-27b",
-      "extraBody": { "thinking": { "type": "disabled" } }
+      "proxy": "http://127.0.0.1:7890",
+      "extraBody": { "thinking": { "type": "disabled" } },
+      "structuredOutput": true
     },
     "anthropic": {
       "apiKey": "sk-ant-...",
@@ -57,8 +59,9 @@ modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、mo
 字段含义：
 
 - `provider`：不传 `-p` 时由哪个 provider 执行。标准名和别名都行（`agy`/`antigravity` 对应 `antigravity-cli`，`gemini` 对应 `gemini-api`，`openai-compat` 对应 `openai`，`claude` 对应 `anthropic`，`claude-code` 对应 `claude-cli`）。留空或缺失表示不钉任何一个：由失败切换链决定，已配置的 API provider 先于 agent CLI 被尝试。
-- `providers.<name>.<field>`：共四个字段，`apiKey`、`baseUrl`、`model`、`extraBody`。每个 provider 条目都可选，条目里的每个字段也都可选。别名键同样会被读取（存在 `gemini` 下的设置在解析到 `gemini-api` 时也能找到），冲突时标准键胜出。
-- `providers.<name>.extraBody`：一个 JSON 对象，合并进 API provider（`gemini-api`、`openai`、`anthropic`）的请求体，用来传厂商有而 modlens 没有对应参数的开关。最常见的用途是关掉思考，见下文小节。嵌套对象逐键合并，所以加一个开关不会动到该块里的其他内容。承载图片、提示词和 schema 约束的字段会被拒绝，报错会点名该字段。两个 CLI provider 不发请求体，所以在 `antigravity-cli` 或 `claude-cli` 上运行时它会被忽略，并在 `meta.warnings` 里说明。
+- `providers.<name>.<field>`：共六个字段，`apiKey`、`baseUrl`、`model`、`proxy`、`extraBody`、`structuredOutput`（仅 openai 路线）。每个 provider 条目都可选，条目里的每个字段也都可选。别名键同样会被读取（存在 `gemini` 下的设置在解析到 `gemini-api` 时也能找到），冲突时标准键胜出。
+- `providers.<name>.extraBody`：一个 JSON 对象，合并进 API provider（`gemini-api`、`openai`、`anthropic`）的请求体，用来传厂商有而 modlens 没有对应参数的开关。最常见的用途是关掉思考，见下文小节。嵌套对象逐键合并，所以加一个开关不会动到该块里的其他内容。承载图片、提示词和各路线自身强制机制的字段会被拒绝，报错会点名该字段。`openai` 路线上的 `response_format` 不在此列：在那里设置它就是有意替换掉 modlens 本来会发的那份 schema。两个 CLI provider 不发请求体，所以在 `antigravity-cli` 或 `claude-cli` 上运行时它会被忽略，并在 `meta.warnings` 里说明。
+- `providers.openai.structuredOutput`：设为 `true` 时，让 OpenAI 兼容网关自己强制执行视觉契约，以 `response_format: json_schema` 的严格形式发出。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400。你在 `extraBody` 里设的 `response_format` 优先级更高。
 - `guards`：调用 guard，给在同一个客户端里既跑纯文本模型又跑视觉模型的人用。两个列表都放 glob 模式（支持 `*` 和 `?`，不区分大小写，同时匹配模型名和 `provider/model`），用 `modlens config set guards.denyModels '["gemini-3*"]'` 或 `guards.allowModels` 设置（JSON 数组或逗号分隔的列表都行，传空则清除）。两种写法表达同一个意图，选列表更短的那种：
   - 只用 `denyModels`：除了列出的视觉模型，其余全部运行引擎。适合你接入的模型大多是纯文本的情况。
   - `allowModels` 非空（白名单模式）：只有列出的模型运行引擎，其他所有已识别的模型一律拒绝。适合 2026 年的实际格局，纯文本模型才是那份短名单。deny 模式仍然优先于 allow 匹配，所以宽泛的 allow 可以把视觉变体剔出去，正如上面的示例：`glm-5.*` 放行文本系列，`glm-*v*` 抓住 `glm-5v-turbo`。allow 模式要锚定得紧一些（写 `deepseek-v4-*` 而不是 `deepseek*`），这样厂商下一代多模态型号会自动掉出名单，等你检查过再上场。
@@ -90,9 +93,13 @@ agy    # 用户需自己在浏览器完成登录，然后退出
 
 ```bash
 modlens config set gemini-api.apiKey <key>
+# 省略值：进入隐藏输入，密钥不进 argv、不进 shell 历史，也不进这段对话
+modlens config set gemini-api.apiKey
 # 或走环境变量：export GEMINI_API_KEY=<key>
 ```
 
+用户就在自己终端前时，先给隐藏输入这条。大多数人图方便还是会把 key 直接贴进对话，那也没问题：照收照存。隐藏输入是留给在乎的人的。
+
 默认模型 `gemini-3.6-flash` 在免费档就有视觉能力（约每分钟 10-15 次请求，每天 1500 次）。免费档的数据可能被 Google 用于改进产品，用户要处理敏感图片时请提醒这一点。
 
 ### openai（任意 OpenAI 兼容的多模态端点）
@@ -105,7 +112,15 @@ modlens config set openai.apiKey <sk-key>
 modlens config set openai.model qwen3.6-27b
 ```
 
-官方 OpenAI 的写法：baseUrl 用 `https://api.openai.com/v1`，配一个具备视觉能力的模型。对应的环境变量：`OPENAI_BASE_URL`、`OPENAI_API_KEY`。模型必须是多模态的，纯文本模型会失败或产生幻觉。这条路线没有服务端 schema 约束，偶发的结构错误会以明确报错的形式暴露出来，重试或换 provider 即可。
+官方 OpenAI 的写法：baseUrl 用 `https://api.openai.com/v1`，配一个具备视觉能力的模型。对应的环境变量：`OPENAI_BASE_URL`、`OPENAI_API_KEY`。模型必须是多模态的，纯文本模型会失败或产生幻觉。
+
+这条路线默认在服务端不做任何约束，能力弱一些的模型可能只答出契约的一半，运行就会以明确报错失败。真遇到就让网关自己强制执行：
+
+```bash
+modlens config set openai.structuredOutput true
+```
+
+契约会以 `response_format: json_schema` 的严格形式发出去，schema 由 modlens 校验用的那份推导而来。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400，端点拒绝就关回去。关掉思考（见下）会让结构错误更容易出现，所以这两项常常一起用。
 
 ### anthropic（Claude API key）
 

package/skills/modlens/references/onboard.md

@@ -27,7 +27,7 @@ Consent rules:
 - One question per decision, never a bundled yes. Reusing Codex and reusing pi credentials are two questions (or one question with independent options), not one.
 - Each question names the harness, whose quota it spends, and the accounting promise. Example wording: "Allow modlens to reuse your signed-in Codex CLI for image reads? Every reused read is labeled in the result so you always see whose quota was spent."
 - The do-nothing outcome must be safe and stated: "If you skip this, modlens just uses the engines you configure yourself."
-- If the user offers an API key, take exactly that key, and never go looking for keys they did not hand over.
+- When a key is needed, offer the clean path first, in one line: "Run `modlens config set gemini-api.apiKey` in your terminal and paste the key at the hidden prompt. It stays out of this chat and out of your shell history, and I never see it." Most users will paste the key into the chat anyway, because that is the convenient path, and that is fine: take exactly the key they hand over, use it, and never go looking for keys they did not. The offer is for the users who care, not a gate.
 
 ## 4. Apply only what was consented to
 

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.16.5
+- Pinned CLI version: 3.16.7
 - 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.16.5'
+$Pinned = '3.16.7'
 # -------------------------------------------------------------------------------
 
 $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.16.5"
+PINNED="3.16.7"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"