@xingular/harness 1.0.0 → 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/index.d.ts

@@ -1,5 +1,6 @@
 import type { PluginDescriptor } from "../plugins/types.js";
-import type { WorldPart } from "../world/world.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;
@@ -12,6 +13,16 @@ export interface BrowserPartOptions {
     network?: NetworkPolicy;
     idleMs?: number;
 }
-export declare function browserPart(options: BrowserPartOptions): WorldPart & {
+/** 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

@@ -1,5 +1,4 @@
-// The browser, as one part of the harness's world tools: a plugin a person can switch off, and one
-// live browser per session.
+// 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";
@@ -18,7 +17,7 @@ export const BROWSER_PLUGIN = {
 };
 /** A browser closes after this long without a call. */
 export const IDLE_MS = 15 * 60_000;
-export function browserPart(options) {
+export function createBrowserEngine(options) {
     const sessions = new Map();
     const diagnosticKeys = new Set();
     const config = () => readBrowserConfig(options.stateDir);
@@ -53,7 +52,6 @@ export function browserPart(options) {
             rmSync(join(options.stateDir, 'browser', 'downloads', fileName(key)), { recursive: true, force: true });
     };
     return {
-        plugin: BROWSER_PLUGIN,
         diagnostics: () => [browserDiagnostic(config)],
         sessions,
         tools: (context) => browserTools(context, () => sessionFor(context)),
@@ -63,3 +61,12 @@ export function browserPart(options) {
         }
     };
 }
+/** 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/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']))
+    };
+}

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

@@ -67,6 +67,7 @@ export declare class BrowserSession {
     private touch;
     private start;
     private adopt;
+    private forget;
     /** A tab by id, or the current one, starting the browser and opening a first tab when needed. */
     tab(id?: string | null): Promise<Tab>;
     open(): Promise<Tab>;

package/dist/sdk/browser/session.js

@@ -9,6 +9,9 @@ export const fileName = (name) => name.replace(/[^A-Za-z0-9._-]/g, '_').replace(
 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) {
@@ -87,17 +90,20 @@ export class BrowserSession {
             this.context = launched.context;
             this.browser = launched.browser;
             this.attached = launched.attached;
-            this.context.setDefaultTimeout(ACTION_TIMEOUT_MS);
-            this.context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-            await this.context.route('**/*', async (route) => {
+            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();
             });
-            this.context.on('page', (page) => this.adopt(page));
-            for (const page of this.context.pages())
+            context.on('page', (page) => this.adopt(page));
+            for (const page of context.pages())
                 this.adopt(page);
         })();
         try {
@@ -132,6 +138,15 @@ export class BrowserSession {
         });
         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();
@@ -146,10 +161,31 @@ export class BrowserSession {
         return this.open();
     }
     async open() {
-        await this.start();
-        const tab = this.adopt(await this.context.newPage());
-        this.current = tab.id;
-        return tab;
+        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);

package/dist/sdk/cli.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-// The `xharness` command.
+// The `xagent` command.
 //
-//   xharness serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]…
-//                  [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
+//   xagent serve --state <dir> [--data <dir>] [--name <product>] [--builtins <dir>]…
+//                [--host-secrets] [--host-policy] [--host-tools] [--host-directory]
 //       Serves the harness to a host process over stdin/stdout (newline-delimited JSON).
-//   xharness wiki <command>     Project notes, skills and history, from inside a terminal session.
-//   xharness refine <command>   Refine a variant from evidence (refine demo needs no model).
-//   xharness mcp <command>      Connected apps, from inside a terminal session.
-//   xharness plugins <command>  List, install, switch and trust plugins.
-//   xharness web <command>      Search keys for web_search.
-//   xharness browser <command>  How the agent's browser runs.
+//   xagent wiki <command>     Project notes, skills and history, from inside a terminal session.
+//   xagent refine <command>   Refine a variant from evidence (refine demo needs no model).
+//   xagent mcp <command>      Connected apps, from inside a terminal session.
+//   xagent plugins <command>  List, install, switch and trust plugins.
+//   xagent web <command>      Search keys for web_search.
+//   xagent browser <command>  How the agent's browser runs.
+//   xagent worktree <command> Managed git worktrees of the repository you are in.
 import { resolve } from 'node:path';
 import manifest from "../../package.json" with { type: 'json' };
 import { log } from "./core/bus.js";
@@ -23,8 +24,9 @@ import { RpcPeer, stdioTransport } from "./server/rpc.js";
 import { attach } from "./server/serve.js";
 import { runAppsCli, runWikiCli } from "./terminal/cli.js";
 import { runStandaloneTerminal, standaloneArguments } from "./terminal/standalone.js";
-const USAGE = `Usage: xharness [--data <dir>] [--state <dir>]
-       xharness <terminal | serve | wiki | mcp | plugins | hub | refine | web | browser> [arguments]
+import { runWorktreeCli } from "./worktrees/cli.js";
+const USAGE = `Usage: xagent [--data <dir>] [--state <dir>]
+       xagent <terminal | serve | wiki | mcp | plugins | hub | refine | web | browser | worktree> [arguments]
 
   --version          Print the package version
   (no command)       Start the interactive Harness terminal
@@ -39,12 +41,16 @@ const USAGE = `Usage: xharness [--data <dir>] [--state <dir>]
   refine <command>   Refine a harness from evidence (refine demo, refine run)
   web <command>      Search keys for the web tools (web help)
   browser <command>  How the agent's browser runs (browser help)
+  worktree <command> Managed git worktrees (worktree help)
 
 Standalone terminal options:
   --data <dir>       Data directory (installed default: ~/.xingular-harness/data;
                      npm run dev default: ~/.xingular-harness-dev/data)
   --state <dir>      State directory (installed default: ~/.xingular-harness/state;
                      npm run dev default: ~/.xingular-harness-dev/state)
+  --worktree [name], -w [name]
+                     Start in a new managed worktree of this repository, or in
+                     the named one
 `;
 function flags(argv) {
     const values = {};
@@ -133,6 +139,8 @@ async function main() {
         return runWebCli(rest);
     if (command === 'browser')
         return runBrowserCli(rest);
+    if (command === 'worktree')
+        return runWorktreeCli(rest);
     process.stdout.write(USAGE);
     return command ? 2 : 0;
 }

package/dist/sdk/core/bus.js

@@ -36,7 +36,7 @@ export function logLine(text) {
 export function redactLogText(text) {
     return text
         .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
-        .replace(/(["']?(?:authorization|proxy-authorization|cookie|set-cookie|x-[\w-]*(?:token|key)|[\w-]*(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|client[_-]?secret))["']?\s*[:=]\s*["']?)[^"'\s,;]+/gi, '$1[redacted]')
+        .replace(/(["']?(?:authorization|proxy-authorization|cookie|set-cookie|x-[\w-]{0,64}(?:token|key)|[\w-]{0,64}(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|client[_-]?secret))["']?\s*[:=]\s*["']?)[^"'\s,;]+/gi, '$1[redacted]')
         .replace(/\b(?:sk|sess)-[A-Za-z0-9_-]{16,}\b/gi, '[redacted]')
         .replace(/\bhttps?:\/\/[^\s"'<>]+/gi, (raw) => {
         const punctuation = /[),.;!?]+$/.exec(raw)?.[0] ?? '';

package/dist/sdk/core/env.d.ts

@@ -6,7 +6,7 @@ export interface Directory {
     sessionAgent(sessionId: string): string | null;
 }
 /** The name used when an application gives none. */
-export declare const DEFAULT_PRODUCT_NAME = "Xingular Harness";
+export declare const DEFAULT_PRODUCT_NAME = "Xingular Agent";
 export declare const EMPTY_DIRECTORY: Directory;
 export interface HarnessEnv {
     /** The data root: `wiki/`, `registry/`, `runs/`, `config/`, `index.sqlite`. */

package/dist/sdk/core/env.js

@@ -1,7 +1,7 @@
 // What every harness module is given: where the data lives, and what the embedding application
 // knows that the harness does not.
 /** The name used when an application gives none. */
-export const DEFAULT_PRODUCT_NAME = 'Xingular Harness';
+export const DEFAULT_PRODUCT_NAME = 'Xingular Agent';
 export const EMPTY_DIRECTORY = { agentName: () => null, sessionAgent: () => null };
 export function createEnv(root, options = {}) {
     return { root, directory: options.directory ?? EMPTY_DIRECTORY, productName: options.productName ?? DEFAULT_PRODUCT_NAME };

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

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