Stealth Web Search

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Sub-agent questions. An agent_run or agent_automate run can pause with the new status waiting and ask the host one question (ask_host), only when it cannot continue correctly without it: before it places an order, pays or takes another step that cannot be undone, when the TASK is ambiguous, for a sign-in code or which account, or for missing information. agent_run, agent_wait, agent_status and the new agent_reply tool return the question at once, with the page it was asked on (read by the server). agent_reply answers it (question_id is required), and the run continues with the same browser. A waiting run gives up its slot, its wait does not count against its step and time budgets, and it continues without an answer after AGENT_REPLY_TIMEOUT_MS (30 minutes). AGENT_MAX_QUESTIONS (5 per run; 0 turns questions off) and allow_questions: false per call limit them, and a model turn pauses on at most one question. Secret answers such as one-time codes, and their code-like parts, are masked in logs, transcripts, results, later questions and on the dashboard, and never stored. Also waiting for your answer lists only the runs of the calling MCP session. See Questions from sub-agents.
  • Purchase guard. agent_run and agent_automate agents always ask the host (reason confirm) before they place an order or pay, also when the TASK tells them to buy something, and the server enforces it: until the host has answered a confirm question asked on the same page, browser_click, the submit of browser_fill_form, browser_type with submit: true and browser_press_key Enter/Space refuse a button whose label looks like the final step of an order or payment (Place your order, Buy now, Pay $17.49 and similar). The host asks its user, or approves the question itself when the user already approved the purchase: the new agent_run and agent_automate parameter purchase_approval carries the user's words, the agent is asked to stay within them, and the question the host gets shows them (question.purchase_approval) with the hint to approve a matching checkout without asking again. The dashboard shows the approval on the run's card. Page scripts, direct navigation and stored scripts (also the script_test runs of agent_automate) are not covered. See Orders and payments.
  • Interactive command-line agent. npm run lmstudio:agent asks you when a sub-agent run it started waits for your answer, for example before it places an order the task did not approve: the model ends its turn with the question (item, total, address, payment method, site), your answer goes back to it, and it answers the sub-agent with agent_reply. It is on by default in a terminal without --quiet; --no-interactive turns it off, and --interactive turns it on for piped input or output. An empty answer stops the agent and leaves the run waiting, so nothing is ordered. The --json transcript lists the questions and answers (userTurns) and the runs still waiting (waitingRuns) or still queued or running (unfinishedRuns) at the end. See Approving a sub-agent's purchase.
  • Snapshots (saved sign-ins). A new snapshots tool group (snapshot_list, snapshot_save, snapshot_describe, snapshot_load, snapshot_delete) saves a browser's cookies and site storage for chosen sites under a name and a description, and loads them into a browser so agents do not sign in again. agent_run takes snapshot to start a sub-agent signed in, refreshes the snapshot when the run succeeds (update_snapshot), and leaves out browser_evaluate in such runs unless allow_evaluate is set. Sub-agents can save a sign-in they made with save_sign_in (AGENT_SNAPSHOT_SAVE). Snapshots are stored owner-only in SNAPSHOTS_DIR (the snapshots Docker volume) and encrypted at rest with AES-256-GCM when SNAPSHOTS_KEY is set. Loading or saving a snapshot unloads the other snapshots loaded in that browser whose sites overlap, a refresh is refused when the browser lost the saved sign-in cookies (signed out), and saving is refused when the page's storage comes from another loaded snapshot. Agents delete a snapshot only when the user asks. See Snapshots.
  • Dashboard. A Snapshots tab next to Agents lists the saved sign-ins and deletes one after a confirmation (DELETE /api/snapshots/<name>, protected by a custom header and an Origin check). The Agents tab shows waiting runs with their whole question and never drops a waiting, running or queued run from its list, and the run details list the questions asked.

Changed

  • The server now offers 57 tools with a sub-agent model configured, 50 without.
  • npm run obscura:download and npm run lmstudio:setup are now Python scripts (scripts/download_obscura.py, scripts/setup_lmstudio.py), standard library only, so they need Python 3.9 or newer: the python3 of a recent Linux distribution, or of macOS with the Xcode Command Line Tools. Their options, output and exit codes are unchanged, and mcp.json is still written byte for byte as before. The downloader streams the archive to disk (peak memory about 30-55 MB instead of about 430 MB), unpacks it with tarfile's data filter where Python has it, installs the binary by rename so a running server keeps its copy, writes .obscura/VERSION only after the new binary runs, gives a hint for CERTIFICATE_VERIFY_FAILED, and takes --dest to install elsewhere; unknown options now exit with 2. Existing .obscura/ folders are not downloaded again.
  • The developer tools that run outside the server are now Python, in the new python/ package. They need Python 3.10 or newer: with uv installed the npm scripts run them as is, otherwise run npm run py:setup once (it creates python/.venv with the versions of python/uv.lock). The npm script names are unchanged and go through the new launcher scripts/py.mjs; new scripts are npm run py:setup, npm run test:py and npm run lint:py. The server, the stdio bridge, the dashboard and the Docker image stay in TypeScript (see Why the server stays in TypeScript).
  • npm run lmstudio:agent and npm run lmstudio:e2e are the sws-lmstudio-agent and sws-lmstudio-e2e commands, with the same options, prompts, transcript (--json), exit codes and interactive questions. --toolsets now reads each tool's group from the server (_meta), so the agent also runs without a checkout (uvx --from ./python sws-lmstudio-agent), and a group the server does not offer is reported as an unknown toolset. Some error texts that come from the HTTP stack are worded differently, and Ctrl+C during a retry wait stops at once. It starts about 150 ms slower than the TypeScript version (loading the MCP SDK) and adds about 0.3-0.7 ms per step on a current Node, which a model's answer time dwarfs.
  • npm run agents:e2e is the sws-agents-e2e command, with the same scenarios, checks, output and --json report. A lost connection to the server now marks the remaining scenarios as crashed and still writes the summary and the report, and --repeat must be a whole number.
  • The website builder (npm run site:build, npm run site:serve) is the sws-site command (markdown-it-py and Pygments), with the same pages, links and colours. npm run docs:tools also writes docs/tools.json, the tool counts the site shows; CI and the Pages workflow fail when it or docs/TOOLS.md is out of date. site:serve takes --port. marked and highlight.js are no longer dependencies.
  • The stdio bridge relays each tool call about 1.5 ms faster on Node 24.17 to 24.20, whose bundled undici waits a timer tick before it reuses a keep-alive connection: there it sends requests through the undici package's Agent (a new dependency), unless a dispatcher such as a proxy was installed. Other Node versions are unchanged.
  • The dashboard encodes each frame and event once for all viewers instead of once per viewer (server CPU with 20 viewers about 3% instead of 14%), and the log feed of the dashboard keeps its last 2000 lines in a ring buffer and parses them only while a viewer is connected (a CDP command with debug logging about 49 µs instead of 66 µs).
  • browser_clear_cookies also unloads the snapshots loaded in the browser, so their site storage is no longer restored on page loads.
  • Cookie expiries more than 400 days ahead are capped at 400 days from now when cookies are saved into a snapshot or restored (snapshots, browser_set_storage_state), so cookies that never expire (Expires=31 Dec 9999) are restored instead of dropped. browser_set_cookie and browser_set_storage_state read an expiry as milliseconds only above 1e12 (was 1e11).
  • Sub-agent prompts: an agent that needs a sign-in asks only for a one-time code or which account, never types a password the TASK did not give it, and otherwise reports which site needs a sign-in. The command-line agent (npm run lmstudio:agent) is told to answer the questions of the sub-agent runs it started itself, to pass a purchase its task approves as purchase_approval and approve the matching question, and, for an order its task did not approve, to ask the user when it runs interactively, or else to refuse it and report it as ready for the user.
  • The Obscura connection budget (--max-connections) now counts runs that wait for an answer.
  • agent_run's confirm_purchases, added earlier in this cycle, is replaced by purchase_approval. The agent now always asks before it orders or pays, also for a purchase the user approved in advance, and the purchase guard is always on in agent_run jobs. agent_automate agents follow the same rule: a TASK that approves the purchase no longer lets them order without asking, the guard now covers their browser tools, and with questions off they never order. A call that still sends confirm_purchases is not refused: the parameter is ignored. The host is told to approve a purchase question itself when it matches what its user approved, and never to approve a purchase its user did not approve.

Fixed

  • Waiting runs belong to the MCP session that started them. Also waiting for your answer (and structuredContent.also_waiting) and the split of agent_status into your runs and (started by …: theirs to answer) matched runs to the caller by client name and version, which every run of the command-line agent shares. A second run of it was then shown a question the first one had left unanswered as its own, and its model asked the user about that question instead of its own run's. The server now records the session that starts a run and compares sessions when the run and the caller both have one; a client without a session (the stateless 2026-07-28 protocol), or a run started without one, is still matched by name and version. agent_status marks a run of another session of the same client (started by another session of <client>: theirs to answer). The session id is not shown in results or on the run's card. See While a run waits.
  • The command-line agent waits for the sub-agent runs it started. A final answer the model gives while a run it started is still queued or running is not taken yet: the model is told to wait for that run with agent_wait (Run r… you started is still working. …), at most twice per run of the agent, interactive or not, and only with a step left and agent_wait among its tools. After that the answer is taken, and the agent says which runs are still working and lists them as unfinishedRuns in the --json transcript. It also names them when it stops at the step limit or on an error. See The command-line agent.
  • A tool call no longer stays in memory for TOOL_TIMEOUT_MS (120 s) after it finishes: its timeout timer was never cleared, so under load every call's logger, abort signal and context were kept. Peak memory in a load test fell from about 750 MB to about 415 MB, and throughput rose by about a third.

0.1.0 - 2026-09-26

First public release.

Added

  • MCP server for the Obscura browser. Streamable HTTP at http://127.0.0.1:8931/mcp for both the 2025 and 2026 protocol revisions, and a stdio bridge (dist/stdio-bridge.js) for stdio-only clients. The Docker image bundles the Obscura v0.2.2 stealth release, checksum-verified at build time.
  • 41 browser_* tools in seven groups (core, content, forms, tabs, state, debug, capture): navigation, page reading (text, Markdown, links, structured extraction), clicking, typing, forms, keyboard, scrolling, waits, tabs, cookies and session state, JavaScript evaluation, console and network inspection, screenshots and PDFs. TOOLSETS limits the tools a client sees. See the tool reference.
  • Sub-agents that run inside the container against any OpenAI-compatible chat completions endpoint (vLLM, LM Studio, Ollama, OpenAI and others): agent_run returns the OUTPUT of a TASK, agent_automate does the task and then writes, verifies and stores a reusable script, and agent_find answers a question with cited sources from several websites (two by default). agent_wait, agent_status and agent_cancel manage runs. Each run gets its own isolated browser, and sub-agent and script browsers run on a second Obscura process (OBSCURA_SEPARATE_ENGINE, on by default). See Sub-agents.
  • Automation scripts. script_list, script_get, script_run and script_delete manage the scripts agent_automate stores. script_run replays a job without a model, in a QuickJS WebAssembly sandbox with no Node.js APIs and with memory, time and call limits.
  • Model configuration file. config/models.json (copy config/models.example.json) configures the sub-agents' model in the provider-list format that editors use for custom endpoints. Comments and trailing commas are accepted, duplicate keys are reported, ${VAR} works in apiKey and url, AGENT_LLM_MODEL picks a model, and environment variables that are set override the file field by field. The model's contextWindow and maxOutputTokens cap the agent's budget. AGENT_MODELS_FILE points at another file. compose.yaml mounts ./config read-only at /app/config. See Model configuration.
  • npm run config:check validates the environment variables and the models file and prints the settings the server will use. --ping checks that the model endpoint answers, and --env-file loads a .env file first.
  • Live dashboard at http://127.0.0.1:8931/: a live view of the agent's tab with click, typing and scroll markers, an Activity timeline of every tool call, and Console, Network, Logs, Sessions and Agents tabs. A browser picker switches the live view to any sub-agent's private browser.
  • Structured logging. Every MCP message, tool call, CDP command and event, page console message and network request is written as JSON lines to rotating files in ./logs/ (level debug), and entries at info and above also go to stdout. Every sub-agent run leaves a JSON transcript in ./logs/agent-runs/ (AGENT_TRANSCRIPTS, on by default). Passwords, cookie values and credential headers are redacted by default (LOG_REDACT_SECRETS). See Logging.
  • LM Studio integration. npm run lmstudio:setup adds the server to LM Studio's mcp.json, npm run lmstudio:agent drives a local model through the browser from the command line, and npm run lmstudio:e2e runs end-to-end scenarios with a real model. See LM Studio.
  • Client examples for LM Studio, Claude Code, Claude Desktop, Cursor, VS Code, OpenAI Codex CLI, Gemini CLI, Continue and Cline in examples/. Each one is explained in Connecting MCP clients.
  • Hardened container. The port is published on 127.0.0.1 only, with optional bearer-token authentication (AUTH_TOKEN) and DNS-rebinding protection. The browser cannot open file: or javascript: URLs or, by default, private networks (ALLOW_PRIVATE_NETWORK). The container runs as a non-root user on a read-only filesystem, with all capabilities dropped, no-new-privileges and a health check at /healthz.
  • Tests and CI. Unit tests, an integration suite that runs against the real Obscura engine (locally or in the container), sub-agent tests with a scripted model, and live checks with a real model (npm run agents:e2e, npm run lmstudio:e2e). GitHub Actions runs the typecheck, the unit and integration tests, the build and the Docker suite.
  • Documentation for getting started, MCP clients, LM Studio, configuration, the models file, sub-agents, tools, logging, troubleshooting and architecture in docs/, also published as a website.