Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
Merge origin/main into fix-529 and unify DNS pinning with private network setting
Emre Sokullu5e7f6c457a30
diff --cc lmstudio-plugin/README.mdindex 0d370309a,aad5301a4..34d09ce31--- a/lmstudio-plugin/README.md+++ b/lmstudio-plugin/README.md@@@ -240,37 -244,16 +244,32 @@@ Everything below concerns `fetch_url`this plugin makes anonymous requests.- **Timeouts.** Default 30 s, hard cap 120 s.-Set `allowPrivate: true` on a per-call basis to opt out of the URL-guard + DNS check — useful when you actually want to talk to-localhost services.+### Private network access++Private targets are opened by you, not by the model. To let `fetch_url`+and `research_url` reach localhost or your LAN, turn on **Allow private+network access** in this plugin's settings in LM Studio. The setting is+per chat and off by default. The tools have no `allowPrivate` argument,+and one sent anyway is ignored, so a page the model reads cannot talk+it into switching the guard off.++Cloud metadata endpoints stay blocked even with the setting on:+`169.254.169.254`, `169.254.170.2`, `169.254.170.23`, `169.254.0.23`,+`100.100.100.200`, `fd00:ec2::254`, `fd00:ec2::23`,+`metadata.google.internal`, `metadata.goog` and `metadata`, including+IPv4-mapped IPv6 spellings, hostnames that resolve to them, and+redirects to them.++While the setting is on, the model still chooses the URL, method,+headers and body, and a page it reads can steer it toward your router,+admin panels or local services. Turn it on only in chats that need it.- ### Known residual gap: DNS rebinding-- An attacker controlling a domain with TTL=0 can return a public IP- when our guard runs `dns.lookup` and a private IP a moment later when- `fetch` connects. Closing this fully requires pinning the resolved- IP via a custom `undici` Agent's `connect.lookup` hook so the- connection uses the exact address we validated. Tracked as a- follow-up. If you're running this on a cloud VM with sensitive- instance-metadata endpoints, use a network policy that blocks- `169.254.169.254` outbound rather than relying solely on this- plugin's checks.+ ### Not a sandbox++ These checks only see the address ranges they know about. If you're+ running this on a cloud VM with sensitive instance-metadata+ endpoints, use a network policy that blocks `169.254.169.254`+ outbound rather than relying solely on this plugin's checks.## Licensediff --cc lmstudio-plugin/package.jsonindex 394081519,98adaa2f9..55ca8f0c3--- a/lmstudio-plugin/package.json+++ b/lmstudio-plugin/package.json@@@ -15,7 -15,7 +15,7 @@@"scripts": {"build": "tsc","dev": "tsc --watch",- "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/privateNetworkSetting.test.mjs",- "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/safeFetch.test.mjs",++ "test": "npm run build && node --test test/browserTask.test.mjs test/urlGuard.test.mjs test/toolParameters.test.mjs test/safeFetch.test.mjs test/privateNetworkSetting.test.mjs","clean": "rm -rf dist"},"keywords": [diff --cc lmstudio-plugin/src/util/safeFetch.tsindex e92713de4,e3379b16c..2777488f7--- a/lmstudio-plugin/src/util/safeFetch.ts+++ b/lmstudio-plugin/src/util/safeFetch.ts@@@ -29,14 -31,16 +31,18 @@@* open-redirect chain.*/- import { lookup as dnsLookup } from "node:dns/promises";- import { isIP } from "node:net";+ import { lookup as dnsLookup, type LookupAddress } from "node:dns";+ import * as http from "node:http";+ import * as https from "node:https";+ import { isIP, type LookupFunction } from "node:net";+ import { pipeline, Readable } from "node:stream";+ import * as zlib from "node:zlib";import {assertSafeUrl,+ isCloudMetadataHost,isPrivateIpv4,isPrivateIpv6,+ PRIVATE_NETWORK_HINT,type UrlGuardOptions,} from "./urlGuard.js";@@@ -70,71 -74,239 +76,255 @@@ function stripCrossOriginHeaders}/**- * Resolve a hostname's A/AAAA records and reject if any address is in- * a private range. Literal IPs skip DNS and are classified directly.+ * Reject if any resolved address is in a private range.*- * Why we check ALL returned addresses rather than just the first one- * fetch will use: defense-in-depth against accidentally-misconfigured- * dual-stack hosts and against future fetch-implementation changes- * about which family wins in `lookup({ all: false })`.+ * Why we check ALL returned addresses rather than just the first one:+ * Node's happy-eyeballs connect may try any of them, and it is+ * defense-in-depth against accidentally-misconfigured dual-stack hosts.+ *- * With allowPrivate the lookup still runs, because a hostname that++ * With allowPrivate the check still runs, because a hostname that+ * resolves to a cloud metadata address stays blocked.*/- async function assertHostnameDoesNotResolveToPrivate(- parsed: URL,- opts: UrlGuardOptions,- ): Promise<void> {- // Strip the [..] wrapper IPv6 URL syntax adds.- let host = parsed.hostname;- if (host.startsWith("[") && host.endsWith("]")) {- host = host.slice(1, -1);- }-- // Literal IP — nothing to resolve, but classify it here as well- // rather than trusting the sync guard ran with the same rules.- const literal = isIP(host);- if (literal === 4 || literal === 6) {- if (!opts.allowPrivate && (literal === 4 ? isPrivateIpv4(host) : isPrivateIpv6(host))) {- throw new Error(- `Refusing private IPv${literal} ${host} — ${PRIVATE_NETWORK_HINT}`,- );-function assertAddressesArePublic(host: string, addresses: LookupAddress[]): void {++function assertAddressesArePublic(host: string, addresses: LookupAddress[], opts: UrlGuardOptions = {}): void {+ for (const { address, family } of addresses) {- if (family === 4 && isPrivateIpv4(address)) {- throw new Error(- `Refusing ${host} — resolves to private IPv4 ${address}. Set allowPrivate to opt in.`,- );++ if (!opts.allowPrivate) {++ if (family === 4 && isPrivateIpv4(address)) {++ throw new Error(++ `Refusing ${host} — resolves to private IPv4 ${address}; ${PRIVATE_NETWORK_HINT}`,++ );++ }++ if (family === 6 && isPrivateIpv6(address)) {++ throw new Error(++ `Refusing ${host} — resolves to private IPv6 ${address}; ${PRIVATE_NETWORK_HINT}`,++ );++ }}- if (isCloudMetadataHost(host)) {- if (family === 6 && isPrivateIpv6(address)) {++ if (isCloudMetadataHost(address)) {throw new Error(- `Refusing cloud metadata endpoint ${host} — blocked even with private network access on.`,- `Refusing ${host} — resolves to private IPv6 ${address}. Set allowPrivate to opt in.`,++ `Refusing ${host} — resolves to cloud metadata endpoint ${address}, which stays blocked even with private network access on.`,);}- return;}+ }- let addresses: Array<{ address: string; family: number }>;- try {- addresses = await dnsLookup(host, { all: true });- } catch (e) {- // Resolution failure isn't a security signal — let the subsequent- // fetch surface a clean error. Don't fail the guard here.- return;+ /**+ * Literal-IP hosts never reach `guardedLookup`: Node connects to them+ * directly without calling the socket's `lookup` hook. Classify them here+ * on every hop so this layer does not depend on `assertSafeUrl` alone.+ */-function assertLiteralIpIsPublic(url: URL): void {++function assertLiteralIpIsPublic(url: URL, opts: UrlGuardOptions = {}): void {+ let host = url.hostname;+ if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);+ const family = isIP(host);- if (family === 4 ? isPrivateIpv4(host) : family === 6 && isPrivateIpv6(host)) {++ if (family === 0) return;++ if (!opts.allowPrivate && (family === 4 ? isPrivateIpv4(host) : isPrivateIpv6(host))) {+ throw new Error(- `Refusing private IPv${family} ${host} — set allowPrivate to opt in.`,++ `Refusing private IPv${family} ${host} — ${PRIVATE_NETWORK_HINT}`,++ );+ }++ if (isCloudMetadataHost(host)) {++ throw new Error(++ `Refusing cloud metadata endpoint ${host} — blocked even with private network access on.`,+ );+ }+ }- for (const { address, family } of addresses) {- if (isCloudMetadataHost(address)) {- throw new Error(- `Refusing ${host} — resolves to cloud metadata endpoint ${address}, which stays blocked even with private network access on.`,- );+ /**+ * `lookup` hook for the request socket. Node calls it when connecting+ * and dials only the addresses it hands back, so the check and the use+ * are the same resolution — resolving first and then letting the HTTP+ * client resolve the name again would let a TTL=0 record answer public+ * to the check and private to the connection. Literal-IP hosts never+ * reach a lookup; `assertLiteralIpIsPublic` covers them.+ */-const guardedLookup: LookupFunction = (hostname, options, callback) => {- dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {- if (err) {- callback(err, "");- return;- }- try {- if (addresses.length === 0) throw new Error(`No addresses found for ${hostname}`);- assertAddressesArePublic(hostname, addresses);- } catch (e) {- callback(e as NodeJS.ErrnoException, "");- return;- }- if (options.all) callback(null, addresses);- else callback(null, addresses[0]!.address, addresses[0]!.family);- });-};++function createGuardedLookup(opts: UrlGuardOptions): LookupFunction {++ return (hostname, options, callback) => {++ dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {++ if (err) {++ callback(err, "");++ return;++ }++ try {++ if (addresses.length === 0) throw new Error(`No addresses found for ${hostname}`);++ assertAddressesArePublic(hostname, addresses, opts);++ } catch (e) {++ callback(e as NodeJS.ErrnoException, "");++ return;++ }++ if (options.all) callback(null, addresses);++ else callback(null, addresses[0]!.address, addresses[0]!.family);++ });++ };++}++ /** Statuses whose Response must have a null body (Fetch standard). */+ const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);+ /** Lenient flushing, as fetch uses, so a truncated stream still yields what decoded. */+ const ZLIB_OPTIONS = {+ flush: zlib.constants.Z_SYNC_FLUSH,+ finishFlush: zlib.constants.Z_SYNC_FLUSH,+ };+ const BROTLI_OPTIONS = {+ flush: zlib.constants.BROTLI_OPERATION_FLUSH,+ finishFlush: zlib.constants.BROTLI_OPERATION_FLUSH,+ };++ function abortReason(signal: AbortSignal): Error {+ return signal.reason ??+ Object.assign(new Error("This operation was aborted"), { name: "AbortError" });+ }++ interface HopInit {+ method: string;+ headers: Record<string, string>;+ body: string | undefined;+ signal?: AbortSignal;+ }++ /**+ * Headers fetch adds on its own. Without them some servers refuse the+ * request (no User-Agent) or skip compression. Caller values win.+ */+ function withFetchDefaultHeaders(+ headers: Record<string, string>,+ body: string | undefined,+ ): Record<string, string> {+ const out = { ...headers };+ const present = new Set(Object.keys(out).map((k) => k.toLowerCase()));+ const defaults: Array<[string, string]> = [+ ["accept", "*/*"],+ ["accept-encoding", "gzip, deflate, br"],+ ["user-agent", "node"],+ ];+ if (body !== undefined) defaults.push(["content-type", "text/plain;charset=UTF-8"]);+ for (const [k, v] of defaults) {+ if (!present.has(k)) out[k] = v;+ }+ return out;+ }++ /**+ * Undo Content-Encoding like fetch: gzip / deflate / br, last-applied+ * first. An unknown coding leaves the body as it came.+ */+ function decodeBody(incoming: http.IncomingMessage): Readable {+ const codings = (incoming.headers["content-encoding"] || "")+ .toLowerCase()+ .split(",")+ .map((c) => c.trim())+ .filter(Boolean)+ .reverse();+ if (codings.length === 0) return incoming;+ const decoders: NodeJS.ReadWriteStream[] = [];+ for (const coding of codings) {+ if (coding === "gzip" || coding === "x-gzip") decoders.push(zlib.createGunzip(ZLIB_OPTIONS));+ else if (coding === "deflate") decoders.push(zlib.createInflate(ZLIB_OPTIONS));+ else if (coding === "br") decoders.push(zlib.createBrotliDecompress(BROTLI_OPTIONS));+ else return incoming;+ }+ // pipeline destroys every stage when one fails or the last is+ // destroyed (e.g. readBodyCapped cancelling), which closes the socket.+ return pipeline([incoming, ...decoders], () => {}) as unknown as Readable;+ }++ /**+ * Send one request (no redirect following) over a connection whose+ * address went through `guardedLookup`, and wrap the reply in a+ * standard `Response` with `url` set, as fetch would return it.+ */+ function pinnedFetch(url: URL, init: HopInit, opts: UrlGuardOptions): Promise<Response> {+ return new Promise((resolve, reject) => {+ const { signal } = init;+ if (url.username || url.password) {+ reject(new TypeError(+ `Request cannot be constructed from a URL that includes credentials: ${url}`,+ ));+ return;}- if (opts.allowPrivate) continue;- if (family === 4 && isPrivateIpv4(address)) {- throw new Error(- `Refusing ${host} — resolves to private IPv4 ${address}; ${PRIVATE_NETWORK_HINT}`,- );+ if (signal?.aborted) {+ reject(abortReason(signal));+ return;}- if (family === 6 && isPrivateIpv6(address)) {- throw new Error(- `Refusing ${host} — resolves to private IPv6 ${address}; ${PRIVATE_NETWORK_HINT}`,- );+- if (!opts.allowPrivate) {- try { assertLiteralIpIsPublic(url); } catch (e) { reject(e); return; }- }++ try { assertLiteralIpIsPublic(url, opts); } catch (e) { reject(e); return; }++ let req: http.ClientRequest;+ try {+ req = (url.protocol === "https:" ? https : http).request(url, {+ method: init.method,+ headers: withFetchDefaultHeaders(init.headers, init.body),+ // A fresh connection per request: a pooled keep-alive socket was+ // resolved for whichever request opened it (possibly one with+ // allowPrivate), so reusing it would skip this request's lookup.+ agent: false,- ...(opts.allowPrivate ? {} : { lookup: guardedLookup }),++ lookup: createGuardedLookup(opts),+ });+ } catch (e) {+ reject(e);+ return;+ }++ const onAbort = () => req.destroy(abortReason(signal!));+ signal?.addEventListener("abort", onAbort, { once: true });+ // Kept for the request's lifetime: a late socket error with no+ // listener would crash the plugin process.+ req.on("error", (e) => {+ signal?.removeEventListener("abort", onAbort);+ reject(e);+ });+ req.once("response", (incoming) => {+ signal?.removeEventListener("abort", onAbort);+ try {+ resolve(toFetchResponse(incoming, url, init.method, signal));+ } catch (e) {+ incoming.destroy();+ reject(e);+ }+ });+ req.end(init.body);+ });+ }++ function toFetchResponse(+ incoming: http.IncomingMessage,+ url: URL,+ method: string,+ signal: AbortSignal | undefined,+ ): Response {+ const status = incoming.statusCode ?? 0;+ if (status < 200 || status > 599) {+ throw new Error(`Unsupported HTTP status ${status} from ${url.origin}`);+ }+ const headers = new Headers();+ for (let i = 0; i + 1 < incoming.rawHeaders.length; i += 2) {+ headers.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);+ }++ let body: ReadableStream<Uint8Array> | null = null;+ if (method === "HEAD" || NULL_BODY_STATUSES.has(status)) {+ incoming.on("error", () => {});+ incoming.resume();+ } else {+ const decoded = decodeBody(incoming);+ if (signal) {+ // Aborting mid-body errors the stream with the abort reason, as fetch does.+ const onAbort = () => decoded.destroy(abortReason(signal));+ signal.addEventListener("abort", onAbort, { once: true });+ decoded.once("close", () => signal.removeEventListener("abort", onAbort));}+ body = Readable.toWeb(decoded) as unknown as ReadableStream<Uint8Array>;}++ // Response's constructor rejects reason phrases fetch would accept;+ // the phrase is cosmetic.+ const statusMessage = incoming.statusMessage ?? "";+ const statusText = /^[\t\x20-\x7e\x80-\xff]*$/.test(statusMessage) ? statusMessage : "";+ const res = new Response(body, { status, statusText, headers });+ // Only fetch() can set Response.url; callers report it as the final URL.+ const finalUrl = new URL(url);+ finalUrl.hash = "";+ Object.defineProperty(res, "url", { value: finalUrl.toString() });+ return res;}export interface SafeFetchInit {diff --cc lmstudio-plugin/src/util/urlGuard.tsindex 42c1e9700,c5ec22ceb..bfe5b78dc--- a/lmstudio-plugin/src/util/urlGuard.ts+++ b/lmstudio-plugin/src/util/urlGuard.ts@@@ -16,25 -16,21 +16,22 @@@* including IPv6 forms that embed a private IPv4 (IPv4-mapped,* NAT64, 6to4, Teredo)* - common private DNS spellings (localhost, *.local, *.internal, *.lan)+ * - cloud metadata endpoints, even when allowPrivate is set*- * The DNS-resolution-aware check- * (`assertHostnameDoesNotResolveToPrivate`) lives in `safeFetch.ts`- * because it requires `node:dns` and is awaited once per redirect hop- * inside the `safeFetch` wrapper. That additional layer closes the case+ * The DNS-resolution-aware check (`guardedLookup`) lives in+ * `safeFetch.ts` because it requires `node:dns`. It runs as the request+ * socket's `lookup` hook on every hop, so the connection can only use+ * addresses that passed it. That additional layer closes the case* where a public-looking hostname has an A record pointing into* RFC1918 / loopback / link-local space, e.g. `attacker.example A- * 127.0.0.1`. `isPrivateIpv4` / `isPrivateIpv6` are exported so the- * resolver-side check reuses the same range definitions.+ * 127.0.0.1`, and DNS rebinding (a TTL=0 record answering public to a+ * check and private to the connection), because there is no separate+ * check to answer. `isPrivateIpv4` / `isPrivateIpv6` are exported so+ * the resolver-side check reuses the same range definitions.*- * Residual gap: DNS rebinding. An attacker controlling a domain with- * TTL=0 can return a public IP at the time of the guard check and a- * private IP at the time `fetch` connects. Closing this fully requires- * pinning the resolved IP via a custom undici Agent + `lookup` hook —- * tracked as a follow-up. The current layered defense (sync check +- * DNS check + per-redirect re-validation) raises the bar enough to- * stop drive-by SSRF from open redirects and naive hostname tricks- * but is NOT a hardened sandbox.+ * The layered defense (sync check + connect-time DNS check ++ * per-redirect re-validation) stops drive-by SSRF from open redirects,+ * naive hostname tricks and rebinding, but is NOT a hardened sandbox.** To opt-out (e.g. you really do want to point this at your intranet)* call assertSafeUrl(url, { allowPrivate: true }) and pass the samediff --cc web/docs/lm-studio/index.htmlindex 1b02aac95,16ea875c8..5100c22d3--- a/web/docs/lm-studio/index.html+++ b/web/docs/lm-studio/index.html@@@ -47,7 -47,7 +47,7 @@@ lms dev --install</code></pre><p>See L<section class="doc-section" id="lifecycle"><h2>Let continuing browser runs continue</h2><p><code>browser_task</code> waits for a result, but its timeout does not cancel work already running in the extension. Keep the returned <code>runId</code> and use the recovery tool that matches the state.</p><div class="status-strip" aria-label="LM Studio browser task statuses"><div class="status-item"><code>running</code><span>Poll with browser_status</span></div><div class="status-item waiting"><code>needs_user_input</code><span>Ask, then browser_respond</span></div><div class="status-item done"><code>completed</code><span>Result is ready</span></div><div class="status-item"><code>failed</code><span>Read the error and evidence</span></div><div class="status-item"><code>aborted</code><span>Stopped; earlier actions remain</span></div></div><ul><li>Do not start a duplicate <code>browser_task</code> after a timeout; poll the existing run.</li><li>Never invent an answer to a WebBrain clarification. Ask the human and forward their response verbatim.</li><li><code>browser_abort</code> stops future steps. It cannot undo a submitted form, sent message, or other completed action.</li></ul></section>- <section class="doc-section" id="security"><h2>Keep the two trust surfaces clear</h2><ul><li><strong>Public HTTP runs in the local plugin process.</strong> <code>fetch_url</code> can send methods, headers, and bodies, so only request a mutation when you intend one.</li><li><strong>Private network targets are blocked by default.</strong> Loopback, RFC1918, link-local, cloud-metadata, and common intranet hostnames are refused. To reach localhost or your LAN, turn on <strong>Allow private network access</strong> in the plugin’s settings in LM Studio, only in a chat that needs it. The model cannot turn it on, and cloud-metadata endpoints stay blocked even when it is on.</li><li><strong>Redirects are rechecked.</strong> The plugin validates each destination and strips credential-like headers when a redirect crosses origins.</li><li><strong>The browser listener stays on loopback.</strong> Never forward or proxy port <code>17375</code>. The extension handshake identifies the client but is not shared-secret authentication; treat local software as trusted.</li><li><strong>Ask mode is the default.</strong> Use Act only when the requested outcome requires visible browser interaction, and keep the browser where you can stop unexpected behavior.</li><li><strong>The LM Studio model sees tool results.</strong> A browser run also sends task context through the active provider configured inside WebBrain. Choose both model boundaries deliberately.</li></ul><p>For the implementation-level details and residual DNS-rebinding limitation, read the plugin’s <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">safety notes</a>.</p></section>- <section class="doc-section" id="security"><h2>Keep the two trust surfaces clear</h2><ul><li><strong>Public HTTP runs in the local plugin process.</strong> <code>fetch_url</code> can send methods, headers, and bodies, so only request a mutation when you intend one.</li><li><strong>Private network targets are blocked by default.</strong> Loopback, RFC1918, link-local, cloud-metadata, and common intranet hostnames are refused. Use <code>allowPrivate: true</code> only for an explicit local-network task you understand.</li><li><strong>Redirects are rechecked.</strong> The plugin validates each destination and strips credential-like headers when a redirect crosses origins.</li><li><strong>The browser listener stays on loopback.</strong> Never forward or proxy port <code>17375</code>. The extension handshake identifies the client but is not shared-secret authentication; treat local software as trusted.</li><li><strong>Ask mode is the default.</strong> Use Act only when the requested outcome requires visible browser interaction, and keep the browser where you can stop unexpected behavior.</li><li><strong>The LM Studio model sees tool results.</strong> A browser run also sends task context through the active provider configured inside WebBrain. Choose both model boundaries deliberately.</li></ul><p>For the implementation-level details, including how each connection is pinned to the address that was checked, read the plugin’s <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">safety notes</a>.</p></section>++ <section class="doc-section" id="security"><h2>Keep the two trust surfaces clear</h2><ul><li><strong>Public HTTP runs in the local plugin process.</strong> <code>fetch_url</code> can send methods, headers, and bodies, so only request a mutation when you intend one.</li><li><strong>Private network targets are blocked by default.</strong> Loopback, RFC1918, link-local, cloud-metadata, and common intranet hostnames are refused. To reach localhost or your LAN, turn on <strong>Allow private network access</strong> in the plugin’s settings in LM Studio, only in a chat that needs it. The model cannot turn it on, and cloud-metadata endpoints stay blocked even when it is on.</li><li><strong>Redirects are rechecked.</strong> The plugin validates each destination and strips credential-like headers when a redirect crosses origins.</li><li><strong>The browser listener stays on loopback.</strong> Never forward or proxy port <code>17375</code>. The extension handshake identifies the client but is not shared-secret authentication; treat local software as trusted.</li><li><strong>Ask mode is the default.</strong> Use Act only when the requested outcome requires visible browser interaction, and keep the browser where you can stop unexpected behavior.</li><li><strong>The LM Studio model sees tool results.</strong> A browser run also sends task context through the active provider configured inside WebBrain. Choose both model boundaries deliberately.</li></ul><p>For the implementation-level details, including how each connection is pinned to the address that was checked, read the plugin’s <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">safety notes</a>.</p></section><section class="doc-section" id="troubleshooting"><h2>Troubleshooting by symptom</h2><div class="table-wrap"><table><thead><tr><th>Symptom</th><th>What it usually means</th><th>Fix</th></tr></thead><tbody><tr><td>The tools do not appear</td><td>The plugin is not enabled for this chat, or the selected model cannot call tools.</td><td>Enable <strong>webbrain/web-tools</strong> beside the chat input and select a tool-capable model.</td></tr><tr><td><code>browser_status</code> reports disconnected</td><td>The plugin is available, but the WebBrain extension has not attached.</td><td>Use Chromium, enable MCP, and enter exactly <code>ws://127.0.0.1:17375/extension</code>.</td></tr><tr><td>The listener cannot start or reports an address conflict</td><td>Another plugin instance or process already owns port <code>17375</code>.</td><td>Close the duplicate instance, then reload the plugin. Inspect first with <code>lsof -nP -iTCP:17375 -sTCP:LISTEN</code>.</td></tr><tr><td>A public page is empty</td><td>The page renders with JavaScript or hides content behind login.</td><td>If <code>spaSuspected</code> is true, connect the extension and use <code>browser_task</code>.</td></tr><tr><td>The task timed out but the browser is still moving</td><td>The wait budget ended without cancelling the WebBrain run.</td><td>Call <code>browser_status</code> with the returned <code>runId</code>, or <code>browser_abort</code> if you want it stopped.</td></tr><tr><td>Firefox never connects</td><td>Firefox has no offscreen-document bridge runtime.</td><td>Use a Chromium browser for browser tools. The two public HTTP tools remain usable without any extension.</td></tr><tr><td>MCP or WebBrain Cloud disconnected</td><td>The LM Studio URL replaced the extension’s one bridge destination.</td><td>Switch Settings back to port <code>17374</code> for MCP or <code>17373</code> for WebBrain Cloud when finished.</td></tr></tbody></table></div></section>diff --cc web/docs/zh/lm-studio/index.htmlindex 2f2abaa30,d8c2bd4fd..7655c1b41--- a/web/docs/zh/lm-studio/index.html+++ b/web/docs/zh/lm-studio/index.html@@@ -48,7 -48,7 +48,7 @@@ lms dev --install</code></pre><p>参�<section class="doc-section" id="lifecycle"><h2>让正在进行的浏览器运行继续</h2><p><code>browser_task</code> 会等待结果,但其超时不会取消扩展中已在运行的工作。保留返回的 <code>runId</code>,并使用与状态匹配的恢复工具。</p><div class="status-strip" aria-label="LM Studio 浏览器任务状态"><div class="status-item"><code>running</code><span>使用 browser_status 轮询</span></div><div class="status-item waiting"><code>needs_user_input</code><span>提问,然后使用 browser_respond</span></div><div class="status-item done"><code>completed</code><span>结果已就绪</span></div><div class="status-item"><code>failed</code><span>查看错误和证据</span></div><div class="status-item"><code>aborted</code><span>已停止;之前的操作仍然有效</span></div></div><ul><li>超时后不要启动重复的 <code>browser_task</code>;轮询现有运行。</li><li>永远不要为 WebBrain 的澄清问题编造答案。询问用户并逐字转发他们的回答。</li><li><code>browser_abort</code> 停止后续步骤。它无法撤销已提交的表单、已发送的消息或其他已完成的操作。</li></ul></section>- <section class="doc-section" id="security"><h2>保持两个信任面清晰</h2><ul><li><strong>公开 HTTP 在本地插件进程中运行。</strong><code>fetch_url</code> 可以发送方法、请求头和请求体,因此仅在你有意时才请求修改操作。</li><li><strong>默认阻止私有网络目标。</strong>本地回环、RFC1918、链路本地、云元数据和常见内网主机名均被拒绝。如需访问 localhost 或局域网,请仅在需要的对话中,于 LM Studio 的插件设置里打开 <strong>Allow private network access</strong>。模型无法自行打开该设置,并且即使打开,云元数据端点仍会被阻止。</li><li><strong>重定向会被重新检查。</strong>插件会验证每个目标,并在重定向跨域时去除类似凭据的请求头。</li><li><strong>浏览器监听器保持在本地回环。</strong>永远不要转发或代理端口 <code>17375</code>。扩展握手可以识别客户端但不是共享密钥认证;将本地软件视为可信软件。</li><li><strong>Ask 模式是默认选项。</strong>仅在请求的结果需要可见浏览器交互时使用 Act,并保持浏览器在你可以停止意外行为的范围内。</li><li><strong>LM Studio 模型可以看到工具结果。</strong>浏览器运行还会通过 WebBrain 内配置的活跃提供商发送任务上下文。请慎重选择两个模型的边界。</li></ul><p>有关实现级别的细节和残余 DNS 重绑定限制,请阅读插件的 <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">安全说明</a>。</p></section>- <section class="doc-section" id="security"><h2>保持两个信任面清晰</h2><ul><li><strong>公开 HTTP 在本地插件进程中运行。</strong><code>fetch_url</code> 可以发送方法、请求头和请求体,因此仅在你有意时才请求修改操作。</li><li><strong>默认阻止私有网络目标。</strong>本地回环、RFC1918、链路本地、云元数据和常见内网主机名均被拒绝。仅在你理解的明确本地网络任务中使用 <code>allowPrivate: true</code>。</li><li><strong>重定向会被重新检查。</strong>插件会验证每个目标,并在重定向跨域时去除类似凭据的请求头。</li><li><strong>浏览器监听器保持在本地回环。</strong>永远不要转发或代理端口 <code>17375</code>。扩展握手可以识别客户端但不是共享密钥认证;将本地软件视为可信软件。</li><li><strong>Ask 模式是默认选项。</strong>仅在请求的结果需要可见浏览器交互时使用 Act,并保持浏览器在你可以停止意外行为的范围内。</li><li><strong>LM Studio 模型可以看到工具结果。</strong>浏览器运行还会通过 WebBrain 内配置的活跃提供商发送任务上下文。请慎重选择两个模型的边界。</li></ul><p>有关实现级别的细节(包括每个连接如何固定到已检查的地址),请阅读插件的 <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">安全说明</a>。</p></section>++ <section class="doc-section" id="security"><h2>保持两个信任面清晰</h2><ul><li><strong>公开 HTTP 在本地插件进程中运行。</strong><code>fetch_url</code> 可以发送方法、请求头和请求体,因此仅在你有意时才请求修改操作。</li><li><strong>默认阻止私有网络目标。</strong>本地回环、RFC1918、链路本地、云元数据和常见内网主机名均被拒绝。如需访问 localhost 或局域网,请仅在需要的对话中,于 LM Studio 的插件设置里打开 <strong>Allow private network access</strong>。模型无法自行打开该设置,并且即使打开,云元数据端点仍会被阻止。</li><li><strong>重定向会被重新检查。</strong>插件会验证每个目标,并在重定向跨域时去除类似凭据的请求头。</li><li><strong>浏览器监听器保持在本地回环。</strong>永远不要转发或代理端口 <code>17375</code>。扩展握手可以识别客户端但不是共享密钥认证;将本地软件视为可信软件。</li><li><strong>Ask 模式是默认选项。</strong>仅在请求的结果需要可见浏览器交互时使用 Act,并保持浏览器在你可以停止意外行为的范围内。</li><li><strong>LM Studio 模型可以看到工具结果。</strong>浏览器运行还会通过 WebBrain 内配置的活跃提供商发送任务上下文。请慎重选择两个模型的边界。</li></ul><p>有关实现级别的细节(包括每个连接如何固定到已检查的地址),请阅读插件的 <a href="https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/README.md#safety-notes">安全说明</a>。</p></section><section class="doc-section" id="troubleshooting"><h2>按症状排查</h2><div class="table-wrap"><table><thead><tr><th>症状</th><th>通常含义</th><th>解决方法</th></tr></thead><tbody><tr><td>工具没有出现</td><td>此聊天未启用插件,或所选模型无法调用工具。</td><td>在聊天输入旁启用 <strong>webbrain/web-tools</strong>,并选择支持工具的模型。</td></tr><tr><td><code>browser_status</code> 报告已断开连接</td><td>插件可用,但 WebBrain 扩展尚未连接。</td><td>使用 Chromium,启用云桥接,并精确输入 <code>ws://127.0.0.1:17375/extension</code>。</td></tr><tr><td>监听器无法启动或报告地址冲突</td><td>另一个插件实例或进程已占用端口 <code>17375</code>。</td><td>关闭重复实例,然后重新加载插件。先使用 <code>lsof -nP -iTCP:17375 -sTCP:LISTEN</code> 检查。</td></tr><tr><td>公开页面为空</td><td>页面使用 JavaScript 渲染或将内容隐藏在登录后。</td><td>如果 <code>spaSuspected</code> 为 true,连接扩展并使用 <code>browser_task</code>。</td></tr><tr><td>任务超时但浏览器仍在操作</td><td>等待预算已用尽,但 WebBrain 运行未被取消。</td><td>使用返回的 <code>runId</code> 调用 <code>browser_status</code>,或在需要停止时使用 <code>browser_abort</code>。</td></tr><tr><td>Firefox 始终无法连接</td><td>Firefox 没有离屏文档桥接运行时。</td><td>使用 Chromium 浏览器进行浏览器工具操作。两个公开 HTTP 工具无需扩展即可使用。</td></tr><tr><td>MCP 或 WebBrain Cloud 已断开连接</td><td>LM Studio URL 替换了扩展的单个桥接目标。</td><td>完成后将设置切换回端口 <code>17374</code>(MCP)或 <code>17373</code>(WebBrain Cloud)。</td></tr></tbody></table></div></section>