@melaya/runner 1.0.118 → 1.1.1

package/dist/connection.js

@@ -26,8 +26,21 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 import { ensureSharedModules, getSharedDir } from "./sharedVendor.js";
 import { startLumaBrowserBridge } from "./lumaBrowserBridge.js";
+// Melaya Browser (plan Sections 3/4/7): the governed browser control
+// bridge + its runner-side grant verifier and engine discovery.
+import { startBrowserBridge } from "./browserBridge.js";
+import { verifyBrowserGrant, createInMemoryReplayStore, loadPinnedPublicKeysFromEnv, BrowserGrantError, } from "./browserGrantVerify.js";
+import { discoverEngines } from "./browserProvisioner.js";
+import { getRunnerDeviceId } from "./sessionManager.js";
 const HEARTBEAT_INTERVAL = 30_000;
 const activeProcesses = new Map();
+// Melaya Browser: the versioned capability advertised in the runner hello
+// (plan Section 4). Bumped when the browser wire contract changes.
+const BROWSER_CONTROL_VERSION = 1;
+// Reserved subprocess env names for the browser bridge. These are injected
+// LAST and must NEVER be overwritten by payload.credentials (plan Section 4
+// protected-env rule). Scrubbed from the inherited env as defense in depth.
+const RESERVED_BROWSER_ENV = ["MEL_BROWSER_URL", "MEL_BROWSER_TOKEN"];
 // PR4/P1-5: the assistant-session wire protocol version. Bumped whenever the
 // handshake contract changes (this rev adds hostInstanceId + configHash + a
 // versioned ready/hello). The server enforces a MINIMUM: a runner advertising a
@@ -65,6 +78,35 @@ export async function connect(opts) {
         reconnectionAttempts: Infinity,
     });
     let relay = null;
+    // ── Melaya Browser bridge state (plan Sections 3/4) ──────────────────
+    // The governed browser control bridge is started lazily on the first
+    // browser run. Grant public keys arrive over the socket (server push)
+    // and/or are pinned via env (operator-hardened). The replay store keeps
+    // single-use jti enforcement local to this runner process.
+    let browserBridge = null;
+    const browserReplayStore = createInMemoryReplayStore();
+    const browserPublicKeys = loadPinnedPublicKeysFromEnv();
+    // socketGeneration: incremented on every (re)connect. A grant is minted
+    // for a specific generation; a stale grant (issued to a previous socket)
+    // is refused (plan Section 4 binding rule).
+    let socketGeneration = 0;
+    const runnerDeviceId = getRunnerDeviceId();
+    const _ensureBrowserBridge = async () => {
+        if (browserBridge)
+            return browserBridge;
+        try {
+            browserBridge = await startBrowserBridge({
+                log: (m) => { if (opts.verbose)
+                    console.log(chalk.gray(`  [browser-bridge] ${m}`)); },
+                verbose: opts.verbose,
+            });
+        }
+        catch (e) {
+            console.log(chalk.yellow(`  ⚠ Browser bridge failed to start: ${e?.message || e}`));
+            browserBridge = null;
+        }
+        return browserBridge;
+    };
     // Luma browser bridge — only started after a successful Luma sign-in
     // (storage state file exists). Reset to a fresh bridge after each
     // luma:login-result so cookie rotation is picked up immediately.
@@ -141,12 +183,39 @@ export async function connect(opts) {
     };
     socket.on("connect", async () => {
         spinner.succeed(chalk.green("Connected to Melaya"));
+        // New socket lifetime → new generation. Grants minted for an earlier
+        // generation are refused (plan Section 4). Any browser runs from the
+        // previous connection are already torn down on the disconnect path.
+        socketGeneration += 1;
         // Report detected models
         socket.emit("runner:models", opts.models);
+        // Discover installed browser engines (Chrome/Edge/Brave/bundled
+        // Chromium) so the hello can advertise the browser_control capability
+        // with an accurate engine + CDP report (plan Section 4). Best-effort:
+        // discovery failure still advertises the base capability so attach
+        // (which needs no local engine) stays available.
+        let browserEngines = [];
+        try {
+            browserEngines = (await discoverEngines()).map((e) => ({ engine: e.engine, version: e.version, hasChannel: e.channel !== null }));
+        }
+        catch { /* non-fatal */ }
         // Advertise capabilities so the server only routes assistant chat sessions
         // to runners new enough to host them (older runners never get one → the
         // server falls back with a clear "update your runner" instead of hanging).
-        socket.emit("runner:hello", { capabilities: ["assistant_session"], package: "@melaya/runner", version: RUNNER_VERSION, assistantProtocol: ASSISTANT_PROTOCOL_VERSION });
+        socket.emit("runner:hello", {
+            capabilities: ["assistant_session", `browser_control_v${BROWSER_CONTROL_VERSION}`],
+            package: "@melaya/runner",
+            version: RUNNER_VERSION,
+            assistantProtocol: ASSISTANT_PROTOCOL_VERSION,
+            // Browser control capability report (plan Section 4).
+            browserControl: {
+                version: BROWSER_CONTROL_VERSION,
+                runnerDevice: runnerDeviceId,
+                socketGeneration,
+                cdp: true,
+                engines: browserEngines,
+            },
+        });
         // Start local event relay
         if (!relay) {
             relay = await startLocalRelay(socket, opts.verbose, opts.serverUrl);
@@ -175,11 +244,89 @@ export async function connect(opts) {
     });
     socket.on("disconnect", (reason) => {
         console.log(chalk.yellow(`\n  Disconnected: ${reason}`));
+        // Melaya Browser: a dropped socket invalidates every browser grant
+        // bound to this socket generation. Tear down ALL browser runs
+        // (cancels in-flight ops, releases leases, closes owned browsers);
+        // this is a terminal path per plan Section 7.
+        if (browserBridge) {
+            browserBridge.teardownAll(`socket_disconnect:${reason}`).catch(() => { });
+        }
         if (reason === "io server disconnect") {
             console.log(chalk.red("  Server closed the connection. Check your token."));
             process.exit(1);
         }
     });
+    // ── Melaya Browser: grant public key delivery (plan Section 0.6) ──────
+    // The server pushes its current EdDSA grant-verification public keys
+    // (kid → base64) so the runner can verify browserGrants. Merged with
+    // any env-pinned keys (env pins win — an operator can lock keys so a
+    // compromised socket cannot swap them). kid rotation is just a new
+    // entry in this map.
+    socket.on("runner:browserGrantKeys", (payload) => {
+        const keys = payload?.keys;
+        if (!keys || typeof keys !== "object")
+            return;
+        const pinned = loadPinnedPublicKeysFromEnv();
+        for (const [kid, b64] of Object.entries(keys)) {
+            if (typeof b64 !== "string" || !b64)
+                continue;
+            if (pinned[kid] !== undefined)
+                continue; // never override an env pin
+            browserPublicKeys[kid] = b64;
+        }
+        if (opts.verbose)
+            console.log(chalk.gray(`  [browser-bridge] grant keys updated (${Object.keys(browserPublicKeys).length} kid(s))`));
+    });
+    // ── Melaya Browser: live-mirror watch-lease (plan Section 10.f) ──────
+    // The server emits `browser:watch { sessionId, active }` when a viewer
+    // starts or stops watching a browser session's mirror. The runner wires
+    // the watch-lease to the bridge which owns the Playwright session.
+    // Frames are POSTed to the server's frame endpoint authenticated by
+    // the runner token (Bearer).
+    socket.on("browser:watch", (payload) => {
+        const sessionId = String(payload?.sessionId || "");
+        const active = Boolean(payload?.active);
+        if (!sessionId || !browserBridge)
+            return;
+        const framePostUrl = opts.serverUrl.replace(/^wss?:\/\//, (m) => (m === "wss://" ? "https://" : "http://")) + "/api/v1/browser/frame";
+        const runAuthHeader = `Bearer ${opts.token}`;
+        browserBridge.setWatchLease(sessionId, active, framePostUrl, runAuthHeader);
+        if (opts.verbose) {
+            console.log(chalk.gray(`  [browser-bridge] watch lease sessionId=${sessionId.slice(0, 16)} active=${active}`));
+        }
+    });
+    // ── BrowserControlPage interactive browser launch (plan BrowserControlPage) ──
+    // The server emits browser:launch when the user clicks "Launch controllable
+    // browser" in the BrowserControlPage UI. Unlike runner:run browser grants,
+    // this is an unprivileged direct-launch (no grant, no CDP intercept) — the
+    // server just wants us to open a browser process the user can observe.
+    // State transitions are relayed back via browser:session so the server can
+    // update agents.browser_sessions.
+    socket.on("browser:launch", async (payload) => {
+        const sessionId = String(payload?.sessionId || "");
+        const engine = String(payload?.engine || "chrome");
+        const profile = String(payload?.profile || "dedicated");
+        if (!sessionId)
+            return;
+        if (opts.verbose) {
+            console.log(chalk.gray(`  [browser-launch] sessionId=${sessionId.slice(0, 16)} engine=${engine} profile=${profile}`));
+        }
+        // Ensure the governed bridge is running before delegating.
+        const bridge = await _ensureBrowserBridge();
+        if (!bridge) {
+            console.log(chalk.yellow(`  ! browser:launch: bridge unavailable for sessionId=${sessionId.slice(0, 16)}`));
+            socket.emit("browser:session", { sessionId, state: "failed", engine });
+            return;
+        }
+        // Delegate to the governed bridge. State transitions (active/closed/failed)
+        // are relayed back through the existing browser:session socket event.
+        await bridge.launchInteractive(sessionId, engine, profile, (sid, state, eng) => {
+            socket.emit("browser:session", { sessionId: sid, state, engine: eng });
+            if (opts.verbose) {
+                console.log(chalk.gray(`  [browser-launch] browser:session sessionId=${sid.slice(0, 16)} state=${state}`));
+            }
+        });
+    });
     // ── Heartbeat ──────────────────────────────────────────────────────
     setInterval(() => {
         if (socket.connected)
@@ -195,6 +342,71 @@ export async function connect(opts) {
                 socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
                 return;
             }
+            // ── Melaya Browser grant verification + bridge start ──────────────
+            // (plan Section 4) A browser run carries a signed browserGrant. We
+            // VERIFY it BEFORE any Python spawns and reject on ANY failure. The
+            // raw grant stays in runner memory (used to register the bridge run);
+            // only the localhost URL + a per-run bearer token reach the child.
+            let browserToken = null;
+            if (payload.browserGrant) {
+                try {
+                    const grant = await verifyBrowserGrant(payload.browserGrant, {
+                        expectedAud: runnerDeviceId,
+                        publicKeysByKid: browserPublicKeys,
+                        replayStore: browserReplayStore,
+                    });
+                    // Bind assertions (plan Section 4): the grant must target THIS
+                    // runner device and THIS socket generation, and its run id must
+                    // match the dispatch. Fail closed on any mismatch.
+                    if (grant.runnerDevice !== runnerDeviceId) {
+                        throw new BrowserGrantError("claims_invalid", `grant runnerDevice '${grant.runnerDevice}' != this device`);
+                    }
+                    if (grant.socketGeneration !== socketGeneration) {
+                        throw new BrowserGrantError("claims_invalid", `grant socketGeneration ${grant.socketGeneration} != current ${socketGeneration}`);
+                    }
+                    if (grant.run !== payload.runId) {
+                        throw new BrowserGrantError("claims_invalid", `grant run '${grant.run}' != dispatched run '${payload.runId}'`);
+                    }
+                    const bridge = await _ensureBrowserBridge();
+                    if (!bridge)
+                        throw new BrowserGrantError("claims_invalid", "browser bridge unavailable");
+                    const spec = {
+                        runId: payload.runId,
+                        grant,
+                        mode: payload.browser?.mode === "attach" ? "attach" : "launch",
+                        engine: payload.browser?.engine,
+                        cdpWsEndpoint: payload.browser?.cdpWsEndpoint,
+                        space: payload.browser?.space ?? { kind: "ephemeral" },
+                        codeMode: payload.browser?.codeMode === true,
+                        headless: payload.browser?.headless === true,
+                    };
+                    const { token } = bridge.registerRun(spec);
+                    browserToken = token;
+                    console.log(chalk.hex("#7C6FF0")(`  🌐 Browser grant verified (mode=${spec.mode}, engine=${spec.engine || "chrome"}, ceiling=${grant.effectCeiling})`));
+                }
+                catch (e) {
+                    const code = e instanceof BrowserGrantError ? e.code : "grant_error";
+                    console.log(chalk.red(`  ✗ Browser grant rejected [${code}]: ${e?.message || e}`));
+                    socket.emit("runner:event", {
+                        run_id: payload.runId,
+                        event_type: "agent_message",
+                        project: payload.project,
+                        replyId: `browser-grant-${payload.runId}`,
+                        replyName: "Runner",
+                        replyRole: "system",
+                        msg: {
+                            id: `browser-grant-${payload.runId}`,
+                            name: "Runner",
+                            role: "system",
+                            content: [{ type: "text", text: `Browser grant rejected (${code}). This run cannot control a browser.` }],
+                            metadata: { browserGrantError: code },
+                            timestamp: new Date().toISOString(),
+                        },
+                    });
+                    socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
+                    return;
+                }
+            }
             // Ensure shared modules are cached
             await ensureSharedModules(opts.serverUrl, payload.sharedVersion, opts.token);
             // Ensure the dedicated venv at ~/.melaya-runner/venv/ has
@@ -377,6 +589,11 @@ export async function connect(opts) {
                 if (k.startsWith("MEL_MODEL_"))
                     delete inherited[k];
             }
+            // Reserved browser bridge env names are runner-owned and injected
+            // LAST below (plan Section 4). Scrub any operator-exported value so
+            // a stale/hostile MEL_BROWSER_* in the shell can't shadow ours.
+            for (const k of RESERVED_BROWSER_ENV)
+                delete inherited[k];
             // certifi CA-bundle path resolved at venv setup. Set as both
             // SSL_CERT_FILE (urllib / openssl) and REQUESTS_CA_BUNDLE (requests
             // library) so EVERY HTTPS-using tool — gmail_send, slack_post_text,
@@ -462,6 +679,14 @@ export async function connect(opts) {
                         MEL_MODEL_DISABLE_THINKING: preflight.profile.thinkingDefault === "off" ? "1" : "0",
                     }
                     : {}),
+                // ── Melaya Browser bridge vars, injected LAST (plan Section 4) ──
+                // These reserved names come AFTER payload.credentials so a
+                // credential can never overwrite them. Present only when this run
+                // passed browser-grant verification above; the raw grant is never
+                // placed in the child env (it stays in the bridge registration).
+                ...(browserToken && browserBridge
+                    ? { MEL_BROWSER_URL: browserBridge.url, MEL_BROWSER_TOKEN: browserToken }
+                    : {}),
             };
             // Surface the tier to the chat panel as a system message so the
             // operator sees WHY a small model is running with tighter caps.
@@ -518,6 +743,12 @@ export async function connect(opts) {
             });
             proc.on("exit", (code) => {
                 activeProcesses.delete(payload.runId);
+                // Melaya Browser terminal path (plan Section 7): the pipeline
+                // process exited, so revoke the grant, cancel in-flight browser
+                // ops, release leases, and close ONLY owned browsers. Idempotent.
+                if (browserBridge && browserBridge.hasRun(payload.runId)) {
+                    browserBridge.teardownRun(payload.runId, `run_exit:${code}`).catch(() => { });
+                }
                 const status = code === 0 ? "done" : "failed";
                 // On non-zero exit, relay the captured stderr tail to the FE
                 // as a system agent_message so the operator sees the actual
@@ -987,6 +1218,14 @@ export async function connect(opts) {
                 // (desktop drives the paired phone remotely). The host ORs this with the
                 // mobile-native surface check. Empty ⇒ not paired ⇒ no phone tools.
                 MEL_ASSISTANT_PHONE_READY: payload.phoneReady ? "1" : "",
+                // Melaya Browser (plan 0.4): the CAPABILITY flag. Presence means the
+                // runner advertises browser control and the browser toolkit should be
+                // included in the host's toolkit. The TARGET GRANT is NEVER in the boot
+                // env; it arrives per-turn on the turn frame and is purged at turn end.
+                // This is part of the config hash so the host reboots if capability
+                // presence changes (a runner that gains/loses browser control restarts
+                // the host automatically via config-drift detection above).
+                MEL_ASSISTANT_BROWSER_CAPABLE: "1",
                 // Connector tool sets the user enabled for this chat (comma-joined service
                 // ids). The host seeds a lazy toolkit from these so ANY connector's tools
                 // are reachable without exploding context.
@@ -1149,7 +1388,7 @@ export async function connect(opts) {
         }
         catch { /* best-effort — host stays as-is on a write failure */ }
     });
-    socket.on("runner:assistant_turn", (payload) => {
+    socket.on("runner:assistant_turn", async (payload) => {
         const s = activeAssistants.get(String(payload.sessionId || ""));
         if (!s) {
             socket.emit("runner:assistant_event", { sessionId: payload.sessionId, turnId: payload.turnId, kind: "error", message: "session_not_found" });
@@ -1171,8 +1410,56 @@ export async function connect(opts) {
         const hitlMode = (payload.hitlMode === "autonomous" || payload.hitlMode === "payments_only") ? payload.hitlMode : "safe";
         // static_context (persona / standing instructions) is forwarded per turn; the
         // host folds it into its system prompt before running (parity with cloud).
+        //
+        // Melaya Browser per-turn grant (plan 0.4): verify the grant ON THIS
+        // RUNNER before forwarding to the host. On failure, send an error event
+        // and abort the turn — never inject an unverified grant token into the
+        // host environment. On success, forward the raw compact JWS token plus
+        // the target ref so the host's _apply_browser_turn_grant can install
+        // them for the duration of the turn and purge them afterward.
+        let verifiedGrantToken = null;
+        let browserTargetRef = null;
+        if (payload.browserGrant) {
+            try {
+                const grant = await verifyBrowserGrant(payload.browserGrant, {
+                    expectedAud: runnerDeviceId,
+                    publicKeysByKid: browserPublicKeys,
+                    replayStore: browserReplayStore,
+                });
+                // Bind assertions: must target this device and socket generation.
+                if (grant.runnerDevice !== runnerDeviceId) {
+                    throw new BrowserGrantError("claims_invalid", `grant runnerDevice mismatch: ${grant.runnerDevice}`);
+                }
+                if (grant.socketGeneration !== socketGeneration) {
+                    throw new BrowserGrantError("claims_invalid", `grant socketGeneration ${grant.socketGeneration} != current ${socketGeneration}`);
+                }
+                // Accept the compact JWS token (the host's browser toolkit verifies
+                // it locally via MEL_BROWSER_TURN_GRANT at call time, fail closed).
+                verifiedGrantToken = payload.browserGrant;
+                browserTargetRef = String(payload.browserTargetRef || grant.target.ref || "");
+                if (opts.verbose) {
+                    console.log(chalk.gray(`  [browser-bridge] turn grant ok (session=${payload.sessionId.slice(0, 10)} ceiling=${grant.effectCeiling})`));
+                }
+            }
+            catch (e) {
+                const code = e instanceof BrowserGrantError ? e.code : "grant_error";
+                console.log(chalk.yellow(`  [browser-bridge] turn grant rejected [${code}]: ${e?.message || e}`));
+                socket.emit("runner:assistant_event", { sessionId: payload.sessionId, turnId: payload.turnId, kind: "error", message: `browser turn grant rejected (${code})` });
+                return;
+            }
+        }
         try {
-            s.proc.stdin?.write(JSON.stringify({ turnId: payload.turnId, message: payload.message, hitl_mode: hitlMode, static_context: typeof payload.staticContext === "string" ? payload.staticContext : "" }) + "\n");
+            s.proc.stdin?.write(JSON.stringify({
+                turnId: payload.turnId,
+                message: payload.message,
+                hitl_mode: hitlMode,
+                static_context: typeof payload.staticContext === "string" ? payload.staticContext : "",
+                // Per-turn browser grant: forwarded to the host as the raw compact
+                // JWS string so the Python browser toolkit can verify it again
+                // (defence-in-depth) and install MEL_BROWSER_TURN_GRANT in the
+                // host env for THIS turn only. Absent when no grant was provided.
+                ...(verifiedGrantToken ? { browser_grant: verifiedGrantToken, browser_target_ref: browserTargetRef ?? "" } : {}),
+            }) + "\n");
         }
         catch (e) {
             socket.emit("runner:assistant_event", { sessionId: payload.sessionId, turnId: payload.turnId, kind: "error", message: `turn write failed: ${e?.message || e}` });
@@ -1727,6 +2014,12 @@ export async function connect(opts) {
             activeProcesses.delete(data.runId);
             console.log(chalk.yellow(`  ■ Killed run ${data.runId.slice(0, 10)}...`));
         }
+        // Melaya Browser terminal path (plan Section 7): an explicit kill
+        // revokes the grant and closes owned browsers even if the Python proc
+        // was already gone. Idempotent.
+        if (browserBridge && browserBridge.hasRun(data.runId)) {
+            browserBridge.teardownRun(data.runId, "runner_kill").catch(() => { });
+        }
     });
     // ── Pause / resume crew strategy (local-runner only) ───────────────
     // For local-runner crew strategies, the Redis-flag pause path used by
@@ -1780,6 +2073,12 @@ export async function connect(opts) {
             catch { /* noop */ }
         }
         activeAssistants.clear();
+        // Melaya Browser terminal path (plan Section 7): shut the bridge down,
+        // which cancels in-flight ops, releases every lease, and closes ONLY
+        // owned browsers (attached user browsers are merely disconnected).
+        if (browserBridge) {
+            browserBridge.shutdown().catch(() => { });
+        }
         relay?.close();
         // Best-effort Chromium teardown. The bridge's shutdown is async but
         // we can't await inside a SIGINT handler — fire and forget; the

package/dist/sessionManager.d.ts

@@ -0,0 +1,108 @@
+type PWBrowser = import("playwright").Browser;
+type PWBrowserContext = import("playwright").BrowserContext;
+type PWPage = import("playwright").Page;
+export declare function getRunnerDeviceId(): string;
+export type SessionOwnership = "owned" | "attached";
+export type SessionState = "connecting" | "ready" | "running" | "paused" | "crashed" | "closed";
+export type SpaceKind = "ephemeral" | "persistent";
+export interface SpaceSpec {
+    kind: SpaceKind;
+    /** Stable opaque id, required for persistent Spaces. */
+    id?: string;
+}
+/** A single @eN binding. Refs are valid only while EVERY generation
+ *  component still matches the live lease (plan Section 8). */
+export interface BoundRef {
+    ref: string;
+    targetRef: string;
+    frameKey: string;
+    backendNodeId: number;
+    snapshotGeneration: number;
+    documentGeneration: number;
+    role: string;
+    name: string;
+}
+export interface TargetLease {
+    /** Opaque target ref (matches grant.target.ref for the leased target). */
+    ref: string;
+    page: PWPage;
+    snapshotGeneration: number;
+    documentGeneration: number;
+    refs: Map<string, BoundRef>;
+    lastActivity: number;
+    /** Serialize writes per target (plan Section 7 concurrency rule). */
+    opChain: Promise<unknown>;
+}
+export interface BrowserSessionRecord {
+    id: string;
+    runId: string;
+    ownership: SessionOwnership;
+    engine: string;
+    state: SessionState;
+    space: SpaceSpec;
+    browser: PWBrowser | null;
+    /** launchPersistentContext returns a context without a Browser handle;
+     *  owned sessions therefore key teardown on context, not browser. */
+    context: PWBrowserContext | null;
+    targets: Map<string, TargetLease>;
+    createdAt: number;
+    lastActivity: number;
+    idleTtlMs: number;
+    maxLifetimeMs: number;
+    /** Set for owned EPHEMERAL sessions: deleted at teardown. */
+    ephemeralUserDataDir: string | null;
+    cancelled: boolean;
+}
+export declare class SessionError extends Error {
+    readonly code: "session_not_found" | "session_crashed" | "session_closed" | "target_not_found" | "stale_ref" | "lease_conflict";
+    constructor(code: SessionError["code"], message: string);
+}
+export declare function spaceUserDataDir(space: SpaceSpec, runId: string): {
+    dir: string;
+    ephemeral: boolean;
+};
+export declare class SessionManager {
+    private sessions;
+    private sweeper;
+    private log;
+    constructor(opts?: {
+        log?: (m: string) => void;
+    });
+    /** Create the session record; the caller (bridge) supplies the live
+     *  Playwright handles once launch/attach succeeds. */
+    createSession(opts: {
+        runId: string;
+        ownership: SessionOwnership;
+        engine: string;
+        space: SpaceSpec;
+        idleTtlMs?: number;
+        maxLifetimeMs?: number;
+    }): BrowserSessionRecord;
+    attachHandles(rec: BrowserSessionRecord, handles: {
+        browser?: PWBrowser | null;
+        context: PWBrowserContext;
+        ephemeralUserDataDir?: string | null;
+    }): void;
+    getSession(runId: string): BrowserSessionRecord;
+    peekSession(runId: string): BrowserSessionRecord | undefined;
+    touch(rec: BrowserSessionRecord): void;
+    leaseTarget(rec: BrowserSessionRecord, ref: string, page: PWPage): TargetLease;
+    getLease(rec: BrowserSessionRecord, ref: string): TargetLease;
+    /** New snapshot -> new generation; every previously issued @eN ref
+     *  becomes stale by construction. */
+    beginSnapshot(lease: TargetLease): number;
+    bindRef(lease: TargetLease, binding: BoundRef): void;
+    /** Resolve an @eN ref, failing closed on ANY generation mismatch. */
+    resolveRef(lease: TargetLease, ref: string): BoundRef;
+    /** Serialize an operation on a target (one write at a time per lease). */
+    runOnTarget<T>(lease: TargetLease, op: () => Promise<T>): Promise<T>;
+    /** Tear down a run's session. Closes ONLY owned contexts/browsers; an
+     *  attached (user-owned) browser is disconnected from, never closed.
+     *  Idempotent; safe on every terminal path. */
+    teardownRun(runId: string, reason: string): Promise<void>;
+    teardownAll(reason: string): Promise<void>;
+    /** TTL sweep: idle timeout + hard max lifetime. */
+    private sweep;
+    dispose(): void;
+}
+export {};