@sema-agent/connector-browser 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog: @sema-agent/connector-browser
+
+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.1.0 (2026-10-16)
+
+### Added
+
+- The browser connector (CN-027), `sema-connector-browser`. With no arguments it
+  is an MCP stdio server: it starts the pinned Playwright MCP server
+  (`@playwright/mcp` 0.0.83, with `playwright` and `playwright-core`
+  1.64.0-alpha-1790635538000) on the Node.js that runs the connector, driving
+  the pinned Chrome for Testing 155.0.8059.12, and passes MCP straight through.
+  `install` fetches the three npm tarballs and this platform's Chrome for Testing
+  zip from the sources `binaries.lock.json` names, compares each with its sha256
+  before anything is unpacked, and unpacks them below
+  `<configuration directory>/connectors/browser/bin/`; nothing is fetched at run
+  time and npm is never run. Chrome for Testing is pinned for `darwin-arm64` and
+  `linux-x64`.
+- `auth` reads one line from standard input: `{}` stores a clean profile, and
+  `{"storageStateFile": "<absolute path>"}` imports a Playwright storage state
+  (at most 4 MiB, a JSON object with exactly `cookies` and `origins`). Either is
+  stored as the secret handle `BROWSER_STORAGE_STATE`.
+- Security baseline: the server always gets `--headless --isolated --browser
+  chromium --sandbox --block-service-workers --no-webmcp --timeout-navigation
+  60000 --output-max-size 67108864`, the Chrome for Testing executable, the
+  output directory and the per-launch copy of the login state, and nothing else;
+  no `PLAYWRIGHT_MCP_*` variable reaches it. Each launch has an output
+  directory of its own, `out` in the launch's directory, which is the server's
+  working directory and goes when the launch ends.

package/NOTICE

@@ -0,0 +1,31 @@
+@sema-agent/connector-browser
+Copyright 2026 The sema-agent Authors
+
+This package is licensed under the Apache License, Version 2.0 (see the LICENSE
+file of the sema-connectors repository).
+
+Third-party programs: Playwright MCP, Playwright and Chrome for Testing
+------------------------------------------------------------------------
+
+This package contains no third-party code. Its install subcommand downloads
+the third-party programs binaries.lock.json pins, checks each against the
+sha256 binaries.lock.json pins, and keeps them in the user's configuration
+directory:
+
+- @playwright/mcp, playwright and playwright-core
+  (https://github.com/microsoft/playwright-mcp,
+  https://github.com/microsoft/playwright), from the npm registry. They are
+  distributed under the Apache License, Version 2.0, with the notice:
+
+    Playwright
+    Copyright (c) Microsoft Corporation
+
+    This software contains code derived from the Puppeteer project
+    (https://github.com/puppeteer/puppeteer), available under the Apache 2.0
+    license (https://github.com/puppeteer/puppeteer/blob/master/LICENSE).
+
+- Chrome for Testing (https://developer.chrome.com/blog/chrome-for-testing),
+  a build of Google Chrome made for automated testing, from the download host
+  Playwright uses for it. It is distributed by Google LLC under its own terms
+  (Copyright Google LLC; the Chromium open source project and other open source
+  software, whose notices the build lists at chrome://credits).

package/bin/sema-connector-browser.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// sema-connector-browser (CN-027): the browser connector's executable. With no arguments it runs the pinned Playwright
+// MCP server as an MCP stdio server; a first argument dispatches install, auth, mount and status
+// (docs/CONNECTORS/browser.md). Implementation: src/cli.ts, built to dist/cli.js.
+import { main } from '../dist/cli.js'
+
+process.exitCode = await main(process.argv.slice(2), process.env)

package/binaries.lock.json

@@ -0,0 +1,60 @@
+{
+  "playwright-mcp": {
+    "version": "0.0.83",
+    "archives": [
+      {
+        "platform": "*",
+        "file": "playwright-mcp-0.0.83.tgz",
+        "source": "https://registry.npmjs.org/@playwright/mcp/-/mcp-{version}.tgz",
+        "sha256": "f0014a13361b1ee2d8607a4e187868ab9a6e8ac637dbcd66e4af43f738d0c8cb",
+        "unpack": {
+          "directory": "package",
+          "to": "node_modules/@playwright/mcp"
+        }
+      },
+      {
+        "platform": "*",
+        "file": "playwright-1.64.0-alpha-1790635538000.tgz",
+        "source": "https://registry.npmjs.org/playwright/-/{file}",
+        "sha256": "436022a21e7a7c34436970fe04ab3fccae87a5045d3ed5af3f66c6e3ba377ee8",
+        "unpack": {
+          "directory": "package",
+          "to": "node_modules/playwright"
+        }
+      },
+      {
+        "platform": "*",
+        "file": "playwright-core-1.64.0-alpha-1790635538000.tgz",
+        "source": "https://registry.npmjs.org/playwright-core/-/{file}",
+        "sha256": "54ad1d38174d6ef56d1f165e52547ece8e6c24b865f2a072d9ebaacfbad1ca47",
+        "unpack": {
+          "directory": "package",
+          "to": "node_modules/playwright-core"
+        }
+      },
+      {
+        "platform": "darwin-arm64",
+        "file": "chrome-mac-arm64.zip",
+        "source": "https://cdn.playwright.dev/builds/cft/155.0.8059.12/mac-arm64/{file}",
+        "sha256": "d64771a096fffd48b49a65e481dda50ae43a7de55fb93acfa6aece26ec3b10db",
+        "unpack": {
+          "directory": "chrome-mac-arm64",
+          "to": "chrome"
+        }
+      },
+      {
+        "platform": "linux-x64",
+        "file": "chrome-linux64.zip",
+        "source": "https://cdn.playwright.dev/builds/cft/155.0.8059.12/linux64/{file}",
+        "sha256": "a24546e0e6c763bf864861ce50498f38783663e24cd2af2a16798c25dc3a9489",
+        "unpack": {
+          "directory": "chrome-linux64",
+          "to": "chrome"
+        }
+      }
+    ],
+    "program": {
+      "node": "node_modules/@playwright/mcp/cli.js"
+    }
+  }
+}

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export declare function auth(configDir: string): Promise<number>;

package/dist/auth.js

@@ -0,0 +1,59 @@
+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';
+const INPUT_LIMIT = 64 * 1024;
+const FILE_KEY = 'storageStateFile';
+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);
+    }
+}
+export async function auth(configDir) {
+    const input = await readStdinJson(INPUT_LIMIT, [], [FILE_KEY]);
+    if (!input.ok) {
+        complain(input.problem);
+        return 1;
+    }
+    const file = input.values[FILE_KEY];
+    let state = EMPTY_STATE;
+    if (file !== undefined) {
+        const read = stateFromFile(file);
+        if (!read.ok) {
+            complain(read.problem);
+            return 1;
+        }
+        state = read.text;
+    }
+    const secrets = openFileSecrets({ configDir, connector: NAME });
+    try {
+        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}`);
+    return 0;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import { type Env } from '@sema-agent/connectors';
+export declare function main(argv: readonly string[], env: Env): Promise<number | undefined>;

package/dist/cli.js

@@ -0,0 +1,9 @@
+import { connectorCli } from '@sema-agent/connectors';
+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';
+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

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

package/dist/names.js

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

package/dist/serve.d.ts

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

package/dist/serve.js

@@ -0,0 +1,74 @@
+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 { 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 });
+        return null;
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            return `the output directory could not be made (${e.code ?? 'unknown error'})`;
+    }
+    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}`;
+}
+export function serve(env) {
+    const refuse = (problem) => {
+        complain(problem);
+        return Promise.resolve(1);
+    };
+    const own = Object.fromEntries(Object.entries(env).filter(([k]) => !k.startsWith(SETTINGS_PREFIX)));
+    const start = PLAYWRIGHT_MCP.start(own);
+    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);
+    if (!read.ok)
+        return refuse(`the stored ${STATE_HANDLE} handle is refused: ${read.problem}; store it again with ${PROGRAM} auth`);
+    const where = CHROME_EXECUTABLE[process.platform];
+    if (where === undefined)
+        return refuse(`Chrome for Testing is not pinned for ${process.platform}`);
+    const chrome = join(start.binDir, where);
+    let executable = false;
+    try {
+        const st = lstatSync(chrome);
+        executable = st.isFile() && (st.mode & 0o111) !== 0;
+    }
+    catch { }
+    if (!executable)
+        return refuse(`Chrome for Testing is not in the bin directory: run ${PROGRAM} install`);
+    const out = join(dirname(state), OUT_DIR);
+    const problem = outputDirectory(out);
+    if (problem !== null)
+        return refuse(problem);
+    process.chdir(out);
+    return start.run(argsFor({ chrome, out, state }), {});
+}

package/dist/state.d.ts

@@ -0,0 +1,10 @@
+export declare const STATE_LIMIT: number;
+export declare const EMPTY_STATE = "{\"cookies\":[],\"origins\":[]}";
+export type StateReading = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function readState(bytes: Uint8Array): StateReading;

package/dist/state.js

@@ -0,0 +1,25 @@
+export const STATE_LIMIT = 4 * 1024 * 1024;
+export const EMPTY_STATE = '{"cookies":[],"origins":[]}';
+export function readState(bytes) {
+    if (bytes.length > STATE_LIMIT)
+        return { ok: false, problem: `the login state is larger than ${STATE_LIMIT} bytes` };
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return { ok: false, problem: 'the login state is not UTF-8 text' };
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, problem: 'the login state is not JSON' };
+    }
+    const object = value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    const keys = object === null ? [] : Object.keys(object).sort();
+    if (object === null || keys.join('\0') !== 'cookies\0origins' || !Array.isArray(object.cookies) || !Array.isArray(object.origins))
+        return { ok: false, problem: 'the login state must be one JSON object with exactly the keys cookies and origins, each a list (a Playwright storage state)' };
+    return { ok: true, text };
+}

package/dist/upstream.d.ts

@@ -0,0 +1,12 @@
+export declare const UPSTREAM = "playwright-mcp";
+export declare const PLAYWRIGHT_MCP: import("@sema-agent/connectors").PinnedUpstream;
+export declare const OUTPUT_MAX_SIZE: number;
+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 function argsFor(paths: {
+    readonly chrome: string;
+    readonly out: string;
+    readonly state: string;
+}): readonly string[];

package/dist/upstream.js

@@ -0,0 +1,15 @@
+import { pinnedUpstream } from '@sema-agent/connectors';
+import { 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 OUTPUT_MAX_SIZE = 64 * 1024 * 1024;
+export const OUT_DIR = 'out';
+export const SETTINGS_PREFIX = 'PLAYWRIGHT_MCP_';
+export const CHROME_EXECUTABLE = Object.freeze({
+    darwin: 'chrome/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    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];
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@sema-agent/connector-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "bin": {
+    "sema-connector-browser": "bin/sema-connector-browser.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "CHANGELOG.md",
+    "binaries.lock.json",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@sema-agent/connectors": "0.6.0",
+    "@sema-agent/connectors-contract": "0.1.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sema-agent/sema-connectors.git",
+    "directory": "packages/connector-browser"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.