@sema-agent/connector-browser 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this package are documented here. Released sections are
 frozen: once a version is published its section is never edited again; new text
 goes into the next version's section.
 
+## 0.2.1 (2026-10-24)
+
+### Changed
+
+- Ships its own copy of `docs/KNOWN-LIMITS.md` as `KNOWN-LIMITS.md` inside the package (CN-063: its README's
+  mention of `docs/KNOWN-LIMITS.md` pointed at a repository path that did not resolve once installed), and is
+  re-pinned to `@sema-agent/connectors` 0.8.1 at release (CN-062, CN-064).
+
+## 0.2.0 (2026-10-23)
+
+### Added
+
+- The export of the login state (CN-055), off until the person turns it on: `auth` also
+  takes `"export": "on"` or `"off"` next to `{}` or `storageStateFile`
+  (`{"export": "on"}`, `{"storageStateFile": "<absolute path>", "export": "on"}`); every
+  `auth` states the whole configuration, so `"off"` or no `export` key turns it off. The
+  switch is the handle `BROWSER_EXPORT` (holding `on`, not a secret), stored or removed in
+  one group with `BROWSER_STORAGE_STATE`; a stored switch that holds anything else refuses
+  the start.
+- With the export on, playwright-mcp also gets `--caps storage`, and the connector's
+  standard input and output pass through a relay. Of the seventeen storage tools only
+  `browser_storage_state` is offered (26 tools in all): the sixteen that answer with cookie
+  or web storage values, or load a state, are withheld from `tools/list` and answered as a
+  tool playwright-mcp does not have, never reaching it. A `browser_storage_state` call is
+  given a file the connector names in the launch's output directory (a name no page can
+  guess, whatever name the caller gave); when it succeeds, that file is held to the login
+  state rule and stored as `BROWSER_STORAGE_STATE`, then removed, and the next launch starts
+  from it. A save that cannot be stored stores nothing and its answer says why, without the
+  content. No other file is read: state files a page downloads into the output directory
+  are never taken for the saved one.
+
+### Changed
+
+- Retires KL-15 (logins made in a session were never kept): with the export on, a session
+  keeps the login it saves. New KL-26: a saved state holds everything the browser holds,
+  the cookies pages set for their own sites included.
+- With the export off, the arguments playwright-mcp gets and the way MCP passes through are
+  exactly as before.
+- With `@sema-agent/connectors` 0.8.0 (CN-040), playwright-mcp runs with `HOME` set to its own home in the
+  connector's directory, so Playwright's registry entry for the running browser lies under `<CONNECTOR_DIR>/home`
+  instead of the user's `Library/Caches` (macOS) or `.cache` (Linux).
+- With `@sema-agent/connectors` 0.8.0 and `@sema-agent/connectors-contract` 0.2.0 (CN-030), a request the launcher
+  does not take is answered with `connector.request_unreadable` and its `error.data.reason` instead of
+  `connector.forbidden_scope`, which now means only a tool outside the granted scope.
+
 ## 0.1.2 (2026-10-21)
 
 ### Documentation

package/KNOWN-LIMITS.md

@@ -0,0 +1,35 @@
+# Known limits
+
+Accepted, low-severity limits that are not scheduled for a fix. Each entry states when it would stop
+being acceptable. An entry must not describe a second source of truth, a documented exception to a
+contract, or a long-lived transitional path: those are defects and get a ticket instead.
+
+| ID | Symptom | Why it is not fixed | Trigger | Upgrade criterion |
+|---|---|---|---|---|
+| KL-01 | A standalone catalog entry names its configuration directory with an absolute `--config-dir`. After the directory is moved, or when the `mcp` domain is exported in a bundle to another machine, the entry still names the old path: the launcher finds no secrets there and reports `unauthorized`, and `mount` (and with it the seed) refuses the stale entry as a conflict until it is removed by hand. | The engine starts stdio connectors with a minimal environment, so the entry must carry the directory (CN-028); an absolute path is machine-local by nature, like the installed connector package the entry also depends on. The seed (CN-009) never overwrites an entry, so it does not repair one. | Moving the configuration directory; importing a bundle that carries connector entries. | The CLI wrapper (CN-012) rewriting entries on import, or an engine that hands its configuration directory to stdio connectors. |
+| KL-02 | The end-to-end gate pins `@sema-agent/server` 7.122.0 word for word in `test/negctl/CN-006.json`: the four helper invocations the server starts outside the egress probe (`ps`, two `git` commands and `/bin/bash`, each with its exact arguments) and the variables `MODEL_ID`, `MODEL_API_KEY` and `APPROVAL_GRANT` it needs for a local run. A server release that changes any of them turns the gate red until a person has reviewed the new invocations or variables and updated the fixture. | The server documents neither its helper processes nor the minimal environment of a local run as a stable contract; the fixture records what 7.122.0 does, and a reviewed change is what the gate is for. | A new version of the `@sema-agent/server` development dependency. | The server documents these helpers and variables as a stable contract, or publishes a machine-readable minimal environment that the gate can read instead of the fixture. |
+| KL-03 | On the hosted http face, `GET /status` answers `503` until a client has opened a session and the connector has answered `initialize`; a health probe on a fresh launcher sees an error although the launcher is fine (the compose healthcheck probes for the `401` instead). | The status lists the tools the caller sees, which only a running connector can tell; a `200` before that would carry an invented empty list, and the contract has no way to say "unknown". | Reading `/status` on a hosted launcher before any session, or after the session ended. | A `connector-status-v1` change that can state the tools as unknown, or a hosted launcher that starts its connector at boot (M2, with the token vault). |
+| KL-04 | A connector that takes none of its waiting input for 10 seconds is ended as "stalled" (`connector.internal` on every pending call; exit 5 on stdio), also when it is merely busy: a client that keeps sending more than the pipe holds while one tool runs synchronously for over 10 seconds loses its pending calls. A reader taking at least about 1 KiB per 10 seconds is not affected. | The launcher cannot tell "stopped reading" from "busy", and without the bound a connector that stops reading leaves the launcher and itself hanging when upstream only closes its pipe (CN-025). | A connector that blocks for more than 10 seconds while more input than the pipe buffer waits for it. | A connector protocol signal for "busy", or a measured need for a longer bound from a real connector (M1). |
+| KL-05 | A connector directory whose `.auth.lock` was left behind (a process killed while holding it, a power loss during `auth`) stops every launch of that connector: the launcher waits 5 seconds, exits 2 and names the lock; `auth` and `status` wait and refuse the same way, until someone removes the lock file by hand. | The lock is never guessed stale (a live holder could be slow), the same rule as the mount lock; a liveness check by pid would be wrong across machines and containers. | A crash or kill while a write or a launch snapshot holds the lock. | A lock that carries a lease the holder renews, or an operator command that removes a lock after checking its holder. |
+| KL-06 | When a connector has secret values, the launcher holds back the last bytes of the connector's stderr until it knows they do not begin a secret, so a receipt line the launcher writes meanwhile can land in the middle of a connector's log line (the line resumes after the receipt). Programs splitting at the documented line breaks still read every receipt whole; only a person reading the log sees the split. | Withholding needs the lookahead, and receipts are written when a call settles. | A connector writing a log line slowly while a call settles. | A reader that needs receipts apart from the connector's log: a sink of their own (CN-035 kept them on the launcher's stderr, with a bound). |
+| KL-07 | `mount` and `auth` report success once the new file is written whole, synced and renamed into place, but the directory is not synced afterwards and the file sync is the ordinary `fsync` (not the full flush some file systems need): a power loss right after a reported success can leave the old `config.d/mcp.json` or token file, or on some file systems an empty one. | The whole-write rule (CN-042) is about never putting a file cut short in place; crash durability is a separate property with a platform-specific cost. | A power loss or kernel crash within moments of a successful `mount` or `auth`. | A measured need from a deployment, or a platform rule for directory sync and full flush. |
+| KL-08 | Storing a secret handle writes its metadata file before its value file, so a value write that fails leaves the new metadata (for example a new `expiresAt`) next to the old value; the connector CLI reports the failure with exit 1 and `auth` has to be run again. | The order keeps a secret from being marked as not a secret halfway through; the pair is written whole again by the next `auth`. | A write failure between the two files of one handle. | A per-handle write that lands both files or neither. |
+| KL-09 | A seed whose marker write fails (a full disk, a file size limit) exits 1 with `write_failed`, but the entries it mounted stay, unrecorded: a person who removes one of them before the next successful seed sees the next seed mount it again. | Undoing a mount would need a second writer that removes entries from `config.d/mcp.json`, outside `mount`; the next seed that can write the marker finds the entries and records them as present. | A marker write that fails, then an entry removed before a seed that succeeds. | A remove operation through `mount` (the CLI wrapper, CN-012) that the seed can undo with, or a measured case of a failing marker write. |
+| KL-10 | A write that fails before anything is in place can leave an empty directory behind: `mount` creates `config.d` before it writes the catalog file, and the secrets backend creates `connectors/<name>` before it writes a handle, so a refused `mount` on a fresh directory leaves an empty `config.d`, a failed `put` an empty `connectors/<name>`, and an `install` refused for an archive that does not match the lock an empty `connectors/<name>/bin` (0700). | An empty directory changes nothing a reader sees (no catalog entry, no handle), and removing it would need a guess that nothing else is about to use it. | A first `mount` or `put` whose write fails (a full disk, a file size limit). | A reader that treats the empty directory as a state of its own. |
+| KL-11 | The GitHub connector hands its personal access token to github-mcp-server in the variable `GITHUB_PERSONAL_ACCESS_TOKEN`: while github-mcp-server runs, a process of the same user (or root) that reads other processes' environments reads the token, and so does a crash report or core dump that records the environment. The Gitea connector hands gitea-mcp only the path of its 0600 copy, so its token is only ever in a file (which the same user can read too). | github-mcp-server 2.0.2 takes a personal access token from that variable only: it has no file or descriptor input for it. An argument would be readable by every process, so the variable is the narrowest way in. | Running the GitHub connector where other processes of the same user are not trusted. | github-mcp-server gains a file or descriptor input for the token (the connector then hands it the per-launch copy's path, as for Gitea). |
+| KL-12 | With a token that looks like a classic personal access token (it starts with `ghp_`), github-mcp-server 2.0.2 sends `HEAD https://api.github.com/` (with a stored host, `HEAD <host>/api/v3/`) with the token every time it starts, before any tool is called, to read the token's scopes: every start of the GitHub connector, `sema-connector-github status` included, contacts GitHub. With a token that starts like a fine-grained one (`github_pat_`) or with neither prefix it connects nowhere until a tool is called; other kinds of token (such as `gho_`) were not measured. | It is github-mcp-server's own start-up (it hides the tools a classic token cannot use) and no option of it turns the request off; the destination is the GitHub API the token belongs to, and the gate fails on any other. | Starting the GitHub connector with a classic personal access token. | github-mcp-server gains an option to skip the scope request, or a deployment needs a start without network (a fine-grained token avoids it today). |
+| KL-13 | A standalone connector that needs no credentials never runs: with no secret handle the launcher parks the session (see "Parked session" in `ARCHITECTURE.md`), so such a connector shows `unauthorized`, lists no tools and has no `auth` to run; storing any secret handle for it starts it. | The state has one judgement (a secret handle is present or not) and no second fact such as a declaration by the connector that it needs none; the private stub and the gates' planted connectors store a handle first. | A connector package that takes no credential, mounted in a standalone directory. | A connector of this repository that genuinely needs no credential (the browser connector of M1 keeps its login state as a handle instead). |
+| KL-14 | `statusCommand` and `seed` find the launcher and the connector packages through this package's own `package.json` (`import.meta.url`), so a copy of `@sema-agent/connectors` inlined into another program's bundle cannot run them (`mount` and `mountCommand` are unaffected); the package is consumed installed. | A bundled copy has no package directory to resolve from, and a second way of finding the launcher would be a second source. | A command-line tool that bundles its dependencies and calls `statusCommand` or `seed`. | A consumer that must bundle; then the launcher path and the resolution root become explicit inputs of those two functions. |
+| KL-23 | A standalone browser connector that is mounted without a `tools.json` grants every tool, `browser_run_code_unsafe` and `browser_evaluate` among them (CN-054 gives the operator the allow list; nothing writes one by default). | A default policy would be a second source of what the operator decides, and the shared layer does not know one connector's tools from another's. | The browser connector mounted with no policy file. | A connector package that ships a default `tools.json` the operator can override, as one rule for every connector. |
+| KL-24 | The GitHub connector authenticates with a personal access token only; github-mcp-server's own OAuth login never runs, because the parked session keeps the upstream from starting without a token (CN-052). | An OAuth flow needs a person at a browser and a place to keep the result; the connector's `auth` and the handle store are that place, and the flow is designed when a deployment needs it rather than guessed now. | A deployment that cannot issue personal access tokens. | A deployment that needs OAuth: then `auth` gains an OAuth form that stores the result as the token handle (the GitHub connector's next minor). |
+| KL-17 | The standalone browser connector has no egress policy: the browser opens whatever URL a tool call names, follows redirects and loads what pages load. playwright-mcp's `--allowed-origins` is not a security boundary (playwright-mcp says so) and is not used. | Browsing what the engine asks for is the connector's purpose; an egress policy belongs to the hosted container (M2, M3), enforced outside the browser. | Any browsing. | The hosted deployment's egress proxy (M3), or a standalone policy with an enforcement point outside the browser. |
+| KL-18 | On Linux, Chromium's sandbox needs unprivileged user namespaces (or a setuid sandbox helper): in a container without them Chromium does not start and every page tool fails. The browser connector always passes `--sandbox` (playwright-mcp leaves the sandbox off on Linux for Chrome for Testing otherwise) and never `--no-sandbox`. | Without the sandbox a compromised renderer acts as the user; the container's profile (user namespaces, seccomp) is the deployment's to provide, not the connector's to work around. | The browser connector on Linux where user namespaces are disabled, as in many container runtimes by default. | The hosted deployment declares a container profile with user namespaces (M2), or a measured deployment that cannot provide them. |
+| KL-19 | Chrome for Testing 155 contacts Google on its own when it starts, although Playwright passes switches meant to keep it quiet: the browser gate's proxied run names `accounts.google.com`, `update.googleapis.com`, `www.google.com` and `android.clients.google.com` (port 443), and past a proxy Chromium also connects a UDP socket to `[2001:4860:4860::8888]:443`; without a proxy it goes through the system's proxy settings or directly. | The requests come from Chromium components no option of playwright-mcp turns off, and the connector passes Chromium no switch of its own; the gate contains them and fails on a host outside google.com and googleapis.com. | Every start of the browser. | A playwright-mcp option or a Chromium switch that stops them, an egress policy (KL-17), or a host outside those domains in the gate's reading. |
+| KL-20 | Chrome for Testing is pinned for `darwin-arm64` and `linux-x64` only: on another platform `install` of the browser connector refuses (`pins no playwright-mcp build for <platform>`). | Chrome for Testing publishes no Linux arm64 build, and the macOS x64 build has not been fetched and checked. | Installing the browser connector on another platform. | A request for another platform, with its archive downloaded and its sha256 checked. |
+| KL-21 | While the browser runs, playwright-mcp publishes it for other Playwright tools of the same user: a socket under `/tmp/pw-<hash>/browser/` (the system's temporary directory: the launcher passes no `TMPDIR` to the connector) and an entry in Playwright's registry, which since CN-040 lies in the program's home in the connector's directory (`<CONNECTOR_DIR>/home/Library/Caches/ms-playwright/b` on macOS, `<CONNECTOR_DIR>/home/.cache/ms-playwright/b` on Linux) rather than in the user's home. A process of the same user can find the socket and attach to the browser and its session there, and the entry stays behind when the browser does not close normally. | It is playwright-mcp's own behaviour, with no option to turn it off; a process of the same user can read the stored login state in the configuration directory anyway. | The browser connector where other processes of the same user are not trusted. | playwright-mcp gains an option not to publish the browser, or the hosted form (one container per session). |
+| KL-22 | When playwright-mcp is killed with `SIGKILL` before it has closed the browser, Chromium (a process group of its own) keeps running, unreachable, until it is killed by hand (measured still running 86 seconds later). The launcher's teardown sends `SIGKILL` two steps (2 s) after the end of input; playwright-mcp closes the browser on the end of its input (measured 0.16 to 0.33 s) or on `SIGTERM` (0.16 s on a quiet machine, 2.2 and 5.4 s in two gate runs on a loaded one), so a close that outlasts the two steps is possible under load. | Playwright starts Chromium in a process group of its own and nothing outside playwright-mcp knows its pid; the teardown steps are one rule for every connector (CN-025). | playwright-mcp killed with `SIGKILL` (out of memory, or a close that outlasts the teardown steps). | A browser left running in normal use, or a way for the connector to learn Chromium's process group. |
+| KL-25 | What a pinned upstream program keeps under its home, `<CONNECTOR_DIR>/home` (CN-040), is neither scanned nor redacted, and nothing removes it: gitea-mcp's log (its tool errors, which can name URLs and user names of the Gitea server), Playwright's registry of running browsers, and whatever caches a program keeps. The gates measured no dummy token in gitea-mcp's log after a tool call. | The files are the program's own and stay inside the 0700 connector directory, outside the user's home; the launcher keeps secret values out of what it forwards (the message path and stderr), and scanning a program's private files would be a second redaction path with no rule for what it may change. | An upstream program that writes a value it was given (a token, a host's credentials) into a file under its home. | A token measured in a file under a program's home, or an upstream option to turn its file log off. |
+| KL-26 | With the browser connector's export of the login state on (CN-055), a save stores everything the browser holds at that moment: the session's login, and also the cookies and local storage any page visited in the session set for its own site, including a login a page forced on another site (a login cross-site request forgery). The next launch starts from all of it, as a browser with a profile on disk would. | The state is playwright-mcp's own `browser_storage_state` of the whole browser context; choosing which origins to keep would be a second rule over a state the connector does not otherwise interpret, and the person turned the export on to keep what the session holds. | A save after browsing pages that are not trusted, with the export on. | A request to keep only named sites, or a measured case of a stored state carrying a page's forced login. |
+| KL-27 | A request line the launcher cannot read on stdio (over 4 MiB, a batch, a repeated key, an id that is neither a string nor a number) is answered with `id` null and `connector.request_unreadable` (CN-030), so an MCP client cannot match the answer to the request it sent: it sees an error it cannot place and waits for that request until its own timeout. Over the hosted http face the same refusal is the answer to its own http request (`400` or `413`), so nothing waits there. | Nothing of a line the launcher cannot read is read, its id included: a batch has no single id, a line over 4 MiB is never parsed, and an object with a repeated key may carry an id that parsers read differently, so reading an id out of it would judge a message the launcher has just refused to judge. JSON-RPC answers a request whose id it cannot detect with id null too. | A tool call whose arguments make its line longer than 4 MiB; a batch, a repeated key or an id of another type, which the MCP SDK clients do not send. | A client measured waiting on such a request in normal use, or one reading of the id that every parser shares agreed for these lines. |
+| KL-28 | A host can stop delivering the sandbox reports of one executable while the sandbox goes on refusing (seen on 2026-10-22: for hours no report of a refused node connection, while bash was reported as before). The connector gates then cannot see what node processes try past the probe, the planted upstreams included: the attempts are refused (the gates' control processes read `EPERM`) but not observed, and the last line of each gate says so ("the host delivered no sandbox reports for node, so attempts by unprobed processes (...) were blocked but not observed"). Delivery is shown only for the executables of the gates' control processes (bash and node); for gitea-mcp, github-mcp-server and Chrome for Testing the gates read the reports that come and cannot tell a host that drops them. | The reports are the host's to deliver, and nothing in sandbox-exec or the system log asks for them; what keeps a connection from leaving is the refusal, which the control still proves on every run. Failing the gate would turn it red for something this repository cannot change. | A host that stops delivering the reports of an executable. | A check that needs the reports themselves, not the refusal, comes to depend on them (github-mcp-server's name lookups are read from its reports), or the reports of a pinned program are seen missing: then that program gets a control process of its own. |
+| KL-29 | On the hosted http face a session that has had no request of its own for 10 minutes is released (CN-033): a client that holds a session, sends nothing for longer and then sends a request gets `404` for its session id and has to `initialize` again (MCP Streamable HTTP answers that `404` with a new session). A request in flight for longer than 10 minutes is not affected, and neither is its session while it waits. The 10 minutes are fixed: no deployment setting changes them. | The face opens no stream, so the launcher has no sign that a client is still there other than its requests; a session held until `DELETE` kept every other client at `409` until the launcher restarted, and one fixed time is one rule for every deployment. | A client idle for more than 10 minutes within one session. | A deployment measuring clients that are idle for longer in normal use, or the hosted session model of M2 (a session per client, or a stream that shows the client is there). |

package/README.md

@@ -10,7 +10,9 @@ configuration directory from `CONFIG_LOCAL_DIR` like every connector's
 ([`INTEGRATION-SERVER.md`](../INTEGRATION-SERVER.md)).
 
 The browser is headless and runs in a fresh, in-memory profile at every start; what it knows of a login is the login
-state `auth` stored (see "The login state"). Chrome for Testing is pinned for `darwin-arm64` and `linux-x64` only.
+state `auth` stored (see "The login state"), which a session can save back when the person has turned the export of the
+login state on (CN-055, see "Exporting the login state"). Chrome for Testing is pinned for `darwin-arm64` and
+`linux-x64` only.
 
 ## Setting it up
 
@@ -25,13 +27,15 @@ sema-connector-browser status
 On Linux the connector keeps Chromium's own sandbox on (`--sandbox`, never `--no-sandbox`), which needs user
 namespaces: in a container that does not allow them (Docker's default seccomp profile, for one) the first
 `browser_navigate` answers `Chromium sandboxing failed!` and nothing is browsed. Run the connector on a host or in a
-container that allows user namespaces (KL-18 in the repository's `docs/KNOWN-LIMITS.md`); the connector never turns
-the sandbox off.
+container that allows user namespaces (KL-18; see `KNOWN-LIMITS.md`, shipped with this package and, in the
+repository, `docs/KNOWN-LIMITS.md`); the connector never turns the sandbox off.
 
 Then restart the engine. To start from a login instead of a clean profile, save a Playwright storage state (for example
 with Playwright's `context.storageState({ path })` after logging in) to a file only you can read, and give `auth` its path:
 `echo '{"storageStateFile": "/absolute/path/state.json"}' | sema-connector-browser auth`. Delete the file afterwards; the
-state is a secret (it holds the session cookies).
+state is a secret (it holds the session cookies). To let sessions keep the logins they make, turn the export on with the
+same line: `echo '{"export": "on"}' | sema-connector-browser auth` (a clean profile, export on), or
+`{"storageStateFile": "/absolute/path/state.json", "export": "on"}`.
 
 ## The pinned build
 
@@ -64,24 +68,33 @@ refuses (`binaries.lock.json pins no playwright-mcp build for <platform>`).
 
 ## auth
 
-`auth` reads exactly one line from standard input (never from an argument), a JSON object with at most one string member:
+`auth` reads exactly one line from standard input (never from an argument), a JSON object with at most the string
+members `storageStateFile` and `export`:
 
 ```json
 {}
 {"storageStateFile": "<absolute path>"}
+{"export": "on"}
+{"storageStateFile": "<absolute path>", "export": "on"}
 ```
 
 - `{}` stores a clean profile, `{"cookies":[],"origins":[]}`. Empty input is refused rather than read as `{}`: a pipe
   whose producer failed must not replace a stored login with an empty one.
 - `storageStateFile` names a Playwright storage state file by its absolute path: at most 4 MiB of UTF-8 JSON holding one
   object with exactly the keys `cookies` and `origins`, each a list. Its text is stored as it is.
-- Any other key, a key given twice, a value that is not a string, or a file outside the rule is refused, and a refusal
-  never repeats what was read.
+- `export` is `"on"` or `"off"`: `"on"` turns the export of the login state on (see "Exporting the login state"),
+  `"off"` or no `export` key turns it off. Every `auth` states the connector's whole configuration: the login state as
+  above, and the export on or off.
+- Any other key, a key given twice, a value that is not a string, another `export` value, or a file outside the rule is
+  refused, and a refusal never repeats what was read.
 
 The state is stored through the secrets backend as the handle `BROWSER_STORAGE_STATE`: a 0600 file in
-`<configuration directory>/connectors/browser/` (0700), a secret (no metadata). The write holds the lock of the
-connector's directory as for every connector (see "Secrets" in [`ARCHITECTURE.md`](../ARCHITECTURE.md)): a connector
-started while `auth` runs gets the old state or the new one, and an `auth` that fails leaves the old one.
+`<configuration directory>/connectors/browser/` (0700), a secret (no metadata). The export switch is the handle
+`BROWSER_EXPORT`, holding `on`, stored when the export is on (a handle that is not a secret, `{"secret": false}`) and
+removed when it is off. Both writes are one group inside the lock of the connector's directory, as for every connector
+(see "Secrets" in [`ARCHITECTURE.md`](../ARCHITECTURE.md)): a connector started while `auth` runs gets the old state and
+switch or the new ones. The switch is written first, so an `auth` that fails leaves the old login state, with the switch
+as it was or already as asked.
 
 ## mount and status
 
@@ -89,24 +102,28 @@ started while `auth` runs gets the old state or the new one, and an `auth` that
 status the launcher serves, as for every connector. Before `auth` there is no handle, so the launcher does not start the
 connector and answers itself (see "Parked session" in [`ARCHITECTURE.md`](../ARCHITECTURE.md)): `status` prints
 `{"state":"unauthorized","tools":[]}`. After `auth` (a clean profile included) the status is `authorized` and lists the
-25 tools of playwright-mcp; reading them starts playwright-mcp but not the browser, which starts at the first tool that
-needs a page.
+25 tools of playwright-mcp (26 with the export on, see "Exporting the login state"); reading them starts playwright-mcp
+but not the browser, which starts at the first tool that needs a page.
 
 ## What runs
 
 With no arguments, `sema-connector-browser` is the connector process the launcher starts. It refuses to start (exit 1,
 with a line on stderr naming what to do) on the shared start check ("Pinned upstream programs": without `CONNECTOR_DIR`,
-without the `BROWSER_STORAGE_STATE` handle, when its per-launch copy is not a regular file in `CONNECTOR_DIR`, when `bin/`
-does not hold the pinned build), when the stored state breaks the rule of "auth", and when Chrome for Testing is not in
-`bin/chrome`. Otherwise it makes the launch's output directory (see "The output directory"), makes it the working
+without the `BROWSER_STORAGE_STATE` handle, when its per-launch copy, or that of `BROWSER_EXPORT`, is not a regular file in
+`CONNECTOR_DIR`, when `bin/` does not hold the pinned build), when the stored state breaks the rule of "auth", when a stored
+`BROWSER_EXPORT` does not hold `on`, when the export is on and `CONNECTOR_DIR` is not
+`<configuration directory>/connectors/browser`, and when Chrome for Testing is not in `bin/chrome`. Otherwise it makes the launch's output directory (see "The output directory"), makes it the working
 directory, and starts `node_modules/@playwright/mcp/cli.js` on its own Node.js as its child on the same standard input,
-output and error, so every MCP message passes between the launcher and playwright-mcp untouched; it ends as playwright-mcp ends, with its exit code or by the signal that ended it, and passes its stop
-signals on. playwright-mcp closes the browser when its input ends or it gets `SIGTERM` (measured well under a second,
+output and error, so every MCP message passes between the launcher and playwright-mcp untouched (with the export on, its
+standard input and output pass through the connector's relay instead: see "Exporting the login state"); it ends as
+playwright-mcp ends, with its exit code or by the signal that ended it, and passes its stop signals on. playwright-mcp closes the browser when its input ends or it gets `SIGTERM` (measured well under a second,
 inside the launcher's teardown steps); killed with `SIGKILL` before that, it leaves Chromium running (KL-22).
 
 playwright-mcp gets the arguments of "Security baseline" and the environment the launcher gave the connector without
-`CONNECTOR_DIR`, `BROWSER_STORAGE_STATE_FILE` and every `PLAYWRIGHT_MCP_*` variable (the variable twins of its options),
-so its options are those arguments whoever starts the connector.
+`CONNECTOR_DIR`, `BROWSER_STORAGE_STATE_FILE`, `BROWSER_EXPORT_FILE` and every `PLAYWRIGHT_MCP_*` variable (the variable
+twins of its options), so its options are those arguments whoever starts the connector, and with `HOME` set to its own
+home in the connector's directory, `<CONNECTOR_DIR>/home` (CN-040; "Pinned upstream programs" in
+[`ARCHITECTURE.md`](../ARCHITECTURE.md)): what Playwright keeps under its home stays there (KL-25).
 
 ## Security baseline
 
@@ -125,9 +142,10 @@ The arguments are one table in `src/upstream.ts`; none comes from the environmen
 | `--executable-path <bin>/chrome/...` | the pinned Chrome for Testing in the bin directory; playwright-mcp never looks for or downloads a browser. |
 | `--output-dir <launch directory>/out` | screenshots, snapshots and other files land in the launch's own directory and go with it. |
 | `--storage-state <per-launch copy>` | the login state, read when the browser context is created. |
+| `--caps storage` | only with the export of the login state on, last: playwright-mcp's storage capability, of whose tools the connector offers only `browser_storage_state` (see "Exporting the login state"). |
 
-Never given: `--no-sandbox`, `--caps` (none of the opt-in capabilities `vision`, `pdf`, `devtools`, `config`, `network`,
-`storage` is on), `--user-data-dir`, `--save-session`, `--secrets`, `--allow-unrestricted-file-access`, `--proxy-server`,
+Never given: `--no-sandbox`, `--caps` other than `--caps storage` with the export on (none of the opt-in capabilities
+`vision`, `pdf`, `devtools`, `config`, `network` is ever on), `--user-data-dir`, `--save-session`, `--secrets`, `--allow-unrestricted-file-access`, `--proxy-server`,
 `--port` and `--host` (MCP runs on standard input and output only), `--init-script`, `--init-page`, `--config`,
 `--extension`, `--cdp-endpoint`, `--allowed-origins` and `--blocked-origins` (playwright-mcp itself says they are not a
 security boundary and do not apply to redirects; the connector does not offer them as one).
@@ -142,8 +160,49 @@ marked `HttpOnly`) reaches the engine like any page content, through `browser_ev
 page. A reply that carries the stored state's text as a whole, the clean profile's `{"cookies":[],"origins":[]}`
 included, is withheld like any secret value (answered with `connector.internal`).
 
-Logins made during a session are not written back: the profile is in memory (`--isolated`), so they end with the browser
-(KL-15). To keep a login, store a new state with `auth`.
+The profile is in memory (`--isolated`): a login made during a session ends with the browser unless the session saves
+it with the export on (below). Otherwise, to keep a login, store a new state with `auth`.
+
+## Exporting the login state
+
+The export (CN-055) lets a session keep the logins it makes. It is off until the person turns it on with `auth`
+(`"export": "on"`, see "auth"); a stored `BROWSER_EXPORT` handle is the only way to turn it on, and nothing else ever
+writes the login state back.
+
+With the export on, playwright-mcp runs with its storage capability (`--caps storage`), and the connector's standard
+input and output pass through the connector's relay, which changes three things and passes every other message on as
+it is (each line whole; a line longer than the launcher's 4 MiB is passed on cut to one byte over it, which the launcher
+refuses as it refuses any longer line):
+
+- **One storage tool is offered.** The capability adds seventeen tools; sixteen of them read, set or load cookies and web
+  storage and answer with their values (`browser_cookie_*`, `browser_localstorage_*`, `browser_sessionstorage_*`,
+  `browser_set_storage_state`). playwright-mcp has no option to leave a tool out, so the relay withholds them: they are
+  not in `tools/list` (nor in the status), and a call naming one never reaches playwright-mcp: the relay answers it with
+  playwright-mcp's own answer for a tool it does not have (`Tool "<name>" not found`, a tool result marked as an
+  error), without starting the browser; a call without an id is dropped. The list in `src/upstream.ts` is the
+  one place that names them. `browser_storage_state` is the one tool the export adds: 26 tools in all.
+- **The connector names the file.** A `browser_storage_state` call reaches playwright-mcp with its arguments replaced by
+  a file of the connector's choosing, in the launch's output directory and under a name no page can guess, whatever file
+  name the caller gave (playwright-mcp would resolve a relative name against the client's first root, outside the
+  launch). playwright-mcp writes the browser's cookies and local storage there, HttpOnly cookies included, and its answer
+  names the file and holds no value. A call without an id is dropped.
+- **A successful save is stored.** When playwright-mcp answers that call with success, the connector reads that one file
+  (never through a symbolic link), holds it to the rule of "auth", stores it as `BROWSER_STORAGE_STATE` through the
+  secrets backend (the lock of the connector's directory, written whole) and removes the file; the answer is passed on as
+  playwright-mcp gave it (a file that cannot be removed is said on the connector's standard error; it goes with the
+  launch's directory). When the file is not there or not a regular file, breaks the rule, is over 4 MiB, or the
+  backend cannot store it, nothing is stored, the file is removed, the answer says `The login state was not stored:`
+  with the reason (never the content) and the connector says the same on its standard error. When playwright-mcp's own
+  answer is a failure, it is passed on as it is and nothing is stored.
+
+No other file is ever read: a page can put files of names of its own choosing into the output directory (a download
+lands there, named as the page says), so a state file there named like playwright-mcp's own (`storage-state-….json` or
+`storage-state.json`) is never taken for the saved one. Each save replaces the stored state; the running launch keeps
+the copy it started with, and the next launch starts from the last state saved. The saved state is everything the
+browser holds at that moment, the cookies a page set for itself included (KL-26).
+
+With the export off, playwright-mcp has no storage capability and the connector passes its standard input and output
+straight through, as before.
 
 ## The output directory
 
@@ -160,18 +219,19 @@ the files its tools read and write (`browser_file_upload`, a screenshot's file n
 
 The connector offers every tool playwright-mcp lists; which of them a caller may use is the launcher's scope stage, and
 standalone grants `tool:*` unless the configuration directory carries a local per-tool policy (CN-054, `ARCHITECTURE.md`,
-"Stages on the launcher hop"). The 25 tools, with what each can reach:
+"Stages on the launcher hop"). The 25 tools, and the one the export adds, with what each can reach:
 
 | Tool | Reach |
 |---|---|
 | `browser_run_code_unsafe` | **Runs arbitrary JavaScript in the playwright-mcp process** (playwright-mcp calls it RCE-equivalent): it can read and write every file the user can, the tokens of the other connectors in the configuration directory included, start processes and connect anywhere. |
 | `browser_evaluate` | Runs JavaScript in the page, with the page's access: its DOM, storage and script-readable cookies, requests as the page. |
-| `browser_network_requests`, `browser_network_request` | The page's requests and responses, headers and bodies included (session cookies and authorization headers of a logged-in site). |
+| `browser_network_requests`, `browser_network_request` | The page's requests and responses, headers and bodies included (authorization headers a page sends, and whatever a logged-in site puts in a body; the request headers Playwright reports carry no cookies). |
 | `browser_file_upload`, `browser_drop` | Give files to a page: files in the output directory or the workspace (see "The output directory"). |
 | `browser_navigate`, `browser_navigate_back`, `browser_tabs` | Open any `http` or `https` URL, as the logged-in user where the state has a login. |
 | `browser_click`, `browser_type`, `browser_press_key`, `browser_fill_form`, `browser_select_option`, `browser_hover`, `browser_drag`, `browser_handle_dialog` | Act on the page as the user (submit forms, confirm dialogs, buy, post, delete). |
 | `browser_snapshot`, `browser_find`, `browser_take_screenshot`, `browser_console_messages` | Read the page (its text, its look, its console); snapshots and screenshots are also written to the output directory. |
 | `browser_resize`, `browser_emulate_media`, `browser_wait_for`, `browser_close` | Change the viewport or media features, wait, close the browser. |
+| `browser_storage_state` | Only with the export on: replaces the stored login state with everything the browser holds (its cookies, HttpOnly ones included, and local storage); the answer holds no value (see "Exporting the login state"). |
 
 ### A recommended policy
 
@@ -196,7 +256,8 @@ The example leaves a fifth tool out as well, `browser_file_upload`: a deployment
 reaches only the output directory and the workspace, not arbitrary files), so the list above holds 20 names and a
 deployment that keeps `browser_file_upload` lists 21. A tool left out of `allow` fails
 `tools/call` with `connector.forbidden_scope` and is absent from `tools/list` and the status resource's `tools`;
-nothing about the connector itself changes.
+nothing about the connector itself changes. With the export on, the example leaves `browser_storage_state` out too, so a
+session cannot save its login until the deployment adds it to `allow`.
 
 ## Outbound connections
 
@@ -210,13 +271,13 @@ also connects a UDP socket to `[2001:4860:4860::8888]:443` (KL-19); the gate fai
 googleapis.com. The browser follows the system's proxy settings.
 
 playwright-mcp also publishes the running browser for other Playwright tools of the same user: a socket under
-`/tmp/pw-<hash>/browser/` and an entry in Playwright's registry directory (`~/Library/Caches/ms-playwright/b` on macOS,
-`~/.cache/ms-playwright/b` on Linux), removed when the browser closes. A process of the same user can attach to the
+`/tmp/pw-<hash>/browser/` and an entry in Playwright's registry directory, which lies in playwright-mcp's home
+(`<CONNECTOR_DIR>/home/Library/Caches/ms-playwright/b` on macOS, `<CONNECTOR_DIR>/home/.cache/ms-playwright/b` on Linux;
+CN-040), both removed when the browser closes. A process of the same user can find the socket and attach to the
 browser there (KL-21).
 
 ## Known limits
 
-- **Logins made in a session are not kept** (KL-15).
 - **No egress policy in the standalone form** (KL-17).
 - **The Chromium sandbox needs user namespaces on Linux** (KL-18): in a container without them Chromium does not start;
   the connector never turns the sandbox off.
@@ -224,6 +285,7 @@ browser there (KL-21).
 - **Two platforms**: `darwin-arm64` and `linux-x64` (KL-20).
 - **Other processes of the user can attach to the running browser** (KL-21).
 - **Chromium outlives a playwright-mcp killed with `SIGKILL`** before it closed the browser (KL-22).
+- **A saved login state holds everything the browser holds**, the cookies a page set included (KL-26).
 - **Check, then start:** as for every pinned upstream program (see "Pinned upstream programs" in
   [`ARCHITECTURE.md`](../ARCHITECTURE.md)): at each start the trees are compared with their archives by their files'
   names, kinds, sizes, modes and link targets, the program by its content.

package/dist/auth.js

@@ -1,41 +1,29 @@
-import { closeSync, fstatSync, openSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { openFileSecrets, readStdinJson } from '@sema-agent/connectors';
-import { NAME, STATE_HANDLE, complain, say } from './names.js';
-import { EMPTY_STATE, STATE_LIMIT, readState } from './state.js';
+import { EXPORT_HANDLE, EXPORT_ON, NAME, STATE_HANDLE, complain, say } from './names.js';
+import { EMPTY_STATE, readState, stateFileBytes } from './state.js';
 const INPUT_LIMIT = 64 * 1024;
 const FILE_KEY = 'storageStateFile';
+const EXPORT_KEY = 'export';
+const EXPORT_OFF = 'off';
 function stateFromFile(path) {
     if (!isAbsolute(path))
         return { ok: false, problem: `${FILE_KEY} must be an absolute path` };
-    let fd;
-    try {
-        fd = openSync(path, 'r');
-    }
-    catch {
-        return { ok: false, problem: `the ${FILE_KEY} cannot be read` };
-    }
-    try {
-        const st = fstatSync(fd);
-        if (!st.isFile())
-            return { ok: false, problem: `the ${FILE_KEY} is not a regular file` };
-        if (st.size > STATE_LIMIT)
-            return { ok: false, problem: `the login state is larger than ${STATE_LIMIT} bytes` };
-        return readState(readFileSync(fd));
-    }
-    catch {
-        return { ok: false, problem: `the ${FILE_KEY} cannot be read` };
-    }
-    finally {
-        closeSync(fd);
-    }
+    const file = stateFileBytes(path, `the ${FILE_KEY}`, true);
+    return file.ok ? readState(file.bytes) : file;
 }
 export async function auth(configDir) {
-    const input = await readStdinJson(INPUT_LIMIT, [], [FILE_KEY]);
+    const input = await readStdinJson(INPUT_LIMIT, [], [FILE_KEY, EXPORT_KEY]);
     if (!input.ok) {
         complain(input.problem);
         return 1;
     }
+    const exportValue = input.values[EXPORT_KEY];
+    if (exportValue !== undefined && exportValue !== EXPORT_ON && exportValue !== EXPORT_OFF) {
+        complain(`${EXPORT_KEY} must be "${EXPORT_ON}" or "${EXPORT_OFF}"`);
+        return 1;
+    }
+    const exportOn = exportValue === EXPORT_ON;
     const file = input.values[FILE_KEY];
     let state = EMPTY_STATE;
     if (file !== undefined) {
@@ -48,12 +36,18 @@ export async function auth(configDir) {
     }
     const secrets = openFileSecrets({ configDir, connector: NAME });
     try {
-        secrets.put(STATE_HANDLE, state);
+        secrets.withLock(() => {
+            if (exportOn)
+                secrets.put(EXPORT_HANDLE, EXPORT_ON, { secret: false });
+            else
+                secrets.remove(EXPORT_HANDLE);
+            secrets.put(STATE_HANDLE, state);
+        });
     }
     catch (e) {
         complain(`the login state was not stored (run auth again): ${e instanceof Error ? e.message : 'unknown error'}`);
         return 1;
     }
-    say(`stored ${file === undefined ? 'an empty login state (a clean profile)' : 'the login state of the file'} of connector ${NAME} as handle ${STATE_HANDLE} under ${secrets.directory}`);
+    say(`stored ${file === undefined ? 'an empty login state (a clean profile)' : 'the login state of the file'} of connector ${NAME} as handle ${STATE_HANDLE} under ${secrets.directory}; export of the login state ${exportOn ? `on (handle ${EXPORT_HANDLE})` : 'off'}`);
     return 0;
 }

package/dist/cli.js

@@ -3,7 +3,7 @@ import { auth } from './auth.js';
 import { NAME } from './names.js';
 import { serve } from './serve.js';
 import { PLAYWRIGHT_MCP } from './upstream.js';
-const AUTH_READS = '{} or {"storageStateFile": "<absolute path>"} as one line';
+const AUTH_READS = '{} or {"storageStateFile": "<absolute path>"}, with "export": "on" or "off" optional, as one line';
 export function main(argv, env) {
     return connectorCli({ name: NAME, serve, install: PLAYWRIGHT_MCP.install, auth, authReads: AUTH_READS }, argv, env);
 }

package/dist/names.d.ts

@@ -1,3 +1,5 @@
 export declare const NAME = "browser";
 export declare const STATE_HANDLE = "BROWSER_STORAGE_STATE";
+export declare const EXPORT_HANDLE = "BROWSER_EXPORT";
+export declare const EXPORT_ON = "on";
 export declare const PROGRAM: string, say: (line: string) => void, complain: (line: string) => void;

package/dist/names.js

@@ -1,4 +1,6 @@
 import { cliOutput } from '@sema-agent/connectors';
 export const NAME = 'browser';
 export const STATE_HANDLE = 'BROWSER_STORAGE_STATE';
+export const EXPORT_HANDLE = 'BROWSER_EXPORT';
+export const EXPORT_ON = 'on';
 export const { program: PROGRAM, say, complain } = cliOutput(NAME);

package/dist/relay.d.ts

@@ -0,0 +1,5 @@
+import type { FileSecrets, UpstreamRelay } from '@sema-agent/connectors';
+export declare function exportRelay({ out, secrets }: {
+    readonly out: string;
+    readonly secrets: FileSecrets;
+}): UpstreamRelay;

package/dist/relay.js

@@ -0,0 +1,81 @@
+import { randomBytes } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_HANDLE, complain } from './names.js';
+import { readState, stateFileBytes } from './state.js';
+import { SAVE_TOOL, WITHHELD } from './upstream.js';
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keyOf = (id) => (typeof id === 'string' || typeof id === 'number' ? `${typeof id}:${String(id)}` : null);
+const lineOf = (m) => Buffer.from(JSON.stringify(m), 'utf8');
+const failed = (id, text) => lineOf({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }], isError: true } });
+const notFound = (id, name) => failed(id, `### Error\nTool "${name}" not found`);
+export function exportRelay({ out, secrets }) {
+    const lists = new Set();
+    const saves = new Map();
+    const store = (file) => {
+        const saved = stateFileBytes(file, 'the saved storage state', false);
+        if (!saved.ok)
+            return saved.problem;
+        const read = readState(saved.bytes);
+        if (!read.ok)
+            return read.problem;
+        try {
+            secrets.put(STATE_HANDLE, read.text);
+        }
+        catch (e) {
+            return `the secrets backend did not store it (${e instanceof Error ? e.message : 'unknown error'})`;
+        }
+        return null;
+    };
+    return {
+        toProgram(line, m) {
+            if (m === null)
+                return line;
+            const key = keyOf(m.id);
+            if (m.method === 'tools/list') {
+                if (key !== null)
+                    lists.add(key);
+                return line;
+            }
+            const params = isObject(m.params) ? m.params : null;
+            if (m.method !== 'tools/call' || typeof params?.name !== 'string')
+                return line;
+            if (WITHHELD.includes(params.name))
+                return key === null ? null : { answer: notFound(m.id, params.name) };
+            if (params.name !== SAVE_TOOL)
+                return line;
+            if (key === null)
+                return null;
+            const file = join(out, `export-${randomBytes(16).toString('hex')}.json`);
+            saves.set(key, file);
+            return lineOf({ ...m, params: { ...params, arguments: { filename: file } } });
+        },
+        toConnector(line, m) {
+            if (m === null || 'method' in m)
+                return line;
+            const key = keyOf(m.id);
+            if (key === null)
+                return line;
+            if (lists.delete(key)) {
+                if (!isObject(m.result) || !Array.isArray(m.result.tools))
+                    return line;
+                return lineOf({ ...m, result: { ...m.result, tools: m.result.tools.filter((t) => !(isObject(t) && typeof t.name === 'string' && WITHHELD.includes(t.name))) } });
+            }
+            const file = saves.get(key);
+            if (file === undefined)
+                return line;
+            saves.delete(key);
+            const problem = isObject(m.result) && m.result.isError !== true ? store(file) : null;
+            try {
+                rmSync(file, { force: true });
+            }
+            catch (e) {
+                complain(`the file of a saved login state could not be removed (${e.code ?? 'unknown error'}); it goes with the launch's directory`);
+            }
+            if (problem === null)
+                return line;
+            complain(`the login state was not stored: ${problem}`);
+            return failed(m.id, `### Error\nThe login state was not stored: ${problem}`);
+        },
+    };
+}

package/dist/serve.d.ts

@@ -1,2 +1,2 @@
-import type { Env } from '@sema-agent/connectors';
+import { type Env } from '@sema-agent/connectors';
 export declare function serve(env: Env): Promise<number>;

package/dist/serve.js

@@ -1,31 +1,10 @@
-import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { NAME, PROGRAM, STATE_HANDLE, complain } from './names.js';
-import { STATE_LIMIT, readState } from './state.js';
+import { lstatSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { openFileSecrets } from '@sema-agent/connectors';
+import { EXPORT_HANDLE, EXPORT_ON, NAME, PROGRAM, STATE_HANDLE, complain } from './names.js';
+import { exportRelay } from './relay.js';
+import { readState, stateFileBytes } from './state.js';
 import { CHROME_EXECUTABLE, OUT_DIR, PLAYWRIGHT_MCP, SETTINGS_PREFIX, argsFor } from './upstream.js';
-function copyOf(path) {
-    let fd;
-    try {
-        fd = openSync(path, 'r');
-    }
-    catch {
-        return null;
-    }
-    try {
-        const st = fstatSync(fd);
-        if (!st.isFile())
-            return null;
-        if (st.size > STATE_LIMIT)
-            return Buffer.alloc(STATE_LIMIT + 1);
-        return readFileSync(fd);
-    }
-    catch {
-        return null;
-    }
-    finally {
-        closeSync(fd);
-    }
-}
 function outputDirectory(out) {
     try {
         mkdirSync(out, { mode: 0o700 });
@@ -37,6 +16,14 @@ function outputDirectory(out) {
     }
     return lstatSync(out).isDirectory() ? null : `${OUT_DIR} next to the ${STATE_HANDLE} copy is not a directory: start the connector with sema-connector run ${NAME}`;
 }
+function exportStored(path) {
+    try {
+        return statSync(path).size <= 64 && readFileSync(path, 'utf8').trim() === EXPORT_ON;
+    }
+    catch {
+        return false;
+    }
+}
 export function serve(env) {
     const refuse = (problem) => {
         complain(problem);
@@ -47,12 +34,17 @@ export function serve(env) {
     if (!start.ok)
         return refuse(start.problem);
     const state = start.files[STATE_HANDLE];
-    const bytes = copyOf(state);
-    if (bytes === null)
-        return refuse(`the ${STATE_HANDLE} handle cannot be read`);
-    const read = readState(bytes);
+    const copy = stateFileBytes(state, `the ${STATE_HANDLE} handle`, false);
+    const read = copy.ok ? readState(copy.bytes) : copy;
     if (!read.ok)
         return refuse(`the stored ${STATE_HANDLE} handle is refused: ${read.problem}; store it again with ${PROGRAM} auth`);
+    const exportFile = start.files[EXPORT_HANDLE];
+    const exportOn = exportFile !== undefined;
+    if (exportOn && !exportStored(exportFile))
+        return refuse(`the stored ${EXPORT_HANDLE} handle is refused: it holds something other than ${EXPORT_ON}; store it again with ${PROGRAM} auth`);
+    const secrets = openFileSecrets({ configDir: dirname(dirname(resolve(start.connectorDir))), connector: NAME });
+    if (exportOn && secrets.directory !== resolve(start.connectorDir))
+        return refuse(`the export of the login state needs the connector's directory to be <configuration directory>/connectors/${NAME}: start the connector with sema-connector run ${NAME}`);
     const where = CHROME_EXECUTABLE[process.platform];
     if (where === undefined)
         return refuse(`Chrome for Testing is not pinned for ${process.platform}`);
@@ -70,5 +62,6 @@ export function serve(env) {
     if (problem !== null)
         return refuse(problem);
     process.chdir(out);
-    return start.run(argsFor({ chrome, out, state }), {});
+    const relay = exportOn ? exportRelay({ out, secrets }) : undefined;
+    return start.run(argsFor({ chrome, out, state }, exportOn), {}, relay);
 }

package/dist/state.d.ts

@@ -7,4 +7,12 @@ export type StateReading = {
     readonly ok: false;
     readonly problem: string;
 };
+export type StateBytes = {
+    readonly ok: true;
+    readonly bytes: Buffer;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function stateFileBytes(path: string, what: string, followLink: boolean): StateBytes;
 export declare function readState(bytes: Uint8Array): StateReading;

package/dist/state.js

@@ -1,5 +1,29 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
 export const STATE_LIMIT = 4 * 1024 * 1024;
 export const EMPTY_STATE = '{"cookies":[],"origins":[]}';
+export function stateFileBytes(path, what, followLink) {
+    let fd;
+    try {
+        fd = openSync(path, followLink ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return { ok: false, problem: `${what} cannot be read` };
+    }
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            return { ok: false, problem: `${what} is not a regular file` };
+        if (st.size > STATE_LIMIT)
+            return { ok: false, problem: `the login state is larger than ${STATE_LIMIT} bytes` };
+        return { ok: true, bytes: readFileSync(fd) };
+    }
+    catch {
+        return { ok: false, problem: `${what} cannot be read` };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function readState(bytes) {
     if (bytes.length > STATE_LIMIT)
         return { ok: false, problem: `the login state is larger than ${STATE_LIMIT} bytes` };

package/dist/upstream.d.ts

@@ -5,8 +5,11 @@ export declare const OUT_DIR = "out";
 export declare const SETTINGS_PREFIX = "PLAYWRIGHT_MCP_";
 export declare const CHROME_EXECUTABLE: Readonly<Record<string, string>>;
 export declare const FIXED_FLAGS: readonly string[];
+export declare const EXPORT_FLAGS: readonly string[];
+export declare const SAVE_TOOL = "browser_storage_state";
+export declare const WITHHELD: readonly string[];
 export declare function argsFor(paths: {
     readonly chrome: string;
     readonly out: string;
     readonly state: string;
-}): readonly string[];
+}, exportOn: boolean): readonly string[];

package/dist/upstream.js

@@ -1,7 +1,7 @@
 import { pinnedUpstream } from '@sema-agent/connectors';
-import { NAME, STATE_HANDLE } from './names.js';
+import { EXPORT_HANDLE, NAME, STATE_HANDLE } from './names.js';
 export const UPSTREAM = 'playwright-mcp';
-export const PLAYWRIGHT_MCP = pinnedUpstream({ connector: NAME, upstream: UPSTREAM, lockFile: new URL('../binaries.lock.json', import.meta.url), handles: [STATE_HANDLE] });
+export const PLAYWRIGHT_MCP = pinnedUpstream({ connector: NAME, upstream: UPSTREAM, lockFile: new URL('../binaries.lock.json', import.meta.url), handles: [STATE_HANDLE], optionalHandles: [EXPORT_HANDLE] });
 export const OUTPUT_MAX_SIZE = 64 * 1024 * 1024;
 export const OUT_DIR = 'out';
 export const SETTINGS_PREFIX = 'PLAYWRIGHT_MCP_';
@@ -10,6 +10,26 @@ export const CHROME_EXECUTABLE = Object.freeze({
     linux: 'chrome/chrome',
 });
 export const FIXED_FLAGS = Object.freeze(['--headless', '--isolated', '--browser', 'chromium', '--sandbox', '--block-service-workers', '--no-webmcp', '--timeout-navigation', '60000', '--output-max-size', String(OUTPUT_MAX_SIZE)]);
-export function argsFor(paths) {
-    return [...FIXED_FLAGS, '--executable-path', paths.chrome, '--output-dir', paths.out, '--storage-state', paths.state];
+export const EXPORT_FLAGS = Object.freeze(['--caps', 'storage']);
+export const SAVE_TOOL = 'browser_storage_state';
+export const WITHHELD = Object.freeze([
+    'browser_cookie_list',
+    'browser_cookie_get',
+    'browser_cookie_set',
+    'browser_cookie_delete',
+    'browser_cookie_clear',
+    'browser_set_storage_state',
+    'browser_localstorage_list',
+    'browser_localstorage_get',
+    'browser_localstorage_set',
+    'browser_localstorage_delete',
+    'browser_localstorage_clear',
+    'browser_sessionstorage_list',
+    'browser_sessionstorage_get',
+    'browser_sessionstorage_set',
+    'browser_sessionstorage_delete',
+    'browser_sessionstorage_clear',
+]);
+export function argsFor(paths, exportOn) {
+    return [...FIXED_FLAGS, '--executable-path', paths.chrome, '--output-dir', paths.out, '--storage-state', paths.state, ...(exportOn ? EXPORT_FLAGS : [])];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connector-browser",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Browser connector: runs the pinned Playwright MCP server and a pinned Chrome for Testing behind the sema-connector launcher, in an isolated, headless session whose login state is a secret handle.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,14 +16,15 @@
     "CHANGELOG.md",
     "binaries.lock.json",
     "NOTICE",
-    "README.md"
+    "README.md",
+    "KNOWN-LIMITS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@sema-agent/connectors": "0.7.0",
-    "@sema-agent/connectors-contract": "0.1.1"
+    "@sema-agent/connectors": "0.8.1",
+    "@sema-agent/connectors-contract": "0.2.0"
   },
   "engines": {
     "node": ">=22"