@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/browser/diagnostics.js

@@ -0,0 +1,38 @@
+import { accessSync, constants } from 'node:fs';
+const outputText = (result) => typeof result === 'string' ? result : result.text;
+/** Exercises the production tool path against a synthetic page in a throwaway profile. */
+export function browserDiagnostic(configure) {
+    return {
+        id: 'browser', category: 'browser', title: 'Isolated browser',
+        tools: ['browser_navigate', 'browser_read', 'browser_snapshot', 'browser_click'],
+        local: async () => {
+            const config = configure();
+            if (config.executablePath)
+                accessSync(config.executablePath, constants.X_OK);
+            return { status: 'pass', evidence: `Browser tools are installed. ${config.cdpUrl ? 'A CDP endpoint is configured; diagnostics will not attach to it.' : 'A dedicated browser will be launched only after live-check confirmation.'} Browser launch is unverified.` };
+        },
+        live: {
+            notice: 'Launch a dedicated headless browser with a disposable profile, open an offline synthetic page, read its marker, and click its test button. No existing browser or profile is used.',
+            run: async (probe) => {
+                if (configure().cdpUrl)
+                    return { status: 'blocked', evidence: 'This backend is configured to attach to a browser. Isolated diagnostics will not attach to it.', remedy: 'Use a dedicated launch configuration to test browser interaction.' };
+                const needed = ['browser_navigate', 'browser_read', 'browser_snapshot', 'browser_click'];
+                if (needed.some(name => !probe.context.tools.includes(name)))
+                    return { status: 'blocked', evidence: 'The browser interaction test requires navigate, read, snapshot, and click capabilities.' };
+                const html = '<!doctype html><title>Harness Doctor</title><p>doctor-ready</p><button onclick="document.querySelector(\'p\').textContent=\'doctor-clicked\'">Diagnostic test</button>';
+                await probe.call('browser_navigate', { url: `data:text/html,${encodeURIComponent(html)}` });
+                const before = outputText(await probe.call('browser_read', {}));
+                if (!before.includes('doctor-ready'))
+                    return { status: 'fail', evidence: 'The diagnostic page marker could not be read.' };
+                const snapshot = outputText(await probe.call('browser_snapshot', {}));
+                const line = snapshot.split('\n').find(line => line.includes('button') && line.includes('Diagnostic test'));
+                const ref = line && /\b(e\d+)\b/.exec(line)?.[1];
+                if (!ref)
+                    return { status: 'fail', evidence: 'The test button was absent from the browser snapshot.' };
+                await probe.call('browser_click', { ref });
+                const after = outputText(await probe.call('browser_read', {}));
+                return after.includes('doctor-clicked') ? { status: 'pass', evidence: 'Navigation, reading, element discovery, and clicking succeeded in the disposable diagnostic browser.' } : { status: 'fail', evidence: 'Clicking did not change the expected page marker.' };
+            }
+        }
+    };
+}

package/dist/sdk/browser/extension/bridge.d.ts

@@ -0,0 +1,55 @@
+export interface BrowserExtensionStatus {
+    state: 'stopped' | 'pairing' | 'waiting' | 'connected' | 'paused';
+    paired: boolean;
+    connected: boolean;
+    paused: boolean;
+    port: number | null;
+    lastSeenAt: number | null;
+}
+export interface BrowserExtensionStart {
+    status: BrowserExtensionStatus;
+    pairingCode?: string;
+    expiresAt?: number;
+}
+export declare class BrowserExtensionBridge {
+    private readonly options;
+    private server;
+    private starting;
+    private port;
+    private accessToken;
+    private origin;
+    private pairing;
+    private lastSeenAt;
+    private paused;
+    private waiter;
+    private waiterTimer;
+    private readonly queue;
+    private readonly sent;
+    private attempts;
+    private nextAttemptAt;
+    constructor(options: {
+        stateDir: string;
+        port?: number;
+    });
+    private settingsFile;
+    private save;
+    status(): BrowserExtensionStatus;
+    /** Starts the loopback bridge and returns a short-lived code for the extension's explicit pair action. */
+    start(): Promise<BrowserExtensionStart>;
+    private startResult;
+    private listen;
+    /** One request from the browser at a time; the extension's poll loop serializes the live tabs. */
+    request(operation: unknown): Promise<unknown>;
+    stop(): Promise<BrowserExtensionStatus>;
+    /** Keeps pairing across a normal Harness shutdown so the extension can reconnect to this profile. */
+    close(): Promise<void>;
+    private revoke;
+    private rejectPending;
+    private closeServer;
+    private flush;
+    private json;
+    private body;
+    private originAllowed;
+    private authorized;
+    private handle;
+}

package/dist/sdk/browser/extension/bridge.js

@@ -0,0 +1,336 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { readJsonOr, writeJson } from "../../core/fs.js";
+const DEFAULT_PORT = 38671;
+const GONE_MS = 45_000;
+const POLL_MS = 20_000;
+const REQUEST_MS = 60_000;
+const PAIR_MS = 5 * 60_000;
+const MAX_BODY = 8_000_000;
+const EXTENSION_ORIGIN = /^chrome-extension:\/\/([a-p]{32})$/;
+const bounded = (value, max) => typeof value === 'string' ? Array.from(value).slice(0, max).join('') : '';
+function sameSecret(candidate, expected) {
+    const left = Buffer.from(candidate);
+    const right = Buffer.from(expected);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+export class BrowserExtensionBridge {
+    options;
+    server = null;
+    starting = null;
+    port = null;
+    accessToken = null;
+    origin = null;
+    pairing = null;
+    lastSeenAt = null;
+    paused = false;
+    waiter = null;
+    waiterTimer = null;
+    queue = [];
+    sent = new Map();
+    attempts = [];
+    nextAttemptAt = 0;
+    constructor(options) {
+        this.options = options;
+        const settingsFile = this.settingsFile();
+        if (existsSync(settingsFile))
+            chmodSync(settingsFile, 0o600);
+        const saved = readJsonOr(settingsFile, {});
+        if (typeof saved.accessToken === 'string' && /^[a-f0-9]{48}$/.test(saved.accessToken) && typeof saved.origin === 'string' && EXTENSION_ORIGIN.test(saved.origin)) {
+            this.accessToken = saved.accessToken;
+            this.origin = saved.origin;
+        }
+        this.paused = saved.paused === true;
+        if (Number.isInteger(saved.port) && saved.port > 0 && saved.port < 65536)
+            this.port = saved.port;
+    }
+    settingsFile() {
+        return join(this.options.stateDir, 'browser', 'extension-bridge.json');
+    }
+    save() {
+        const path = this.settingsFile();
+        mkdirSync(join(this.options.stateDir, 'browser'), { recursive: true });
+        if (!this.accessToken || !this.origin || !this.port) {
+            rmSync(path, { force: true });
+            return;
+        }
+        writeJson(path, { port: this.port, accessToken: this.accessToken, origin: this.origin, paused: this.paused });
+        chmodSync(path, 0o600);
+    }
+    status() {
+        const connected = Boolean(this.lastSeenAt && Date.now() - this.lastSeenAt <= GONE_MS);
+        const paired = Boolean(this.accessToken && this.origin);
+        const state = !this.server
+            ? 'stopped'
+            : this.paused && connected
+                ? 'paused'
+                : connected
+                    ? 'connected'
+                    : paired
+                        ? 'waiting'
+                        : 'pairing';
+        return { state, paired, connected, paused: this.paused, port: this.server ? this.port : null, lastSeenAt: connected ? this.lastSeenAt : null };
+    }
+    /** Starts the loopback bridge and returns a short-lived code for the extension's explicit pair action. */
+    start() {
+        if (this.server)
+            return Promise.resolve(this.startResult());
+        this.starting ??= this.listen().finally(() => { this.starting = null; });
+        return this.starting;
+    }
+    startResult() {
+        if (this.accessToken && this.origin)
+            return { status: this.status() };
+        if (!this.pairing || this.pairing.expiresAt <= Date.now()) {
+            this.pairing = { code: randomBytes(6).toString('hex').toUpperCase(), expiresAt: Date.now() + PAIR_MS };
+        }
+        return {
+            status: this.status(),
+            pairingCode: `${this.port}:${this.pairing.code}`,
+            expiresAt: this.pairing.expiresAt
+        };
+    }
+    async listen() {
+        const savedPort = this.options.port ?? this.port ?? DEFAULT_PORT;
+        const server = createServer((request, response) => void this.handle(request, response));
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(savedPort, '127.0.0.1', () => {
+                server.removeListener('error', reject);
+                resolve();
+            });
+        });
+        this.server = server;
+        this.port = server.address().port;
+        this.save();
+        return this.startResult();
+    }
+    /** One request from the browser at a time; the extension's poll loop serializes the live tabs. */
+    request(operation) {
+        if (!this.server || !this.accessToken || !this.origin || !this.status().connected) {
+            return Promise.reject(new Error('Brave is not connected. Connect the extension in Browser settings; nothing was done.'));
+        }
+        if (this.paused)
+            return Promise.reject(new Error('Brave control is paused by the user. Resume it from the page badge; nothing was done.'));
+        return new Promise((resolve, reject) => {
+            const pending = {
+                id: randomUUID(), operation, resolve, reject,
+                timer: setTimeout(() => {
+                    this.sent.delete(pending.id);
+                    const queued = this.queue.indexOf(pending);
+                    if (queued >= 0)
+                        this.queue.splice(queued, 1);
+                    reject(new Error('Brave did not answer before the browser call timed out. Its outcome is unknown; take a fresh snapshot before trying again.'));
+                }, REQUEST_MS)
+            };
+            pending.timer.unref?.();
+            this.queue.push(pending);
+            this.flush();
+        });
+    }
+    async stop() {
+        this.revoke();
+        await this.closeServer();
+        return this.status();
+    }
+    /** Keeps pairing across a normal Harness shutdown so the extension can reconnect to this profile. */
+    async close() {
+        this.lastSeenAt = null;
+        this.rejectPending(new Error('The Harness stopped the Brave bridge.'), 503);
+        await this.closeServer();
+    }
+    revoke() {
+        const origin = this.origin;
+        this.pairing = null;
+        this.accessToken = null;
+        this.origin = null;
+        this.lastSeenAt = null;
+        this.paused = false;
+        this.save();
+        this.rejectPending(new Error('Brave control was stopped by the user.'), 410, origin);
+    }
+    rejectPending(error, status = 410, origin = this.origin) {
+        if (this.waiter)
+            this.json(this.waiter, status, { error: status === 410 ? 'bridge_stopped' : 'bridge_unavailable' }, origin ?? undefined);
+        this.waiter = null;
+        if (this.waiterTimer)
+            clearTimeout(this.waiterTimer);
+        this.waiterTimer = null;
+        for (const pending of [...this.queue, ...this.sent.values()]) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.queue.length = 0;
+        this.sent.clear();
+    }
+    async closeServer() {
+        const server = this.server;
+        this.server = null;
+        this.port = null;
+        if (!server)
+            return;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    flush() {
+        if (!this.waiter || !this.queue.length)
+            return;
+        const pending = this.queue.shift();
+        this.sent.set(pending.id, pending);
+        const waiter = this.waiter;
+        this.waiter = null;
+        if (this.waiterTimer)
+            clearTimeout(this.waiterTimer);
+        this.waiterTimer = null;
+        this.json(waiter, 200, { id: pending.id, operation: pending.operation });
+    }
+    json(response, status, body, origin) {
+        response.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            'access-control-allow-origin': origin ?? 'null',
+            'access-control-allow-methods': 'GET, POST, OPTIONS',
+            'access-control-allow-headers': 'Authorization, Content-Type',
+            'access-control-max-age': '60',
+            vary: 'Origin'
+        });
+        response.end(body === undefined ? undefined : JSON.stringify(body));
+    }
+    async body(request) {
+        let size = 0;
+        const chunks = [];
+        for await (const chunk of request) {
+            size += chunk.length;
+            if (size > MAX_BODY)
+                return null;
+            chunks.push(chunk);
+        }
+        try {
+            const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    originAllowed(origin, pairing = false) {
+        if (!origin || !EXTENSION_ORIGIN.test(origin))
+            return false;
+        return pairing || origin === this.origin;
+    }
+    // Extension service-worker fetches may omit Origin; the bearer token remains mandatory.
+    authorized(request, origin) {
+        if (!this.accessToken || (origin !== null && !this.originAllowed(origin)))
+            return false;
+        const authorization = request.headers.authorization ?? '';
+        const token = authorization.startsWith('Bearer ') ? authorization.slice(7) : '';
+        return sameSecret(token, this.accessToken);
+    }
+    async handle(request, response) {
+        try {
+            const port = this.port;
+            if (!port || request.headers.host !== `127.0.0.1:${port}`)
+                return this.json(response, 421);
+            const origin = typeof request.headers.origin === 'string' ? request.headers.origin : null;
+            const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`);
+            if (request.method === 'OPTIONS') {
+                const pairing = url.pathname === '/pair';
+                if (!this.originAllowed(origin, pairing))
+                    return this.json(response, 403);
+                return this.json(response, 204, undefined, origin);
+            }
+            if (request.method === 'POST' && url.pathname === '/pair') {
+                if (!this.originAllowed(origin, true))
+                    return this.json(response, 403);
+                if (Date.now() < this.nextAttemptAt)
+                    return this.json(response, 429, { error: 'rate_limited' }, origin);
+                const body = await this.body(request);
+                const supplied = bounded(body?.code, 40);
+                const expected = this.pairing?.code ?? '';
+                const valid = Boolean(expected && this.pairing && this.pairing.expiresAt > Date.now() && sameSecret(supplied, expected));
+                if (!valid) {
+                    this.attempts.push(Date.now());
+                    this.attempts = this.attempts.filter((at) => Date.now() - at < 60_000);
+                    if (this.attempts.length >= 5)
+                        this.nextAttemptAt = Date.now() + 60_000;
+                    return this.json(response, this.attempts.length >= 5 ? 429 : 403, { error: 'invalid_pairing_code' }, origin);
+                }
+                this.pairing = null;
+                this.attempts = [];
+                this.nextAttemptAt = 0;
+                this.accessToken = randomBytes(24).toString('hex');
+                this.origin = origin;
+                this.lastSeenAt = null;
+                this.paused = false;
+                this.save();
+                return this.json(response, 200, { token: this.accessToken }, origin);
+            }
+            if (!this.authorized(request, origin))
+                return this.json(response, 403);
+            if (request.method === 'GET' && url.pathname === '/status')
+                return this.json(response, 200, this.status(), origin);
+            if (request.method === 'GET' && url.pathname === '/poll') {
+                this.lastSeenAt = Date.now();
+                if (this.waiter)
+                    this.json(this.waiter, 409, { error: 'poll_replaced' }, origin);
+                this.waiter = response;
+                if (this.waiterTimer)
+                    clearTimeout(this.waiterTimer);
+                this.waiterTimer = setTimeout(() => {
+                    if (this.waiter !== response)
+                        return;
+                    this.waiter = null;
+                    this.json(response, 204, undefined, origin);
+                }, POLL_MS);
+                this.waiterTimer.unref?.();
+                this.flush();
+                return;
+            }
+            if (request.method === 'POST' && url.pathname === '/reply') {
+                const body = await this.body(request);
+                const id = bounded(body?.id, 80);
+                const pending = this.sent.get(id);
+                if (!pending)
+                    return this.json(response, 404, { error: 'unknown_request' }, origin);
+                this.sent.delete(id);
+                clearTimeout(pending.timer);
+                pending.resolve(body?.result);
+                return this.json(response, 200, { ok: true }, origin);
+            }
+            if (request.method === 'POST' && url.pathname === '/control') {
+                const body = await this.body(request);
+                const action = body?.action;
+                if (action === 'pause') {
+                    this.paused = true;
+                    this.save();
+                    for (const pending of this.queue.splice(0)) {
+                        clearTimeout(pending.timer);
+                        pending.reject(new Error('Brave control was paused by the user; nothing was done.'));
+                    }
+                }
+                else if (action === 'resume') {
+                    this.paused = false;
+                    this.save();
+                }
+                else if (action === 'stop') {
+                    this.revoke();
+                    const status = this.status();
+                    this.json(response, 200, { status }, origin);
+                    setImmediate(() => void this.closeServer());
+                    return;
+                }
+                else
+                    return this.json(response, 400, { error: 'invalid_action' }, origin);
+                return this.json(response, 200, { status: this.status() }, origin);
+            }
+            this.json(response, 404, { error: 'not_found' }, origin);
+        }
+        catch {
+            if (!response.headersSent)
+                this.json(response, 500, { error: 'bridge_error' });
+            else
+                response.end();
+        }
+    }
+}

package/dist/sdk/browser/extension/session.d.ts

@@ -0,0 +1,50 @@
+import type { NetworkPolicy } from "../network.js";
+import type { Download } from "../session.js";
+import type { BrowserToolSession, BrowserToolTab } from "../tools.js";
+import type { BrowserExtensionBridge } from "./bridge.js";
+interface RemoteTab {
+    tabId: number;
+    url: string;
+    title: string;
+    generation: number;
+    active: boolean;
+}
+export declare class BraveBrowserSession implements BrowserToolSession {
+    private readonly options;
+    private readonly tabs;
+    private current;
+    private queue;
+    private idle;
+    private readonly idleMs;
+    readonly downloads: Download[];
+    readonly profileNote = "Brave is using your existing profile. Only normal tabs on sites you allowed in the extension are available; Incognito tabs are never exposed.";
+    constructor(options: {
+        bridge: BrowserExtensionBridge;
+        network: NetworkPolicy;
+        idleMs: number;
+        onIdle: () => void;
+    });
+    run<T>(work: () => Promise<T>): Promise<T>;
+    private touch;
+    invoke<T>(operation: Record<string, unknown>): Promise<T>;
+    private idFor;
+    private refreshTabs;
+    refresh(): Promise<void>;
+    refreshOne(id: string): Promise<RemoteTabState>;
+    get(id: string): RemoteTabState;
+    tab(id?: string | null): Promise<RemoteTabState>;
+    open(): Promise<RemoteTabState>;
+    select(id: string): Promise<RemoteTabState>;
+    list(): {
+        id: string;
+        url: string;
+        current: boolean;
+    }[];
+    get network(): NetworkPolicy;
+    get started(): boolean;
+    close(): Promise<void>;
+}
+interface RemoteTabState extends BrowserToolTab {
+    remote: RemoteTab;
+}
+export {};