@sema-agent/connector-browser 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.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/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
 
@@ -31,7 +33,9 @@ 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.0",
   "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",
@@ -22,8 +22,8 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@sema-agent/connectors": "0.7.0",
-    "@sema-agent/connectors-contract": "0.1.1"
+    "@sema-agent/connectors": "0.8.0",
+    "@sema-agent/connectors-contract": "0.2.0"
   },
   "engines": {
     "node": ">=22"