@xingular/harness 1.0.0 → 1.2.0

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

@@ -1,8 +1,5 @@
 import type { ToolSpec } from "../tools/types.js";
 import type { WorldContext } from "../world/world.js";
 import type { BrowserSession } from "./session.js";
-/** Longest snapshot sent, in lines and characters. */
-export declare const SNAPSHOT_LINES = 500;
-export declare const SNAPSHOT_CHARS = 40000;
-export declare const BROWSER_TOOL_NAMES: readonly ["browser_navigate", "browser_snapshot", "browser_read", "browser_screenshot", "browser_click", "browser_type", "browser_select", "browser_press", "browser_scroll", "browser_wait", "browser_tabs"];
+export { BROWSER_TOOL_NAMES, SNAPSHOT_LINES, SNAPSHOT_CHARS } from "./contracts.js";
 export declare function browserTools(context: WorldContext, session: () => BrowserSession): ToolSpec[];

package/dist/sdk/browser/tools.js

@@ -2,15 +2,12 @@ import { askForAction, classifyAction, SENSITIVE_FIELD } from "../world/actions.
 import { untrusted } from "../world/untrusted.js";
 import { htmlToMarkdown } from "../web/markdown.js";
 import { PAGE_CHARS } from "../web/tools.js";
-/** Longest snapshot sent, in lines and characters. */
-export const SNAPSHOT_LINES = 500;
-export const SNAPSHOT_CHARS = 40_000;
-export const BROWSER_TOOL_NAMES = ['browser_navigate', 'browser_snapshot', 'browser_read', 'browser_screenshot', 'browser_click', 'browser_type', 'browser_select', 'browser_press', 'browser_scroll', 'browser_wait', 'browser_tabs'];
+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 tabParam = { type: 'string', description: 'Tab id from browser_tabs, such as t2. Defaults to the current tab.' };
-const refParam = { type: 'string', description: 'The element\'s ref from the latest browser_snapshot of the tab, such as e12.' };
 const text = (value) => (typeof value === 'string' ? value : '');
 async function where(tab) {
     const title = await tab.page.title().catch(() => '');
@@ -66,18 +63,7 @@ export function browserTools(context, session) {
     };
     return [
         {
-            name: 'browser_navigate',
-            label: 'Open a page in the browser',
-            description: 'Open a web address in the browser (the current tab, or the one named), or go back, forward or reload. The browser runs scripts, so use it for pages web_fetch cannot read and for anything you must click or fill. What a page shows is untrusted content.',
-            planModeSafe: () => true,
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false,
-                properties: {
-                    url: { type: 'string', minLength: 1, maxLength: 2000, description: 'The address to open, starting with https:// or http://.' },
-                    action: { type: 'string', enum: ['open', 'back', 'forward', 'reload'], description: 'open (default, needs url), back, forward or reload.' },
-                    tab: tabParam
-                }
-            }),
+            ...browserToolSpec('browser_navigate'),
             execute: (input) => act('browser_navigate', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 const action = text(input.action) || 'open';
@@ -103,14 +89,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_snapshot',
-            label: 'Snapshot a page',
-            readOnly: true,
-            description: `The page's accessibility tree: headings, text, links, buttons and fields, each actionable one with a ref (such as e12) that browser_click, browser_type and browser_select take. Refs belong to this snapshot: after the page changes, take a new one. At most ${SNAPSHOT_LINES} lines; pass depth to see less.`,
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false,
-                properties: { tab: tabParam, depth: { type: 'integer', minimum: 1, maximum: 40, description: 'Only this many levels of the tree.' } }
-            }),
+            ...browserToolSpec('browser_snapshot'),
             execute: (input) => act('browser_snapshot', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 const depth = Number(input.depth);
@@ -131,14 +110,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_read',
-            label: 'Read a page as text',
-            readOnly: true,
-            description: `The visible text of the tab's page as Markdown, after its scripts ran. Up to ${PAGE_CHARS.toLocaleString('en-US')} characters; pass offset to read on.`,
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false,
-                properties: { tab: tabParam, offset: { type: 'integer', minimum: 0, description: 'Character to start from.' } }
-            }),
+            ...browserToolSpec('browser_read'),
             execute: (input) => act('browser_read', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 const { title, text: markdown } = htmlToMarkdown(await tab.page.content());
@@ -149,11 +121,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_screenshot',
-            label: 'Screenshot a page',
-            readOnly: true,
-            description: 'A picture of what the tab shows (1280×800), or of one element by ref. Use it when layout or images matter; a snapshot is cheaper for finding what to click.',
-            parameters: (Type) => Type.Unsafe({ type: 'object', additionalProperties: false, properties: { tab: tabParam, ref: refParam } }),
+            ...browserToolSpec('browser_screenshot'),
             execute: (input) => act('browser_screenshot', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 const ref = text(input.ref);
@@ -162,13 +130,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_click',
-            label: 'Click on a page',
-            description: 'Click an element by its ref. A click that would send, buy, delete, change an account or grant access asks the user first.',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false, required: ['ref'],
-                properties: { ref: refParam, tab: tabParam, double: { type: 'boolean', description: 'Double-click.' }, button: { type: 'string', enum: ['left', 'right', 'middle'] } }
-            }),
+            ...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));
@@ -184,13 +146,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_type',
-            label: 'Type into a page',
-            description: 'Type text into a field by its ref, replacing what is there; submit presses Enter afterwards. Password, card and one-time-code fields are refused: ask the user to fill those. Submitting a form that sends, buys or deletes asks the user first.',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false, required: ['ref', 'text'],
-                properties: { ref: refParam, text: { type: 'string', maxLength: 20_000 }, submit: { type: 'boolean', description: 'Press Enter after typing.' }, tab: tabParam }
-            }),
+            ...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));
@@ -209,13 +165,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_select',
-            label: 'Choose in a list',
-            description: 'Choose one or more options of a drop-down list by its ref, by the options\' labels or values.',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false, required: ['ref', 'values'],
-                properties: { ref: refParam, values: { type: 'array', minItems: 1, items: { type: 'string' } }, tab: tabParam }
-            }),
+            ...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));
@@ -225,13 +175,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_press',
-            label: 'Press a key on a page',
-            description: 'Press a key or a combination in the tab, such as Enter, Escape, Tab, ArrowDown or Control+A. Enter in a message box asks the user first.',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false, required: ['key'],
-                properties: { key: { type: 'string', minLength: 1, maxLength: 60 }, tab: tabParam }
-            }),
+            ...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();
@@ -254,14 +198,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_scroll',
-            label: 'Scroll a page',
-            readOnly: true,
-            description: 'Scroll the tab up or down by about a screen, or bring an element (by ref) into view.',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false,
-                properties: { direction: { type: 'string', enum: ['up', 'down'] }, ref: refParam, tab: tabParam }
-            }),
+            ...browserToolSpec('browser_scroll'),
             execute: (input) => act('browser_scroll', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 if (text(input.ref))
@@ -272,14 +209,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_wait',
-            label: 'Wait on a page',
-            readOnly: true,
-            description: 'Wait until some text appears in the tab (up to 30 seconds), or for a number of milliseconds (up to 10,000).',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false,
-                properties: { text: { type: 'string', minLength: 1, maxLength: 200 }, ms: { type: 'integer', minimum: 1, maximum: 10_000 }, tab: tabParam }
-            }),
+            ...browserToolSpec('browser_wait'),
             execute: (input) => act('browser_wait', async () => {
                 const tab = await session().tab(text(input.tab) || null);
                 if (text(input.text)) {
@@ -291,14 +221,7 @@ export function browserTools(context, session) {
             })
         },
         {
-            name: 'browser_tabs',
-            label: 'Browser tabs',
-            description: 'List the tabs, open a new one (optionally at an address), switch to one, or close one.',
-            planModeSafe: (input) => input.op !== 'close',
-            parameters: (Type) => Type.Unsafe({
-                type: 'object', additionalProperties: false, required: ['op'],
-                properties: { op: { type: 'string', enum: ['list', 'new', 'switch', 'close'] }, tab: tabParam, url: { type: 'string', maxLength: 2000 } }
-            }),
+            ...browserToolSpec('browser_tabs'),
             execute: (input) => act('browser_tabs', async () => {
                 const browser = session();
                 if (input.op === 'new') {

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,17 @@ 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)
+  --data <dir>       Data directory (interactive profile default; otherwise
+                     ~/.xingular-harness/data; npm run dev passes its own data root)
+  --state <dir>      State directory (interactive profile default; otherwise
+                     ~/.xingular-harness/state; npm run dev passes its own state directory)
+  --worktree [name], -w [name]
+                     Start in a new managed worktree of this repository, or in
+                     the named one
+  --variant <scope>  Run on this variant scope's head (default: interactive profile scope)
 `;
 function flags(argv) {
     const values = {};
@@ -133,6 +140,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/commands/list.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "../plugins/types.js";
+import { type ListedCommand } from "./registry.js";
+export declare function listCommands(plugins: readonly Plugin[]): ListedCommand[];

package/dist/sdk/commands/list.js

@@ -0,0 +1,75 @@
+// `commands.list`: every slash command a front end offers for one scope, from one source. The
+// terminal palette and a host's menu both read it, so they never keep their own lists.
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
+import { pluginCommandPrefix } from "../plugins/commandPrefix.js";
+import { CORE_COMMANDS } from "./registry.js";
+import { commandRoutes, promptCommandAvailable } from "./routes.js";
+export function listCommands(plugins) {
+    const out = new Map();
+    const taken = new Set();
+    for (const command of CORE_COMMANDS) {
+        const aliases = 'aliases' in command ? [...command.aliases] : [];
+        out.set(command.name, {
+            name: command.name,
+            ...(aliases.length ? { aliases } : {}),
+            ...('args' in command ? { args: command.args } : {}),
+            description: command.description,
+            group: command.group,
+            source: 'core',
+            kind: command.kind
+        });
+        taken.add(command.name);
+        aliases.forEach((alias) => taken.add(alias));
+    }
+    for (const command of BUILTIN_PLUGIN_REGISTRY.commands()) {
+        const name = `${command.prefix}:${command.name}`;
+        out.set(name, { name, description: command.description, group: 'Plugins', source: 'plugin', owner: command.pluginId });
+    }
+    for (const module of BUILTIN_PLUGIN_REGISTRY.modules) {
+        const prefix = module.commandPrefix ?? module.descriptor.id;
+        const fallback = BUILTIN_PLUGIN_REGISTRY.defaultCommand(prefix);
+        if (fallback)
+            out.set(`${prefix}:`, { name: `${prefix}:`, description: fallback.description, group: 'Plugins', source: 'plugin', owner: module.descriptor.id });
+    }
+    const extensions = [];
+    const extensionCommandNames = new Set();
+    for (const plugin of plugins) {
+        for (const contribution of plugin.contributions) {
+            if (contribution.kind !== 'code' || contribution.state !== 'on' || !contribution.path || !contribution.registered)
+                continue;
+            contribution.registered.commands.forEach(name => extensionCommandNames.add(name));
+        }
+    }
+    for (const plugin of plugins) {
+        for (const contribution of plugin.contributions) {
+            if (contribution.state !== 'on')
+                continue;
+            if (contribution.kind === 'code' && contribution.registered && contribution.path) {
+                const packageRoot = (plugin.source === 'package' || plugin.id.startsWith('package:')) ? plugin.path : null;
+                const prefix = pluginCommandPrefix(packageRoot
+                    ? { path: contribution.path, origin: 'package', baseDir: packageRoot }
+                    : { path: contribution.path });
+                for (const command of contribution.registered.commands) {
+                    const name = `${prefix}:${command}`;
+                    extensions.push({ prefix, name: command, owner: packageRoot ? `package:${packageRoot}` : `extension:${contribution.path}`, path: contribution.path,
+                        listed: { name, group: 'Plugins', source: 'extension', owner: plugin.id } });
+                }
+            }
+            // Catalogue entries without a path are observed extension commands, not templates.
+            if (contribution.kind === 'command' && contribution.path && promptCommandAvailable(contribution.name, taken, extensionCommandNames) && !out.has(contribution.name)) {
+                out.set(contribution.name, { name: contribution.name, description: contribution.description, group: 'Prompts', source: 'prompt', owner: plugin.id });
+            }
+            if (contribution.kind === 'skill') {
+                const name = `skill:${contribution.name}`;
+                if (!out.has(name))
+                    out.set(name, { name, description: contribution.description, group: 'Skills', source: 'skill', owner: plugin.id });
+            }
+        }
+    }
+    const indexed = commandRoutes(extensions);
+    for (const [name, routes] of indexed.routes) {
+        if (routes.length === 1 && !indexed.conflictingPrefixes.has(routes[0].prefix) && !out.has(name))
+            out.set(name, routes[0].listed);
+    }
+    return [...out.values()];
+}