synapse-orch-ai 1.9.2 → 1.9.3

package/backend/core/browser_automation.py

@@ -0,0 +1,91 @@
+"""What the Browser Automation server may be asked to do.
+
+The server is Playwright's MCP server (`@playwright/mcp`), started by `core/server.py`, on by default, and called
+by agents that read web pages, so what a page says can steer it. Its tools are offered through `gated()`:
+
+* **Only the tools reviewed for the pinned version.** None that run code in the server's own process
+  (`browser_run_code_unsafe`; Playwright's own description calls it RCE-equivalent), run a model's script in the
+  page (`browser_evaluate`), or read local files into a page (`browser_file_upload`, `browser_drop`). A tool a
+  later version adds is not offered until someone reviews it and adds it here.
+* **A `url` is http(s)**, or `about:blank`: never `file:`, `chrome:`, `data:` and the like.
+* **A `filename` stays in the server's folder**: relative, no `..`. The server is started with that folder as its
+  working directory and output directory, so it is where its own files land.
+
+Where the browser may connect is not decided here: its network goes through the egress proxy
+(`core.egress_proxy`). BRW1's browser component replaces this server and its gate (`core/browser/gate.py`).
+"""
+from __future__ import annotations
+
+from pathlib import PurePosixPath, PureWindowsPath
+from typing import Any
+from urllib.parse import urlsplit
+
+#: The server's name in `core/server.py`'s list, and the package it runs, pinned: `npx -y @playwright/mcp` ran
+#: whatever was newest the first time, and a new version's new tools reached agents unreviewed.
+BROWSER_AUTOMATION = "Browser Automation"
+PLAYWRIGHT_MCP = "@playwright/mcp@0.0.83"
+
+#: The tools of the pinned version that are offered. Reviewed 2026-10-28 against what 0.0.83 lists.
+OFFERED = frozenset({
+    "browser_navigate", "browser_navigate_back", "browser_tabs", "browser_snapshot", "browser_find",
+    "browser_wait_for", "browser_take_screenshot", "browser_console_messages", "browser_network_requests",
+    "browser_network_request", "browser_click", "browser_type", "browser_fill_form", "browser_select_option",
+    "browser_press_key", "browser_hover", "browser_drag", "browser_handle_dialog", "browser_resize",
+    "browser_emulate_media", "browser_close",
+})
+
+_URL_ARGS = ("url",)
+_FILE_ARGS = ("filename",)
+
+
+def refusal(name: str, arguments: dict | None) -> str | None:
+    """Why this call is not made, or None when it may be."""
+    if name not in OFFERED:
+        return f"{name} is not available in Synapse's browser."
+    args = arguments or {}
+    for key in _URL_ARGS:
+        url = args.get(key)
+        if url is None:
+            continue
+        scheme = urlsplit(str(url)).scheme.lower()
+        if scheme not in ("http", "https") and str(url) != "about:blank":
+            return f"{name} opens http and https addresses only."
+    for key in _FILE_ARGS:
+        filename = args.get(key)
+        if filename is None:
+            continue
+        text = str(filename)
+        if (text.startswith(("/", "\\", "~")) or PureWindowsPath(text).drive
+                or ".." in PurePosixPath(text.replace("\\", "/")).parts):
+            return f"{name} saves only inside its own folder: give a file name, not a path."
+    return None
+
+
+class _Gated:
+    """The server's session, offering only `OFFERED` and refusing what `refusal` refuses. Anything else (a ping,
+    initialize) is the session's own."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._session, name)
+
+    async def list_tools(self, *args: Any, **kwargs: Any) -> Any:
+        result = await self._session.list_tools(*args, **kwargs)
+        return result.model_copy(update={"tools": [t for t in result.tools if t.name in OFFERED]})
+
+    async def call_tool(self, name: str, arguments: dict | None = None, *args: Any, **kwargs: Any) -> Any:
+        reason = refusal(name, arguments)
+        if reason is not None:
+            import mcp.types as types
+
+            return types.CallToolResult(content=[types.TextContent(type="text", text=reason)], isError=True)
+        return await self._session.call_tool(name, arguments, *args, **kwargs)
+
+
+def gated(server_name: str, session: Any) -> Any:
+    """`session`, gated when it is the Browser Automation server's; any other server's as it is."""
+    if server_name != BROWSER_AUTOMATION or isinstance(session, _Gated):
+        return session
+    return _Gated(session)

package/backend/core/egress_guard.py

@@ -149,13 +149,34 @@ async def check_host(host: str) -> None:
         raise BlockedEgress("that URL has no host")
     if host in allowed_hosts():
         return
+    _check_addresses(host, await _addresses(host))
 
+
+async def checked_addresses(host: str) -> list[str]:
+    """The addresses behind `host`, every one of them public, or raise `BlockedEgress`.
+
+    For a caller that opens the connection itself (`core.egress_proxy`): it dials
+    one of these and never the name again, so the address it checked is the
+    address it reaches. A host in `EGRESS_ALLOW_HOSTS` is resolved, not checked.
+    """
+    host = host.strip().lower().strip("[]")
+    if not host:
+        raise BlockedEgress("that URL has no host")
+    addresses = await _addresses(host)
+    if host not in allowed_hosts():
+        _check_addresses(host, addresses)
+    return addresses
+
+
+async def _addresses(host: str) -> list[str]:
     try:
         ipaddress.ip_address(host)
-        addresses = [host]
+        return [host]
     except ValueError:
-        addresses = await resolve(host)
+        return await resolve(host)
+
 
+def _check_addresses(host: str, addresses: list[str]) -> None:
     for address in addresses:
         reason = reject_address(address)
         if reason is not None:

package/backend/core/egress_proxy.py

@@ -0,0 +1,229 @@
+"""One egress proxy for every browser Synapse starts.
+
+`core/egress_guard.py` decides where a fetch may go. A browser makes its own
+requests — redirects, a page's scripts, in-page fetches, WebSockets, service
+workers — and a hook inside the browser does not see every one of them. A
+proxy does: the browser is started with this one as its proxy, Playwright puts
+loopback through it too (`<-loopback>` in Chromium's bypass list), and it opens
+no connection the guard refuses.
+
+It also closes the window the guard leaves open on purpose. The guard resolves
+a name, and the fetch it guards resolves it again; here the address that was
+checked (`egress_guard.checked_addresses`) is the address dialled, and the name
+is never looked up a second time.
+
+What it speaks is the least a browser needs: `CONNECT host:port` for TLS and
+WebSockets, and an absolute-form `http://` request for plain HTTP, sent on as
+one request per connection (`Connection: close`) so a second request on the
+same connection cannot name another host. A refusal is a `403` whose body is
+the guard's message (it names the host asked for, never an address it
+resolved to); anything that is not a proxy request is a `400`.
+
+It listens on loopback and needs no credentials: what it reaches is the public
+internet, which anything on the machine reaches already.
+
+Deliberately stdlib-only, like the guard: the scraper's subprocess starts its own.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+from urllib.parse import urlsplit
+
+from core import egress_guard
+
+#: What a Chromium behind this proxy is started with. UDP never goes through a proxy: WebRTC takes the proxied path
+#: or none, and QUIC, which WebTransport rides with no route in its way, is off.
+CHROMIUM_ARGS = ("--force-webrtc-ip-handling-policy=disable_non_proxied_udp", "--disable-quic")
+
+#: A request head larger than this is not one a browser sends.
+_HEAD_LIMIT = 64 * 1024
+_HEAD_TIMEOUT_SECONDS = 30.0
+CONNECT_TIMEOUT_SECONDS = 10.0
+#: After the browser closes its side, how long the other side has to finish.
+_DRAIN_SECONDS = 30.0
+
+_REASONS = {400: "Bad Request", 403: "Forbidden", 502: "Bad Gateway"}
+
+#: Headers meant for the proxy itself, never sent on.
+_FOR_THE_PROXY = {"proxy-connection", "proxy-authorization", "proxy-authenticate"}
+
+
+class _BadRequest(ValueError):
+    pass
+
+
+class _Request:
+    def __init__(self, head: bytes):
+        lines = head[:-4].decode("latin-1").split("\r\n")
+        parts = lines[0].split(" ")
+        if len(parts) != 3 or not parts[2].startswith("HTTP/"):
+            raise _BadRequest("not an HTTP request")
+        self.method, target, version = parts
+        self.tunnel = self.method.upper() == "CONNECT"
+        try:
+            if self.tunnel:
+                url = urlsplit(f"//{target}")
+                self.host, self.port = url.hostname, url.port
+                if not self.host or not self.port:
+                    raise _BadRequest("CONNECT needs host:port")
+                self.forward = b""
+                return
+            url = urlsplit(target)
+            self.host, self.port = url.hostname, url.port or 80
+        except ValueError as exc:
+            raise _BadRequest(f"not an address: {exc}") from None
+        if url.scheme != "http" or not self.host:
+            raise _BadRequest("a proxy request is CONNECT host:port or an absolute http:// URL")
+
+        headers = []
+        for line in lines[1:]:
+            name, _, value = line.partition(":")
+            if name.strip().lower() not in _FOR_THE_PROXY:
+                headers.append((name.strip(), value.strip()))
+        connection = {v.strip().lower() for n, value in headers if n.lower() == "connection"
+                      for v in value.split(",")}
+        upgrade = "upgrade" in connection and any(n.lower() == "upgrade" for n, _ in headers)
+        if not upgrade:
+            headers = [(n, v) for n, v in headers if n.lower() not in ("connection", "keep-alive")]
+            headers.append(("Connection", "close"))
+        path = (url.path or "/") + (f"?{url.query}" if url.query else "")
+        self.forward = "".join([f"{self.method} {path} {version}\r\n",
+                                *(f"{n}: {v}\r\n" for n, v in headers), "\r\n"]).encode("latin-1")
+
+
+class EgressProxy:
+    """A loopback proxy that dials only what `core.egress_guard` allows. `start()` once, `close()` when done."""
+
+    host = "127.0.0.1"
+
+    def __init__(self) -> None:
+        self.port = 0
+        self.loop: asyncio.AbstractEventLoop | None = None
+        self._server: asyncio.base_events.Server | None = None
+        self._starting: asyncio.Future | None = None
+        self._writers: set[asyncio.StreamWriter] = set()
+        self._closed = False
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    async def start(self) -> str:
+        """Listen, once; every caller waits for the same start."""
+        if self._starting is None:
+            self.loop = asyncio.get_running_loop()
+            self._starting = asyncio.ensure_future(self._listen())
+        await asyncio.shield(self._starting)
+        return self.url
+
+    async def _listen(self) -> None:
+        self._server = await asyncio.start_server(self._serve, self.host, 0, limit=_HEAD_LIMIT)
+        self.port = self._server.sockets[0].getsockname()[1]
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._server is not None:
+            self._server.close()
+        for writer in list(self._writers):
+            writer.close()
+        if self._server is not None:
+            await self._server.wait_closed()
+
+    async def _serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._writers.add(writer)
+        upstream: asyncio.StreamWriter | None = None
+        host = ""
+        try:
+            try:
+                head = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), _HEAD_TIMEOUT_SECONDS)
+            except (asyncio.IncompleteReadError, asyncio.LimitOverrunError, TimeoutError, ConnectionError):
+                return
+            request = _Request(head)
+            host = request.host
+            addresses = await egress_guard.checked_addresses(host)
+            up_reader, upstream = await _dial(addresses, request.port)
+            self._writers.add(upstream)
+            if request.tunnel:
+                writer.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+            else:
+                upstream.write(request.forward)
+            await _relay(reader, writer, up_reader, upstream)
+        except _BadRequest as exc:
+            _answer(writer, 400, str(exc))
+        except egress_guard.BlockedEgress as exc:
+            print(f"egress proxy: refused {host}: {exc}", file=sys.stderr)
+            _answer(writer, 403, str(exc))
+        except (OSError, TimeoutError):
+            _answer(writer, 502, f"could not reach {host}")
+        finally:
+            for w in (upstream, writer):
+                if w is not None:
+                    self._writers.discard(w)
+                    w.close()
+
+
+async def _dial(addresses: list[str], port: int):
+    """A connection to the first of `addresses` that answers. Never the name: the addresses are what was checked."""
+    last: BaseException = OSError("no address")
+    for address in addresses:
+        try:
+            return await asyncio.wait_for(asyncio.open_connection(address, port), CONNECT_TIMEOUT_SECONDS)
+        except (OSError, TimeoutError) as exc:
+            last = exc
+    raise last
+
+
+async def _pipe(src: asyncio.StreamReader, dst: asyncio.StreamWriter) -> None:
+    try:
+        while data := await src.read(65536):
+            dst.write(data)
+            await dst.drain()
+    except ConnectionError:
+        pass
+
+
+async def _relay(client_r, client_w, up_r, up_w) -> None:
+    """Both ways until the far side is done. The browser closing its side gives the far side a moment to finish."""
+    outbound = asyncio.ensure_future(_pipe(client_r, up_w))
+    inbound = asyncio.ensure_future(_pipe(up_r, client_w))
+    try:
+        done, _ = await asyncio.wait({outbound, inbound}, return_when=asyncio.FIRST_COMPLETED)
+        if inbound not in done:
+            if up_w.can_write_eof():
+                try:
+                    up_w.write_eof()
+                except OSError:
+                    pass
+            await asyncio.wait({inbound}, timeout=_DRAIN_SECONDS)
+    finally:
+        for task in (outbound, inbound):
+            task.cancel()
+
+
+def _answer(writer: asyncio.StreamWriter, status: int, reason: str) -> None:
+    body = f"{reason}\n".encode()
+    try:
+        writer.write(f"HTTP/1.1 {status} {_REASONS[status]}\r\nContent-Type: text/plain; charset=utf-8\r\n"
+                     f"Content-Length: {len(body)}\r\nX-Synapse-Egress: refused\r\nConnection: close\r\n\r\n"
+                     .encode() + body)
+    except (OSError, RuntimeError):
+        pass
+
+
+_shared: EgressProxy | None = None
+
+
+async def shared() -> EgressProxy:
+    """This event loop's proxy, started on first use. A closed one, or one from another loop, is replaced."""
+    global _shared
+    loop = asyncio.get_running_loop()
+    proxy = _shared
+    if proxy is None or proxy.closed or (proxy.loop is not None and proxy.loop is not loop):
+        proxy = _shared = EgressProxy()
+    await proxy.start()
+    return proxy

package/backend/core/server.py

@@ -88,6 +88,7 @@ _settings = load_settings()
 if _settings.get("ollama_base_url"):
     os.environ["OLLAMA_BASE_URL"] = _settings["ollama_base_url"]
 
+from core.browser_automation import gated
 from core.tools_registry import ALL_NATIVE_TOOLS
 TOOLS_LIST = dict(ALL_NATIVE_TOOLS)
 
@@ -178,6 +179,18 @@ def _filesystem_server_spec() -> dict:
     }
 
 
+#: Synapse's egress proxy (`core.egress_proxy`), which Browser Automation's browser goes through; lifespan starts it.
+_browser_proxy_url: str | None = None
+
+
+def _native_tool_args(name: str) -> list[str]:
+    """What a native tool's server is started with beyond its script. The scraper saves screenshots in its own
+    folder in the vault and nowhere else (F1066)."""
+    if name == "web_scraper":
+        return ["--output-dir", str((Path(DATA_DIR) / "vault" / "tool_outputs" / "screenshots").resolve())]
+    return []
+
+
 def _build_native_mcp_servers() -> list[dict]:
     """
     Build the list of native MCP servers to connect at startup.
@@ -198,12 +211,31 @@ def _build_native_mcp_servers() -> list[dict]:
             # Fallback for old configs
             env_dict["PLAYWRIGHT_BROWSERS_PATH"] = os.path.expanduser("~/.cache/ms-playwright")
 
-        servers.append({
-            "name": "Browser Automation",
-            "command": _NPX_CMD,
-            "args": ["-y", "@playwright/mcp", "--browser", "chrome", "--output-dir", "data/vault/playwright"],
-            "env": env_dict,
-        })
+        from core.browser_automation import BROWSER_AUTOMATION, PLAYWRIGHT_MCP
+
+        if _browser_proxy_url is None:
+            # Never without its proxy: lifespan starts it before any server is spawned.
+            print("Warning: the egress proxy is not running — not starting Browser Automation.")
+        else:
+            # Its own folder is its output directory and its working directory: the server reads and writes files
+            # only inside those two. It was the relative "data/vault/playwright", resolved against the home
+            # directory it was started in.
+            folder = (Path(DATA_DIR) / "vault" / "playwright").resolve()
+            folder.mkdir(parents=True, exist_ok=True)
+            # Its browser's own flags, in a file outside that folder (its tools write there), rewritten at every start.
+            from core import egress_proxy
+
+            config = Path(DATA_DIR) / "browser_automation" / "config.json"
+            config.parent.mkdir(parents=True, exist_ok=True)
+            config.write_text(json.dumps({"browser": {"launchOptions": {"args": list(egress_proxy.CHROMIUM_ARGS)}}}))
+            servers.append({
+                "name": BROWSER_AUTOMATION,
+                "command": _NPX_CMD,
+                "args": ["-y", PLAYWRIGHT_MCP, "--browser", "chrome", "--output-dir", str(folder),
+                         "--proxy-server", _browser_proxy_url, "--config", str(config)],
+                "env": env_dict,
+                "cwd": str(folder),
+            })
 
     # --- Google Workspace MCP Server (Gmail, Drive, Calendar) ---
     google_env = _get_google_oauth_env()
@@ -392,10 +424,14 @@ def _log_security_posture() -> None:
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    global exit_stack
+    global exit_stack, _browser_proxy_url
     print("Starting Multi-Agent Orchestrator...")
     _log_security_posture()
     exit_stack = AsyncExitStack()
+    # Before any browser is started: every one goes through it.
+    from core import egress_proxy
+
+    _browser_proxy_url = (await egress_proxy.shared()).url
     
     if _settings.get("coding_agent_enabled"):
         try:
@@ -415,7 +451,7 @@ async def lifespan(app: FastAPI):
 
             server_params = StdioServerParameters(
                 command=sys.executable,
-                args=[script_path],
+                args=[script_path, *_native_tool_args(agent_name)],
                 env=env
             )
 
@@ -479,13 +515,15 @@ async def lifespan(app: FastAPI):
                     command=cmd,
                     args=mcp_cfg["args"],
                     env=env,
-                    cwd=str(Path.home()),
+                    cwd=mcp_cfg.get("cwd") or str(Path.home()),
                 )
                 read, write = await exit_stack.enter_async_context(stdio_client(server_params))
                 session = await exit_stack.enter_async_context(
                     ClientSession(read, write, read_timeout_seconds=_SESSION_READ_TIMEOUT)
                 )
                 await session.initialize()
+                # The Browser Automation server offers only what its gate allows (`core.browser_automation`).
+                session = gated(mcp_name, session)
 
                 agent_sessions[mcp_name] = session
 

package/backend/tools/web_scraper.py

@@ -4,9 +4,10 @@ import json
 import logging
 import os
 import sys
-import tempfile
+import time
 import weakref
 from contextlib import contextmanager
+from pathlib import Path
 from urllib.parse import urlparse
 
 
@@ -37,6 +38,8 @@ logging.getLogger("crawl4ai.async_webcrawler").setLevel(logging.ERROR)
 from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
 from crawl4ai.extraction_strategy import JsonCssExtractionStrategy
 
+from core import egress_proxy
+from core.file_roots import within
 from core.egress_guard import BlockedEgress, check_host, check_url
 
 # ---------------------------------------------------------------------------
@@ -44,7 +47,52 @@ from core.egress_guard import BlockedEgress, check_host, check_url
 # ---------------------------------------------------------------------------
 
 MAX_MARKDOWN_LEN = 50_000
-MAX_SCREENSHOT_B64 = 2_000_000  # auto-save to tmp file above this size
+MAX_SCREENSHOT_B64 = 2_000_000  # saved in OUTPUT_DIR above this size
+
+#: Where `screenshot_url` saves a screenshot, and the only place it writes (F1066): the folder this server was
+#: started with (`--output-dir`; the backend gives it `<vault>/tool_outputs/screenshots`). None on a worker's
+#: shared server, which serves every tenant on its task and has no folder of theirs: nothing is saved there.
+OUTPUT_DIR: Path | None = None
+
+
+def output_dir_from(argv: list[str]) -> Path | None:
+    """`--output-dir <path>` from this server's arguments, or None."""
+    if "--output-dir" in argv[:-1]:
+        return Path(argv[argv.index("--output-dir") + 1])
+    return None
+
+
+def _screenshot_target(requested: str | None) -> Path:
+    """Where a screenshot asked to be saved as `requested` goes: inside `OUTPUT_DIR`, links and `..` resolved, or
+    `ValueError`. A bare name is placed in the folder; no name gets one."""
+    folder = OUTPUT_DIR
+    if folder is None:
+        raise ValueError("Screenshots are not saved to disk here: leave out output_path and the image comes back "
+                         "in the answer.")
+    path = Path(requested or f"screenshot-{time.strftime('%Y%m%d-%H%M%S')}.png").expanduser()
+    if not path.is_absolute():
+        path = folder / path
+    folder.mkdir(parents=True, exist_ok=True)
+    if not within(path, [folder]):
+        raise ValueError(f"Screenshots are saved only inside {folder}: give a file name such as 'page.png'.")
+    return path
+
+
+def _write_new(path: Path, data: bytes) -> Path:
+    """Write `data` to a file that did not exist: `path`, else `path` with -1, -2… before its suffix. Never over a
+    file, and never through a link at the last step."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    for n in range(1000):
+        candidate = path if n == 0 else path.with_name(f"{path.stem}-{n}{path.suffix}")
+        try:
+            fd = os.open(candidate, flags, 0o644)
+        except FileExistsError:
+            continue
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        return candidate
+    raise ValueError(f"too many screenshots named {path.name}")
 
 # ---------------------------------------------------------------------------
 # Crawler singleton — started lazily on first use
@@ -112,21 +160,29 @@ _crawler: AsyncWebCrawler | None = None
 _crawler_lock = asyncio.Lock()
 
 
+def browser_config(local_proxy: str | None = None) -> BrowserConfig:
+    """`local_proxy` is Synapse's own egress proxy (`core.egress_proxy`): the browser's whole network goes through
+    it, so what the route guard does not see (a page's WebSockets, its service workers) is refused there."""
+    return BrowserConfig(
+        headless=True,
+        browser_type="chromium",
+        enable_stealth=True,
+        verbose=False,
+        user_agent=(
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            "Chrome/120.0.0.0 Safari/537.36"
+        ),
+        extra_args=list(egress_proxy.CHROMIUM_ARGS),
+        **({"proxy_config": {"server": local_proxy}} if local_proxy else {}),
+    )
+
+
 async def get_crawler() -> AsyncWebCrawler:
     global _crawler
     async with _crawler_lock:
         if _crawler is None:
-            config = BrowserConfig(
-                headless=True,
-                browser_type="chromium",
-                enable_stealth=True,
-                verbose=False,
-                user_agent=(
-                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-                    "AppleWebKit/537.36 (KHTML, like Gecko) "
-                    "Chrome/120.0.0.0 Safari/537.36"
-                ),
-            )
+            config = browser_config((await egress_proxy.shared()).url)
             _crawler = AsyncWebCrawler(config=config)
             _crawler.crawler_strategy.set_hook(
                 "on_page_context_created", _attach_egress_guard
@@ -407,8 +463,8 @@ async def list_tools() -> list[types.Tool]:
             name="screenshot_url",
             description=(
                 "Take a screenshot of a webpage and return it as a base64-encoded PNG. "
-                "Supports full-page capture and optional save-to-disk. "
-                "If the screenshot exceeds 2 MB it is automatically saved to a temp file."
+                "Supports full-page capture and optional saving to the vault's screenshots folder. "
+                "If the screenshot exceeds 2 MB it is saved there automatically."
             ),
             inputSchema={
                 "type": "object",
@@ -423,7 +479,7 @@ async def list_tools() -> list[types.Tool]:
                     },
                     "output_path": {
                         "type": "string",
-                        "description": "Absolute file path to save the PNG (e.g. '/tmp/screenshot.png'). If omitted, returns base64 in the response."
+                        "description": "File name to save the PNG under, in the vault's screenshots folder (e.g. 'page.png'). If omitted, returns base64 in the response."
                     },
                     "full_page": {
                         "type": "boolean",
@@ -700,6 +756,13 @@ async def _handle_screenshot_url(args: dict) -> list[types.TextContent]:
         return _err("url is required")
     if (blocked := await _preflight(url)) is not None:
         return _err(blocked)
+    # Where it would be saved, refused before the page is fetched.
+    target = None
+    if args.get("output_path"):
+        try:
+            target = _screenshot_target(str(args["output_path"]))
+        except ValueError as exc:
+            return _err(str(exc))
 
     delay = float(args.get("delay", 0))
     full_page = args.get("full_page", False)
@@ -720,21 +783,21 @@ async def _handle_screenshot_url(args: dict) -> list[types.TextContent]:
         return _err("Screenshot capture returned no data")
 
     screenshot_b64: str = result.screenshot
-    output_path: str | None = args.get("output_path")
 
-    # Auto-save to temp file if too large for inline embedding
-    if not output_path and len(screenshot_b64) > MAX_SCREENSHOT_B64:
-        tmp = tempfile.NamedTemporaryFile(suffix=".png", delete=False)
-        output_path = tmp.name
-        tmp.close()
+    # Too large to hand back inline: saved in the folder, under a name of its own.
+    if target is None and len(screenshot_b64) > MAX_SCREENSHOT_B64:
+        try:
+            target = _screenshot_target(None)
+        except ValueError:
+            return _err(f"The screenshot is larger than {MAX_SCREENSHOT_B64 // 1_000_000} MB and is not saved "
+                        "to disk here; take it without full_page")
 
-    if output_path:
+    if target is not None:
         try:
             img_bytes = base64.b64decode(screenshot_b64)
-            with open(output_path, "wb") as fh:
-                fh.write(img_bytes)
-            return _ok({"success": True, "url": url, "saved_to": output_path, "size_bytes": len(img_bytes)})
-        except Exception as exc:
+            saved = _write_new(target, img_bytes)
+            return _ok({"success": True, "url": url, "saved_to": str(saved), "size_bytes": len(img_bytes)})
+        except (OSError, ValueError) as exc:
             return _err(f"Failed to save screenshot: {exc}")
 
     return _ok({"success": True, "url": url, "screenshot_base64": screenshot_b64, "format": "png"})
@@ -858,7 +921,8 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
 # ---------------------------------------------------------------------------
 
 async def main() -> None:
-    global _crawler
+    global _crawler, OUTPUT_DIR
+    OUTPUT_DIR = output_dir_from(sys.argv)
     async with stdio_server() as (read_stream, write_stream):
         try:
             await app.run(read_stream, write_stream, app.create_initialization_options())

package/frontend-build/.next/BUILD_ID

@@ -1 +1 @@
-YrERDQ96GLlwEG7rNI1lz
+OIEoX5QA1J1xrSoahxwNa

package/frontend-build/.next/build-manifest.json

@@ -7,9 +7,9 @@
     "static/chunks/03~yq9q893hmn.js"
   ],
   "lowPriorityFiles": [
-    "static/YrERDQ96GLlwEG7rNI1lz/_buildManifest.js",
-    "static/YrERDQ96GLlwEG7rNI1lz/_ssgManifest.js",
-    "static/YrERDQ96GLlwEG7rNI1lz/_clientMiddlewareManifest.js"
+    "static/OIEoX5QA1J1xrSoahxwNa/_buildManifest.js",
+    "static/OIEoX5QA1J1xrSoahxwNa/_ssgManifest.js",
+    "static/OIEoX5QA1J1xrSoahxwNa/_clientMiddlewareManifest.js"
   ],
   "rootMainFiles": [
     "static/chunks/0qmh881w772ef.js",