@sdods/mcp 0.3.2 → 0.5.1

package/dist/browser/config.js

@@ -0,0 +1,100 @@
+import { join } from 'node:path';
+/**
+ * SDODS browser name -> the child's `--browser` value, plus a device for the mobile profiles.
+ *
+ * `--browser` is always passed. The child defaults to chromium on the `chrome` channel — real
+ * Google Chrome — which is not on a CI runner and is not what `-b chromium` means anywhere else
+ * in SDODS.
+ */
+const CHILD_BROWSER = {
+    chromium: { browser: 'chromium' },
+    edge: { browser: 'msedge' },
+    firefox: { browser: 'firefox' },
+    webkit: { browser: 'webkit' },
+    'mobile-chrome': { browser: 'chromium', device: 'Pixel 7' },
+    'mobile-safari': { browser: 'webkit', device: 'iPhone 15' },
+};
+function definedOnly(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+function originOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildSessionLaunch(resolved, spec, opts = {}) {
+    const browser = spec.browser ?? 'chromium';
+    const child = CHILD_BROWSER[browser];
+    const safeId = spec.sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    const runsDir = resolved.runtime.artifactsDir ?? join(resolved.runtime.repoRoot, '.sdods/runs');
+    // Inside a run, artifacts belong with it. Outside one they must NOT go under .sdods/runs:
+    // `listRuns` treats every directory there as a run, and `runtime.runId` from `config show` is a
+    // freshly minted id on every call — so a session would invent a run with no results, once per
+    // open, and `sdods report --last` would start pointing at browsing rather than testing.
+    const outputDir = opts.runId
+        ? join(runsDir, opts.runId, 'browser', safeId)
+        : join(resolved.runtime.repoRoot, '.sdods', 'browser', safeId);
+    const configPath = join(outputDir, 'mcp.config.json');
+    const use = resolved.env.use ?? {};
+    const contextOptions = definedOnly({
+        storageState: opts.storageStateFile,
+        viewport: spec.viewport ?? resolved.project.screenshots?.viewport,
+        locale: use.locale,
+        timezoneId: use.timezoneId,
+        colorScheme: use.colorScheme,
+        geolocation: use.geolocation,
+        permissions: use.permissions,
+        ignoreHTTPSErrors: use.ignoreHTTPSErrors,
+        extraHTTPHeaders: use.extraHTTPHeaders,
+        httpCredentials: use.httpCredentials,
+    });
+    // Origins are opt-in. Deriving an allowlist from the app's own baseUrl would block fonts, CDNs,
+    // analytics and SSO redirects on any real application — and upstream states the flag is not a
+    // security boundary and does not follow redirects, so it must not be sold as one.
+    const allowedOrigins = resolved.env.ui?.allowedOrigins
+        ?.map((o) => originOf(o) ?? o)
+        .filter(Boolean);
+    const blockedOrigins = resolved.env.ui?.blockedOrigins;
+    const configFile = definedOnly({
+        browser: {
+            // Without `isolated`, the child reuses the browser's existing context and every value in
+            // contextOptions above is silently discarded — the session would ignore its own storage
+            // state, locale, viewport and headers while appearing to work.
+            isolated: true,
+            contextOptions,
+            launchOptions: { headless: !spec.headed },
+        },
+        testIdAttribute: resolved.project.testIdAttribute,
+        outputDir,
+        network: allowedOrigins?.length || blockedOrigins?.length
+            ? definedOnly({ allowedOrigins, blockedOrigins })
+            : undefined,
+        timeouts: definedOnly({
+            action: resolved.project.timeouts?.action,
+            navigation: resolved.project.timeouts?.navigation,
+        }),
+    });
+    const argv = ['mcp', '--isolated', '--config', configPath, '--browser', child.browser];
+    const device = spec.device ?? child.device;
+    if (device)
+        argv.push('--device', device);
+    if (!spec.headed)
+        argv.push('--headless');
+    if (spec.caps?.length)
+        argv.push('--caps', [...new Set(spec.caps)].join(','));
+    if (spec.snapshotMode)
+        argv.push('--snapshot-mode', spec.snapshotMode);
+    if (spec.images === 'omit')
+        argv.push('--image-responses', 'omit');
+    // A parsed dotenv file, not a path, once the child has it: keeping it on the command line stops
+    // secret VALUES being written into the config file under .sdods/runs.
+    if (opts.secretsFile)
+        argv.push('--secrets', opts.secretsFile);
+    return { configFile, argv, outputDir, configPath };
+}
+//# sourceMappingURL=config.js.map

package/dist/browser/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './config.js';
+export * from './manifest.js';
+export * from './policy.js';
+export * from './session.js';
+export { UPSTREAM_SHAPES, UPSTREAM_DEFAULTS, type UpstreamToolName } from './shapes.js';
+export { resolvePlaywrightBin, createPlaywrightDriver } from './playwright-driver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './config.js';
+export * from './manifest.js';
+export * from './policy.js';
+export * from './session.js';
+export { UPSTREAM_SHAPES, UPSTREAM_DEFAULTS } from './shapes.js';
+export { resolvePlaywrightBin, createPlaywrightDriver } from './playwright-driver.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/manifest.d.ts

@@ -0,0 +1,35 @@
+import type { UpstreamToolName } from './shapes.js';
+/**
+ * The SDODS view of each Playwright MCP tool: what it costs a caller, and who may call it.
+ *
+ * Kept separate from `shapes.ts` (generated) because these are judgements, not transcription. They
+ * are also the only place the wrapper differs from upstream on purpose, so the differences are
+ * reviewable in one screen rather than spread across 42 definitions.
+ */
+export type BrowserAccess = 'read' | 'write';
+/** Which `--caps` pack the child needs before the tool exists at all. */
+export type CapsPack = 'default' | 'vision' | 'pdf' | 'devtools';
+export interface BrowserToolSpec {
+    pack: CapsPack;
+    access: BrowserAccess;
+    /** Overrides the access/domain scope derivation. Used to keep the two RCE-shaped tools apart. */
+    scope?: 'browser:admin';
+    /** Appended to the upstream description; says what SDODS adds or restricts. */
+    note?: string;
+}
+/**
+ * `read` vs `write` rather than `run`: `run` derives `runs:write` through `scopeForToolAccess`,
+ * which is the wrong scope for a browser and would hand browser control to anything that may
+ * start a test.
+ *
+ * Two deliberate divergences from upstream's own annotations:
+ *  - `browser_take_screenshot` and `browser_pdf_save` write files, and upstream still marks them
+ *    read-only. They stay `read` here because they only write into the session's own output
+ *    directory, but the note says so rather than leaving it implied.
+ *  - Everything that changes page state is `write`, including `browser_navigate`, which upstream
+ *    does not flag. Navigating away is not an observation.
+ */
+export declare const BROWSER_TOOLS: Record<UpstreamToolName, BrowserToolSpec>;
+/** Tools gated behind the unsafe opt-in. */
+export declare const UNSAFE_TOOLS: ("browser_annotate" | "browser_click" | "browser_close" | "browser_console_messages" | "browser_drag" | "browser_drop" | "browser_evaluate" | "browser_file_upload" | "browser_fill_form" | "browser_find" | "browser_handle_dialog" | "browser_hide_highlight" | "browser_highlight" | "browser_hover" | "browser_mouse_click_xy" | "browser_mouse_down" | "browser_mouse_drag_xy" | "browser_mouse_move_xy" | "browser_mouse_up" | "browser_mouse_wheel" | "browser_navigate" | "browser_navigate_back" | "browser_network_request" | "browser_network_requests" | "browser_pdf_save" | "browser_press_key" | "browser_resize" | "browser_resume" | "browser_run_code_unsafe" | "browser_select_option" | "browser_snapshot" | "browser_start_recording" | "browser_start_tracing" | "browser_start_video" | "browser_stop_recording" | "browser_stop_tracing" | "browser_stop_video" | "browser_tabs" | "browser_take_screenshot" | "browser_type" | "browser_video_chapter" | "browser_video_hide_actions" | "browser_video_show_actions" | "browser_wait_for")[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/browser/manifest.js

@@ -0,0 +1,105 @@
+/**
+ * `read` vs `write` rather than `run`: `run` derives `runs:write` through `scopeForToolAccess`,
+ * which is the wrong scope for a browser and would hand browser control to anything that may
+ * start a test.
+ *
+ * Two deliberate divergences from upstream's own annotations:
+ *  - `browser_take_screenshot` and `browser_pdf_save` write files, and upstream still marks them
+ *    read-only. They stay `read` here because they only write into the session's own output
+ *    directory, but the note says so rather than leaving it implied.
+ *  - Everything that changes page state is `write`, including `browser_navigate`, which upstream
+ *    does not flag. Navigating away is not an observation.
+ */
+export const BROWSER_TOOLS = {
+    // ---- observe -----------------------------------------------------------------------------
+    browser_snapshot: { pack: 'default', access: 'read' },
+    browser_find: { pack: 'default', access: 'read' },
+    browser_console_messages: { pack: 'default', access: 'read' },
+    browser_network_requests: { pack: 'default', access: 'read' },
+    browser_network_request: {
+        pack: 'default',
+        access: 'read',
+        note: 'Authorization, cookie and API-key headers are redacted before the result is returned.',
+    },
+    browser_take_screenshot: {
+        pack: 'default',
+        access: 'read',
+        note: 'Returns the image inline; a `filename` writes into the session output directory only.',
+    },
+    browser_wait_for: { pack: 'default', access: 'read' },
+    // ---- act ---------------------------------------------------------------------------------
+    browser_navigate: { pack: 'default', access: 'write' },
+    browser_navigate_back: { pack: 'default', access: 'write' },
+    browser_click: { pack: 'default', access: 'write' },
+    browser_type: { pack: 'default', access: 'write' },
+    browser_fill_form: { pack: 'default', access: 'write' },
+    browser_press_key: { pack: 'default', access: 'write' },
+    browser_hover: { pack: 'default', access: 'write' },
+    browser_drag: { pack: 'default', access: 'write' },
+    browser_drop: { pack: 'default', access: 'write' },
+    browser_select_option: { pack: 'default', access: 'write' },
+    browser_file_upload: {
+        pack: 'default',
+        access: 'write',
+        note: 'Paths resolve inside the repository root the server was started in.',
+    },
+    browser_resize: { pack: 'default', access: 'write' },
+    browser_tabs: { pack: 'default', access: 'write' },
+    browser_handle_dialog: { pack: 'default', access: 'write' },
+    browser_close: {
+        pack: 'default',
+        access: 'write',
+        note: 'Closes the page. The session and its browser stay up — use browser_session_close to end the session.',
+    },
+    // ---- arbitrary code: the two that are RCE-shaped ------------------------------------------
+    browser_evaluate: {
+        pack: 'default',
+        access: 'write',
+        scope: 'browser:admin',
+        note: 'Runs caller-supplied JavaScript in the page. Off unless SDODS_BROWSER_ALLOW_UNSAFE is set.',
+    },
+    browser_run_code_unsafe: {
+        pack: 'default',
+        access: 'write',
+        scope: 'browser:admin',
+        note: 'Executes arbitrary JavaScript in the Playwright server process — upstream calls this RCE-equivalent. Off unless SDODS_BROWSER_ALLOW_UNSAFE is set.',
+    },
+    // ---- vision: coordinate input, no accessibility tree --------------------------------------
+    browser_mouse_move_xy: { pack: 'vision', access: 'write' },
+    browser_mouse_click_xy: { pack: 'vision', access: 'write' },
+    browser_mouse_drag_xy: { pack: 'vision', access: 'write' },
+    browser_mouse_down: { pack: 'vision', access: 'write' },
+    browser_mouse_up: { pack: 'vision', access: 'write' },
+    browser_mouse_wheel: { pack: 'vision', access: 'write' },
+    // ---- pdf ----------------------------------------------------------------------------------
+    browser_pdf_save: {
+        pack: 'pdf',
+        access: 'read',
+        note: 'Writes into the session output directory only.',
+    },
+    // ---- devtools: tracing, video, annotation -------------------------------------------------
+    browser_start_tracing: { pack: 'devtools', access: 'read' },
+    browser_stop_tracing: { pack: 'devtools', access: 'read' },
+    browser_start_video: { pack: 'devtools', access: 'read' },
+    browser_stop_video: { pack: 'devtools', access: 'read' },
+    browser_video_chapter: { pack: 'devtools', access: 'read' },
+    browser_video_show_actions: { pack: 'devtools', access: 'read' },
+    browser_video_hide_actions: { pack: 'devtools', access: 'read' },
+    browser_start_recording: {
+        pack: 'devtools',
+        access: 'read',
+        note: 'Records what a person does in the browser; pair with browser_stop_recording. Not for unattended runs.',
+    },
+    browser_stop_recording: { pack: 'devtools', access: 'read' },
+    browser_highlight: { pack: 'devtools', access: 'write' },
+    browser_hide_highlight: { pack: 'devtools', access: 'write' },
+    browser_annotate: {
+        pack: 'devtools',
+        access: 'write',
+        note: 'Waits for a person to draw in the browser, so it blocks until they finish. Not for unattended runs.',
+    },
+    browser_resume: { pack: 'devtools', access: 'write' },
+};
+/** Tools gated behind the unsafe opt-in. */
+export const UNSAFE_TOOLS = Object.keys(BROWSER_TOOLS).filter((n) => BROWSER_TOOLS[n].scope === 'browser:admin');
+//# sourceMappingURL=manifest.js.map

package/dist/browser/playwright-driver.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserDriver } from './types.js';
+/**
+ * Drives the Playwright MCP server that ships inside the pinned `playwright`.
+ *
+ * Not `npx playwright mcp`: npx resolves at run time, which is how this repo ended up with
+ * `.mcp.json` pointing at a server nobody had pinned. The binary is resolved from node_modules so
+ * the tools the wrapper declares and the tools the child offers come from the same install — the
+ * drift test asserts exactly that.
+ */
+export declare function resolvePlaywrightBin(repoRoot: string): string | null;
+export interface PlaywrightDriverOptions {
+    repoRoot: string;
+    argv: string[];
+    /** Merged into the child's args map before each call; see UPSTREAM_DEFAULTS. */
+    defaultsFor?: (tool: string) => Record<string, unknown> | undefined;
+}
+export declare function createPlaywrightDriver(opts: PlaywrightDriverOptions): Promise<BrowserDriver>;
+//# sourceMappingURL=playwright-driver.d.ts.map

package/dist/browser/playwright-driver.js

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { redactHeaders } from './policy.js';
+/**
+ * Drives the Playwright MCP server that ships inside the pinned `playwright`.
+ *
+ * Not `npx playwright mcp`: npx resolves at run time, which is how this repo ended up with
+ * `.mcp.json` pointing at a server nobody had pinned. The binary is resolved from node_modules so
+ * the tools the wrapper declares and the tools the child offers come from the same install — the
+ * drift test asserts exactly that.
+ */
+export function resolvePlaywrightBin(repoRoot) {
+    const candidates = [
+        join(repoRoot, 'node_modules', '.bin', 'playwright'),
+        join(repoRoot, 'node_modules', '@playwright', 'test', 'cli.js'),
+    ];
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+export async function createPlaywrightDriver(opts) {
+    const bin = resolvePlaywrightBin(opts.repoRoot);
+    if (!bin) {
+        throw Object.assign(new Error('Playwright is not installed in this workspace.'), {
+            error: { code: 'BROWSER_UNAVAILABLE', hint: 'Run `bun install`.' },
+        });
+    }
+    const { Client } = await import('@modelcontextprotocol/client');
+    const { StdioClientTransport } = await import('@modelcontextprotocol/client/stdio');
+    const client = new Client({ name: 'sdods-browser', version: '0.1.0' });
+    const transport = new StdioClientTransport({
+        command: bin.endsWith('.js') ? process.execPath : bin,
+        args: bin.endsWith('.js') ? [bin, ...opts.argv] : opts.argv,
+        env: { ...process.env },
+        // The child restricts file access to its workspace roots, so the repo root is what makes
+        // browser_file_upload of a repo path and the .sdods output directory reachable.
+        cwd: opts.repoRoot,
+        stderr: 'ignore',
+    });
+    await client.connect(transport);
+    const server = client.getServerVersion() ?? { name: 'unknown', version: 'unknown' };
+    return {
+        info: () => ({ server: String(server.name), version: String(server.version) }),
+        async listTools() {
+            return (await client.listTools()).tools.map((t) => t.name);
+        },
+        async call(tool, args) {
+            // Upstream schemas are additionalProperties:false, so SDODS-only arguments must not be
+            // forwarded, and the properties upstream marks required-with-default must be filled back in.
+            const { sessionId: _drop, ...rest } = args;
+            const merged = { ...(opts.defaultsFor?.(tool) ?? {}), ...rest };
+            const result = (await client.callTool({ name: tool, arguments: merged }));
+            const out = { text: '', images: [], isError: Boolean(result.isError) };
+            const parts = [];
+            for (const c of result.content ?? []) {
+                if (c.type === 'text')
+                    parts.push(String(c.text ?? ''));
+                else if (c.type === 'image')
+                    out.images.push({ data: String(c.data), mimeType: String(c.mimeType ?? 'image/png') });
+                else
+                    parts.push(`[${String(c.type)}]`);
+            }
+            out.text = redactHeaders(parts.join('\n'));
+            return out;
+        },
+        async close() {
+            await client.close().catch(() => undefined);
+        },
+    };
+}
+//# sourceMappingURL=playwright-driver.js.map

package/dist/browser/policy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the wrapper refuses, and what it never lets back out.
+ *
+ * Applied in the driver rather than in each tool, so a tool cannot forget to call it.
+ */
+/**
+ * Network results come back as TEXT, so the keyed-object redactor used elsewhere in SDODS does not
+ * apply — headers arrive as `authorization: Bearer ey...` inside a formatted block.
+ *
+ * Bodies are deliberately not regex-scrubbed: Playwright's own `--secrets` masks known values at
+ * capture time, which a post-hoc guess cannot do without also mangling legitimate content.
+ */
+export declare function redactHeaders(text: string): string;
+/**
+ * Arbitrary-code tools are off unless explicitly enabled.
+ *
+ * A scope alone is not enough: the stdio principal is LOCAL_ADMIN and holds every scope, so on a
+ * developer machine `browser_run_code_unsafe` would otherwise always be available. This is the
+ * switch an operator can set for a deployment; the scope is what governs HTTP principals.
+ */
+export declare function unsafeToolsEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare const UNSAFE_DISABLED_HINT = "Set SDODS_BROWSER_ALLOW_UNSAFE=1 to enable it. It runs caller-supplied code, which upstream documents as RCE-equivalent.";
+//# sourceMappingURL=policy.d.ts.map

package/dist/browser/policy.js

@@ -0,0 +1,30 @@
+/**
+ * What the wrapper refuses, and what it never lets back out.
+ *
+ * Applied in the driver rather than in each tool, so a tool cannot forget to call it.
+ */
+/** Header lines whose value must never reach a transcript. */
+const SECRET_HEADER = /^(\s*[-*]?\s*)(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-auth-token|x-csrf-token)(\s*:\s*)(.+)$/gim;
+/**
+ * Network results come back as TEXT, so the keyed-object redactor used elsewhere in SDODS does not
+ * apply — headers arrive as `authorization: Bearer ey...` inside a formatted block.
+ *
+ * Bodies are deliberately not regex-scrubbed: Playwright's own `--secrets` masks known values at
+ * capture time, which a post-hoc guess cannot do without also mangling legitimate content.
+ */
+export function redactHeaders(text) {
+    return text.replace(SECRET_HEADER, (_m, lead, name, sep) => `${lead}${name}${sep}***`);
+}
+/**
+ * Arbitrary-code tools are off unless explicitly enabled.
+ *
+ * A scope alone is not enough: the stdio principal is LOCAL_ADMIN and holds every scope, so on a
+ * developer machine `browser_run_code_unsafe` would otherwise always be available. This is the
+ * switch an operator can set for a deployment; the scope is what governs HTTP principals.
+ */
+export function unsafeToolsEnabled(env = process.env) {
+    const raw = env.SDODS_BROWSER_ALLOW_UNSAFE;
+    return raw === '1' || raw === 'true';
+}
+export const UNSAFE_DISABLED_HINT = 'Set SDODS_BROWSER_ALLOW_UNSAFE=1 to enable it. It runs caller-supplied code, which upstream documents as RCE-equivalent.';
+//# sourceMappingURL=policy.js.map

package/dist/browser/session.d.ts

@@ -0,0 +1,57 @@
+import { type ResolvedForBrowser } from './config.js';
+import type { BrowserDriver, BrowserSessionSpec, SessionInfo } from './types.js';
+/**
+ * Live browser sessions for ONE MCP connection.
+ *
+ * Deliberately not a module-level map keyed by a caller-supplied id. The HTTP transport builds one
+ * server and one ToolContext per mcp-session-id and already refuses a session whose principal
+ * differs; a process-wide map would let a second principal name the first one's session id and
+ * drive their logged-in browser. Ownership by context makes that unreachable.
+ */
+export interface SessionManagerOptions {
+    rootDir: string;
+    /** Reaps a session that nobody has used. Browsers are expensive to leave running. */
+    idleMs?: number;
+    maxSessions?: number;
+    /**
+     * Seams. The default implementations spawn the pinned Playwright MCP child and shell out to
+     * `sdods config show`; overriding them lets the lifecycle be tested without either, and is where
+     * a second BrowserDriver would be plugged in.
+     */
+    createDriver?: (args: {
+        repoRoot: string;
+        argv: string[];
+    }) => Promise<BrowserDriver>;
+    resolveConfig?: (project: string, env?: string) => Promise<ResolvedForBrowser>;
+}
+interface Entry {
+    driver: BrowserDriver;
+    info: SessionInfo;
+    timer?: NodeJS.Timeout;
+}
+export declare const DEFAULT_IDLE_MS: number;
+export declare const DEFAULT_MAX_SESSIONS = 4;
+export declare class BrowserSessionManager {
+    private readonly opts;
+    private readonly sessions;
+    private readonly idleMs;
+    private readonly maxSessions;
+    constructor(opts: SessionManagerOptions);
+    list(): SessionInfo[];
+    has(id: string): boolean;
+    open(spec: BrowserSessionSpec): Promise<SessionInfo>;
+    /** The session for a call, opening a default one from the connection's project when needed. */
+    ensure(id: string, fallback: Omit<BrowserSessionSpec, 'sessionId'>): Promise<Entry>;
+    get(id: string): Entry | undefined;
+    close(id: string): Promise<boolean>;
+    closeAll(): Promise<void>;
+    private touch;
+    /**
+     * Config comes through the CLI, like every other SDODS MCP tool, rather than by importing
+     * @sdods/core — so a browser session sees exactly what `sdods config show` would print.
+     */
+    private resolve;
+    private storageStateFor;
+}
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/browser/session.js

@@ -0,0 +1,145 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { sdodsCli } from '../cli.js';
+import { buildSessionLaunch } from './config.js';
+import { createPlaywrightDriver } from './playwright-driver.js';
+import { UPSTREAM_DEFAULTS } from './shapes.js';
+export const DEFAULT_IDLE_MS = 10 * 60_000;
+export const DEFAULT_MAX_SESSIONS = 4;
+export class BrowserSessionManager {
+    opts;
+    sessions = new Map();
+    idleMs;
+    maxSessions;
+    constructor(opts) {
+        this.opts = opts;
+        this.idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+        this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    }
+    list() {
+        return [...this.sessions.values()].map((e) => e.info);
+    }
+    has(id) {
+        return this.sessions.has(id);
+    }
+    async open(spec) {
+        await this.close(spec.sessionId);
+        if (this.sessions.size >= this.maxSessions) {
+            throw Object.assign(new Error(`At most ${this.maxSessions} browser sessions at a time.`), {
+                error: {
+                    code: 'BROWSER_TOO_MANY_SESSIONS',
+                    hint: 'Close one with browser_session_close, or list them with browser_session_list.',
+                },
+            });
+        }
+        const resolved = await this.resolve(spec.project, spec.env);
+        const storageStateFile = spec.role
+            ? await this.storageStateFor(spec.project, spec.env, spec.role)
+            : undefined;
+        // Only correlate with a run when one is actually in progress; see buildSessionLaunch.
+        const launch = buildSessionLaunch(resolved, spec, {
+            storageStateFile,
+            runId: process.env.SDODS_RUN_ID || undefined,
+        });
+        mkdirSync(dirname(launch.configPath), { recursive: true });
+        writeFileSync(launch.configPath, `${JSON.stringify(launch.configFile, null, 2)}\n`);
+        const driver = this.opts.createDriver
+            ? await this.opts.createDriver({ repoRoot: this.opts.rootDir, argv: launch.argv })
+            : await createPlaywrightDriver({
+                repoRoot: this.opts.rootDir,
+                argv: launch.argv,
+                defaultsFor: (tool) => UPSTREAM_DEFAULTS[tool],
+            });
+        const now = new Date().toISOString();
+        const info = {
+            sessionId: spec.sessionId,
+            project: spec.project,
+            env: spec.env ?? resolved.env.name,
+            role: spec.role,
+            browser: (spec.browser ?? 'chromium'),
+            headed: Boolean(spec.headed),
+            outputDir: launch.outputDir,
+            openedAt: now,
+            lastUsed: now,
+            server: `${driver.info().server} ${driver.info().version}`,
+        };
+        const entry = { driver, info };
+        this.sessions.set(spec.sessionId, entry);
+        this.touch(spec.sessionId);
+        return info;
+    }
+    /** The session for a call, opening a default one from the connection's project when needed. */
+    async ensure(id, fallback) {
+        const existing = this.sessions.get(id);
+        if (existing) {
+            this.touch(id);
+            return existing;
+        }
+        await this.open({ ...fallback, sessionId: id });
+        return this.sessions.get(id);
+    }
+    get(id) {
+        const e = this.sessions.get(id);
+        if (e)
+            this.touch(id);
+        return e;
+    }
+    async close(id) {
+        const entry = this.sessions.get(id);
+        if (!entry)
+            return false;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        this.sessions.delete(id);
+        await entry.driver.close();
+        return true;
+    }
+    async closeAll() {
+        await Promise.all([...this.sessions.keys()].map((id) => this.close(id)));
+    }
+    touch(id) {
+        const entry = this.sessions.get(id);
+        if (!entry)
+            return;
+        entry.info.lastUsed = new Date().toISOString();
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = setTimeout(() => void this.close(id), this.idleMs);
+        // A pending reap must never hold the process open.
+        entry.timer.unref?.();
+    }
+    /**
+     * Config comes through the CLI, like every other SDODS MCP tool, rather than by importing
+     * @sdods/core — so a browser session sees exactly what `sdods config show` would print.
+     */
+    async resolve(project, env) {
+        if (this.opts.resolveConfig)
+            return this.opts.resolveConfig(project, env);
+        const args = ['config', 'show', '-p', project];
+        if (env)
+            args.push('-e', env);
+        const r = await sdodsCli(args, { cwd: this.opts.rootDir });
+        return r.json;
+    }
+    async storageStateFor(project, env, role) {
+        const args = ['auth', 'list', '-p', project];
+        if (env)
+            args.push('-e', env);
+        const rows = (await sdodsCli(args, { cwd: this.opts.rootDir }))
+            .json;
+        const hit = (Array.isArray(rows) ? rows : []).find((r) => String(r.role ?? r.user) === role && String(r.fresh ?? 'yes') !== 'no');
+        const file = hit?.file ? String(hit.file) : undefined;
+        if (!file) {
+            // Capturing would drive a real login flow, which is not something a read of "open a browser
+            // as this role" should trigger on its own.
+            throw Object.assign(new Error(`No fresh login state for role "${role}".`), {
+                error: {
+                    code: 'BROWSER_NO_AUTH_STATE',
+                    hint: `Run \`sdods auth capture -p ${project}${env ? ` -e ${env}` : ''} -u ${role}\` first.`,
+                },
+            });
+        }
+        return file;
+    }
+}
+//# sourceMappingURL=session.js.map