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_runoragent_automaterun can pause with the new statuswaitingand 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_statusand the newagent_replytool return the question at once, with the page it was asked on (read by the server).agent_replyanswers it (question_idis 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 afterAGENT_REPLY_TIMEOUT_MS(30 minutes).AGENT_MAX_QUESTIONS(5 per run;0turns questions off) andallow_questions: falseper 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 answerlists only the runs of the calling MCP session. See Questions from sub-agents. - Purchase guard.
agent_runandagent_automateagents always ask the host (reasonconfirm) 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 aconfirmquestion asked on the same page,browser_click, the submit ofbrowser_fill_form,browser_typewithsubmit: trueandbrowser_press_keyEnter/Spacerefuse 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 newagent_runandagent_automateparameterpurchase_approvalcarries 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 thescript_testruns ofagent_automate) are not covered. See Orders and payments. - Interactive command-line agent.
npm run lmstudio:agentasks 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 withagent_reply. It is on by default in a terminal without--quiet;--no-interactiveturns it off, and--interactiveturns it on for piped input or output. An empty answer stops the agent and leaves the run waiting, so nothing is ordered. The--jsontranscript 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
snapshotstool 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_runtakessnapshotto start a sub-agent signed in, refreshes the snapshot when the run succeeds (update_snapshot), and leaves outbrowser_evaluatein such runs unlessallow_evaluateis set. Sub-agents can save a sign-in they made withsave_sign_in(AGENT_SNAPSHOT_SAVE). Snapshots are stored owner-only inSNAPSHOTS_DIR(thesnapshotsDocker volume) and encrypted at rest with AES-256-GCM whenSNAPSHOTS_KEYis 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 anOrigincheck). 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:downloadandnpm run lmstudio:setupare now Python scripts (scripts/download_obscura.py,scripts/setup_lmstudio.py), standard library only, so they need Python 3.9 or newer: thepython3of a recent Linux distribution, or of macOS with the Xcode Command Line Tools. Their options, output and exit codes are unchanged, andmcp.jsonis 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'sdatafilter where Python has it, installs the binary by rename so a running server keeps its copy, writes.obscura/VERSIONonly after the new binary runs, gives a hint forCERTIFICATE_VERIFY_FAILED, and takes--destto 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 runnpm run py:setuponce (it createspython/.venvwith the versions ofpython/uv.lock). The npm script names are unchanged and go through the new launcherscripts/py.mjs; new scripts arenpm run py:setup,npm run test:pyandnpm 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:agentandnpm run lmstudio:e2eare thesws-lmstudio-agentandsws-lmstudio-e2ecommands, with the same options, prompts, transcript (--json), exit codes and interactive questions.--toolsetsnow 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:e2eis thesws-agents-e2ecommand, with the same scenarios, checks, output and--jsonreport. A lost connection to the server now marks the remaining scenarios as crashed and still writes the summary and the report, and--repeatmust be a whole number.- The website builder (
npm run site:build,npm run site:serve) is thesws-sitecommand (markdown-it-py and Pygments), with the same pages, links and colours.npm run docs:toolsalso writesdocs/tools.json, the tool counts the site shows; CI and the Pages workflow fail when it ordocs/TOOLS.mdis out of date.site:servetakes--port.markedandhighlight.jsare 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
undicipackage'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_cookiesalso 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_cookieandbrowser_set_storage_stateread 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 aspurchase_approvaland 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'sconfirm_purchases, added earlier in this cycle, is replaced bypurchase_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 inagent_runjobs.agent_automateagents 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 sendsconfirm_purchasesis 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(andstructuredContent.also_waiting) and the split ofagent_statusinto 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_statusmarks 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 andagent_waitamong its tools. After that the answer is taken, and the agent says which runs are still working and lists them asunfinishedRunsin the--jsontranscript. 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/mcpfor 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.TOOLSETSlimits 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_runreturns the OUTPUT of a TASK,agent_automatedoes the task and then writes, verifies and stores a reusable script, andagent_findanswers a question with cited sources from several websites (two by default).agent_wait,agent_statusandagent_cancelmanage 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_runandscript_deletemanage the scriptsagent_automatestores.script_runreplays 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(copyconfig/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 inapiKeyandurl,AGENT_LLM_MODELpicks a model, and environment variables that are set override the file field by field. The model'scontextWindowandmaxOutputTokenscap the agent's budget.AGENT_MODELS_FILEpoints at another file.compose.yamlmounts./configread-only at/app/config. See Model configuration. npm run config:checkvalidates the environment variables and the models file and prints the settings the server will use.--pingchecks that the model endpoint answers, and--env-fileloads a.envfile 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/(leveldebug), and entries atinfoand 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:setupadds the server to LM Studio'smcp.json,npm run lmstudio:agentdrives a local model through the browser from the command line, andnpm run lmstudio:e2eruns 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.1only, with optional bearer-token authentication (AUTH_TOKEN) and DNS-rebinding protection. The browser cannot openfile:orjavascript: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-privilegesand 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.