Tools exposed (13)

browser_open, browser_snapshot, browser_screenshot, browser_click, browser_type, browser_press, browser_get_text, browser_page_info, browser_wait, browser_find, browser_navigate, browser_eval, browser_close. Curated from agent-browser's 100+ subcommand surface — chosen to be the set an LLM actually needs without polluting the model's tool list.

Two bugs hit and fixed

1. spawn npx ENOENT

LM Studio's plugin runtime does not inherit the user's shell PATH. spawn("npx", ...) fails because the plugin's process.env.PATH is something like /usr/bin:/bin — Homebrew's /opt/homebrew/bin (where npx lives on Apple silicon) isn't on it.

Constraint from the user: do NOT bundle agent-browser as a plugin dependency. The plugin must work via the host system's npx / agent-browser.

Fix (src/agentBrowser.ts): resolveAbsolute(cmd) resolves npx (or whatever the user configures) to an absolute path before spawn:

• Scans candidate dirs: Homebrew (/opt/homebrew/bin, /usr/local/bin), system bins, plus ~/.volta/bin, ~/.fnm/current/bin, ~/.nvm/current/bin, ~/.asdf/shims, ~/.bun/bin, ~/.local/bin, ~/.npm-global/bin, and ~/node_modules/.bin.
• Falls back to /bin/sh -lc 'command -v <cmd>' (login shell sources the user's profile) if scanning misses.
• Caches the resolved path so we pay the cost once.

Spawned children also receive an enriched PATH (enrichedPath()) so npx itself can find node and resolve agent-browser.

2. WebSocket closed by the client on every tool call

Symptom: plugin loaded fine, every tool call failed silently with the WS-close message in LM Studio.

Root cause: agent-browser's CLI parses subcommands first and global flags after the subcommand. The wrapper was emitting

agent-browser --session lmstudio --timeout 30000 open https://...

agent-browser saw --timeout as the subcommand, exited with Unknown command: --timeout in ~150ms, the tool returned an error string, and LM Studio's tool-call layer surfaced "WebSocket closed by the client" downstream.

Fix (src/agentBrowser.ts:152): subcommand args go first, global flags last:

agent-browser open https://... --session lmstudio --timeout 30000

Verified by running the binary directly, then by the integration test below.

Integration test

test/verify-nytimes.js, run via npm run test:verify:

• Strips process.env.PATH to /usr/bin:/bin to mimic the LM Studio plugin runtime (so PATH discovery is exercised, not bypassed by the developer's shell).
• Uses a per-run unique session name to avoid colliding with the user's open browser session.
• Sequence: open https://www.nytimes.com → snapshot -c -d 3 → get title → get url → close.
• Asserts: every step exits 0; snapshot contains [ref=e; title matches /new york times/i; URL contains nytimes.com.
• Last verified PASS in 4.2s.

Config (configSchematics.ts)

createConfigSchematics() field types verified against the SDK's basicKVValueTypesLibrary declaration in @lmstudio/sdk/dist/index.d.ts: numeric accepts min, max, int, step; select takes options as strings or {value, displayName} objects.

Human-emulation flag plumbing

The five human-emulation fields are appended to globalFlags in runAgentBrowser, so they tail the subcommand and respect invariant #2. agent-browser applies these when its daemon launches Chrome; once a session is already running they're effectively no-ops, so re-sending on every command is safe (matches how --session/--timeout already work).

viewport and extraBrowserArgs both target --args and are merged into a single comma-separated value via buildLaunchArgs. Empty fields drop out individually — clearing userAgent doesn't affect viewport, etc.

Wrapper invariants worth preserving

• Argument order in runAgentBrowser: [...prefix, ...args, ...globalFlags]. Do not reorder — the CLI parses subcommands first.
• resolveCommand is async because the shell-fallback path uses execFile.
• Spawned child gets env: { ...process.env, PATH: enrichedPath() } so npx can re-resolve descendants.
• Abort handling: signal.addEventListener("abort", ...) sends SIGTERM, and the listener is removed on close/error. No SIGKILL escalation yet — add one if hangs surface.

Known unknowns / not done

• No CI wiring. npm run test:verify is meant for local validation; it makes real network calls to nytimes.com and depends on Chrome for Testing being installed via agent-browser install.
• No screenshot tool integration test. Easy to add — call browser_screenshot and assert the file exists.
• No Windows verification. PATH discovery has Windows branches but they're untested.
• No prewarm step on plugin startup. If first tool calls feel slow because npx hasn't cached agent-browser yet, consider firing runAgentBrowser(settings, ["--version"], { includeSession: false, includeTimeout: false }) in toolsProvider (don't await) to pre-download.

How to run

cd /Users/mbagley/working/lmstudio-agent-browser-plugin
npm install
agent-browser install      # one-time: download Chrome for Testing (host-side)
npm run dev                # lms dev — load into LM Studio
npm run test:verify        # network integration test

LM Studio Hub: mbagley/agent-browser (revision 1, not yet pushed).