@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/browser/session.js

@@ -0,0 +1,228 @@
+// One live browser for one session: an isolated profile, numbered tabs, and the refs of each
+// tab's latest snapshot. Calls run one at a time; the browser starts on first use and closes when
+// the session ends or sits idle.
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Any name as a file or folder name: other characters become `_`. */
+export const fileName = (name) => name.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '_').slice(0, 100) || '_';
+export const VIEWPORT = { width: 1280, height: 800 };
+export const ACTION_TIMEOUT_MS = 15_000;
+export const NAVIGATION_TIMEOUT_MS = 30_000;
+function isClosedBrowserError(error) {
+    return error instanceof Error && /Target page, context or browser has been closed|browser has been closed|context has been closed/i.test(error.message);
+}
+export const launchBrowser = async ({ profileDir, downloads, config }) => {
+    const { chromium } = await import('playwright-core');
+    if (config.cdpUrl) {
+        // A browser a person runs: we open our own context in it and never close the browser itself.
+        const browser = await chromium.connectOverCDP(config.cdpUrl);
+        const context = await browser.newContext({ viewport: VIEWPORT, acceptDownloads: true });
+        return { context, browser, attached: true };
+    }
+    const options = { headless: !config.headed, viewport: VIEWPORT, acceptDownloads: true, downloadsPath: downloads };
+    const attempts = config.executablePath ? [{ executablePath: config.executablePath }] : [{ channel: 'chrome' }, { channel: 'msedge' }, {}];
+    let last = null;
+    for (const attempt of attempts) {
+        try {
+            const context = profileDir
+                ? await chromium.launchPersistentContext(profileDir, { ...options, ...attempt })
+                : await (await chromium.launch({ ...options, ...attempt })).newContext({ viewport: VIEWPORT, acceptDownloads: true });
+            return { context, browser: context.browser(), attached: false };
+        }
+        catch (error) {
+            last = error;
+        }
+    }
+    throw new Error(`No browser could be started. Install Google Chrome, or run \`npx playwright install chromium\`. (${last instanceof Error ? last.message.split('\n')[0] : String(last)})`);
+};
+export class BrowserSession {
+    options;
+    closed = false;
+    context = null;
+    browser = null;
+    attached = false;
+    starting = null;
+    tabs = new Map();
+    current = null;
+    nextTab = 1;
+    queue = Promise.resolve();
+    idle = null;
+    temporaryProfile = null;
+    downloads = [];
+    /** Set when the kept profile was in use and a throwaway one was opened instead. */
+    profileNote = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Runs `work` after every earlier call of this session has finished. */
+    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.options.idleMs);
+        this.idle.unref?.();
+    }
+    async start() {
+        if (this.closed)
+            throw new Error('The browser session has ended.');
+        if (this.context)
+            return;
+        this.starting ??= (async () => {
+            mkdirSync(this.options.downloadsDir, { recursive: true });
+            let launched;
+            try {
+                launched = await this.options.launch({ profileDir: this.options.profileDir, downloads: this.options.downloadsDir, config: this.options.config() });
+            }
+            catch (error) {
+                // Another session holds the kept profile: work in a throwaway one rather than wait.
+                if (!this.options.profileDir || !/ProcessSingleton|already in use|lock/i.test(String(error)))
+                    throw error;
+                this.temporaryProfile = mkdtempSync(join(tmpdir(), `harness-browser-${fileName(this.options.key)}-`));
+                launched = await this.options.launch({ profileDir: this.temporaryProfile, downloads: this.options.downloadsDir, config: this.options.config() });
+                this.profileNote = 'The saved browser profile is in use by another session, so this one started without its sign-ins.';
+            }
+            this.context = launched.context;
+            this.browser = launched.browser;
+            this.attached = launched.attached;
+            const context = launched.context;
+            context.on('close', () => this.forget(context));
+            launched.browser?.on('disconnected', () => this.forget(context));
+            context.setDefaultTimeout(ACTION_TIMEOUT_MS);
+            context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+            await context.route('**/*', async (route) => {
+                const refusal = await this.options.network.refusal(route.request().url());
+                if (refusal)
+                    await route.abort('blockedbyclient');
+                else
+                    await route.continue();
+            });
+            context.on('page', (page) => this.adopt(page));
+            for (const page of context.pages())
+                this.adopt(page);
+        })();
+        try {
+            await this.starting;
+            if (this.closed)
+                throw new Error('The browser session has ended.');
+        }
+        finally {
+            this.starting = null;
+        }
+    }
+    adopt(page) {
+        const existing = [...this.tabs.values()].find((tab) => tab.page === page);
+        if (existing)
+            return existing;
+        const tab = { id: `t${this.nextTab++}`, page, generation: 0, refs: new Map(), refsGeneration: -1 };
+        this.tabs.set(tab.id, tab);
+        this.current ??= tab.id;
+        page.on('framenavigated', (frame) => {
+            if (frame === page.mainFrame())
+                tab.generation += 1;
+        });
+        page.on('close', () => {
+            this.tabs.delete(tab.id);
+            if (this.current === tab.id)
+                this.current = this.tabs.keys().next().value ?? null;
+        });
+        page.on('download', (download) => {
+            const name = fileName(download.suggestedFilename() || 'download');
+            const path = join(this.options.downloadsDir, `${Date.now()}-${name}`);
+            void download.saveAs(path).then(() => this.downloads.push({ tab: tab.id, path, name })).catch(() => undefined);
+        });
+        return tab;
+    }
+    forget(context) {
+        if (this.context !== context)
+            return;
+        this.context = null;
+        this.browser = null;
+        this.attached = false;
+        this.tabs.clear();
+        this.current = null;
+    }
+    /** A tab by id, or the current one, starting the browser and opening a first tab when needed. */
+    async tab(id) {
+        await this.start();
+        if (id) {
+            const tab = this.tabs.get(id);
+            if (!tab)
+                throw new Error(`There is no tab ${id}. browser_tabs lists them.`);
+            return tab;
+        }
+        if (this.current && this.tabs.has(this.current))
+            return this.tabs.get(this.current);
+        return this.open();
+    }
+    async open() {
+        let lastClosedError;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            await this.start();
+            const context = this.context;
+            if (!context)
+                continue;
+            try {
+                const page = await context.newPage();
+                if (this.context !== context) {
+                    await page.close().catch(() => undefined);
+                    continue;
+                }
+                const tab = this.adopt(page);
+                this.current = tab.id;
+                return tab;
+            }
+            catch (error) {
+                if (attempt !== 0 || !isClosedBrowserError(error))
+                    throw error;
+                lastClosedError = error;
+                this.forget(context);
+                await context.close().catch(() => undefined);
+            }
+        }
+        throw lastClosedError ?? new Error('The browser closed while opening a page.');
+    }
+    select(id) {
+        const tab = this.tabs.get(id);
+        if (!tab)
+            throw new Error(`There is no tab ${id}.`);
+        this.current = id;
+        return tab;
+    }
+    list() {
+        return [...this.tabs.values()].map((tab) => ({ id: tab.id, url: tab.page.url(), current: tab.id === this.current }));
+    }
+    /** What pages in this browser may reach. */
+    get network() {
+        return this.options.network;
+    }
+    get currentId() {
+        return this.current;
+    }
+    get started() {
+        return this.context !== null;
+    }
+    async close() {
+        this.closed = true;
+        await this.starting?.catch(() => undefined);
+        if (this.idle)
+            clearTimeout(this.idle);
+        const { context, browser, attached } = this;
+        this.context = null;
+        this.browser = null;
+        this.tabs.clear();
+        this.current = null;
+        await context?.close().catch(() => undefined);
+        // An attached browser belongs to a person: only our context goes.
+        if (!attached)
+            await browser?.close().catch(() => undefined);
+        if (this.temporaryProfile)
+            rmSync(this.temporaryProfile, { recursive: true, force: true });
+        this.temporaryProfile = null;
+    }
+}

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

@@ -0,0 +1,102 @@
+import type { ToolSpec } from "../tools/types.js";
+import type { NetworkPolicy } from "./network.js";
+import type { WorldContext } from "../world/world.js";
+import type { Download } from "./session.js";
+export { BROWSER_TOOL_NAMES, SNAPSHOT_LINES, SNAPSHOT_CHARS } from "./contracts.js";
+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

@@ -0,0 +1,257 @@
+import { askForAction, classifyAction, SENSITIVE_FIELD } from "../world/actions.js";
+import { untrusted } from "../world/untrusted.js";
+import { htmlToMarkdown } from "../web/markdown.js";
+import { PAGE_CHARS } from "../web/tools.js";
+export { BROWSER_TOOL_NAMES, SNAPSHOT_LINES, SNAPSHOT_CHARS } from "./contracts.js";
+import { SNAPSHOT_LINES, SNAPSHOT_CHARS } from "./contracts.js";
+import { browserToolSpec } from "./backend.js";
+const message = (error) => (error instanceof Error ? error.message.split('\n')[0] : String(error));
+const isTimeout = (error) => error instanceof Error && (error.name === 'TimeoutError' || /Timeout \d+ms exceeded/.test(error.message));
+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}` : ''}`;
+}
+/** An element named by a ref of the tab's latest snapshot. */
+function element(tab, ref) {
+    const id = ref.trim().replace(/^@/, '').replace(/^ref=/, '');
+    if (tab.refsGeneration !== tab.generation)
+        throw new Error(`The page in ${tab.id} changed since its last snapshot. Take browser_snapshot again and use a ref from it.`);
+    const line = tab.refs.get(id);
+    if (!line)
+        throw new Error(`There is no ref ${id} in the latest snapshot of ${tab.id}. Take browser_snapshot again.`);
+    return { locator: tab.page.getByRef(id), line };
+}
+/** Asks the person when the action falls in a category that needs them; null when it may go ahead. */
+async function approve(context, tool, tab, target, args) {
+    const verdict = classifyAction(target);
+    if (!verdict)
+        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 {
+        host = new URL(before.url).host;
+    }
+    catch {
+        host = before.url;
+    }
+    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;
+}
+function attendedOnly(context, tool) {
+    return context.attended && !context.subagent ? null : `${tool} acts on a page and needs a person present; in this run the browser can only open and read pages.`;
+}
+export function browserTools(context, session) {
+    const act = (name, work) => session().run(async () => {
+        try {
+            return await work();
+        }
+        catch (error) {
+            return isTimeout(error) ? `${name} timed out. ${UNKNOWN}` : `${name} failed: ${message(error)}`;
+        }
+    });
+    const done = async (tab, what) => {
+        const downloads = session().downloads.filter((download) => download.tab === tab.id).splice(0).map((download) => download.path);
+        return untrusted(`${what}\n${await where(tab)}${downloads.length ? `\nDownloaded: ${downloads.join(', ')}` : ''}\nTake browser_snapshot to see the page now.`);
+    };
+    return [
+        {
+            ...browserToolSpec('browser_navigate'),
+            execute: (input) => act('browser_navigate', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const action = text(input.action) || 'open';
+                if (action === 'back')
+                    await tab.page.goBack({ waitUntil: 'domcontentloaded' });
+                else if (action === 'forward')
+                    await tab.page.goForward({ waitUntil: 'domcontentloaded' });
+                else if (action === 'reload')
+                    await tab.page.reload({ waitUntil: 'domcontentloaded' });
+                else {
+                    const url = text(input.url).trim();
+                    if (!url)
+                        return 'Give the address to open.';
+                    const refusal = await session().network.refusal(url);
+                    if (refusal)
+                        return refusal;
+                    const response = await tab.page.goto(url, { waitUntil: 'domcontentloaded' });
+                    if (response && response.status() >= 400)
+                        return untrusted(`The page answered with status ${response.status()}.\n${await where(tab)}`);
+                }
+                const note = session().profileNote;
+                return untrusted(`${await where(tab)}${note ? `\n${note}` : ''}\nTake browser_snapshot to see what is on it, or browser_read for its text.`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_snapshot'),
+            execute: (input) => act('browser_snapshot', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const depth = Number(input.depth);
+                const snapshot = await tab.page.ariaSnapshot({ mode: 'ai', ...(Number.isInteger(depth) && depth > 0 ? { depth } : {}), timeout: 15_000 });
+                tab.refs = new Map();
+                for (const line of snapshot.split('\n')) {
+                    const ref = /\[ref=([a-z0-9]+)\]/i.exec(line)?.[1];
+                    if (ref)
+                        tab.refs.set(ref, line.trim().replace(/^- /, '').slice(0, 240));
+                }
+                tab.refsGeneration = tab.generation;
+                const lines = snapshot.split('\n');
+                let shown = lines.slice(0, SNAPSHOT_LINES).join('\n');
+                const cut = lines.length > SNAPSHOT_LINES || shown.length > SNAPSHOT_CHARS;
+                if (shown.length > SNAPSHOT_CHARS)
+                    shown = shown.slice(0, SNAPSHOT_CHARS);
+                return untrusted(`${await where(tab)}\n\n${shown}${cut ? `\n\n(The snapshot was cut at ${SNAPSHOT_LINES} lines. Pass a smaller depth, scroll, or use browser_read for the text.)` : ''}`);
+            })
+        },
+        {
+            ...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);
+                const more = end < markdown.length ? `\n\n(More: call browser_read with offset ${end}.)` : '';
+                return untrusted(`Tab ${tab.id}: ${tab.page.url()}${title ? ` — ${title}` : ''}\nCharacters ${offset}–${end} of ${markdown.length}\n\n${markdown.slice(offset, end)}${more}`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_screenshot'),
+            execute: (input) => act('browser_screenshot', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const ref = text(input.ref);
+                const shot = ref ? await element(tab, ref).locator.screenshot({ type: 'jpeg', quality: 70 }) : await tab.page.screenshot({ type: 'jpeg', quality: 70 });
+                return { text: untrusted(`Screenshot of ${ref ? `element ${ref} in ` : ''}${await where(tab)}`), image: { data: shot.toString('base64'), mimeType: 'image/jpeg' } };
+            })
+        },
+        {
+            ...browserToolSpec('browser_click'),
+            execute: async (input) => attendedOnly(context, 'browser_click') ?? act('browser_click', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const { locator, line } = element(tab, text(input.ref));
+                const refusal = await approve(context, 'browser_click', tab, line, input);
+                if (refusal)
+                    return refusal;
+                const button = input.button === 'right' || input.button === 'middle' ? input.button : 'left';
+                if (input.double === true)
+                    await locator.dblclick({ button });
+                else
+                    await locator.click({ button });
+                return done(tab, `Clicked ${line}.`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_type'),
+            execute: async (input) => attendedOnly(context, 'browser_type') ?? act('browser_type', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const { locator, line } = element(tab, text(input.ref));
+                const secret = SENSITIVE_FIELD.test(line) || await locator.evaluate(field => field.getAttribute('type') === 'password' || /cc-|one-time-code|current-password|new-password/.test(field.getAttribute('autocomplete') ?? '')).catch(() => false);
+                if (secret)
+                    return 'That field takes a password, a card number or a code. Ask the user to fill it themselves.';
+                if (input.submit === true) {
+                    const refusal = await approve(context, 'browser_type', tab, `submit ${line}`, { ...input, text: `[${text(input.text).length} characters]` });
+                    if (refusal)
+                        return refusal;
+                }
+                await locator.fill(text(input.text));
+                if (input.submit === true)
+                    await locator.press('Enter');
+                return done(tab, `Typed ${text(input.text).length} characters into ${line}${input.submit === true ? ' and submitted' : ''}.`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_select'),
+            execute: async (input) => attendedOnly(context, 'browser_select') ?? act('browser_select', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const { locator, line } = element(tab, text(input.ref));
+                const values = Array.isArray(input.values) ? input.values.filter((value) => typeof value === 'string') : [];
+                const chosen = await locator.selectOption(values);
+                return done(tab, `Chose ${chosen.join(', ') || 'nothing'} in ${line}.`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_press'),
+            execute: async (input) => attendedOnly(context, 'browser_press') ?? act('browser_press', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                const key = text(input.key).trim();
+                if (/(^|\+)Enter$/i.test(key)) {
+                    // Runs in the page: what has focus, and whether Enter there would send something.
+                    const focused = await tab.page.evaluate(`(() => {
+            const node = document.activeElement
+            if (!node) return ''
+            const sends = node.tagName === 'TEXTAREA' || node.isContentEditable || !!node.closest('form')
+            return sends ? 'submit ' + (node.getAttribute('aria-label') || node.getAttribute('placeholder') || node.tagName.toLowerCase()) + ' form' : ''
+          })()`).then((value) => String(value ?? '')).catch(() => '');
+                    if (focused) {
+                        const refusal = await approve(context, 'browser_press', tab, `${focused} (send)`, input);
+                        if (refusal)
+                            return refusal;
+                    }
+                }
+                await tab.page.keyboard.press(key);
+                return done(tab, `Pressed ${key}.`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_scroll'),
+            execute: (input) => act('browser_scroll', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                if (text(input.ref))
+                    await element(tab, text(input.ref)).locator.scrollIntoViewIfNeeded();
+                else
+                    await tab.page.mouse.wheel(0, input.direction === 'up' ? -650 : 650);
+                return untrusted(`Scrolled. ${await where(tab)}`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_wait'),
+            execute: (input) => act('browser_wait', async () => {
+                const tab = await session().tab(text(input.tab) || null);
+                if (text(input.text)) {
+                    await tab.page.getByText(text(input.text)).first().waitFor({ timeout: 30_000 });
+                    return untrusted(`"${text(input.text)}" is on the page. ${await where(tab)}`);
+                }
+                await tab.page.waitForTimeout(Math.min(10_000, Math.max(1, Math.floor(Number(input.ms)) || 1000)));
+                return untrusted(`Waited. ${await where(tab)}`);
+            })
+        },
+        {
+            ...browserToolSpec('browser_tabs'),
+            execute: (input) => act('browser_tabs', async () => {
+                const browser = session();
+                if (input.op === 'new') {
+                    const url = text(input.url).trim();
+                    if (url) {
+                        const refusal = await browser.network.refusal(url);
+                        if (refusal)
+                            return refusal;
+                    }
+                    const tab = await browser.open();
+                    if (url)
+                        await tab.page.goto(url, { waitUntil: 'domcontentloaded' });
+                    return untrusted(`Opened ${await where(tab)}`);
+                }
+                if (input.op === 'switch')
+                    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();
+                    return `Closed ${tab.id}.`;
+                }
+                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/capabilities/api.d.ts

@@ -0,0 +1,22 @@
+import type { Harness } from "../harness.js";
+import type { CallerContext } from "../core/caller.js";
+import type { Launch } from "../prompt/compile.js";
+import * as pluginApi from "../plugins/api.js";
+import type { CapabilityCatalogue, CapabilityScope, CapabilitySet } from "./types.js";
+export interface ListParams extends CapabilityScope {
+}
+export interface InventoryParams extends CapabilityScope {
+    context?: CallerContext;
+    launch?: Launch;
+    tools?: string[];
+    connections?: boolean;
+}
+export declare function list(harness: Harness, params?: ListParams): Promise<CapabilityCatalogue>;
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export declare function resolve(harness: Harness, params: ListParams & {
+    tools?: readonly string[];
+}): Promise<CapabilitySet>;
+export declare function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools?: readonly string[]): CapabilitySet;
+export declare function inventory(harness: Harness, params?: InventoryParams): Promise<import("../index.js").Inventory>;
+export declare function attach(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue>;
+export declare function switchCapability(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue>;

package/dist/sdk/capabilities/api.js

@@ -0,0 +1,54 @@
+// A generic view of what is available to a caller. The existing plugin, registry, and connector
+// stores remain the source of truth; this module gives hosts one capability-shaped contract.
+import { invalid } from "../core/errors.js";
+import * as pluginApi from "../plugins/api.js";
+const unique = (values) => [...new Set(values.filter((value) => value.length > 0))];
+function contributions(plugins) {
+    return plugins.flatMap((plugin) => plugin.contributions.map((item) => ({
+        id: item.id,
+        pluginId: plugin.id,
+        kind: item.kind,
+        name: item.name,
+        description: item.description,
+        source: plugin.source,
+        state: item.state,
+        attachment: item.attachment
+    })));
+}
+export async function list(harness, params = {}) {
+    const plugins = await pluginApi.list(harness, params);
+    return { plugins, capabilities: contributions(plugins) };
+}
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export async function resolve(harness, params) {
+    const caller = { agentId: params.agentId ?? null, projectId: params.projectId ?? null };
+    const catalogue = await list(harness, params);
+    const connectors = harness.apps.connections.forScope(caller).map((connection) => connection.id);
+    return {
+        version: 1,
+        tools: unique(params.tools ?? []),
+        connectors: unique(connectors),
+        contributions: catalogue.capabilities.filter((item) => item.state === 'on').map((item) => item.id)
+    };
+}
+export function toolIntersection(parent, assignee, taskTools) {
+    const permitted = taskTools === undefined ? null : new Set(taskTools);
+    return {
+        version: 1,
+        tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && (!permitted || permitted.has(tool))),
+        connectors: parent.connectors.filter((id) => assignee.connectors.includes(id)),
+        contributions: parent.contributions.filter((id) => assignee.contributions.includes(id))
+    };
+}
+export function inventory(harness, params = {}) {
+    return pluginApi.inventoryFor(harness, params);
+}
+export async function attach(harness, params, on) {
+    const plugins = await pluginApi.attach(harness, params, on);
+    return { plugins, capabilities: contributions(plugins) };
+}
+export async function switchCapability(harness, params, on) {
+    if (!params.id.trim())
+        throw invalid('A capability id is required.');
+    return attach(harness, params, on);
+}