@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/runtime/local-cloak/actions.js

@@ -0,0 +1,240 @@
+import { waitForDownload } from './downloads.js';
+class CloakActionError extends Error {
+    errorCode;
+    page;
+    errorHint;
+    constructor(errorCode, error, page, errorHint) {
+        super(error);
+        this.errorCode = errorCode;
+        this.page = page;
+        this.errorHint = errorHint;
+    }
+}
+function commandProfileId(command) {
+    return command.profileId ?? command.contextId ?? 'default';
+}
+function invalidRequest(command, error) {
+    return { id: command.id, ok: false, errorCode: 'invalid_request', error };
+}
+async function resolveLease(manager, command) {
+    if (command.page) {
+        const existing = manager.findPageById(command.page, { idleTimeout: command.idleTimeout });
+        if (existing)
+            return existing;
+        throw new CloakActionError('stale_page_identity', `Page not found: ${command.page} — stale page identity`);
+    }
+    return manager.getPage({
+        profileId: commandProfileId(command),
+        session: command.session,
+        surface: command.surface,
+        siteSession: command.siteSession,
+        idleTimeout: command.idleTimeout,
+    });
+}
+function execTarget(page, frameIndex, pageId) {
+    if (frameIndex == null)
+        return page;
+    const frame = page.frames().slice(1)[frameIndex];
+    if (!frame)
+        throw new CloakActionError('frame_not_found', `Frame not found: ${frameIndex}`, pageId);
+    return frame;
+}
+async function applyScreenshotViewport(page, command) {
+    const width = Number.isFinite(command.width) && command.width > 0 ? Math.ceil(command.width) : undefined;
+    const height = !command.fullPage && Number.isFinite(command.height) && command.height > 0 ? Math.ceil(command.height) : undefined;
+    if (width === undefined && height === undefined)
+        return null;
+    const current = page.viewportSize();
+    await page.setViewportSize({
+        width: width ?? current?.width ?? 1280,
+        height: height ?? current?.height ?? 720,
+    });
+    return current;
+}
+export async function dispatchCloakAction(manager, command) {
+    try {
+        switch (command.action) {
+            case 'navigate': {
+                if (!command.url)
+                    return invalidRequest(command, 'Missing url');
+                const lease = await resolveLease(manager, command);
+                await lease.page.goto(command.url, { waitUntil: 'load' });
+                return { id: command.id, ok: true, data: { title: await lease.page.title(), url: lease.page.url(), timedOut: false }, page: lease.pageId };
+            }
+            case 'exec': {
+                if (!command.code)
+                    return invalidRequest(command, 'Missing code');
+                const lease = await resolveLease(manager, command);
+                const target = execTarget(lease.page, command.frameIndex, lease.pageId);
+                const data = await target.evaluate(command.code);
+                return { id: command.id, ok: true, data, page: lease.pageId };
+            }
+            case 'cookies': {
+                const lease = await resolveLease(manager, command);
+                const cookies = await lease.context.cookies(command.url ? [command.url] : undefined);
+                const data = command.domain ? cookies.filter((cookie) => cookie.domain.includes(command.domain)) : cookies;
+                return { id: command.id, ok: true, data };
+            }
+            case 'screenshot': {
+                const lease = await resolveLease(manager, command);
+                const previousViewport = await applyScreenshotViewport(lease.page, command);
+                try {
+                    const buffer = await lease.page.screenshot({
+                        type: command.format ?? 'png',
+                        quality: command.format === 'jpeg' ? command.quality : undefined,
+                        fullPage: command.fullPage,
+                    });
+                    return { id: command.id, ok: true, data: buffer.toString('base64'), page: lease.pageId };
+                }
+                finally {
+                    if (previousViewport)
+                        await lease.page.setViewportSize(previousViewport);
+                }
+            }
+            case 'close-window': {
+                if (command.page) {
+                    const closed = await manager.closePage({ profileId: commandProfileId(command), pageId: command.page });
+                    return { id: command.id, ok: true, data: { closed: Boolean(closed), page: closed ?? command.page, session: command.session } };
+                }
+                else {
+                    await manager.release({
+                        profileId: commandProfileId(command),
+                        session: command.session,
+                        surface: command.surface,
+                    });
+                    return { id: command.id, ok: true, data: { closed: true, session: command.session } };
+                }
+            }
+            case 'tabs': {
+                switch (command.op ?? 'list') {
+                    case 'list': {
+                        const tabs = await manager.listPages({ profileId: commandProfileId(command) });
+                        return { id: command.id, ok: true, data: tabs };
+                    }
+                    case 'new': {
+                        const lease = await manager.newPage({
+                            profileId: commandProfileId(command),
+                            session: command.session,
+                            surface: command.surface,
+                            siteSession: command.siteSession,
+                            idleTimeout: command.idleTimeout,
+                            url: command.url,
+                        });
+                        return { id: command.id, ok: true, data: { title: await lease.page.title(), url: lease.page.url() }, page: lease.pageId };
+                    }
+                    case 'select': {
+                        const lease = await manager.selectPage({ profileId: commandProfileId(command), pageId: command.page, index: command.index });
+                        if (!lease)
+                            return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: 'Tab not found' };
+                        return { id: command.id, ok: true, data: { selected: true, url: lease.page.url() }, page: lease.pageId };
+                    }
+                    case 'close': {
+                        const closed = await manager.closePage({ profileId: commandProfileId(command), pageId: command.page, index: command.index });
+                        if (!closed)
+                            return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: 'Tab not found' };
+                        return { id: command.id, ok: true, data: { closed } };
+                    }
+                    default:
+                        return invalidRequest(command, `Unknown tabs op: ${command.op}`);
+                }
+            }
+            case 'set-file-input': {
+                if (!command.files?.length)
+                    return invalidRequest(command, 'Missing or empty files array');
+                const lease = await resolveLease(manager, command);
+                const locator = lease.page.locator(command.selector ?? 'input[type="file"]').first();
+                await locator.setInputFiles(command.files);
+                return { id: command.id, ok: true, data: { count: command.files.length }, page: lease.pageId };
+            }
+            case 'insert-text': {
+                if (typeof command.text !== 'string')
+                    return invalidRequest(command, 'Missing text payload');
+                const lease = await resolveLease(manager, command);
+                await lease.page.keyboard.insertText(command.text);
+                return { id: command.id, ok: true, data: { inserted: true }, page: lease.pageId };
+            }
+            case 'network-capture-start': {
+                const lease = await resolveLease(manager, command);
+                manager.networkCapture.start(command.pattern ?? '', lease.page);
+                return { id: command.id, ok: true, data: { started: true }, page: lease.pageId };
+            }
+            case 'network-capture-read': {
+                const lease = await resolveLease(manager, command);
+                return { id: command.id, ok: true, data: await manager.networkCapture.read(lease.page), page: lease.pageId };
+            }
+            case 'wait-download': {
+                const lease = await resolveLease(manager, command);
+                const result = await waitForDownload(lease.page, command.pattern ?? '', command.timeoutMs ?? 30_000);
+                return { id: command.id, ok: true, data: result, page: lease.pageId };
+            }
+            case 'cdp': {
+                if (!command.cdpMethod)
+                    return invalidRequest(command, 'Missing cdpMethod');
+                const lease = await resolveLease(manager, command);
+                const session = await lease.context.newCDPSession(lease.page);
+                const data = await session.send(command.cdpMethod, command.cdpParams ?? {});
+                return { id: command.id, ok: true, data, page: lease.pageId };
+            }
+            case 'frames': {
+                const lease = await resolveLease(manager, command);
+                const frames = lease.page.frames().slice(1).map((frame, index) => ({
+                    index,
+                    frameId: frame.name() || String(index),
+                    url: frame.url(),
+                    name: frame.name(),
+                }));
+                return { id: command.id, ok: true, data: frames, page: lease.pageId };
+            }
+            case 'bind':
+                if (!command.page && command.index == null) {
+                    return {
+                        id: command.id,
+                        ok: false,
+                        errorCode: 'invalid_request',
+                        error: 'Bind requires --page or --index for a Cloak runtime tab',
+                        errorHint: 'Run `webcmd browser <session> tab list`, then retry with `webcmd browser <session> bind --page <page-id>`.',
+                    };
+                }
+                {
+                    const lease = await manager.bindPage({
+                        profileId: commandProfileId(command),
+                        session: command.session,
+                        surface: command.surface,
+                        siteSession: command.siteSession,
+                        idleTimeout: command.idleTimeout,
+                        pageId: command.page,
+                        index: command.index,
+                    });
+                    if (!lease) {
+                        return {
+                            id: command.id,
+                            ok: false,
+                            errorCode: 'bound_tab_not_found',
+                            error: 'Cloak tab not found for bind target',
+                            errorHint: 'Run `webcmd browser <session> tab list` and choose a current Cloak tab id or index.',
+                        };
+                    }
+                    return {
+                        id: command.id,
+                        ok: true,
+                        page: lease.pageId,
+                        data: {
+                            bound: true,
+                            session: command.session,
+                            page: lease.pageId,
+                            url: lease.page.url(),
+                            title: await lease.page.title().catch(() => ''),
+                        },
+                    };
+                }
+            default:
+                return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: `Unknown action: ${command.action}` };
+        }
+    }
+    catch (err) {
+        if (err instanceof CloakActionError) {
+            return { id: command.id, ok: false, errorCode: err.errorCode, error: err.message, ...(err.page && { page: err.page }), ...(err.errorHint && { errorHint: err.errorHint }) };
+        }
+        return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: err instanceof Error ? err.message : String(err) };
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Page } from 'playwright-core';
+import type { BrowserDownloadWaitResult } from '../../../types.js';
+export declare function waitForDownload(page: Page, pattern: string, timeoutMs: number): Promise<BrowserDownloadWaitResult>;

package/dist/src/browser/runtime/local-cloak/downloads.js

@@ -0,0 +1,28 @@
+export async function waitForDownload(page, pattern, timeoutMs) {
+    const startedAt = Date.now();
+    try {
+        const download = await page.waitForEvent('download', {
+            timeout: timeoutMs,
+            predicate: (candidate) => {
+                if (!pattern)
+                    return true;
+                return candidate.url().includes(pattern) || candidate.suggestedFilename().includes(pattern);
+            },
+        });
+        const failure = await download.failure();
+        return {
+            downloaded: !failure,
+            filename: download.suggestedFilename(),
+            url: download.url(),
+            error: failure ?? undefined,
+            elapsedMs: Date.now() - startedAt,
+        };
+    }
+    catch (err) {
+        return {
+            downloaded: false,
+            error: err instanceof Error ? err.message : String(err),
+            elapsedMs: Date.now() - startedAt,
+        };
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { Page } from 'playwright-core';
+export interface NetworkCaptureEntry {
+    kind: 'cdp';
+    url: string;
+    method: string;
+    requestHeaders?: Record<string, string>;
+    requestBodyKind?: string;
+    requestBodyPreview?: string;
+    requestBodyFullSize?: number;
+    requestBodyTruncated?: boolean;
+    responseStatus?: number;
+    responseContentType?: string;
+    responseHeaders?: Record<string, string>;
+    responsePreview?: string;
+    responseBodyFullSize?: number;
+    responseBodyTruncated?: boolean;
+    timestamp: number;
+}
+export declare class CloakNetworkCapture {
+    private readonly limit;
+    private readonly states;
+    constructor(limit?: number);
+    start(pattern: string, page: Page): void;
+    read(page: Page): Promise<NetworkCaptureEntry[]>;
+    stop(page: Page): void;
+    private captureResponse;
+    private bound;
+}

package/dist/src/browser/runtime/local-cloak/network.js

@@ -0,0 +1,120 @@
+const BODY_LIMIT = 8 * 1024 * 1024;
+export class CloakNetworkCapture {
+    limit;
+    states = new WeakMap();
+    constructor(limit = 200) {
+        this.limit = limit;
+    }
+    start(pattern, page) {
+        this.stop(page);
+        const entries = [];
+        const byRequest = new WeakMap();
+        const pending = new Set();
+        const state = {
+            pattern,
+            entries,
+            byRequest,
+            pending,
+            onRequest: (request) => {
+                const url = request.url();
+                if (pattern && !url.includes(pattern))
+                    return;
+                const body = request.postData() ?? undefined;
+                const entry = {
+                    kind: 'cdp',
+                    url,
+                    method: request.method(),
+                    requestHeaders: request.headers(),
+                    requestBodyKind: body === undefined ? undefined : 'text',
+                    requestBodyPreview: body === undefined ? undefined : body.slice(0, BODY_LIMIT),
+                    requestBodyFullSize: body?.length,
+                    requestBodyTruncated: body ? body.length > BODY_LIMIT : undefined,
+                    timestamp: Date.now(),
+                };
+                entries.push(entry);
+                byRequest.set(request, entry);
+                this.bound(entries);
+            },
+            onResponse: (response) => {
+                const capture = this.captureResponse(response, pattern, entries, byRequest)
+                    .finally(() => pending.delete(capture));
+                pending.add(capture);
+            },
+        };
+        page.on('request', state.onRequest);
+        page.on('response', state.onResponse);
+        this.states.set(page, state);
+    }
+    async read(page) {
+        const state = this.states.get(page);
+        if (!state)
+            return [];
+        await Promise.allSettled([...state.pending]);
+        return [...state.entries];
+    }
+    stop(page) {
+        const state = this.states.get(page);
+        if (!state)
+            return;
+        page.off('request', state.onRequest);
+        page.off('response', state.onResponse);
+        this.states.delete(page);
+    }
+    async captureResponse(response, pattern, entries, byRequest) {
+        const url = response.url();
+        if (pattern && !url.includes(pattern))
+            return;
+        const headers = response.headers();
+        const contentType = headers['content-type'];
+        let preview;
+        let fullSize;
+        let truncated;
+        const contentLength = Number(headers['content-length']);
+        if (Number.isFinite(contentLength) && contentLength >= 0)
+            fullSize = contentLength;
+        if (isTextLikeContentType(contentType)) {
+            try {
+                const text = await response.text();
+                fullSize = text.length;
+                truncated = text.length > BODY_LIMIT;
+                preview = text.slice(0, BODY_LIMIT);
+            }
+            catch {
+                preview = undefined;
+            }
+        }
+        const responseRequest = typeof response.request === 'function' ? response.request() : undefined;
+        const existing = responseRequest
+            ? byRequest.get(responseRequest)
+            : [...entries].reverse().find((entry) => entry.url === url && entry.responseStatus === undefined);
+        const target = existing ?? {
+            kind: 'cdp',
+            url,
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        target.responseStatus = response.status();
+        target.responseContentType = contentType;
+        target.responseHeaders = headers;
+        target.responsePreview = preview;
+        target.responseBodyFullSize = fullSize;
+        target.responseBodyTruncated = truncated;
+        if (!existing)
+            entries.push(target);
+        this.bound(entries);
+    }
+    bound(entries) {
+        while (entries.length > this.limit)
+            entries.shift();
+    }
+}
+function isTextLikeContentType(contentType) {
+    if (!contentType)
+        return false;
+    const normalized = contentType.toLowerCase();
+    return normalized.startsWith('text/')
+        || normalized.includes('json')
+        || normalized.includes('javascript')
+        || normalized.includes('xml')
+        || normalized.includes('x-www-form-urlencoded');
+}

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

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

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

@@ -0,0 +1,124 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, it, vi } from 'vitest';
+import { CloakNetworkCapture } from './network.js';
+class FakePage extends EventEmitter {
+    off(event, listener) {
+        this.removeListener(event, listener);
+        return this;
+    }
+}
+describe('CloakNetworkCapture', () => {
+    it('captures matching request and response metadata with a bounded buffer', async () => {
+        const page = new FakePage();
+        const capture = new CloakNetworkCapture(2);
+        capture.start('api.example', page);
+        const req = {
+            url: () => 'https://api.example/items',
+            method: () => 'POST',
+            headers: () => ({ accept: 'application/json' }),
+            postData: () => '{"x":1}',
+        };
+        const res = {
+            url: () => 'https://api.example/items',
+            status: () => 200,
+            headers: () => ({ 'content-type': 'application/json' }),
+            text: async () => '{"ok":true}',
+        };
+        page.emit('request', req);
+        page.emit('response', res);
+        expect(await capture.read(page)).toEqual([expect.objectContaining({
+                kind: 'cdp',
+                url: 'https://api.example/items',
+                method: 'POST',
+                responseStatus: 200,
+                responsePreview: '{"ok":true}',
+            })]);
+    });
+    it('matches same-url responses to their exact request identity', async () => {
+        const page = new FakePage();
+        const capture = new CloakNetworkCapture(10);
+        capture.start('api.example', page);
+        const firstReq = {
+            url: () => 'https://api.example/items',
+            method: () => 'POST',
+            headers: () => ({ 'x-request': 'first' }),
+            postData: () => 'first',
+        };
+        const secondReq = {
+            url: () => 'https://api.example/items',
+            method: () => 'PUT',
+            headers: () => ({ 'x-request': 'second' }),
+            postData: () => 'second',
+        };
+        const firstRes = {
+            url: () => 'https://api.example/items',
+            request: () => firstReq,
+            status: () => 201,
+            headers: () => ({ 'content-type': 'application/json' }),
+            text: async () => '{"first":true}',
+        };
+        page.emit('request', firstReq);
+        page.emit('request', secondReq);
+        page.emit('response', firstRes);
+        const entries = await capture.read(page);
+        expect(entries).toEqual([
+            expect.objectContaining({
+                method: 'POST',
+                requestBodyPreview: 'first',
+                responseStatus: 201,
+                responsePreview: '{"first":true}',
+            }),
+            expect.objectContaining({
+                method: 'PUT',
+                requestBodyPreview: 'second',
+            }),
+        ]);
+        expect(entries[1]).not.toHaveProperty('responseStatus');
+        expect(entries[1]).not.toHaveProperty('responsePreview');
+    });
+    it('skips response body previews for non-text content types', async () => {
+        const page = new FakePage();
+        const capture = new CloakNetworkCapture(10);
+        capture.start('api.example', page);
+        const req = {
+            url: () => 'https://api.example/image.png',
+            method: () => 'GET',
+            headers: () => ({}),
+            postData: () => null,
+        };
+        const text = vi.fn(async () => 'binary-ish body');
+        const res = {
+            url: () => 'https://api.example/image.png',
+            request: () => req,
+            status: () => 200,
+            headers: () => ({ 'content-type': 'image/png', 'content-length': '15' }),
+            text,
+        };
+        page.emit('request', req);
+        page.emit('response', res);
+        expect(await capture.read(page)).toEqual([expect.objectContaining({
+                responseContentType: 'image/png',
+                responseBodyFullSize: 15,
+                responseBodyTruncated: undefined,
+                responsePreview: undefined,
+            })]);
+        expect(text).not.toHaveBeenCalled();
+    });
+    it('evicts older entries when the bounded buffer limit is exceeded', async () => {
+        const page = new FakePage();
+        const capture = new CloakNetworkCapture(2);
+        capture.start('api.example', page);
+        for (const id of ['one', 'two', 'three']) {
+            page.emit('request', {
+                url: () => `https://api.example/${id}`,
+                method: () => 'GET',
+                headers: () => ({}),
+                postData: () => null,
+            });
+        }
+        expect(await capture.read(page)).toEqual([
+            expect.objectContaining({ url: 'https://api.example/two' }),
+            expect.objectContaining({ url: 'https://api.example/three' }),
+        ]);
+    });
+});

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

@@ -0,0 +1,6 @@
+export interface CloakProfileDirOptions {
+    baseDir?: string;
+}
+export declare function normalizeProfileId(value: string | undefined | null): string;
+export declare function getWebcmdConfigDir(): string;
+export declare function resolveCloakProfileDir(profileId: string, opts?: CloakProfileDirOptions): string;

package/dist/src/browser/runtime/local-cloak/profiles.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import { CONFIG_DIR_NAME, ENV_PREFIX } from '../../../brand.js';
+import os from 'node:os';
+export function normalizeProfileId(value) {
+    const id = value?.trim() || 'default';
+    if (!/^[A-Za-z0-9._-]+$/.test(id) || id === '.' || id === '..') {
+        throw new Error(`Invalid profile id: ${value ?? ''}`);
+    }
+    return id;
+}
+export function getWebcmdConfigDir() {
+    return process.env[`${ENV_PREFIX}_CONFIG_DIR`] || path.join(os.homedir(), CONFIG_DIR_NAME);
+}
+export function resolveCloakProfileDir(profileId, opts = {}) {
+    const safeProfileId = normalizeProfileId(profileId);
+    return path.join(opts.baseDir ?? getWebcmdConfigDir(), 'cloak', 'profiles', safeProfileId);
+}

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

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

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

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { normalizeProfileId, resolveCloakProfileDir } from './profiles.js';
+describe('cloak profile resolution', () => {
+    it('normalizes empty profile ids to default', () => {
+        expect(normalizeProfileId(undefined)).toBe('default');
+        expect(normalizeProfileId('')).toBe('default');
+        expect(normalizeProfileId('  work  ')).toBe('work');
+    });
+    it('rejects path traversal and separators', () => {
+        expect(() => normalizeProfileId('../x')).toThrow(/Invalid profile id/);
+        expect(() => normalizeProfileId('a/b')).toThrow(/Invalid profile id/);
+        expect(() => normalizeProfileId('a\\b')).toThrow(/Invalid profile id/);
+    });
+    it('resolves under the webcmd cloak profiles directory', () => {
+        expect(resolveCloakProfileDir('work', { baseDir: '/tmp/webcmd' }))
+            .toBe(path.join('/tmp/webcmd', 'cloak', 'profiles', 'work'));
+    });
+});

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

@@ -0,0 +1,15 @@
+import type { BrowserRuntimeCommand, BrowserRuntimeResult, BrowserRuntimeStatus } from '../../protocol.js';
+import type { BrowserRuntimeProvider, RuntimeStatusOptions } from '../provider.js';
+import type { LaunchPersistentContext } from './session-manager.js';
+export interface LocalCloakRuntimeProviderOptions {
+    baseDir?: string;
+    launchPersistentContext?: LaunchPersistentContext;
+}
+export declare class LocalCloakRuntimeProvider implements BrowserRuntimeProvider {
+    private readonly opts;
+    private readonly manager;
+    constructor(opts?: LocalCloakRuntimeProviderOptions);
+    status(_opts?: RuntimeStatusOptions): Promise<BrowserRuntimeStatus>;
+    dispatch(command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;
+    shutdown(): Promise<void>;
+}

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

@@ -0,0 +1,27 @@
+import { dispatchCloakAction } from './actions.js';
+import { CloakSessionManager } from './session-manager.js';
+export class LocalCloakRuntimeProvider {
+    opts;
+    manager;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.manager = new CloakSessionManager(opts);
+    }
+    async status(_opts = {}) {
+        const profiles = this.manager.profileStatuses();
+        return {
+            runtimeConnected: true,
+            runtimeName: 'cloak',
+            runtimeVersion: undefined,
+            profiles,
+            pending: 0,
+            commandResultUnknown: 0,
+        };
+    }
+    async dispatch(command) {
+        return dispatchCloakAction(this.manager, command);
+    }
+    async shutdown() {
+        await this.manager.shutdown();
+    }
+}

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

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