@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/annotations/store.js

@@ -0,0 +1,386 @@
+// Page notes (PROP-0017): what a person wrote about a whole web page, a quoted passage or an element
+// of it. One JSON file per note under `<data root>/annotations/`, changed only with the version the
+// caller last saw. A note is private until a person shares it with a session or an agent; the
+// model can only read notes shared with it.
+import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { newId, now, readJson, safeId, writeJson } from "../core/fs.js";
+export const MAX_NOTES = 10_000;
+const MAX_HISTORY = 100;
+const codepoints = (value) => Array.from(value).length;
+function bounded(value, max, required, field) {
+    if (typeof value !== 'string' || codepoints(value) > max || (required && !value.trim()))
+        throw invalid(`Invalid note ${field}.`);
+    return value;
+}
+export function validateUrl(value) {
+    const text = bounded(value, 4096, true, 'URL');
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw invalid('Invalid note URL.');
+    }
+    const authority = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(text)?.[1] ?? null;
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password || authority === null || authority.includes('@') || /[\s\p{Cc}]/u.test(text)) {
+        throw invalid('Note URLs must be HTTP(S) without credentials.');
+    }
+    return text;
+}
+const APP_SCHEMES = new Set(['http:', 'https:', 'file:', 'app:', 'tauri:', 'electron:', 'asset:']);
+/** An app window's address: web addresses, plus the local schemes desktop apps load from. Never credentials. */
+export function validateAppUrl(value) {
+    const text = bounded(value, 4096, true, 'URL');
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw invalid('Invalid note URL.');
+    }
+    if (!APP_SCHEMES.has(url.protocol) || url.username || url.password || /[\s\p{Cc}]/u.test(text))
+        throw invalid('An app note URL must be a web, file or app address without credentials.');
+    return text;
+}
+function validateApp(app) {
+    if (app == null)
+        return null;
+    const value = app;
+    if (value.kind !== 'cdp' && value.kind !== 'bridge')
+        throw invalid('A note app is attached through cdp or a bridge.');
+    return { kind: value.kind, name: bounded(value.name, 200, true, 'app name') };
+}
+function validateSource(source) {
+    if (!source || typeof source !== 'object')
+        throw invalid('A note needs its source page.');
+    const value = source;
+    const app = validateApp(value.app);
+    return {
+        url: app ? validateAppUrl(value.url) : validateUrl(value.url),
+        ...(app ? { app } : {}),
+        title: bounded(value.title ?? '', 200, false, 'title'),
+        capturedAt: typeof value.capturedAt === 'string' && value.capturedAt ? value.capturedAt : now(),
+        ...(value.surface != null ? { surface: bounded(value.surface, 200, true, 'surface') } : {}),
+        ...(value.representationHint != null ? { representationHint: bounded(value.representationHint, 128, true, 'representation hint') } : {})
+    };
+}
+export function validateTarget(target) {
+    if (!target || typeof target !== 'object')
+        throw invalid('A note needs a target.');
+    const value = target;
+    const keys = Object.keys(value).sort().join(',');
+    if (value.kind === 'page') {
+        if (keys !== 'kind')
+            throw invalid('Invalid page target.');
+        return { kind: 'page' };
+    }
+    if (value.kind === 'text') {
+        if (keys !== 'end,exact,kind,prefix,start,suffix')
+            throw invalid('Invalid text target.');
+        const exact = bounded(value.exact, 4000, true, 'exact text');
+        const prefix = bounded(value.prefix, 128, false, 'text prefix');
+        const suffix = bounded(value.suffix, 128, false, 'text suffix');
+        const start = value.start;
+        const end = value.end;
+        // Offsets count Unicode code points of the page's normalised text, not UTF-16 units.
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start || end - start !== codepoints(exact)) {
+            throw invalid('Note text offsets do not match the exact text.');
+        }
+        return { kind: 'text', exact, prefix, suffix, start: start, end: end };
+    }
+    if (value.kind === 'element') {
+        if (keys !== 'context,kind,name,role,selector,tag,text')
+            throw invalid('Invalid element target.');
+        const element = {
+            kind: 'element',
+            tag: bounded(value.tag, 40, true, 'element tag'),
+            role: bounded(value.role, 80, false, 'element role'),
+            name: bounded(value.name, 200, false, 'element name'),
+            text: bounded(value.text, 500, false, 'element text'),
+            context: bounded(value.context, 200, false, 'element context'),
+            selector: bounded(value.selector, 500, false, 'element selector')
+        };
+        if (!element.name.trim() && !element.text.trim())
+            throw invalid('An element note needs a meaningful name or text.');
+        return element;
+    }
+    throw invalid('A note target is a page, text or an element.');
+}
+function normalizeBody(body) {
+    return bounded(typeof body === 'string' ? body.trim() : body, 10_000, true, 'body');
+}
+function normalizeTags(tags) {
+    if (tags === undefined)
+        return [];
+    if (!Array.isArray(tags) || tags.length > 12)
+        throw invalid('A note takes at most 12 tags.');
+    return [...new Set(tags.map((tag) => bounded(typeof tag === 'string' ? tag.trim() : tag, 40, true, 'tag')))];
+}
+function validatePrincipal(principal) {
+    const value = (principal ?? {});
+    const result = {};
+    if (typeof value.sessionId === 'string' && value.sessionId)
+        result.sessionId = safeId(value.sessionId);
+    if (typeof value.agentId === 'string' && value.agentId)
+        result.agentId = safeId(value.agentId);
+    if (!result.sessionId === !result.agentId)
+        throw invalid('Share a note with exactly one session or one agent.');
+    return result;
+}
+const samePrincipal = (left, right) => left.sessionId === right.sessionId && left.agentId === right.agentId;
+/** Whether a caller may read a note through the model tools. */
+export function visibleTo(note, caller) {
+    return note.grants.some((grant) => (grant.principal.sessionId && grant.principal.sessionId === caller.sessionId) ||
+        (grant.principal.agentId && grant.principal.agentId === caller.agentId));
+}
+export function notesDir(root) {
+    return join(root, 'annotations');
+}
+function folder(root) {
+    const dir = notesDir(root);
+    if (existsSync(dir) && (lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory()))
+        throw new HarnessError('invalid_data', 'Note storage must be a plain folder.');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function file(root, id) {
+    return join(folder(root), `${safeId(id)}.json`);
+}
+function validNote(note, id) {
+    if (!note || note.id !== id || note.author !== 'user' || !Number.isSafeInteger(note.version) || note.version < 1 || !Array.isArray(note.grants) || !Array.isArray(note.history)) {
+        throw new HarnessError('invalid_data', `Note ${id} is not a valid note.`);
+    }
+    return note;
+}
+export function read(root, id) {
+    const path = file(root, id);
+    if (!existsSync(path))
+        throw notFound('Note');
+    if (lstatSync(path).isSymbolicLink())
+        throw new HarnessError('invalid_data', 'Note records must not be links.');
+    return validNote(readJson(path), id);
+}
+function all(root) {
+    const notes = [];
+    for (const name of readdirSync(folder(root))) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            notes.push(read(root, name.slice(0, -'.json'.length)));
+        }
+        catch {
+            // A damaged file is skipped, never shown as a note.
+        }
+    }
+    return notes;
+}
+function matchingNotes(root, filter) {
+    const query = filter.query?.trim().toLowerCase();
+    return all(root)
+        .filter((note) => !filter.url || note.source.url === filter.url)
+        .filter((note) => !filter.status || note.status === filter.status)
+        .filter((note) => !query || [note.body, note.source.title, note.source.url, ...note.tags, note.target.kind === 'text' ? note.target.exact : note.target.kind === 'element' ? note.target.name : ''].join('\n').toLowerCase().includes(query))
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.id.localeCompare(right.id));
+}
+/** All matching notes for internal consumers that paginate after applying their own visibility filter. */
+export function listAll(root, filter = {}) {
+    return matchingNotes(root, filter);
+}
+export function list(root, filter = {}) {
+    const matching = matchingNotes(root, filter);
+    const offset = Math.max(0, Math.floor(filter.offset ?? 0));
+    const limit = Math.max(1, Math.min(200, Math.floor(filter.limit ?? 50)));
+    return { notes: matching.slice(offset, offset + limit), total: matching.length };
+}
+function save(root, note, operation) {
+    note.version += 1;
+    note.updatedAt = now();
+    note.history.push({ version: note.version, operation, at: note.updatedAt });
+    if (note.history.length > MAX_HISTORY)
+        note.history.splice(0, note.history.length - MAX_HISTORY);
+    writeJson(file(root, note.id), note);
+    return note;
+}
+function current(root, id, expectedVersion) {
+    const note = read(root, id);
+    if (expectedVersion !== undefined && note.version !== expectedVersion)
+        throw new HarnessError('version_conflict', 'The note changed. Read it again before saving.');
+    return note;
+}
+export function create(root, input) {
+    const source = validateSource(input?.source);
+    const target = validateTarget(input?.target);
+    const body = normalizeBody(input?.body);
+    const tags = normalizeTags(input?.tags);
+    if (readdirSync(folder(root)).filter((name) => name.endsWith('.json')).length >= MAX_NOTES) {
+        throw new HarnessError('annotation_limit', `At most ${MAX_NOTES} notes may be kept.`);
+    }
+    const at = now();
+    const note = { id: newId(), version: 1, source, target, body, tags, status: 'open', author: 'user', createdAt: at, updatedAt: at, grants: [], history: [{ version: 1, operation: 'create', at }] };
+    writeJson(file(root, note.id), note);
+    return note;
+}
+export function update(root, id, expectedVersion, patch) {
+    const note = current(root, id, expectedVersion);
+    if (patch.body !== undefined)
+        note.body = normalizeBody(patch.body);
+    if (patch.tags !== undefined)
+        note.tags = normalizeTags(patch.tags);
+    if (patch.status !== undefined) {
+        if (patch.status !== 'open' && patch.status !== 'resolved')
+            throw invalid('A note is open or resolved.');
+        note.status = patch.status;
+        if (patch.status === 'resolved' && note.delivery?.state === 'queued')
+            note.delivery = null;
+    }
+    if (patch.target !== undefined)
+        note.target = validateTarget(patch.target);
+    return save(root, note, 'update');
+}
+export function remove(root, id, expectedVersion) {
+    current(root, id, expectedVersion);
+    rmSync(file(root, id));
+}
+/** A person lets one session or agent read the note through the model tools. */
+export function share(root, id, principal, binding = null) {
+    const who = validatePrincipal(principal);
+    const note = current(root, id, undefined);
+    note.grants = note.grants.filter((grant) => !samePrincipal(grant.principal, who));
+    note.grants.push({ principal: who, ...(binding ? { binding: bounded(binding, 200, true, 'binding') } : {}), grantedAt: now() });
+    return save(root, note, 'share');
+}
+export function unshare(root, id, principal) {
+    const who = validatePrincipal(principal);
+    const note = current(root, id, undefined);
+    note.grants = note.grants.filter((grant) => !samePrincipal(grant.principal, who));
+    return save(root, note, 'unshare');
+}
+/** The host withdrew what a binding stood for (a tab closed or was shared again): every grant made with it ends. */
+export function revokeBinding(root, binding) {
+    bounded(binding, 200, true, 'binding');
+    let changed = 0;
+    for (const note of all(root)) {
+        if (!note.grants.some((grant) => grant.binding === binding))
+            continue;
+        note.grants = note.grants.filter((grant) => grant.binding !== binding);
+        save(root, note, 'revoke_binding');
+        changed += 1;
+    }
+    return changed;
+}
+/** Takes notes another store kept, keeping their ids. A note whose id exists is skipped. */
+export function importNotes(root, notes) {
+    const imported = [];
+    const skipped = [];
+    for (const raw of Array.isArray(notes) ? notes : []) {
+        const value = (raw ?? {});
+        const id = typeof value.id === 'string' ? value.id : null;
+        try {
+            if (!id)
+                throw invalid('A note needs an id.');
+            safeId(id);
+            if (existsSync(file(root, id))) {
+                skipped.push({ id, reason: 'exists' });
+                continue;
+            }
+            const at = now();
+            const note = {
+                id,
+                version: 1,
+                source: validateSource(value.source),
+                target: validateTarget(value.target),
+                body: normalizeBody(value.body),
+                tags: normalizeTags(value.tags),
+                status: value.status === 'resolved' ? 'resolved' : 'open',
+                author: 'user',
+                createdAt: typeof value.createdAt === 'string' ? value.createdAt : at,
+                updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : at,
+                grants: Array.isArray(value.grants) ? value.grants.map((grant) => {
+                    const entry = (grant ?? {});
+                    return { principal: validatePrincipal(entry.principal), ...(typeof entry.binding === 'string' && entry.binding ? { binding: entry.binding } : {}), grantedAt: typeof entry.grantedAt === 'string' ? entry.grantedAt : at };
+                }) : [],
+                history: [{ version: 1, operation: 'import', at }]
+            };
+            writeJson(file(root, id), note);
+            imported.push(id);
+        }
+        catch (error) {
+            skipped.push({ id, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { imported, skipped };
+}
+// ---- Delivery to an agent (PROP-0018) ----------------------------------------------------------
+/**
+ * A person asks a session to act on the note: it is shared with that session (if it was not) and
+ * waits in the session's queue until it is sent.
+ */
+export function queue(root, id, expectedVersion, sessionId, options = {}) {
+    const session = safeId(sessionId);
+    const note = current(root, id, expectedVersion);
+    if (note.status === 'resolved')
+        throw invalid('Reopen this note before queueing it.');
+    if (!note.grants.some((grant) => grant.principal.sessionId === session))
+        note.grants.push({ principal: { sessionId: session }, grantedAt: now() });
+    const confirmationRequired = options.confirm === true || (note.delivery?.confirm === true && options.confirmed !== true);
+    note.delivery = {
+        state: 'queued',
+        sessionId: session,
+        queuedAt: now(),
+        ...(options.autoSend ? { autoSend: true } : {}),
+        ...(confirmationRequired ? { confirm: true } : {})
+    };
+    return save(root, note, 'queue');
+}
+/** Takes the note out of the queue. It stays shared; unshare withdraws that. */
+export function dequeue(root, id, expectedVersion) {
+    const note = current(root, id, expectedVersion);
+    if (note.delivery?.state !== 'queued')
+        throw invalid('This note is not waiting to be sent.');
+    note.delivery = null;
+    return save(root, note, 'dequeue');
+}
+/** The notes waiting for one session, oldest first. `auto` keeps only those to send when it is idle. */
+export function queued(root, sessionId, filter = {}) {
+    const ids = filter.ids ? new Set(filter.ids) : null;
+    return all(root)
+        .filter((note) => note.status === 'open' && note.delivery?.state === 'queued' && note.delivery.sessionId === sessionId)
+        .filter((note) => !filter.auto || (note.delivery?.autoSend === true && note.delivery.confirm !== true))
+        .filter((note) => !ids || ids.has(note.id))
+        .sort((left, right) => (left.delivery.queuedAt).localeCompare(right.delivery.queuedAt) || left.id.localeCompare(right.id));
+}
+/** The notes went to the session as part of `runId`. */
+export function markSent(root, ids, sessionId, runId) {
+    const session = safeId(sessionId);
+    const run = safeId(runId);
+    const notes = [...new Set(ids)].map((id) => current(root, id, undefined));
+    for (const note of notes) {
+        if (note.status !== 'open')
+            throw invalid('Resolved notes cannot be sent.');
+        if (note.delivery?.state !== 'queued' || note.delivery.sessionId !== session)
+            throw invalid('This note is not queued for this session.');
+        if (note.delivery.confirm)
+            throw invalid('Confirm this note before sending it.');
+    }
+    return notes.map((note) => {
+        note.delivery = { ...note.delivery, state: 'sent', sessionId: session, sentAt: now(), runId: run };
+        delete note.delivery.autoSend;
+        delete note.delivery.confirm;
+        return save(root, note, 'deliver');
+    });
+}
+/** The agent says it acted on a note shared with it. The note stays open until a person resolves it. */
+export function markFixed(root, id, caller, summary) {
+    const note = current(root, id, undefined);
+    if (!visibleTo(note, caller))
+        throw notFound('Note');
+    const sessionId = note.delivery?.sessionId ?? caller.sessionId ?? note.grants.find((grant) => grant.principal.sessionId)?.principal.sessionId;
+    if (!sessionId)
+        throw invalid('This note was never sent to a session.');
+    note.delivery = { ...(note.delivery ?? { queuedAt: now() }), state: 'fixed', sessionId, fixedAt: now(), summary: bounded(summary.trim(), 2000, true, 'summary') };
+    delete note.delivery.autoSend;
+    delete note.delivery.confirm;
+    return save(root, note, 'mark_fixed');
+}

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

@@ -0,0 +1,16 @@
+export interface BrowserConfig {
+    /** Show the browser window instead of running it headless. */
+    headed: boolean;
+    /** Attach to a browser a person already runs (its DevTools address) instead of launching one. */
+    cdpUrl: string | null;
+    /** A browser program to launch; otherwise Chrome, then Edge, then Playwright's Chromium. */
+    executablePath: string | null;
+    /** Let pages reach this machine and private networks (local development servers). */
+    allowPrivate: boolean;
+    /** When set, pages may only reach these sites (and their subdomains). */
+    allowedDomains: string[];
+}
+export declare const DEFAULT_BROWSER_CONFIG: BrowserConfig;
+export declare const configPath: (stateDir: string) => string;
+export declare function readBrowserConfig(stateDir: string): BrowserConfig;
+export declare function writeBrowserConfig(stateDir: string, change: Partial<BrowserConfig>): BrowserConfig;

package/dist/sdk/browser/config.js

@@ -0,0 +1,22 @@
+// How the harness's browser runs, kept on this device: `<state dir>/browser.json`. Only a person
+// (through a command or the application) writes it; no tool argument can point the browser at
+// another endpoint or profile.
+import { join } from 'node:path';
+import { readJsonOr, writeJson } from "../core/fs.js";
+export const DEFAULT_BROWSER_CONFIG = { headed: false, cdpUrl: null, executablePath: null, allowPrivate: false, allowedDomains: [] };
+export const configPath = (stateDir) => join(stateDir, 'browser.json');
+export function readBrowserConfig(stateDir) {
+    const saved = readJsonOr(configPath(stateDir), {});
+    return {
+        headed: saved.headed === true,
+        cdpUrl: typeof saved.cdpUrl === 'string' && /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/.test(saved.cdpUrl) ? saved.cdpUrl : null,
+        executablePath: typeof saved.executablePath === 'string' && saved.executablePath.trim() ? saved.executablePath : null,
+        allowPrivate: saved.allowPrivate === true,
+        allowedDomains: Array.isArray(saved.allowedDomains) ? saved.allowedDomains.filter((domain) => typeof domain === 'string' && /^[a-z0-9.-]+$/i.test(domain)).map((domain) => domain.toLowerCase()) : []
+    };
+}
+export function writeBrowserConfig(stateDir, change) {
+    const next = { ...readBrowserConfig(stateDir), ...change };
+    writeJson(configPath(stateDir), next);
+    return readBrowserConfig(stateDir);
+}

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

@@ -0,0 +1,4 @@
+import type { BrowserConfig } from "./config.js";
+import type { DoctorCheck } from "../doctor/types.js";
+/** Exercises the production tool path against a synthetic page in a throwaway profile. */
+export declare function browserDiagnostic(configure: () => BrowserConfig): DoctorCheck;

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/index.d.ts

@@ -0,0 +1,28 @@
+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";
+export declare const BROWSER_PLUGIN: PluginDescriptor;
+/** A browser closes after this long without a call. */
+export declare const IDLE_MS: number;
+export interface BrowserPartOptions {
+    stateDir: string;
+    launch?: Launcher;
+    /** Replaces the address check in tests. */
+    network?: NetworkPolicy;
+    idleMs?: number;
+}
+/** Foundation-owned isolated browser engine. Plugin tools receive sessions through this interface. */
+export interface BrowserEngine {
+    sessions: Map<string, BrowserSession>;
+    diagnostics: NonNullable<WorldPart['diagnostics']>;
+    tools(context: WorldContext): ToolSpec[];
+    release(sessionKey: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createBrowserEngine(options: BrowserPartOptions): BrowserEngine;
+/** Plugin adapter that exposes the Foundation engine's checked browser tools to a session. */
+export declare function browserPluginPart(engine: BrowserEngine): WorldPart;
+/** Combined adapter retained for direct browser tests and embedders that construct a WorldPart. */
+export declare function browserPart(options: BrowserPartOptions): WorldPart & Pick<BrowserEngine, 'sessions' | 'release' | 'close'>;

package/dist/sdk/browser/index.js

@@ -0,0 +1,72 @@
+// Foundation owns the isolated browser engine; the Browser plugin exposes its user-facing tools.
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { readBrowserConfig } from "./config.js";
+import { browserDiagnostic } from "./diagnostics.js";
+import { NetworkPolicy } from "./network.js";
+import { BrowserSession, fileName, launchBrowser } from "./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.',
+    manage: 'tools',
+    switchable: { on: true },
+    // Its tools are listed in the World group, which the Web plugin owns.
+    tools: BROWSER_TOOL_NAMES.map((name) => ({ name }))
+};
+/** A browser closes after this long without a call. */
+export const IDLE_MS = 15 * 60_000;
+export function createBrowserEngine(options) {
+    const sessions = 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);
+        if (!session) {
+            const owner = context.caller.agentId ?? context.caller.projectId ?? 'default';
+            const key = context.sessionKey;
+            const diagnostic = context.caller.surface === 'doctor';
+            if (diagnostic)
+                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)
+            });
+            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 });
+    };
+    return {
+        diagnostics: () => [browserDiagnostic(config)],
+        sessions,
+        tools: (context) => browserTools(context, () => sessionFor(context)),
+        release,
+        close: async () => {
+            await Promise.all([...sessions.keys()].map(release));
+        }
+    };
+}
+/** Plugin adapter that exposes the Foundation engine's checked browser tools to a session. */
+export function browserPluginPart(engine) {
+    return { plugin: BROWSER_PLUGIN, diagnostics: engine.diagnostics, tools: context => engine.tools(context) };
+}
+/** Combined adapter retained for direct browser tests and embedders that construct a WorldPart. */
+export function browserPart(options) {
+    const engine = createBrowserEngine(options);
+    return { ...browserPluginPart(engine), sessions: engine.sessions, release: engine.release, close: engine.close };
+}

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

@@ -0,0 +1,10 @@
+import type { BrowserConfig } from "./config.js";
+export declare class NetworkPolicy {
+    private readonly config;
+    private readonly resolve;
+    private readonly hosts;
+    constructor(config: () => BrowserConfig, resolve?: (host: string) => Promise<string[]>);
+    /** Why an address may not be loaded, or null when it may. */
+    refusal(address: string): Promise<string | null>;
+    private isPublic;
+}

package/dist/sdk/browser/network.js

@@ -0,0 +1,59 @@
+// What a page in the harness's browser may reach. The same rule as `web_fetch`: public addresses
+// only, unless a person allowed private ones for local development. This filters the browser's
+// requests; it is a guard, not a sandbox (a page's own DNS can still differ from ours).
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { isPublicAddress } from "../web/safeRequest.js";
+const OPEN_SCHEMES = new Set(['data:', 'blob:', 'about:']);
+const CACHE_MS = 60_000;
+export class NetworkPolicy {
+    config;
+    resolve;
+    hosts = new Map();
+    constructor(config, resolve = async (host) => (await lookup(host, { all: true, verbatim: true })).map((entry) => entry.address)) {
+        this.config = config;
+        this.resolve = resolve;
+    }
+    /** Why an address may not be loaded, or null when it may. */
+    async refusal(address) {
+        let url;
+        try {
+            url = new URL(address);
+        }
+        catch {
+            return 'That is not a web address.';
+        }
+        if (OPEN_SCHEMES.has(url.protocol))
+            return null;
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return `${url.protocol} addresses cannot be opened.`;
+        if (url.username || url.password)
+            return 'Addresses with a username or password cannot be opened.';
+        const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        const { allowedDomains, allowPrivate } = this.config();
+        if (allowedDomains.length && !allowedDomains.some((domain) => host === domain || host.endsWith(`.${domain}`)))
+            return `${host} is not among the sites this browser may reach.`;
+        if (allowPrivate)
+            return null;
+        return (await this.isPublic(host)) ? null : `${host} is not a public address. A person can allow private addresses in the browser settings.`;
+    }
+    async isPublic(host) {
+        if (isIP(host))
+            return isPublicAddress(host);
+        if (host === 'localhost' || host.endsWith('.localhost'))
+            return false;
+        const cached = this.hosts.get(host);
+        if (cached && Date.now() - cached.at < CACHE_MS)
+            return cached.ok;
+        let ok = false;
+        try {
+            const addresses = await this.resolve(host);
+            ok = addresses.length > 0 && addresses.every(isPublicAddress);
+        }
+        catch {
+            ok = false;
+        }
+        this.hosts.set(host, { at: Date.now(), ok });
+        return ok;
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function browserServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/browser/serverMethods.js

@@ -0,0 +1,7 @@
+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']))
+    };
+}