@xingular/harness 1.5.0-unstable → 1.6.0-unstable

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

@@ -0,0 +1,321 @@
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+const escaped = (value) => value.replace(/[&<>]/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[char]);
+const quote = (value) => JSON.stringify(value.slice(0, 240));
+const ACTIONABLE = new Set(['button', 'link', 'textbox', 'combobox', 'checkbox', 'radio', 'menuitem', 'tab', 'switch', 'option']);
+export class BraveBrowserSession {
+    options;
+    tabs = new Map();
+    current = null;
+    queue = Promise.resolve();
+    idle = null;
+    idleMs;
+    downloads = [];
+    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) {
+        this.options = options;
+        this.idleMs = options.idleMs;
+    }
+    run(work) {
+        const next = this.queue.then(work, work);
+        this.queue = next.catch(() => undefined);
+        this.touch();
+        return next;
+    }
+    touch() {
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = setTimeout(this.options.onIdle, this.idleMs);
+        this.idle.unref?.();
+    }
+    async invoke(operation) {
+        const response = await this.options.bridge.request(operation);
+        if (!isRecord(response) || typeof response.ok !== 'boolean')
+            throw new Error('The Brave extension returned an invalid response.');
+        if (!response.ok)
+            throw new Error(typeof response.error === 'string' ? response.error : 'The Brave extension could not complete the operation.');
+        return response.value;
+    }
+    idFor(tabId) {
+        return `b${tabId.toString(36)}`;
+    }
+    async refreshTabs() {
+        const remote = await this.invoke({ op: 'tabs.list' });
+        if (!Array.isArray(remote))
+            throw new Error('The Brave extension returned an invalid tab list.');
+        const live = new Set();
+        this.current = null;
+        for (const entry of remote) {
+            if (!isRecord(entry) || !Number.isInteger(entry.tabId) || typeof entry.url !== 'string' || typeof entry.title !== 'string' || !Number.isInteger(entry.generation))
+                continue;
+            if (await this.options.network.refusal(entry.url))
+                continue;
+            const tabId = Number(entry.tabId);
+            const id = this.idFor(tabId);
+            live.add(id);
+            const old = this.tabs.get(id);
+            if (old) {
+                old.remote = { tabId, url: entry.url, title: entry.title, generation: Number(entry.generation), active: entry.active === true };
+                old.generation = Number(entry.generation);
+            }
+            else {
+                this.tabs.set(id, {
+                    id,
+                    remote: { tabId, url: entry.url, title: entry.title, generation: Number(entry.generation), active: entry.active === true },
+                    generation: Number(entry.generation), refs: new Map(), refsGeneration: -1,
+                    page: new BravePage(this, id)
+                });
+            }
+            if (entry.active === true)
+                this.current = id;
+        }
+        for (const id of this.tabs.keys())
+            if (!live.has(id))
+                this.tabs.delete(id);
+        if (this.current && !this.tabs.has(this.current))
+            this.current = null;
+    }
+    async refresh() {
+        await this.refreshTabs();
+    }
+    async refreshOne(id) {
+        await this.refreshTabs();
+        const tab = this.tabs.get(id);
+        if (!tab)
+            throw new Error(`Brave tab ${id} is no longer available. The tab may have closed, or the page may have moved to a site you have not allowed.`);
+        return tab;
+    }
+    get(id) {
+        const tab = this.tabs.get(id);
+        if (!tab)
+            throw new Error(`There is no tab ${id}. browser_tabs lists the available tabs.`);
+        return tab;
+    }
+    async tab(id) {
+        await this.refreshTabs();
+        if (id) {
+            const tab = this.tabs.get(id);
+            if (!tab)
+                throw new Error(`There is no tab ${id}. browser_tabs lists the available tabs.`);
+            return tab;
+        }
+        if (this.current && this.tabs.has(this.current))
+            return this.tabs.get(this.current);
+        return this.open();
+    }
+    async open() {
+        const tabId = await this.invoke({ op: 'tabs.create' });
+        if (!Number.isInteger(tabId))
+            throw new Error('The Brave extension did not return the new tab.');
+        await this.refreshTabs();
+        const tab = this.tabs.get(this.idFor(tabId));
+        if (!tab)
+            throw new Error('Brave created a tab but it is not available yet. Try browser_tabs again.');
+        this.current = tab.id;
+        return tab;
+    }
+    async select(id) {
+        const tab = this.get(id);
+        await this.invoke({ op: 'tabs.activate', tabId: tab.remote.tabId });
+        this.current = id;
+        await this.refreshTabs();
+        return this.get(id);
+    }
+    list() {
+        return [...this.tabs.entries()].map(([id, tab]) => ({ id, url: tab.remote.url, current: id === this.current }));
+    }
+    get network() {
+        return this.options.network;
+    }
+    get started() {
+        return true;
+    }
+    async close() {
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.tabs.clear();
+        this.current = null;
+    }
+}
+class BravePage {
+    session;
+    id;
+    refs = new Map();
+    constructor(session, id) {
+        this.session = session;
+        this.id = id;
+    }
+    get tab() {
+        return this.session.get(this.id);
+    }
+    async refresh() {
+        const tab = await this.session.refreshOne(this.id);
+        tab.generation = tab.remote.generation;
+    }
+    url() {
+        return this.tab.remote.url;
+    }
+    async title() {
+        await this.refresh();
+        return this.tab.remote.title;
+    }
+    async goto(url) {
+        await this.session.invoke({ op: 'page.navigate', tabId: this.tab.remote.tabId, url });
+        await this.refresh();
+        return null;
+    }
+    async goBack() {
+        await this.session.invoke({ op: 'page.back', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async goForward() {
+        await this.session.invoke({ op: 'page.forward', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async reload() {
+        await this.session.invoke({ op: 'page.reload', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async close() {
+        await this.session.invoke({ op: 'tabs.close', tabId: this.tab.remote.tabId });
+    }
+    async ariaSnapshot(options = { mode: 'ai' }) {
+        const response = await this.session.invoke({
+            op: 'page.snapshot', tabId: this.tab.remote.tabId,
+            ...(options.depth ? { depth: Math.max(1, Math.min(40, options.depth)) } : {})
+        });
+        const tab = this.tab;
+        tab.generation = response.generation;
+        tab.remote.generation = response.generation;
+        this.refs.clear();
+        const nodes = Array.isArray(response.nodes) ? response.nodes : [];
+        const byId = new Map(nodes.filter(node => node && typeof node.nodeId === 'string').map(node => [node.nodeId, node]));
+        const lines = [];
+        let nextRef = 1;
+        const walk = (node, depth) => {
+            if (depth > (options.depth ?? 12))
+                return;
+            const role = node.role || 'text';
+            const name = node.name?.trim() ?? '';
+            const actionable = ACTIONABLE.has(role) && Number.isInteger(node.backendDOMNodeId);
+            if (!node.ignored && role !== 'rootWebArea' && role !== 'none' && (name || actionable)) {
+                const ref = actionable ? `e${nextRef++}` : null;
+                if (ref)
+                    this.refs.set(ref, { backendDOMNodeId: node.backendDOMNodeId, generation: response.generation });
+                const suffix = ref ? ` [ref=${ref}]` : '';
+                const level = role === 'heading' && Number.isInteger(node.level) ? ` [level=${node.level}]` : '';
+                lines.push(`${'  '.repeat(depth)}- ${role}${name ? ` ${quote(name)}` : ''}${level}${suffix}`);
+            }
+            for (const childId of node.childIds ?? []) {
+                const child = byId.get(childId);
+                if (child)
+                    walk(child, depth + 1);
+            }
+        };
+        const roots = nodes.filter(node => !node.parentId || !byId.has(node.parentId));
+        for (const root of roots)
+            walk(root, 0);
+        return lines.join('\n');
+    }
+    async content() {
+        await this.refresh();
+        const value = await this.session.invoke({ op: 'page.text', tabId: this.tab.remote.tabId });
+        this.tab.remote.title = value.title;
+        return `<html><head><title>${escaped(value.title)}</title></head><body>${escaped(value.text)}</body></html>`;
+    }
+    async screenshot(options) {
+        return this.capture(options);
+    }
+    getByRef(ref) {
+        const target = this.refs.get(ref);
+        if (!target)
+            throw new Error(`There is no live element for ref ${ref}. Take browser_snapshot again.`);
+        return new BraveLocator(this, target);
+    }
+    async evaluate(expression) {
+        await this.refresh();
+        return this.session.invoke({ op: 'page.evaluate', tabId: this.tab.remote.tabId, expression });
+    }
+    keyboard = {
+        press: async (key) => {
+            await this.session.invoke({ op: 'page.press', tabId: this.tab.remote.tabId, key });
+        }
+    };
+    mouse = {
+        wheel: async (x, y) => {
+            await this.session.invoke({ op: 'page.scroll', tabId: this.tab.remote.tabId, x, y });
+        }
+    };
+    async waitForTimeout(ms) {
+        await new Promise(resolve => setTimeout(resolve, Math.min(10_000, Math.max(0, ms))));
+    }
+    getByText(text) {
+        return { first: () => ({ waitFor: async ({ timeout }) => {
+                    const end = Date.now() + timeout;
+                    while (Date.now() < end) {
+                        const found = await this.session.invoke({ op: 'page.containsText', tabId: this.tab.remote.tabId, text });
+                        if (found)
+                            return;
+                        await new Promise(resolve => setTimeout(resolve, 250));
+                    }
+                    const error = new Error(`Timeout ${timeout}ms exceeded while waiting for text`);
+                    error.name = 'TimeoutError';
+                    throw error;
+                } }) };
+    }
+    getNode(target) {
+        if (target.generation !== this.tab.generation || this.tab.refsGeneration !== this.tab.generation)
+            throw new Error(`The page in ${this.id} changed since its last snapshot. Take browser_snapshot again and use a ref from it.`);
+        return target.backendDOMNodeId;
+    }
+    async locatorCall(target, method, args = {}) {
+        await this.refresh();
+        const backendDOMNodeId = this.getNode(target);
+        return this.session.invoke({ op: 'page.element', tabId: this.tab.remote.tabId, backendDOMNodeId, generation: target.generation, method, ...args });
+    }
+    async capture(options, target) {
+        await this.refresh();
+        const args = { op: 'page.screenshot', tabId: this.tab.remote.tabId, quality: Math.max(10, Math.min(95, options.quality)) };
+        if (target) {
+            args.backendDOMNodeId = this.getNode(target);
+            args.generation = target.generation;
+        }
+        const result = await this.session.invoke(args);
+        return Buffer.from(result.data, 'base64');
+    }
+}
+class BraveLocator {
+    page;
+    target;
+    constructor(page, target) {
+        this.page = page;
+        this.target = target;
+    }
+    async click(options = {}) {
+        await this.page.locatorCall({ ...this.target }, 'click', { button: options.button ?? 'left', double: false });
+    }
+    async dblclick(options = {}) {
+        await this.page.locatorCall({ ...this.target }, 'click', { button: options.button ?? 'left', double: true });
+    }
+    async screenshot(options) {
+        return this.page.capture(options, this.target);
+    }
+    async evaluate(callback) {
+        const declaration = callback.toString();
+        return this.page.locatorCall({ ...this.target }, 'evaluate', { functionDeclaration: `function(){ return (${declaration})(this) }` });
+    }
+    async fill(value) {
+        await this.page.locatorCall({ ...this.target }, 'fill', { text: value });
+    }
+    async press(key) {
+        await this.page.locatorCall({ ...this.target }, 'press', { key });
+    }
+    async selectOption(values) {
+        return this.page.locatorCall({ ...this.target }, 'select', { values });
+    }
+    async scrollIntoViewIfNeeded() {
+        await this.page.locatorCall({ ...this.target }, 'scrollIntoView');
+    }
+}

package/dist/sdk/browser/index.d.ts

@@ -2,7 +2,9 @@ import type { PluginDescriptor } from "../plugins/types.js";
 import type { WorldContext, WorldPart } from "../world/world.js";
 import type { ToolSpec } from "../tools/types.js";
 import { NetworkPolicy } from "./network.js";
-import { BrowserSession, type Launcher } from "./session.js";
+import { type Launcher } from "./session.js";
+import type { BrowserToolSession } from "./tools.js";
+import { BrowserExtensionBridge } from "./extension/bridge.js";
 export declare const BROWSER_PLUGIN: PluginDescriptor;
 /** A browser closes after this long without a call. */
 export declare const IDLE_MS: number;
@@ -12,12 +14,15 @@ export interface BrowserPartOptions {
     /** Replaces the address check in tests. */
     network?: NetworkPolicy;
     idleMs?: number;
+    extensionPort?: number;
 }
 /** Foundation-owned isolated browser engine. Plugin tools receive sessions through this interface. */
 export interface BrowserEngine {
-    sessions: Map<string, BrowserSession>;
+    sessions: Map<string, BrowserToolSession>;
+    extension: BrowserExtensionBridge;
     diagnostics: NonNullable<WorldPart['diagnostics']>;
     tools(context: WorldContext): ToolSpec[];
+    toolsForSession(session: import("../tools/types.js").ToolSession, context: WorldContext): ToolSpec[];
     release(sessionKey: string): Promise<void>;
     close(): Promise<void>;
 }

package/dist/sdk/browser/index.js

@@ -5,11 +5,13 @@ import { readBrowserConfig } from "./config.js";
 import { browserDiagnostic } from "./diagnostics.js";
 import { NetworkPolicy } from "./network.js";
 import { BrowserSession, fileName, launchBrowser } from "./session.js";
+import { BrowserExtensionBridge } from "./extension/bridge.js";
+import { BraveBrowserSession } from "./extension/session.js";
 import { BROWSER_TOOL_NAMES, browserTools } from "./tools.js";
 export const BROWSER_PLUGIN = {
     id: 'browser',
     title: 'Browser',
-    description: 'A browser the agent drives: open pages that need scripts, read them, click, type and choose. Each session has its own; sign-ins are kept per agent on this device. Sending, buying, deleting, account changes and granting access always ask you.',
+    description: 'The browser backend selected by the person: an isolated Harness profile or the connected Brave profile. Brave exposes only normal tabs on sites explicitly allowed in the extension, never Incognito; a disconnect refuses calls and never switches backends. Sending, buying, deleting, account changes and granting access always ask you.',
     manage: 'tools',
     switchable: { on: true },
     // Its tools are listed in the World group, which the Web plugin owns.
@@ -19,45 +21,76 @@ export const BROWSER_PLUGIN = {
 export const IDLE_MS = 15 * 60_000;
 export function createBrowserEngine(options) {
     const sessions = new Map();
+    const owners = new Map();
     const diagnosticKeys = new Set();
     const config = () => readBrowserConfig(options.stateDir);
     const network = options.network ?? new NetworkPolicy(config);
-    const sessionFor = (context) => {
-        let session = sessions.get(context.sessionKey);
+    const extension = new BrowserExtensionBridge({ stateDir: options.stateDir, port: options.extensionPort });
+    const releaseExact = async (key) => {
+        const session = sessions.get(key);
+        sessions.delete(key);
+        owners.delete(key);
+        await session?.close();
+        if (diagnosticKeys.delete(key))
+            rmSync(join(options.stateDir, 'browser', 'downloads', fileName(key)), { recursive: true, force: true });
+    };
+    const sessionFor = (context, backend) => {
+        const key = `${backend}:${context.sessionKey}`;
+        let session = sessions.get(key);
         if (!session) {
-            const owner = context.caller.agentId ?? context.caller.projectId ?? 'default';
-            const key = context.sessionKey;
-            const diagnostic = context.caller.surface === 'doctor';
-            if (diagnostic)
+            owners.set(key, context.sessionKey);
+            if (context.caller.surface === 'doctor') {
                 diagnosticKeys.add(key);
-            session = new BrowserSession({
-                key,
-                profileDir: diagnostic ? null : join(options.stateDir, 'browser', 'profiles', fileName(owner)),
-                downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
-                config: diagnostic ? () => ({ ...config(), cdpUrl: null, headed: false }) : config,
-                network,
-                launch: options.launch ?? launchBrowser,
-                idleMs: options.idleMs ?? IDLE_MS,
-                onIdle: () => void release(key)
-            });
+                session = new BrowserSession({
+                    key,
+                    profileDir: null,
+                    downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
+                    config: () => ({ ...config(), backend: 'isolated', cdpUrl: null, headed: false }),
+                    network,
+                    launch: options.launch ?? launchBrowser,
+                    idleMs: options.idleMs ?? IDLE_MS,
+                    onIdle: () => void releaseExact(key)
+                });
+            }
+            else if (backend === 'brave') {
+                session = new BraveBrowserSession({ bridge: extension, network, idleMs: options.idleMs ?? IDLE_MS, onIdle: () => void releaseExact(key) });
+            }
+            else {
+                const owner = context.caller.agentId ?? context.caller.projectId ?? 'default';
+                session = new BrowserSession({
+                    key,
+                    profileDir: join(options.stateDir, 'browser', 'profiles', fileName(owner)),
+                    downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
+                    config,
+                    network,
+                    launch: options.launch ?? launchBrowser,
+                    idleMs: options.idleMs ?? IDLE_MS,
+                    onIdle: () => void releaseExact(key)
+                });
+            }
             sessions.set(key, session);
         }
         return session;
     };
-    const release = async (key) => {
-        const session = sessions.get(key);
-        sessions.delete(key);
-        await session?.close();
-        if (diagnosticKeys.delete(key))
-            rmSync(join(options.stateDir, 'browser', 'downloads', fileName(key)), { recursive: true, force: true });
+    const toolsForContext = (context) => {
+        const backend = context.caller.surface !== 'doctor' && config().backend === 'brave' ? 'brave' : 'isolated';
+        const session = sessionFor(context, backend);
+        return browserTools(context, () => session);
+    };
+    const release = async (sessionKey) => {
+        const keys = [...owners.entries()].filter(([, owner]) => owner === sessionKey).map(([key]) => key);
+        await Promise.all(keys.map(releaseExact));
     };
     return {
         diagnostics: () => [browserDiagnostic(config)],
         sessions,
-        tools: (context) => browserTools(context, () => sessionFor(context)),
+        extension,
+        tools: toolsForContext,
+        toolsForSession: (_session, context) => toolsForContext(context),
         release,
         close: async () => {
-            await Promise.all([...sessions.keys()].map(release));
+            await Promise.all([...sessions.keys()].map(releaseExact));
+            await extension.close();
         }
     };
 }

package/dist/sdk/browser/serverMethods.js

@@ -2,6 +2,9 @@ import { pick } from "../server/params.js";
 export function browserServerMethods(harness) {
     return {
         'browser.config': () => harness.world.browserConfig(),
-        'browser.configure': (params) => harness.world.configureBrowser(pick(params, ['headed', 'cdpUrl', 'executablePath', 'allowPrivate', 'allowedDomains']))
+        'browser.configure': (params) => harness.world.configureBrowser(pick(params, ['backend', 'headed', 'cdpUrl', 'executablePath', 'allowPrivate', 'allowedDomains'])),
+        'browser.extension.status': () => harness.world.browserExtensionStatus(),
+        'browser.extension.start': () => harness.world.browserExtensionStart(),
+        'browser.extension.stop': () => harness.world.browserExtensionStop()
     };
 }

package/dist/sdk/browser/tools.d.ts

@@ -1,5 +1,102 @@
 import type { ToolSpec } from "../tools/types.js";
+import type { NetworkPolicy } from "./network.js";
 import type { WorldContext } from "../world/world.js";
-import type { BrowserSession } from "./session.js";
+import type { Download } from "./session.js";
 export { BROWSER_TOOL_NAMES, SNAPSHOT_LINES, SNAPSHOT_CHARS } from "./contracts.js";
-export declare function browserTools(context: WorldContext, session: () => BrowserSession): ToolSpec[];
+export interface BrowserToolElement {
+    getAttribute(name: string): string | null;
+}
+export interface BrowserToolLocator {
+    click(options?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    dblclick(options?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    screenshot(options: {
+        type: 'jpeg';
+        quality: number;
+    }): Promise<Buffer>;
+    evaluate<T>(callback: (element: BrowserToolElement) => T): Promise<T>;
+    fill(value: string): Promise<void>;
+    press(key: string): Promise<void>;
+    selectOption(values: string[]): Promise<string[]>;
+    scrollIntoViewIfNeeded(): Promise<void>;
+}
+export interface BrowserToolPage {
+    url(): string;
+    title(): Promise<string>;
+    refresh?(): Promise<void>;
+    goto(url: string, options?: {
+        waitUntil?: 'domcontentloaded';
+    }): Promise<{
+        status(): number;
+    } | null>;
+    goBack(options?: {
+        waitUntil?: 'domcontentloaded';
+    }): Promise<{
+        status(): number;
+    } | null>;
+    goForward(options?: {
+        waitUntil?: 'domcontentloaded';
+    }): Promise<{
+        status(): number;
+    } | null>;
+    reload(options?: {
+        waitUntil?: 'domcontentloaded';
+    }): Promise<{
+        status(): number;
+    } | null>;
+    close(): Promise<void>;
+    ariaSnapshot(options?: {
+        mode: 'ai';
+        depth?: number;
+        timeout?: number;
+    }): Promise<string>;
+    content(): Promise<string>;
+    screenshot(options: {
+        type: 'jpeg';
+        quality: number;
+    }): Promise<Buffer>;
+    getByRef(ref: string): BrowserToolLocator;
+    evaluate<T = unknown>(expression: string): Promise<T>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    mouse: {
+        wheel(x: number, y: number): Promise<void>;
+    };
+    waitForTimeout(ms: number): Promise<void>;
+    getByText(text: string): {
+        first(): {
+            waitFor(options: {
+                timeout: number;
+            }): Promise<void>;
+        };
+    };
+}
+export interface BrowserToolTab {
+    id: string;
+    page: BrowserToolPage;
+    generation: number;
+    refs: Map<string, string>;
+    refsGeneration: number;
+}
+export interface BrowserToolSession {
+    run<T>(work: () => Promise<T>): Promise<T>;
+    tab(id?: string | null): Promise<BrowserToolTab>;
+    open(): Promise<BrowserToolTab>;
+    select(id: string): BrowserToolTab | Promise<BrowserToolTab>;
+    list(): {
+        id: string;
+        url: string;
+        current: boolean;
+    }[];
+    refresh?(): Promise<void>;
+    readonly network: NetworkPolicy;
+    readonly downloads: Download[];
+    close(): Promise<void>;
+    readonly profileNote: string | null;
+    readonly started: boolean;
+}
+export declare function browserTools(context: WorldContext, session: () => BrowserToolSession): ToolSpec[];

package/dist/sdk/browser/tools.js

@@ -10,6 +10,7 @@ const isTimeout = (error) => error instanceof Error && (error.name === 'TimeoutE
 const UNKNOWN = 'Its outcome is unknown: take browser_snapshot before trying again, so nothing is clicked, sent or bought twice.';
 const text = (value) => (typeof value === 'string' ? value : '');
 async function where(tab) {
+    await tab.page.refresh?.();
     const title = await tab.page.title().catch(() => '');
     return `Tab ${tab.id}: ${tab.page.url()}${title ? ` — ${title}` : ''}`;
 }
@@ -30,6 +31,7 @@ async function approve(context, tool, tab, target, args) {
         return null;
     if (!context.attended || !context.run)
         return `Refused: this would ${verdict.reason}, and nobody can approve it in this run.`;
+    await tab.page.refresh?.();
     const before = { url: tab.page.url(), generation: tab.generation };
     let host = '';
     try {
@@ -41,6 +43,7 @@ async function approve(context, tool, tab, target, args) {
     const refusal = await askForAction({ run: context.run, tool, target: `${target}${host ? ` on ${host}` : ''}`, args, reason: verdict.reason });
     if (refusal)
         return refusal;
+    await tab.page.refresh?.();
     if (tab.page.url() !== before.url || tab.generation !== before.generation)
         return 'The page changed while waiting for approval, so nothing was done. Take browser_snapshot and decide again.';
     return null;
@@ -113,6 +116,7 @@ export function browserTools(context, session) {
             ...browserToolSpec('browser_read'),
             execute: (input) => act('browser_read', async () => {
                 const tab = await session().tab(text(input.tab) || null);
+                await tab.page.refresh?.();
                 const { title, text: markdown } = htmlToMarkdown(await tab.page.content());
                 const offset = Math.max(0, Math.floor(Number(input.offset)) || 0);
                 const end = Math.min(markdown.length, offset + PAGE_CHARS);
@@ -237,7 +241,7 @@ export function browserTools(context, session) {
                     return untrusted(`Opened ${await where(tab)}`);
                 }
                 if (input.op === 'switch')
-                    return untrusted(`Now in ${await where(browser.select(text(input.tab)))}`);
+                    return untrusted(`Now in ${await where(await browser.select(text(input.tab)))}`);
                 if (input.op === 'close') {
                     const tab = await browser.tab(text(input.tab) || null);
                     await tab.page.close();
@@ -245,6 +249,7 @@ export function browserTools(context, session) {
                 }
                 if (!browser.started)
                     return 'No tabs are open yet. browser_navigate opens one.';
+                await browser.refresh?.();
                 return untrusted(browser.list().map((tab) => `${tab.current ? '*' : ' '} ${tab.id} ${tab.url}`).join('\n'));
             })
         }

package/dist/sdk/commands/registry.d.ts

@@ -143,6 +143,11 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Inspect";
     readonly kind: "session";
     readonly methods: readonly ["runs.todo"];
+}, {
+    readonly name: "follow-up";
+    readonly description: "Manage queued follow-up and steering messages";
+    readonly group: "Run";
+    readonly kind: "page";
 }, {
     readonly name: "trajectory";
     readonly args: "[run-id]";

package/dist/sdk/commands/registry.js

@@ -21,6 +21,7 @@ export const CORE_COMMANDS = [
     { name: 'copy', description: 'Copy the last reply', group: 'Inspect', kind: 'local', methods: ['sessions.lastReply'] },
     { name: 'export', args: '[path.html|path.jsonl]', description: 'Export this branch to HTML or JSONL', group: 'Inspect', kind: 'session', methods: ['sessions.export', 'sessions.run'] },
     { name: 'todo', aliases: ['checklist'], description: 'Show the current todo list', group: 'Inspect', kind: 'session', methods: ['runs.todo'] },
+    { name: 'follow-up', description: 'Manage queued follow-up and steering messages', group: 'Run', kind: 'page' },
     { name: 'trajectory', args: '[run-id]', description: 'Inspect recorded runs for this session', group: 'Inspect', kind: 'page', methods: ['runs.list', 'runs.events'] },
     { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness', kind: 'session', methods: ['sessions.reload'] },
     { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness', kind: 'page', methods: ['accounts.list'] },

package/dist/sdk/harness.d.ts

@@ -33,6 +33,10 @@ import type { WorktreesOptions } from "./worktrees/types.js";
 export interface HarnessOptions {
     /** Disable the generic backend when a host supplies its own browser tools. */
     browser?: boolean;
+    /** Enables the Brave extension bridge when a host supplies its own isolated browser. */
+    browserExtension?: {
+        port?: number;
+    };
     hub?: HubOptions;
     /** Where knowledge and history live. May be set later with `open`. */
     dataRoot?: string | null;