@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,299 @@
+/** Where a command's work happens. */
+export type CoreCommandKind = 
+/** Changes or reads the current session through a Harness method. */
+'session'
+/** Opens a capability page (doctor, worktrees, tools, ...). */
+ | 'page'
+/** Presentation only: help, key bindings, copying, showing thinking, leaving. */
+ | 'local';
+export type CoreCommandGroup = 'Core' | 'Run' | 'Model' | 'Session' | 'Inspect' | 'Harness';
+export interface CoreCommand {
+    name: string;
+    aliases?: readonly string[];
+    /** What follows the name, for the palette: `<brief>`, `[path]`. */
+    args?: string;
+    description: string;
+    group: CoreCommandGroup;
+    kind: CoreCommandKind;
+    /** The Harness server methods the command uses, when it uses any. */
+    methods?: readonly string[];
+}
+export declare const CORE_COMMANDS: readonly [{
+    readonly name: "help";
+    readonly description: "List the commands";
+    readonly group: "Core";
+    readonly kind: "local";
+}, {
+    readonly name: "plan";
+    readonly args: "[brief]";
+    readonly description: "Plan one request, read-only: /plan <brief>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "goal";
+    readonly args: "[<objective>|edit|pause|resume|clear]";
+    readonly description: "Set or view a goal for a long-running task: /goal <objective>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "btw";
+    readonly aliases: readonly ["side"];
+    readonly args: "[question]";
+    readonly description: "Ask a side question without interrupting: /btw <question>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sideQuestions.start", "sideQuestions.cancel"];
+}, {
+    readonly name: "new";
+    readonly description: "Start a new session";
+    readonly group: "Session";
+    readonly kind: "session";
+}, {
+    readonly name: "stop";
+    readonly description: "Stop the current reply";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["runs.interrupt"];
+}, {
+    readonly name: "session";
+    readonly aliases: readonly ["resume"];
+    readonly args: "[path]";
+    readonly description: "Choose a saved session in this account and folder";
+    readonly group: "Session";
+    readonly kind: "session";
+}, {
+    readonly name: "history";
+    readonly aliases: readonly ["tree"];
+    readonly description: "Navigate branches in the current session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.tree", "sessions.navigate"];
+}, {
+    readonly name: "fork";
+    readonly description: "Fork from an earlier message";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.tree", "sessions.fork"];
+}, {
+    readonly name: "remote-control";
+    readonly aliases: readonly ["rc"];
+    readonly args: "[off|tailscale|lan]";
+    readonly description: "Continue this session from your phone or iPad";
+    readonly group: "Session";
+    readonly kind: "page";
+    readonly methods: readonly ["terminal.remoteControl.start", "terminal.remoteControl.stop", "terminal.remoteControl.status"];
+}, {
+    readonly name: "clone";
+    readonly description: "Clone this branch into a new session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.clone"];
+}, {
+    readonly name: "model";
+    readonly args: "[search]";
+    readonly description: "Choose the model";
+    readonly group: "Model";
+    readonly kind: "session";
+    readonly methods: readonly ["accounts.models"];
+}, {
+    readonly name: "effort";
+    readonly args: "[level]";
+    readonly description: "Choose the thinking effort";
+    readonly group: "Model";
+    readonly kind: "session";
+}, {
+    readonly name: "thinking";
+    readonly args: "[show|hide]";
+    readonly description: "Toggle transcript thinking visibility: /thinking [show|hide]";
+    readonly group: "Model";
+    readonly kind: "local";
+}, {
+    readonly name: "name";
+    readonly args: "[name]";
+    readonly description: "Name this session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.rename"];
+}, {
+    readonly name: "compact";
+    readonly args: "[instructions]";
+    readonly description: "Compact the context";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "copy";
+    readonly description: "Copy the last reply";
+    readonly group: "Inspect";
+    readonly kind: "local";
+    readonly methods: readonly ["sessions.lastReply"];
+}, {
+    readonly name: "export";
+    readonly args: "[path.html|path.jsonl]";
+    readonly description: "Export this branch to HTML or JSONL";
+    readonly group: "Inspect";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.export", "sessions.run"];
+}, {
+    readonly name: "todo";
+    readonly aliases: readonly ["checklist"];
+    readonly description: "Show the current todo list";
+    readonly group: "Inspect";
+    readonly kind: "session";
+    readonly methods: readonly ["runs.todo"];
+}, {
+    readonly name: "follow-up";
+    readonly description: "Manage queued follow-up and steering messages";
+    readonly group: "Run";
+    readonly kind: "page";
+}, {
+    readonly name: "trajectory";
+    readonly args: "[run-id]";
+    readonly description: "Inspect recorded runs for this session";
+    readonly group: "Inspect";
+    readonly kind: "page";
+    readonly methods: readonly ["runs.list", "runs.events"];
+}, {
+    readonly name: "reload";
+    readonly description: "Reload trusted resources and keybindings";
+    readonly group: "Harness";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.reload"];
+}, {
+    readonly name: "accounts";
+    readonly description: "Sign in, switch, check and remove Pi accounts";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["accounts.list"];
+}, {
+    readonly name: "permissions";
+    readonly description: "Full Permission and per-tool approvals";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["approvals.get"];
+}, {
+    readonly name: "harness";
+    readonly description: "Browse foundation, variant and all resources";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "skills";
+    readonly description: "View, inspect and use skills; discover more";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "connections";
+    readonly description: "Manage local and remote MCP connections";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "mcp";
+    readonly description: "Open Connections in the Harness browser";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "tools";
+    readonly description: "Inspect available tools, owners and approvals";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "plugins";
+    readonly description: "Manage local plugins, packages, trust and settings";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["plugins.list", "plugins.attach", "plugins.detach", "plugins.trust", "plugins.untrust", "plugins.configure", "plugins.install", "plugins.update", "plugins.remove", "hub.list"];
+}, {
+    readonly name: "hub";
+    readonly description: "Browse the Community catalog and manage Hub installs";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["hub.list", "hub.install", "hub.uninstall"];
+}, {
+    readonly name: "components";
+    readonly description: "Browse skills, prompts and rules for this Harness scope";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "variant";
+    readonly args: "[use|restore|tag|untag|diff|revert]";
+    readonly description: "Versions of this variant: switch, restore, tag, compare, take components back";
+    readonly group: "Harness";
+    readonly kind: "session";
+    readonly methods: readonly ["variants.lineage", "variants.compare", "variants.restore", "variants.tag", "variants.untag", "variants.revert"];
+}, {
+    readonly name: "refine";
+    readonly args: "[guidance|status|review|stop]";
+    readonly description: "Improve this variant by replaying your last request: /refine <what to look at>";
+    readonly group: "Harness";
+    readonly kind: "session";
+    readonly methods: readonly ["refine.fromRun", "refine.start", "refine.list", "refine.cancel", "refine.candidates", "refine.candidateDiff", "refine.candidateOutput", "refine.adopt"];
+}, {
+    readonly name: "settings";
+    readonly description: "Session, terminal and browser settings";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "doctor";
+    readonly description: "Check account, model, tools and runtime readiness";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["doctor.start", "doctor.read"];
+}, {
+    readonly name: "worktree";
+    readonly description: "Manage repository worktrees";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["worktrees.list"];
+}, {
+    readonly name: "subagents";
+    readonly description: "Watch current subagent tasks and activity";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "agents";
+    readonly description: "Browse and edit agent profiles";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["agents.list"];
+}, {
+    readonly name: "log";
+    readonly description: "Harness diagnostics and this conversation's run events";
+    readonly group: "Inspect";
+    readonly kind: "page";
+}, {
+    readonly name: "context";
+    readonly args: "[growth]";
+    readonly description: "What the latest request was made of, and where the rest of the window went";
+    readonly group: "Inspect";
+    readonly kind: "page";
+    readonly methods: readonly ["context.attribution"];
+}, {
+    readonly name: "hotkeys";
+    readonly description: "Keyboard controls";
+    readonly group: "Core";
+    readonly kind: "local";
+}, {
+    readonly name: "quit";
+    readonly description: "Restore the terminal and exit";
+    readonly group: "Core";
+    readonly kind: "local";
+}];
+export type CoreCommandName = typeof CORE_COMMANDS[number]['name'];
+/** The core command a typed name or alias stands for. */
+export declare function coreCommand(name: string): CoreCommand | undefined;
+/** Every listed command, as `commands.list` returns it. */
+export interface ListedCommand {
+    /** What the person types after `/`: `fork`, `annotate:notes`, `skill:review`. */
+    name: string;
+    aliases?: string[];
+    args?: string;
+    description?: string;
+    group: string;
+    source: 'core' | 'plugin' | 'extension' | 'prompt' | 'skill';
+    /** Core commands only. */
+    kind?: CoreCommandKind;
+    /** The owning plugin of a plugin or extension command. */
+    owner?: string;
+}

package/dist/sdk/commands/registry.js

@@ -0,0 +1,54 @@
+// The core slash commands every front end offers. This module is plain data with no imports, so a
+// browser renderer can read it as well as the terminal. A front end must handle every `action`
+// here (INV-PAR-1); `commands.list` adds plugin commands, prompt templates and skills.
+export const CORE_COMMANDS = [
+    { name: 'help', description: 'List the commands', group: 'Core', kind: 'local' },
+    { name: 'plan', args: '[brief]', description: 'Plan one request, read-only: /plan <brief>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
+    { name: 'goal', args: '[<objective>|edit|pause|resume|clear]', description: 'Set or view a goal for a long-running task: /goal <objective>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
+    { name: 'btw', aliases: ['side'], args: '[question]', description: 'Ask a side question without interrupting: /btw <question>', group: 'Run', kind: 'session', methods: ['sideQuestions.start', 'sideQuestions.cancel'] },
+    { name: 'new', description: 'Start a new session', group: 'Session', kind: 'session' },
+    { name: 'stop', description: 'Stop the current reply', group: 'Run', kind: 'session', methods: ['runs.interrupt'] },
+    { name: 'session', aliases: ['resume'], args: '[path]', description: 'Choose a saved session in this account and folder', group: 'Session', kind: 'session' },
+    { name: 'history', aliases: ['tree'], description: 'Navigate branches in the current session', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.navigate'] },
+    { name: 'fork', description: 'Fork from an earlier message', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.fork'] },
+    { name: 'remote-control', aliases: ['rc'], args: '[off|tailscale|lan]', description: 'Continue this session from your phone or iPad', group: 'Session', kind: 'page', methods: ['terminal.remoteControl.start', 'terminal.remoteControl.stop', 'terminal.remoteControl.status'] },
+    { name: 'clone', description: 'Clone this branch into a new session', group: 'Session', kind: 'session', methods: ['sessions.clone'] },
+    { name: 'model', args: '[search]', description: 'Choose the model', group: 'Model', kind: 'session', methods: ['accounts.models'] },
+    { name: 'effort', args: '[level]', description: 'Choose the thinking effort', group: 'Model', kind: 'session' },
+    { name: 'thinking', args: '[show|hide]', description: 'Toggle transcript thinking visibility: /thinking [show|hide]', group: 'Model', kind: 'local' },
+    { name: 'name', args: '[name]', description: 'Name this session', group: 'Session', kind: 'session', methods: ['sessions.rename'] },
+    { name: 'compact', args: '[instructions]', description: 'Compact the context', group: 'Session', kind: 'session', methods: ['sessions.run'] },
+    { name: 'copy', description: 'Copy the last reply', group: 'Inspect', kind: 'local', methods: ['sessions.lastReply'] },
+    { name: 'export', args: '[path.html|path.jsonl]', description: 'Export this branch to HTML or JSONL', group: 'Inspect', kind: 'session', methods: ['sessions.export', 'sessions.run'] },
+    { name: 'todo', aliases: ['checklist'], description: 'Show the current todo list', group: 'Inspect', kind: 'session', methods: ['runs.todo'] },
+    { name: 'follow-up', description: 'Manage queued follow-up and steering messages', group: 'Run', kind: 'page' },
+    { name: 'trajectory', args: '[run-id]', description: 'Inspect recorded runs for this session', group: 'Inspect', kind: 'page', methods: ['runs.list', 'runs.events'] },
+    { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness', kind: 'session', methods: ['sessions.reload'] },
+    { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness', kind: 'page', methods: ['accounts.list'] },
+    { name: 'permissions', description: 'Full Permission and per-tool approvals', group: 'Harness', kind: 'page', methods: ['approvals.get'] },
+    { name: 'harness', description: 'Browse foundation, variant and all resources', group: 'Harness', kind: 'page' },
+    { name: 'skills', description: 'View, inspect and use skills; discover more', group: 'Harness', kind: 'page' },
+    { name: 'connections', description: 'Manage local and remote MCP connections', group: 'Harness', kind: 'page' },
+    { name: 'mcp', description: 'Open Connections in the Harness browser', group: 'Harness', kind: 'page' },
+    { name: 'tools', description: 'Inspect available tools, owners and approvals', group: 'Harness', kind: 'page' },
+    { name: 'plugins', description: 'Manage local plugins, packages, trust and settings', group: 'Harness', kind: 'page', methods: ['plugins.list', 'plugins.attach', 'plugins.detach', 'plugins.trust', 'plugins.untrust', 'plugins.configure', 'plugins.install', 'plugins.update', 'plugins.remove', 'hub.list'] },
+    { name: 'hub', description: 'Browse the Community catalog and manage Hub installs', group: 'Harness', kind: 'page', methods: ['hub.list', 'hub.install', 'hub.uninstall'] },
+    { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope', group: 'Harness', kind: 'page' },
+    { name: 'variant', args: '[use|restore|tag|untag|diff|revert]', description: 'Versions of this variant: switch, restore, tag, compare, take components back', group: 'Harness', kind: 'session', methods: ['variants.lineage', 'variants.compare', 'variants.restore', 'variants.tag', 'variants.untag', 'variants.revert'] },
+    { name: 'refine', args: '[guidance|status|review|stop]', description: 'Improve this variant by replaying your last request: /refine <what to look at>', group: 'Harness', kind: 'session', methods: ['refine.fromRun', 'refine.start', 'refine.list', 'refine.cancel', 'refine.candidates', 'refine.candidateDiff', 'refine.candidateOutput', 'refine.adopt'] },
+    { name: 'settings', description: 'Session, terminal and browser settings', group: 'Harness', kind: 'page' },
+    { name: 'doctor', description: 'Check account, model, tools and runtime readiness', group: 'Harness', kind: 'page', methods: ['doctor.start', 'doctor.read'] },
+    { name: 'worktree', description: 'Manage repository worktrees', group: 'Harness', kind: 'page', methods: ['worktrees.list'] },
+    { name: 'subagents', description: 'Watch current subagent tasks and activity', group: 'Harness', kind: 'page' },
+    { name: 'agents', description: 'Browse and edit agent profiles', group: 'Harness', kind: 'page', methods: ['agents.list'] },
+    { name: 'log', description: "Harness diagnostics and this conversation's run events", group: 'Inspect', kind: 'page' },
+    { name: 'context', args: '[growth]', description: 'What the latest request was made of, and where the rest of the window went', group: 'Inspect', kind: 'page', methods: ['context.attribution'] },
+    { name: 'hotkeys', description: 'Keyboard controls', group: 'Core', kind: 'local' },
+    { name: 'quit', description: 'Restore the terminal and exit', group: 'Core', kind: 'local' }
+];
+const ALIASES = new Map(CORE_COMMANDS.flatMap((command) => ('aliases' in command ? command.aliases : []).map((alias) => [alias, command.name])));
+/** The core command a typed name or alias stands for. */
+export function coreCommand(name) {
+    const canonical = ALIASES.get(name) ?? name;
+    return CORE_COMMANDS.find((command) => command.name === canonical);
+}

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

@@ -0,0 +1,16 @@
+/** One observed registration, identified by its package or loose extension owner. */
+export interface CommandRoute {
+    prefix: string;
+    name: string;
+    owner: string;
+    path: string;
+}
+/** Listing and dispatch reject the whole prefix when different owners claim it. */
+export declare function commandRoutes<T extends CommandRoute>(commands: readonly T[]): {
+    routes: Map<string, T[]>;
+    byName: Map<string, T[]>;
+    ownersByPrefix: Map<string, Map<string, Set<string>>>;
+    conflictingPrefixes: Map<string, string[]>;
+};
+/** Namespace roots and reserved routes cannot be claimed by prompt templates. */
+export declare function promptCommandAvailable(name: string, taken: ReadonlySet<string>, extensionCommands?: ReadonlySet<string>): boolean;

package/dist/sdk/commands/routes.js

@@ -0,0 +1,33 @@
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
+/** Listing and dispatch reject the whole prefix when different owners claim it. */
+export function commandRoutes(commands) {
+    const routes = new Map();
+    const byName = new Map();
+    const ownersByPrefix = new Map();
+    const builtinPrefixes = new Map(BUILTIN_PLUGIN_REGISTRY.commands().map(command => [command.prefix, command.pluginId]));
+    for (const command of commands) {
+        const owners = ownersByPrefix.get(command.prefix) ?? new Map();
+        const paths = owners.get(command.owner) ?? new Set();
+        paths.add(command.path);
+        owners.set(command.owner, paths);
+        ownersByPrefix.set(command.prefix, owners);
+        const route = `${command.prefix}:${command.name}`;
+        routes.set(route, [...(routes.get(route) ?? []), command]);
+        byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
+    }
+    const conflictingPrefixes = new Map();
+    for (const [prefix, owners] of ownersByPrefix) {
+        const builtin = builtinPrefixes.get(prefix);
+        if (owners.size > 1 || builtin || prefix === 'plugin' || prefix === 'skill') {
+            conflictingPrefixes.set(prefix, [
+                ...(builtin ? [`built-in plugin ${builtin}`] : []),
+                ...[...owners.values()].flatMap(paths => [...paths])
+            ]);
+        }
+    }
+    return { routes, byName, ownersByPrefix, conflictingPrefixes };
+}
+/** Namespace roots and reserved routes cannot be claimed by prompt templates. */
+export function promptCommandAvailable(name, taken, extensionCommands = new Set()) {
+    return !name.includes(':') && !taken.has(name) && !extensionCommands.has(name);
+}

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

@@ -0,0 +1,4 @@
+import type { AgentSession } from '@earendil-works/pi-coding-agent';
+import type { Found } from "../plugins/discover.js";
+/** Intercept before Pi can dispatch a bare extension command. */
+export declare function installPluginCommandRouter(session: AgentSession, found: readonly Found[], barePrompts: Set<string>): () => string[];

package/dist/sdk/commands/runtimeRouter.js

@@ -0,0 +1,48 @@
+import { resolve, sep } from 'node:path';
+import { HarnessError } from "../core/errors.js";
+import { pluginCommandPrefix } from "../plugins/commandPrefix.js";
+import { commandRoutes } from "./routes.js";
+/** Intercept before Pi can dispatch a bare extension command. */
+export function installPluginCommandRouter(session, found, barePrompts) {
+    const registrations = () => session.extensionRunner.getRegisteredCommands().map(command => {
+        const source = command.sourceInfo;
+        const path = resolve(source.path);
+        const owner = found.filter(item => item.kind === 'extension' && item.packageRoot && (path === resolve(item.path) || path.startsWith(`${resolve(item.path)}${sep}`))).sort((a, b) => b.path.length - a.path.length)[0];
+        const prefix = pluginCommandPrefix(owner?.packageRoot ? { path: source.path, origin: 'package', baseDir: owner.packageRoot } : source);
+        return { ...command, prefix, owner: owner?.packageRoot ? `package:${owner.packageRoot}` : source.origin === 'package' ? `package:${source.baseDir ?? source.source}` : `extension:${source.path}`, path: source.path };
+    });
+    const originalPrompt = session.prompt.bind(session);
+    session.prompt = async (text, options) => {
+        if (options?.expandPromptTemplates === false)
+            return originalPrompt(text, options);
+        const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+        if (match) {
+            const name = match[1];
+            const index = commandRoutes(registrations());
+            const promptNames = new Set(session.resourceLoader.getPrompts().prompts.map(prompt => prompt.name));
+            if (name.startsWith('plugin:') || index.byName.has(name) || (barePrompts.has(name) && !promptNames.has(name))) {
+                throw new HarnessError('invalid_request', `Plugin command /${name} requires its owner prefix.`);
+            }
+            const separator = name.indexOf(':');
+            const prefix = separator < 0 ? '' : name.slice(0, separator);
+            if (separator > 0 && index.ownersByPrefix.has(prefix)) {
+                if (index.conflictingPrefixes.has(prefix))
+                    throw new HarnessError('invalid_request', `Plugin prefix /${prefix}: is ambiguous.`);
+                const matches = index.routes.get(name) ?? [];
+                if (matches.length > 1 || matches.length === 1 && promptNames.has(name))
+                    throw new HarnessError('invalid_request', `Plugin command /${name} is ambiguous.`);
+                if (matches.length === 1) {
+                    const command = session.extensionRunner.getCommand(matches[0].invocationName);
+                    if (!command)
+                        throw new HarnessError('invalid_request', `Plugin command /${name} is unavailable.`);
+                    await command.handler(match[2]?.trim() ?? '', session.extensionRunner.createCommandContext());
+                    return;
+                }
+                if (!promptNames.has(name))
+                    throw new HarnessError('invalid_request', `Unknown plugin command /${name}.`);
+            }
+        }
+        await originalPrompt(text, options);
+    };
+    return () => [...registrations().map(command => `${command.prefix}:${command.name}`), ...session.resourceLoader.getPrompts().prompts.map(prompt => prompt.name)];
+}

package/dist/sdk/computer/boundary.d.ts

@@ -0,0 +1,40 @@
+import type { ToolSession } from "../tools/types.js";
+import { type ComputerControlBackend } from "./control.js";
+export type ComputerAction = 'click' | 'type' | 'key' | 'activate';
+export interface ComputerApprovalDetails {
+    action: ComputerAction;
+    target: string;
+    /** Backend window identity; the host must not use a mutable selection as its handle. */
+    handle: string;
+    args: Record<string, unknown>;
+    capture?: {
+        id: string;
+        sha256: string;
+        width: number;
+        height: number;
+        mimeType: string;
+    };
+}
+/** Trusted parent backend. Revalidation must refuse revoked or changed targets/captures. Each
+ * effect must itself atomically enforce the control backend's point-of-effect requirements;
+ * a separate revalidation cannot close the race with revocation or window changes. */
+export interface ComputerBoundaryBackend extends ComputerControlBackend {
+    revalidate(session: ToolSession, details: Readonly<ComputerApprovalDetails>): Promise<void>;
+}
+/** Trusted live state, not model input. Missing/unknown state must not be reported as attended. */
+export interface ComputerBoundaryState {
+    attended: boolean;
+    plan: boolean;
+}
+/** An unregistered parent-side boundary for one ToolSession. The caller must still route every
+ * tool call through the normal gate, and keep this instance and its backend in the parent process.
+ * Target selection and capture are observations; click, type, key and activate each ask anew.
+ * The approval includes typed text and window identity in run events: do not use for secrets. */
+export declare function createComputerBoundary(session: ToolSession, backend: ComputerBoundaryBackend, state: () => ComputerBoundaryState): {
+    target: (input: unknown) => Promise<import("./contracts.js").ComputerTarget>;
+    screenshot: (input: unknown) => Promise<import("./contracts.js").ComputerControlScreenshot>;
+    click: (input: unknown) => Promise<void>;
+    type: (input: unknown) => Promise<void>;
+    key: (input: unknown) => Promise<void>;
+    activate: (input: unknown) => Promise<void>;
+};

package/dist/sdk/computer/boundary.js

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { createComputerControl } from "./control.js";
+/** An unregistered parent-side boundary for one ToolSession. The caller must still route every
+ * tool call through the normal gate, and keep this instance and its backend in the parent process.
+ * Target selection and capture are observations; click, type, key and activate each ask anew.
+ * The approval includes typed text and window identity in run events: do not use for secrets. */
+export function createComputerBoundary(session, backend, state) {
+    const run = session.run;
+    let current;
+    let busy = false;
+    function check() {
+        if (session.run !== run || run.finished)
+            throw new HarnessError('run_stopped', 'The run was stopped; computer control is cancelled.');
+        const live = state();
+        if (!live || live.attended !== true || live.plan !== false)
+            throw new HarnessError('computer_unavailable', 'Computer control requires an attended, non-plan run.');
+    }
+    async function approve(handle, shot) {
+        check();
+        if (!current)
+            throw new HarnessError('computer_error', 'Missing computer action.');
+        const { action, input } = current;
+        const details = {
+            action, target: input.target, handle,
+            args: Object.fromEntries(Object.entries(input).filter(([key]) => key !== 'target' && key !== 'screenshot')),
+            ...(shot ? { capture: { id: input.screenshot, sha256: createHash('sha256').update(shot.data).digest('hex'), width: shot.width, height: shot.height, mimeType: shot.mimeType } } : {})
+        };
+        // Pass independent copies across trust boundaries; neither approval presentation nor a backend
+        // may mutate the private, approved action before the effect.
+        const description = JSON.stringify(details);
+        const decision = await run.requestApproval({ target: `computer_${action}`, action: description, operation: { tool: `computer_${action}`, args: JSON.parse(description) }, rememberable: false, standing: 'none' });
+        check();
+        if (decision !== 'approved')
+            throw new HarnessError('computer_denied', 'Computer action was not approved.');
+        await backend.revalidate(session, JSON.parse(description));
+        check();
+    }
+    const guarded = {
+        target: (s) => backend.target(s),
+        screenshot: (s, handle) => backend.screenshot(s, handle),
+        click: async (s, handle, shot, input) => { await approve(handle, shot); check(); await backend.click(s, handle, shot, input); },
+        type: async (s, handle, text) => { await approve(handle); check(); await backend.type(s, handle, text); },
+        key: async (s, handle, key) => { await approve(handle); check(); await backend.key(s, handle, key); },
+        activate: async (s, handle) => { await approve(handle); check(); await backend.activate(s, handle); }
+    };
+    const control = createComputerControl(session, guarded);
+    async function call(input, action, execute) {
+        check();
+        if (busy)
+            throw new HarnessError('computer_busy', 'A computer operation is already in progress.');
+        // Clone before the first await, including while another actor can hold the input object.
+        let copy;
+        try {
+            copy = structuredClone(input);
+        }
+        catch {
+            throw new HarnessError('invalid_input', 'Invalid computer control input.');
+        }
+        busy = true;
+        try {
+            if (action)
+                current = { action, input: copy };
+            return await execute(copy);
+        }
+        finally {
+            current = undefined;
+            busy = false;
+        }
+    }
+    return {
+        target: (input) => call(input, undefined, control.target),
+        screenshot: (input) => call(input, undefined, control.screenshot),
+        click: (input) => call(input, 'click', control.click),
+        type: (input) => call(input, 'type', control.type),
+        key: (input) => call(input, 'key', control.key),
+        activate: (input) => call(input, 'activate', control.activate)
+    };
+}