@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/runtime/local-cloak/provider.test.js

@@ -0,0 +1,244 @@
+import { describe, expect, it, vi } from 'vitest';
+import { LocalCloakRuntimeProvider } from './provider.js';
+function fakePage(url) {
+    let closed = false;
+    let viewportSize = { width: 1280, height: 720 };
+    return {
+        isClosed: vi.fn(() => closed),
+        goto: vi.fn(async (nextUrl) => {
+            url = nextUrl;
+        }),
+        evaluate: vi.fn().mockResolvedValue({ ok: true }),
+        frames: vi.fn(() => []),
+        title: vi.fn().mockResolvedValue('Example'),
+        url: vi.fn(() => url),
+        screenshot: vi.fn().mockResolvedValue(Buffer.from('image')),
+        viewportSize: vi.fn(() => viewportSize),
+        setViewportSize: vi.fn(async (size) => {
+            viewportSize = size;
+        }),
+        locator: vi.fn(),
+        bringToFront: vi.fn().mockResolvedValue(undefined),
+        close: vi.fn().mockImplementation(async () => {
+            closed = true;
+        }),
+    };
+}
+function makeProviderWithFakePage() {
+    const pages = [fakePage('https://example.com/')];
+    const context = {
+        pages: vi.fn(() => pages.filter((page) => !page.isClosed())),
+        newPage: vi.fn(async () => {
+            const page = fakePage('about:blank');
+            pages.push(page);
+            return page;
+        }),
+        cookies: vi.fn().mockResolvedValue([{ name: 'sid', value: '1', domain: 'example.com', path: '/' }]),
+        close: vi.fn().mockResolvedValue(undefined),
+    };
+    const provider = new LocalCloakRuntimeProvider({
+        baseDir: '/tmp/webcmd-test',
+        launchPersistentContext: vi.fn().mockResolvedValue(context),
+    });
+    return { provider, page: pages[0], pages, context };
+}
+describe('LocalCloakRuntimeProvider', () => {
+    it('reports a runtime-named connected status before any profile launches', async () => {
+        const provider = new LocalCloakRuntimeProvider({ baseDir: '/tmp/webcmd-test' });
+        await expect(provider.status()).resolves.toMatchObject({
+            runtimeConnected: true,
+            runtimeName: 'cloak',
+            profiles: [],
+            pending: 0,
+        });
+    });
+    it('navigates and returns page identity', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const result = await provider.dispatch({
+            id: 'cmd-1',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+            profileId: 'default',
+        });
+        expect(result).toMatchObject({ id: 'cmd-1', ok: true, page: expect.any(String) });
+        expect(page.goto).toHaveBeenCalledWith('https://example.com/', expect.objectContaining({ waitUntil: 'load' }));
+    });
+    it('evaluates JavaScript in the resolved page', async () => {
+        const { provider } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', page: nav.page, code: '1 + 1', profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'exec', ok: true, data: { ok: true }, page: nav.page });
+    });
+    it('evaluates JavaScript in the requested iframe', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const frame = { evaluate: vi.fn().mockResolvedValue('inside frame'), url: vi.fn(() => 'https://frame.example/'), name: vi.fn(() => 'frame') };
+        page.frames.mockReturnValue([page, frame]);
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', page: nav.page, frameIndex: 0, code: 'document.body.textContent', profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'exec', ok: true, data: 'inside frame', page: nav.page });
+        expect(frame.evaluate).toHaveBeenCalledWith('document.body.textContent');
+        expect(page.evaluate).not.toHaveBeenCalledWith('document.body.textContent');
+    });
+    it('returns a typed error when the requested iframe is out of range', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        page.frames.mockReturnValue([page]);
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', page: nav.page, frameIndex: 0, code: '1 + 1', profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'exec',
+            ok: false,
+            errorCode: 'frame_not_found',
+            error: 'Frame not found: 0',
+            page: nav.page,
+        });
+    });
+    it('returns a typed stale page error instead of falling back when command.page is unknown', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', page: 'page-stale', code: '1 + 1', profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'exec',
+            ok: false,
+            errorCode: 'stale_page_identity',
+            error: 'Page not found: page-stale — stale page identity',
+        });
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+    it('returns typed validation errors for missing navigate url and exec code', async () => {
+        const { provider } = makeProviderWithFakePage();
+        await expect(provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'nav', ok: false, errorCode: 'invalid_request', error: 'Missing url' });
+        await expect(provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'exec', ok: false, errorCode: 'invalid_request', error: 'Missing code' });
+    });
+    it('returns filtered cookies from the resolved context', async () => {
+        const { provider } = makeProviderWithFakePage();
+        await expect(provider.dispatch({ id: 'cookies', action: 'cookies', session: 'work', surface: 'browser', domain: 'example.com', profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'cookies', ok: true, data: [{ name: 'sid', value: '1', domain: 'example.com', path: '/' }] });
+    });
+    it('captures screenshots as base64 and preserves page identity', async () => {
+        const { provider } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', fullPage: true, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'shot', ok: true, data: Buffer.from('image').toString('base64'), page: nav.page });
+    });
+    it('applies screenshot width overrides with the current viewport height', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', width: 900, profileId: 'default' });
+        expect(page.setViewportSize).toHaveBeenCalledWith({ width: 900, height: 720 });
+        expect(page.screenshot).toHaveBeenCalledWith(expect.objectContaining({ fullPage: undefined }));
+    });
+    it('applies screenshot height overrides with the current viewport width', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', height: 480, profileId: 'default' });
+        expect(page.setViewportSize).toHaveBeenCalledWith({ width: 1280, height: 480 });
+    });
+    it('restores the previous viewport after screenshot overrides', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', width: 900, height: 480, profileId: 'default' });
+        expect(page.setViewportSize).toHaveBeenNthCalledWith(1, { width: 900, height: 480 });
+        expect(page.setViewportSize).toHaveBeenNthCalledWith(2, { width: 1280, height: 720 });
+        expect(page.screenshot).toHaveBeenCalledTimes(1);
+    });
+    it('ignores screenshot height overrides for full-page captures while applying width', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await provider.dispatch({ id: 'shot', action: 'screenshot', session: 'work', surface: 'browser', page: nav.page, format: 'png', fullPage: true, width: 700, height: 480, profileId: 'default' });
+        expect(page.setViewportSize).toHaveBeenCalledWith({ width: 700, height: 720 });
+        expect(page.screenshot).toHaveBeenCalledWith(expect.objectContaining({ fullPage: true }));
+    });
+    it('requires an explicit Cloak tab target for bind', async () => {
+        const { provider } = makeProviderWithFakePage();
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'work', surface: 'browser', profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'bind',
+            ok: false,
+            errorCode: 'invalid_request',
+            error: 'Bind requires --page or --index for a Cloak runtime tab',
+        });
+    });
+    it('binds a browser session to an existing Cloak tab by page id', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'manual', surface: 'browser', url: 'https://signed-in.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'work', surface: 'browser', page: created.page, profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'bind',
+            ok: true,
+            page: created.page,
+            data: { bound: true, session: 'work', page: created.page, url: 'https://signed-in.example/' },
+        });
+        await provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', code: 'window.__loggedIn', profileId: 'default' });
+        expect(pages[1].evaluate).toHaveBeenCalledWith('window.__loggedIn');
+        expect(pages[0].evaluate).not.toHaveBeenCalledWith('window.__loggedIn');
+    });
+    it('binds a browser session to an existing Cloak tab by index', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        await provider.dispatch({ id: 'nav', action: 'navigate', session: 'first', surface: 'browser', url: 'https://first.example/', profileId: 'default' });
+        await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'manual', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'work', surface: 'browser', index: 1, profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'bind',
+            ok: true,
+            data: { bound: true, session: 'work', url: 'https://second.example/' },
+        });
+        await provider.dispatch({ id: 'exec', action: 'exec', session: 'work', surface: 'browser', code: 'document.readyState', profileId: 'default' });
+        expect(pages[1].evaluate).toHaveBeenCalledWith('document.readyState');
+    });
+    it('returns a typed bind error when the requested Cloak tab is missing', async () => {
+        const { provider } = makeProviderWithFakePage();
+        await provider.dispatch({ id: 'nav', action: 'navigate', session: 'first', surface: 'browser', url: 'https://first.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'bind', action: 'bind', session: 'work', surface: 'browser', page: 'missing-page', profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'bind',
+            ok: false,
+            errorCode: 'bound_tab_not_found',
+            error: 'Cloak tab not found for bind target',
+        });
+    });
+    it('sets file input through the first matching locator', async () => {
+        const { provider, page } = makeProviderWithFakePage();
+        const setInputFiles = vi.fn().mockResolvedValue(undefined);
+        page.locator = vi.fn().mockReturnValue({ first: () => ({ setInputFiles }) });
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'upload', action: 'set-file-input', session: 'work', surface: 'browser', page: nav.page, files: ['/tmp/a.txt'], profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'upload', ok: true, data: { count: 1 } });
+        expect(setInputFiles).toHaveBeenCalledWith(['/tmp/a.txt']);
+    });
+    it('lists current tabs with page identities', async () => {
+        const { provider } = makeProviderWithFakePage();
+        const nav = await provider.dispatch({ id: 'nav', action: 'navigate', session: 'work', surface: 'browser', url: 'https://example.com/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'tabs', action: 'tabs', op: 'list', session: 'work', surface: 'browser', profileId: 'default' }))
+            .resolves.toMatchObject({
+            id: 'tabs',
+            ok: true,
+            data: [expect.objectContaining({ id: nav.page, page: nav.page, index: 0, url: 'https://example.com/' })],
+        });
+    });
+    it('creates, selects, and closes tabs by command op', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const created = await provider.dispatch({ id: 'new', action: 'tabs', op: 'new', session: 'work', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        expect(created).toMatchObject({ id: 'new', ok: true, page: expect.any(String), data: { url: 'https://second.example/' } });
+        expect(pages[1].goto).toHaveBeenCalledWith('https://second.example/', expect.objectContaining({ waitUntil: 'load' }));
+        await expect(provider.dispatch({ id: 'select', action: 'tabs', op: 'select', session: 'work', surface: 'browser', page: created.page, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'select', ok: true, page: created.page, data: { selected: true } });
+        expect(pages[1].bringToFront).toHaveBeenCalled();
+        await expect(provider.dispatch({ id: 'close', action: 'tabs', op: 'close', session: 'work', surface: 'browser', page: created.page, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'close', ok: true, data: { closed: created.page } });
+        expect(pages[1].close).toHaveBeenCalled();
+    });
+    it('closes a window by page identity when command.page is provided', async () => {
+        const { provider, pages } = makeProviderWithFakePage();
+        const first = await provider.dispatch({ id: 'first', action: 'navigate', session: 'first', surface: 'browser', url: 'https://first.example/', profileId: 'default' });
+        const second = await provider.dispatch({ id: 'second', action: 'tabs', op: 'new', session: 'second', surface: 'browser', url: 'https://second.example/', profileId: 'default' });
+        await expect(provider.dispatch({ id: 'close-window', action: 'close-window', session: 'first', surface: 'browser', page: second.page, profileId: 'default' }))
+            .resolves.toMatchObject({ id: 'close-window', ok: true, data: { closed: true, page: second.page } });
+        expect(pages[0].isClosed()).toBe(false);
+        expect(pages[1].close).toHaveBeenCalled();
+        expect(first.page).not.toBe(second.page);
+    });
+});

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -0,0 +1,77 @@
+import type { BrowserContext, Page as PlaywrightPage } from 'playwright-core';
+import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
+import type { BrowserSurface, SiteSessionMode } from '../../protocol.js';
+import { CloakNetworkCapture } from './network.js';
+export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
+export interface SessionKeyInput {
+    profileId?: string;
+    session?: string;
+    surface?: BrowserSurface;
+    siteSession?: SiteSessionMode;
+    idleTimeout?: number;
+}
+export interface CloakPageLease {
+    profileId: string;
+    leaseKey: string;
+    context: BrowserContext;
+    page: PlaywrightPage;
+    pageId: string;
+}
+export interface CloakTabInfo {
+    id: string;
+    page: string;
+    index: number;
+    title: string;
+    url: string;
+    profileId: string;
+    session: string;
+    surface: BrowserSurface;
+    selected: boolean;
+}
+export interface CloakSessionManagerOptions {
+    baseDir?: string;
+    launchPersistentContext?: LaunchPersistentContext;
+}
+export declare function resolveLeaseKey(input: SessionKeyInput): string;
+export declare class CloakSessionManager {
+    private readonly opts;
+    readonly networkCapture: CloakNetworkCapture;
+    private readonly launchPersistentContext;
+    private readonly profiles;
+    constructor(opts?: CloakSessionManagerOptions);
+    profileStatuses(): {
+        contextId: string;
+        runtimeConnected: boolean;
+        runtimeVersion: string | undefined;
+        pending: number;
+        lastSeenAt: number;
+    }[];
+    getPage(input: SessionKeyInput): Promise<CloakPageLease>;
+    findPageById(pageId: string, opts?: Pick<SessionKeyInput, 'idleTimeout'>): CloakPageLease | null;
+    pageIdFor(page: PlaywrightPage): string | undefined;
+    registerPage(input: SessionKeyInput, page: PlaywrightPage): string;
+    listPages(input: Pick<SessionKeyInput, 'profileId'>): Promise<CloakTabInfo[]>;
+    newPage(input: SessionKeyInput & {
+        url?: string;
+    }): Promise<CloakPageLease>;
+    selectPage(input: Pick<SessionKeyInput, 'profileId'> & {
+        pageId?: string;
+        index?: number;
+    }): Promise<CloakPageLease | null>;
+    bindPage(input: SessionKeyInput & {
+        pageId?: string;
+        index?: number;
+    }): Promise<CloakPageLease | null>;
+    closePage(input: Pick<SessionKeyInput, 'profileId'> & {
+        pageId?: string;
+        index?: number;
+    }): Promise<string | null>;
+    release(input: SessionKeyInput): Promise<void>;
+    shutdown(): Promise<void>;
+    private getProfileRuntime;
+    private openEntries;
+    private findEntryByPageId;
+    private refreshIdleTimer;
+    private expireLease;
+    private clearIdleTimer;
+}

package/dist/src/browser/runtime/local-cloak/session-manager.js

@@ -0,0 +1,280 @@
+import fs from 'node:fs';
+import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
+import { normalizeProfileId, resolveCloakProfileDir } from './profiles.js';
+import { CloakNetworkCapture } from './network.js';
+let pageCounter = 0;
+export function resolveLeaseKey(input) {
+    const surface = input.surface === 'adapter' ? 'adapter' : 'browser';
+    const session = input.session?.trim();
+    if (!session)
+        throw new Error('Browser session is required.');
+    return `${surface}\u0000${encodeURIComponent(session)}`;
+}
+function pageIsClosed(page) {
+    return page.isClosed?.() === true;
+}
+export class CloakSessionManager {
+    opts;
+    networkCapture = new CloakNetworkCapture();
+    launchPersistentContext;
+    profiles = new Map();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.launchPersistentContext = opts.launchPersistentContext ?? cloakLaunchPersistentContext;
+    }
+    profileStatuses() {
+        return [...this.profiles.entries()].map(([contextId, runtime]) => ({
+            contextId,
+            runtimeConnected: true,
+            runtimeVersion: runtime.runtimeVersion,
+            pending: 0,
+            lastSeenAt: runtime.lastSeenAt,
+        }));
+    }
+    async getPage(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const session = requireSession(input.session);
+        const surface = normalizeSurface(input.surface);
+        const leaseKey = resolveLeaseKey(input);
+        const runtime = await this.getProfileRuntime(profileId);
+        const existing = runtime.pages.get(leaseKey);
+        if (existing && !pageIsClosed(existing.page)) {
+            runtime.lastSeenAt = Date.now();
+            existing.idleTimeout = input.idleTimeout;
+            this.refreshIdleTimer(runtime, leaseKey, existing);
+            return { profileId, leaseKey, context: runtime.context, page: existing.page, pageId: existing.pageId };
+        }
+        const existingPages = runtime.context.pages();
+        const page = existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
+        const pageId = nextPageId();
+        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
+        runtime.pages.set(leaseKey, entry);
+        this.refreshIdleTimer(runtime, leaseKey, entry);
+        runtime.selectedPageId = pageId;
+        runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey, context: runtime.context, page, pageId };
+    }
+    findPageById(pageId, opts = {}) {
+        for (const [profileId, runtime] of this.profiles.entries()) {
+            for (const [leaseKey, entry] of runtime.pages.entries()) {
+                if (entry.pageId === pageId && !pageIsClosed(entry.page)) {
+                    entry.idleTimeout = opts.idleTimeout;
+                    this.refreshIdleTimer(runtime, leaseKey, entry);
+                    return { profileId, leaseKey, context: runtime.context, page: entry.page, pageId: entry.pageId };
+                }
+            }
+        }
+        return null;
+    }
+    pageIdFor(page) {
+        for (const runtime of this.profiles.values()) {
+            for (const entry of runtime.pages.values()) {
+                if (entry.page === page)
+                    return entry.pageId;
+            }
+        }
+        return undefined;
+    }
+    registerPage(input, page) {
+        const profileId = normalizeProfileId(input.profileId);
+        const session = requireSession(input.session);
+        const surface = normalizeSurface(input.surface);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            throw new Error(`Profile ${profileId} is not running`);
+        const pageId = nextPageId();
+        const leaseKey = `${resolveLeaseKey(input)}\u0000${pageId}`;
+        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
+        runtime.pages.set(leaseKey, entry);
+        this.refreshIdleTimer(runtime, leaseKey, entry);
+        runtime.selectedPageId = pageId;
+        runtime.lastSeenAt = Date.now();
+        return pageId;
+    }
+    async listPages(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            return [];
+        const entries = this.openEntries(runtime);
+        return Promise.all(entries.map(async ([, entry], index) => ({
+            id: entry.pageId,
+            page: entry.pageId,
+            index,
+            title: await entry.page.title().catch(() => ''),
+            url: entry.page.url(),
+            profileId,
+            session: entry.session,
+            surface: entry.surface,
+            selected: runtime.selectedPageId === entry.pageId,
+        })));
+    }
+    async newPage(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const session = requireSession(input.session);
+        const surface = normalizeSurface(input.surface);
+        const runtime = await this.getProfileRuntime(profileId);
+        const page = await runtime.context.newPage();
+        if (input.url) {
+            await page.goto(input.url, { waitUntil: 'load' });
+        }
+        const pageId = nextPageId();
+        const leaseKey = `${resolveLeaseKey(input)}\u0000${pageId}`;
+        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
+        runtime.pages.set(leaseKey, entry);
+        this.refreshIdleTimer(runtime, leaseKey, entry);
+        runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey, context: runtime.context, page, pageId };
+    }
+    async selectPage(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            return null;
+        const match = input.pageId ? this.findEntryByPageId(runtime, input.pageId) : this.openEntries(runtime)[input.index ?? -1];
+        if (!match)
+            return null;
+        const [leaseKey, entry] = match;
+        await entry.page.bringToFront?.().catch(() => { });
+        runtime.selectedPageId = entry.pageId;
+        runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey, context: runtime.context, page: entry.page, pageId: entry.pageId };
+    }
+    async bindPage(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const session = requireSession(input.session);
+        const surface = normalizeSurface(input.surface);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            return null;
+        const match = input.pageId ? this.findEntryByPageId(runtime, input.pageId) : this.openEntries(runtime)[input.index ?? -1];
+        if (!match)
+            return null;
+        const [sourceKey, entry] = match;
+        const canonicalKey = resolveLeaseKey({ profileId, session, surface });
+        const currentCanonical = runtime.pages.get(canonicalKey);
+        if (currentCanonical && currentCanonical !== entry && !pageIsClosed(currentCanonical.page)) {
+            const preservedKey = `${canonicalKey}\u0000${currentCanonical.pageId}`;
+            runtime.pages.delete(canonicalKey);
+            runtime.pages.set(preservedKey, currentCanonical);
+            this.refreshIdleTimer(runtime, preservedKey, currentCanonical);
+        }
+        if (sourceKey !== canonicalKey)
+            runtime.pages.delete(sourceKey);
+        entry.session = session;
+        entry.surface = surface;
+        entry.siteSession = input.siteSession;
+        entry.idleTimeout = input.idleTimeout;
+        runtime.pages.set(canonicalKey, entry);
+        await entry.page.bringToFront?.().catch(() => { });
+        this.refreshIdleTimer(runtime, canonicalKey, entry);
+        runtime.selectedPageId = entry.pageId;
+        runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey: canonicalKey, context: runtime.context, page: entry.page, pageId: entry.pageId };
+    }
+    async closePage(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            return null;
+        const match = input.pageId ? this.findEntryByPageId(runtime, input.pageId) : this.openEntries(runtime)[input.index ?? -1];
+        if (!match)
+            return null;
+        const [leaseKey, entry] = match;
+        runtime.pages.delete(leaseKey);
+        this.clearIdleTimer(entry);
+        if (runtime.selectedPageId === entry.pageId)
+            runtime.selectedPageId = undefined;
+        if (!pageIsClosed(entry.page))
+            await entry.page.close().catch(() => { });
+        runtime.lastSeenAt = Date.now();
+        return entry.pageId;
+    }
+    async release(input) {
+        const profileId = normalizeProfileId(input.profileId);
+        const runtime = this.profiles.get(profileId);
+        if (!runtime)
+            return;
+        const leaseKey = resolveLeaseKey(input);
+        const exactEntry = runtime.pages.get(leaseKey);
+        const entries = exactEntry
+            ? [[leaseKey, exactEntry]]
+            : this.openEntries(runtime).filter(([, entry]) => entry.session === requireSession(input.session) && entry.surface === normalizeSurface(input.surface));
+        for (const [key, entry] of entries) {
+            runtime.pages.delete(key);
+            this.clearIdleTimer(entry);
+            if (runtime.selectedPageId === entry.pageId)
+                runtime.selectedPageId = undefined;
+            if (entry.siteSession !== 'persistent' && !pageIsClosed(entry.page)) {
+                await entry.page.close().catch(() => { });
+            }
+        }
+    }
+    async shutdown() {
+        for (const runtime of this.profiles.values()) {
+            for (const entry of runtime.pages.values())
+                this.clearIdleTimer(entry);
+            await runtime.context.close().catch(() => { });
+        }
+        this.profiles.clear();
+    }
+    async getProfileRuntime(profileId) {
+        const existing = this.profiles.get(profileId);
+        if (existing)
+            return existing;
+        const userDataDir = resolveCloakProfileDir(profileId, { baseDir: this.opts.baseDir });
+        fs.mkdirSync(userDataDir, { recursive: true });
+        const context = await this.launchPersistentContext({
+            userDataDir,
+            headless: false,
+            humanize: true,
+        });
+        const runtime = { context, pages: new Map(), lastSeenAt: Date.now() };
+        this.profiles.set(profileId, runtime);
+        return runtime;
+    }
+    openEntries(runtime) {
+        return [...runtime.pages.entries()].filter(([, entry]) => !pageIsClosed(entry.page));
+    }
+    findEntryByPageId(runtime, pageId) {
+        return this.openEntries(runtime).find(([, entry]) => entry.pageId === pageId) ?? null;
+    }
+    refreshIdleTimer(runtime, leaseKey, entry) {
+        this.clearIdleTimer(entry);
+        if (!entry.idleTimeout || entry.idleTimeout <= 0 || entry.siteSession === 'persistent')
+            return;
+        entry.idleTimer = setTimeout(() => {
+            void this.expireLease(runtime, leaseKey, entry);
+        }, entry.idleTimeout);
+        entry.idleTimer.unref?.();
+    }
+    async expireLease(runtime, leaseKey, entry) {
+        if (runtime.pages.get(leaseKey) !== entry)
+            return;
+        runtime.pages.delete(leaseKey);
+        this.clearIdleTimer(entry);
+        if (runtime.selectedPageId === entry.pageId)
+            runtime.selectedPageId = undefined;
+        runtime.lastSeenAt = Date.now();
+        if (entry.siteSession !== 'persistent' && !pageIsClosed(entry.page)) {
+            await entry.page.close().catch(() => { });
+        }
+    }
+    clearIdleTimer(entry) {
+        if (entry.idleTimer)
+            clearTimeout(entry.idleTimer);
+        entry.idleTimer = undefined;
+    }
+}
+function nextPageId() {
+    return `page-${Date.now()}-${++pageCounter}`;
+}
+function normalizeSurface(surface) {
+    return surface === 'adapter' ? 'adapter' : 'browser';
+}
+function requireSession(session) {
+    const normalized = session?.trim();
+    if (!normalized)
+        throw new Error('Browser session is required.');
+    return normalized;
+}

package/dist/src/browser/runtime/local-cloak/session-manager.test.d.ts

@@ -0,0 +1 @@
+export {};