@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/browserControl.js

@@ -0,0 +1,187 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { describePlugin } from "../plugins/surfaces.js";
+import * as path from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { invalid } from "../core/errors.js";
+import { connectionInputSchema } from "../mcp/types.js";
+import * as library from "../variant/components.js";
+import { PI_SURFACE, componentOf } from "../variant/surface.js";
+import { headVariant } from "../variant/store.js";
+const MAX_CONTENT = 256 * 1024;
+export function isWithinBoundary(boundary, file, pathApi = path) {
+    const within = pathApi.relative(boundary, file);
+    return within !== '..' && !within.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(within);
+}
+function readText(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_CONTENT)
+            throw invalid('Preview requires a regular text file smaller than 256 KiB.');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Only the protected terminal control route calls this adapter. It never loads discovered code. */
+export class BrowserControl {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async snapshot(refresh = false) {
+        const { root, pinned, apps } = this.options;
+        const plugins = await this.options.plugins();
+        const scope = pinned?.scope ?? null;
+        const latest = scope ? headVariant(root, scope) : null;
+        const items = [];
+        const add = (item) => items.push(item);
+        for (const [id, name, description] of [
+            ['runtime', 'Runtime and recording', 'The foundation runs sessions and records their events. Changes require a release.'],
+            ['prompt', 'Prompt compiler', 'Assembles the stable prompt and context updates. Variant c1–c4 supply configurable instructions.'],
+            ['loader', 'Resource loader', 'Selects plugins and their contributions. Discovered code waits for exact-code trust.'],
+            ['gate', 'Tool approval gate', 'Checks capabilities, policy and approvals for every tool call. Availability never grants authorization.'],
+            ['accounts', 'Accounts and secrets', 'Keeps account identities isolated and credentials in the secret store.'],
+            ['surface', 'Variant surface', 'Defines c1–c8, validation and immutable versions. Only a validated variant version may change.']
+        ])
+            add({ id: `foundation:${id}`, section: 'foundation', name: name, description: description, owner: 'Foundation', origin: 'Built-in', status: 'Read-only' });
+        for (const plugin of plugins) {
+            add({ id: `plugin:${plugin.id}`, section: 'plugins', name: plugin.title, description: describePlugin(plugin),
+                owner: plugin.title, origin: plugin.source, status: plugin.required ? 'Required' : plugin.trust === 'untrusted' ? 'Needs trust' : 'Saved configuration',
+                pluginId: plugin.id, path: plugin.path ?? undefined, required: plugin.required });
+            for (const entry of plugin.contributions) {
+                if (!['skill', 'tool', 'command', 'instruction'].includes(entry.kind))
+                    continue;
+                if ((entry.kind === 'command' || entry.kind === 'instruction') && !entry.path)
+                    continue;
+                const section = entry.kind === 'skill' ? 'skills' : entry.kind === 'tool' ? 'tools' : 'library';
+                add({ id: `contribution:${entry.id}`, section, name: entry.name, description: entry.description,
+                    owner: plugin.title, origin: plugin.source, pluginId: plugin.id, contributionId: entry.id,
+                    path: entry.path ?? undefined, scope: entry.scope, status: entry.state === 'off' ? 'Disabled' : entry.state === 'untrusted' ? 'Needs trust' : 'Enabled for future sessions',
+                    read: Boolean(entry.path && ['skill', 'command', 'instruction'].includes(entry.kind)) });
+            }
+        }
+        for (const item of library.list(root)) {
+            const added = Boolean(latest && library.isInVariant(root, latest.variant, item.id));
+            const existing = items.find(existing => existing.path === item.path);
+            if (existing) {
+                existing.componentId = item.id;
+                existing.added = added;
+                continue;
+            }
+            add({ id: `library:${item.id}`, section: item.kind === 'skills' ? 'skills' : 'library', name: item.name,
+                description: item.description, owner: 'Reusable library', origin: item.builtin ? 'Built-in library' : 'Local library', path: item.path,
+                componentId: item.id, added, status: added ? 'Saved in latest variant' : 'Library only', read: true });
+        }
+        const paths = new Set([...Object.keys(pinned?.files ?? {}), ...Object.keys(latest?.variant ?? {})]);
+        for (const path of [...paths].sort()) {
+            const component = PI_SURFACE.components.find(entry => entry.id === componentOf(PI_SURFACE, path));
+            if (!component)
+                continue;
+            const current = pinned?.files[path];
+            const future = latest?.variant[path];
+            const status = !latest || current === future ? 'Pinned version' : current === undefined ? 'Added in latest' : future === undefined ? 'Removed in latest' : 'Changed in latest';
+            add({ id: `variant:${path}`, section: 'variant', name: path, description: `c${component.index} · ${component.title}: ${component.description}`,
+                owner: 'Variant', origin: 'Variant', status, read: true });
+            if (/^skills\/[^/]+\/SKILL\.md$/.test(path) && current !== undefined) {
+                const name = path.split('/')[1];
+                const fullPath = join(pinned.dir, path);
+                if (!items.some(item => item.section === 'skills' && item.path === fullPath))
+                    add({ id: `variant-skill:${path}`, section: 'skills', name,
+                        description: /^description:\s*(.+)$/m.exec(current)?.[1] ?? '', owner: 'Variant', origin: 'Variant', status: 'Prepared for this session',
+                        path: fullPath, read: true });
+            }
+        }
+        const connections = apps.connections.list().map(connection => ({ ...connection,
+            error: connection.error ? String(apps.connections.scrub(connection.error, connection.id)) : null,
+            tools: apps.connections.scrub(connection.tools, connection.id) }));
+        for (const connection of connections)
+            add({ id: `connection:${connection.id}`, section: 'connections', name: connection.name || connection.id,
+                description: `${connection.kind === 'remote' ? 'Remote HTTP' : 'Local stdio'} MCP · ${connection.tools.length} tools${connection.checkedAt ? ` · last checked ${connection.checkedAt}` : ' · never tested'}`,
+                owner: 'Connected apps', origin: connection.kind === 'remote' ? 'Remote' : 'Local', connectionId: connection.id,
+                scope: connection.global ? 'Everywhere' : connection.projectIds.join(', ') || 'No project scope',
+                status: !connection.enabled ? 'Disabled' : connection.auth === 'oauth' && connection.authState !== 'signed_in' ? 'Sign in required' : connection.error ? 'Last check failed' : connection.checkedAt ? 'Last check passed' : 'Not tested' });
+        return { items, plugins, connections, variant: { scope, pinned: pinned?.fingerprint ?? null, latest: latest?.fingerprint ?? null,
+                writable: this.options.writable && Boolean(scope && latest) }, hub: this.options.hub ? await this.options.hub.list(refresh) : null };
+    }
+    async read(id, latestVersion = false) {
+        const { root, pinned } = this.options;
+        const snapshot = await this.snapshot();
+        const item = snapshot.items.find(entry => entry.id === id);
+        if (!item?.read)
+            throw invalid('This resource has no inspectable content.');
+        if (id.startsWith('variant:') || id.startsWith('variant-skill:')) {
+            const path = id.slice(id.indexOf(':') + 1);
+            const files = latestVersion && pinned?.scope ? headVariant(root, pinned.scope)?.variant : pinned?.files;
+            const content = files?.[path] ?? '(File absent in this version.)';
+            return { content: content.length > MAX_CONTENT ? content.slice(0, MAX_CONTENT) + '\n[Preview truncated.]' : content };
+        }
+        if (!item.path)
+            throw invalid('This resource has no file.');
+        const plugin = snapshot.plugins.find(plugin => plugin.id === item.pluginId);
+        const registryItem = item.componentId ? library.list(root).find(entry => entry.id === item.componentId) : undefined;
+        const boundary = realpathSync(registryItem && !registryItem.builtin ? join(root, 'registry') : plugin?.path ?? dirname(item.path));
+        const file = realpathSync(item.path);
+        if (!isWithinBoundary(boundary, file))
+            throw invalid('Resource is outside its owner folder.');
+        return { content: readText(file) };
+    }
+    importSkill(input) {
+        const start = resolve(this.options.cwd, input);
+        const folder = lstatSync(start).isDirectory() ? start : dirname(start);
+        if (start !== folder && basename(start) !== 'SKILL.md')
+            throw invalid('Choose a skill folder or its SKILL.md.');
+        const files = [];
+        let bytes = 0;
+        let directories = 0;
+        const visit = (directory, depth = 0) => {
+            if (++directories > 100 || depth > 16)
+                throw invalid('Skill import exceeds its directory limit.');
+            for (const name of readdirSync(directory)) {
+                if (name.startsWith('.'))
+                    continue;
+                const path = join(directory, name);
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    throw invalid('Skill imports cannot contain symbolic links.');
+                if (stat.isDirectory()) {
+                    visit(path, depth + 1);
+                    continue;
+                }
+                if (!stat.isFile() || files.length >= 100 || stat.size > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds its file limit.');
+                bytes += stat.size;
+                if (bytes > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds 10 MiB.');
+                files.push({ path: relative(folder, path), content: readFileSync(path).toString('base64'), encoding: 'base64' });
+            }
+        };
+        if (lstatSync(folder).isSymbolicLink())
+            throw invalid('Choose a regular skill folder.');
+        visit(folder);
+        library.importItems(this.options.root, 'skills', [{ name: basename(folder), files }]);
+    }
+    async connection(action, params) {
+        const apps = this.options.apps;
+        if (action === 'appClients')
+            return apps.appClients();
+        if (action === 'save')
+            return apps.save(connectionInputSchema.parse(params.input));
+        const id = typeof params.id === 'string' ? params.id : '';
+        if (!apps.connections.list().some(connection => connection.id === id))
+            throw invalid('Unknown connection.');
+        if (action === 'test') {
+            const result = await apps.test(id);
+            return { ...result, error: result.error ? String(apps.connections.scrub(result.error, id)) : null,
+                tools: apps.connections.scrub(result.tools, id) };
+        }
+        if (action === 'signIn')
+            return apps.signIn(id);
+        if (action === 'signOut')
+            return apps.signOut(id);
+        if (action === 'remove')
+            return apps.remove(id);
+        throw invalid('Unknown connection action.');
+    }
+}

package/dist/sdk/terminal/cli.d.ts

@@ -0,0 +1,20 @@
+import type { HarnessCall } from "../tools/definitions.js";
+export declare const WIKI_COMMAND = "xagent-wiki";
+export declare const APPS_COMMAND = "xagent-mcp";
+export declare const USAGE = "Usage: xagent-wiki <command> [arguments]\n\n  search <query> [--project SLUG]    Search the Wiki's project notes\n  read <path>                        Read one note, e.g. projects/<slug>/decisions\n  list [project slug | library]      List notes\n  write <path> <text | ->            Save a note (when this session may write the Wiki)\n  skill [name]                       Load one of your skills, or list them\n  history <query> [--scope all] [--since YYYY-MM-DD]\n                                     Search earlier conversations and runs (also: recall)\n  history-read <run id>              Read one earlier run (also: recall-read)\n";
+export declare const APPS_USAGE = "Usage: xagent-mcp <command>\n\n  list                               The app and connected-app tools this session may use\n  call <tool-name> '<JSON arguments>'\n                                     Use one of them\n";
+export type CliCommand = {
+    kind: 'call';
+    call: HarnessCall;
+    params: Record<string, unknown>;
+} | {
+    kind: 'help';
+} | {
+    kind: 'stdin-write';
+    path: string;
+};
+export declare function parseCli(argv: string[]): CliCommand;
+/** Runs `xagent-wiki <argv>`; returns the exit code. */
+export declare function runWikiCli(argv: string[]): Promise<number>;
+/** Runs `xagent-mcp <argv>`; returns the exit code. */
+export declare function runAppsCli(argv: string[]): Promise<number>;

package/dist/sdk/terminal/cli.js

@@ -0,0 +1,121 @@
+import { connectionFromEnv, socketCall } from "./client.js";
+export const WIKI_COMMAND = 'xagent-wiki';
+export const APPS_COMMAND = 'xagent-mcp';
+export const USAGE = `Usage: ${WIKI_COMMAND} <command> [arguments]
+
+  search <query> [--project SLUG]    Search the Wiki's project notes
+  read <path>                        Read one note, e.g. projects/<slug>/decisions
+  list [project slug | library]      List notes
+  write <path> <text | ->            Save a note (when this session may write the Wiki)
+  skill [name]                       Load one of your skills, or list them
+  history <query> [--scope all] [--since YYYY-MM-DD]
+                                     Search earlier conversations and runs (also: recall)
+  history-read <run id>              Read one earlier run (also: recall-read)
+`;
+export const APPS_USAGE = `Usage: ${APPS_COMMAND} <command>
+
+  list                               The app and connected-app tools this session may use
+  call <tool-name> '<JSON arguments>'
+                                     Use one of them
+`;
+function options(args) {
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith('--') && index + 1 < args.length) {
+            flags[arg.slice(2)] = args[index + 1];
+            index += 1;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+export function parseCli(argv) {
+    const [command, ...rest] = argv;
+    const { positional, flags } = options(rest);
+    const joined = positional.join(' ').trim();
+    switch (command) {
+        case 'search':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.search', params: { query: joined, ...(flags.project ? { project: flags.project } : {}) } };
+        case 'read':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.read', params: { path: joined } };
+        case 'list':
+            return { kind: 'call', call: 'wiki.list', params: joined ? { project: joined } : {} };
+        case 'write': {
+            const [path, ...words] = positional;
+            if (!path)
+                return { kind: 'help' };
+            if (words.join(' ').trim() === '-')
+                return { kind: 'stdin-write', path };
+            if (!words.length)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.write', params: { path, text: words.join(' ') } };
+        }
+        case 'skill':
+            return { kind: 'call', call: 'skill.load', params: joined ? { name: joined } : {} };
+        case 'history':
+        case 'recall':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'recall.search', params: { query: joined, ...(flags.scope ? { scope: flags.scope } : {}), ...(flags.since ? { since: flags.since } : {}) } };
+        case 'history-read':
+        case 'recall-read':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'recall.read', params: { run: joined } };
+        default:
+            return { kind: 'help' };
+    }
+}
+async function readStdin() {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk.toString();
+    return text;
+}
+const errorText = (error) => (error instanceof Error ? error.message : String(error));
+/** Runs `xagent-wiki <argv>`; returns the exit code. */
+export async function runWikiCli(argv) {
+    const command = parseCli(argv);
+    if (command.kind === 'help') {
+        process.stdout.write(USAGE);
+        return argv.length ? 2 : 0;
+    }
+    try {
+        const connection = connectionFromEnv();
+        const result = command.kind === 'stdin-write'
+            ? await socketCall(connection, 'wiki.write', { path: command.path, text: await readStdin() })
+            : await socketCall(connection, command.call, command.params);
+        process.stdout.write(`${typeof result === 'string' ? result : JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${errorText(error)}\n`);
+        return 1;
+    }
+}
+/** Runs `xagent-mcp <argv>`; returns the exit code. */
+export async function runAppsCli(argv) {
+    const [command, name, args] = argv;
+    if (command !== 'list' && !(command === 'call' && name)) {
+        process.stdout.write(APPS_USAGE);
+        return argv.length ? 2 : 0;
+    }
+    try {
+        const connection = connectionFromEnv();
+        const result = command === 'list' ? await socketCall(connection, 'mcp.list', {}, 90_000) : await socketCall(connection, 'mcp.call', { name, args: JSON.parse(args ?? '{}') }, 1_230_000);
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${errorText(error)}\n`);
+        return 1;
+    }
+}

package/dist/sdk/terminal/client.d.ts

@@ -0,0 +1,20 @@
+export declare const SOCKET_ENV = "XINGULAR_HARNESS_SOCKET";
+export declare const TOKEN_ENV = "XINGULAR_HARNESS_TOKEN";
+/** Set by `xagent --remote-control`: the terminal turns on `/remote-control` as it opens. */
+export declare const REMOTE_CONTROL_ENV = "XINGULAR_HARNESS_REMOTE_CONTROL";
+export declare class SocketError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface SocketConnection {
+    socket: string;
+    token: string;
+}
+export declare function connectionFromEnv(env?: NodeJS.ProcessEnv): SocketConnection;
+/** A memory, Wiki, recall, or connected-app call made on behalf of the session that owns the token. */
+export declare function socketCall<T = unknown>(connection: SocketConnection, call: string, params?: Record<string, unknown>, timeoutMs?: number, control?: string, signal?: AbortSignal): Promise<T>;
+/** Effectful requests must never be replayed after an ambiguous disconnect. Use a fresh connection
+ * and report an unknown outcome if it closes, times out or is cancelled without a reply. */
+export declare function socketCallOnce<T = unknown>(connection: SocketConnection, call: string, params?: Record<string, unknown>, timeoutMs?: number, control?: string, signal?: AbortSignal): Promise<T>;
+/** Telemetry and decisions from the native `pi` process. Approvals may wait on a person, so the default wait is long. */
+export declare function terminalCall<T = Record<string, unknown>>(event: string, data?: Record<string, unknown>, timeoutMs?: number): Promise<T>;

package/dist/sdk/terminal/client.js

@@ -0,0 +1,148 @@
+// How a process outside the harness (the `pi` command's extension, the `xagent-wiki` and
+// `xagent-mcp` commands) reaches it: newline-delimited JSON requests and replies on the session
+// socket, authorized by the token the harness put in its environment. A reply leaves its connection
+// open for the next request, so the terminal's frequent small calls do not each open a socket.
+import { createConnection } from 'node:net';
+export const SOCKET_ENV = 'XINGULAR_HARNESS_SOCKET';
+export const TOKEN_ENV = 'XINGULAR_HARNESS_TOKEN';
+/** Set by `xagent --remote-control`: the terminal turns on `/remote-control` as it opens. */
+export const REMOTE_CONTROL_ENV = 'XINGULAR_HARNESS_REMOTE_CONTROL';
+export class SocketError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function connectionFromEnv(env = process.env) {
+    const socket = env[SOCKET_ENV];
+    const token = env[TOKEN_ENV];
+    if (!socket || !token)
+        throw new SocketError('not_configured', `This command only works inside a terminal session the harness started (${SOCKET_ENV} and ${TOKEN_ENV} are not set).`);
+    return { socket, token };
+}
+const MAX_IDLE_PER_SOCKET = 4;
+/** Open connections waiting for their next request, per socket path. Idle ones never keep a process alive. */
+const idle = new Map();
+function takeIdle(path) {
+    const entries = idle.get(path);
+    const entry = entries?.values().next().value;
+    if (!entries || !entry)
+        return undefined;
+    entries.delete(entry);
+    entry.stream.off('close', entry.drop);
+    entry.stream.off('error', entry.drop);
+    entry.stream.ref();
+    return entry.stream;
+}
+function putIdle(path, stream) {
+    const entries = idle.get(path) ?? new Set();
+    if (stream.destroyed || entries.size >= MAX_IDLE_PER_SOCKET) {
+        stream.end();
+        return;
+    }
+    const entry = { stream, drop: () => { entries.delete(entry); stream.destroy(); } };
+    stream.once('close', entry.drop);
+    stream.on('error', entry.drop);
+    stream.unref();
+    entries.add(entry);
+    idle.set(path, entries);
+}
+function request(connection, body, what, timeoutMs, signal) {
+    const reused = takeIdle(connection.socket);
+    return attempt(connection, body, what, timeoutMs, reused, signal).catch((error) => {
+        // An idle connection the harness had already closed fails before any reply; one fresh retry.
+        if (reused && error instanceof StaleConnection)
+            return attempt(connection, body, what, timeoutMs, undefined, signal);
+        throw error;
+    });
+}
+class StaleConnection extends Error {
+}
+function attempt(connection, body, what, timeoutMs, reused, signal) {
+    return new Promise((resolve, reject) => {
+        const stream = reused ?? createConnection(connection.socket);
+        let buffer = '';
+        let replied = false;
+        let settled = false;
+        const send = () => stream.write(`${JSON.stringify({ token: connection.token, ...body, keep: true })}\n`);
+        const onData = (chunk) => {
+            replied = true;
+            buffer += chunk.toString('utf8');
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const rest = buffer.slice(newline + 1);
+            try {
+                const reply = JSON.parse(buffer.slice(0, newline));
+                if (reply.error) {
+                    const error = typeof reply.error === 'string' ? { message: reply.error } : reply.error;
+                    finish(() => reject(new SocketError(error.code ?? 'error', error.message ?? `${what} failed.`)), !rest);
+                }
+                else
+                    finish(() => resolve(reply.result), !rest);
+            }
+            catch {
+                finish(() => reject(new SocketError('invalid_reply', 'The harness sent an unreadable reply.')));
+            }
+        };
+        const onError = (error) => finish(() => reject(reused && !replied ? new StaleConnection(error.message) : new SocketError('unavailable', `The harness is not reachable: ${error.message}.`)));
+        const onClose = () => finish(() => reject(reused && !replied ? new StaleConnection('closed') : new SocketError('unavailable', 'The harness closed the connection.')));
+        const finish = (action, keep = false) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            stream.off('connect', send);
+            stream.off('data', onData);
+            stream.off('error', onError);
+            stream.off('close', onClose);
+            if (keep)
+                putIdle(connection.socket, stream);
+            else {
+                stream.on('error', () => { });
+                stream.end();
+            }
+            action();
+        };
+        const timer = setTimeout(() => {
+            stream.destroy();
+            finish(() => reject(new SocketError('timeout', `The harness did not answer ${what}.`)));
+        }, timeoutMs);
+        const onAbort = () => { stream.destroy(); finish(() => reject(new SocketError('aborted', `${what} was cancelled.`))); };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        stream.on('data', onData);
+        stream.on('error', onError);
+        stream.on('close', onClose);
+        if (reused)
+            send();
+        else
+            stream.on('connect', send);
+    });
+}
+/** A memory, Wiki, recall, or connected-app call made on behalf of the session that owns the token. */
+export function socketCall(connection, call, params = {}, timeoutMs = 120_000, control, signal) {
+    return request(connection, { call, params, ...(control ? { control } : {}) }, call, timeoutMs, signal);
+}
+/** Effectful requests must never be replayed after an ambiguous disconnect. Use a fresh connection
+ * and report an unknown outcome if it closes, times out or is cancelled without a reply. */
+export async function socketCallOnce(connection, call, params = {}, timeoutMs = 120_000, control, signal) {
+    try {
+        return await attempt(connection, { call, params, ...(control ? { control } : {}) }, call, timeoutMs, undefined, signal);
+    }
+    catch (error) {
+        if (error instanceof SocketError && ['unavailable', 'timeout', 'aborted'].includes(error.code)) {
+            throw new SocketError('outcome_unknown', `${call} did not return a result. Its outcome is unknown; inspect before retrying.`);
+        }
+        throw error;
+    }
+}
+/** Telemetry and decisions from the native `pi` process. Approvals may wait on a person, so the default wait is long. */
+export function terminalCall(event, data = {}, timeoutMs = 600_000) {
+    return request(connectionFromEnv(), { event, data }, event, timeoutMs);
+}

package/dist/sdk/terminal/commandHelp.d.ts

@@ -0,0 +1,17 @@
+export interface TerminalCommandCompletion {
+    name: string;
+    aliases?: string[];
+    description?: string;
+    group: string;
+}
+export interface TerminalCommandHelpEntry {
+    name: string;
+    aliases?: string[];
+    description?: string;
+}
+export declare function formatTerminalCommandLabel(name: string, aliases?: readonly string[]): string;
+export interface TerminalCommandHelpGroup {
+    name: string;
+    commands: TerminalCommandHelpEntry[];
+}
+export declare function groupTerminalCommands(commands: readonly TerminalCommandCompletion[]): TerminalCommandHelpGroup[];

package/dist/sdk/terminal/commandHelp.js

@@ -0,0 +1,20 @@
+export function formatTerminalCommandLabel(name, aliases) {
+    return aliases?.length ? `${name} (${aliases.join(', ')})` : name;
+}
+const GROUP_ORDER = ['Core', 'Run', 'Model', 'Session', 'Inspect', 'Harness', 'Plugins', 'Extensions', 'Prompts'];
+export function groupTerminalCommands(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const group = groups.get(command.group) ?? [];
+        group.push({
+            name: command.name,
+            ...(command.aliases?.length ? { aliases: command.aliases } : {}),
+            description: command.description
+        });
+        groups.set(command.group, group);
+    }
+    const order = new Map(GROUP_ORDER.map((name, index) => [name, index]));
+    return [...groups]
+        .sort(([left], [right]) => (order.get(left) ?? GROUP_ORDER.length) - (order.get(right) ?? GROUP_ORDER.length))
+        .map(([name, entries]) => ({ name, commands: entries }));
+}

package/dist/sdk/terminal/control.d.ts

@@ -0,0 +1,4 @@
+import { type SocketConnection } from "./client.js";
+/** A process owns the claim across native session replacement; it never enters the environment. */
+export declare function claimTerminalControl(connection?: SocketConnection): Promise<string>;
+export declare function controlCall<T = unknown>(call: string, params?: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<T>;

package/dist/sdk/terminal/control.js

@@ -0,0 +1,25 @@
+import { connectionFromEnv, socketCall } from "./client.js";
+const claims = new Map();
+/** A process owns the claim across native session replacement; it never enters the environment. */
+export function claimTerminalControl(connection = connectionFromEnv()) {
+    const identity = JSON.stringify([connection.socket, connection.token]);
+    let claim = claims.get(identity);
+    if (!claim) {
+        claim = socketCall(connection, 'control.claim', {}, 15_000).then(({ key }) => {
+            if (!key)
+                throw new Error('The terminal controller returned no control key.');
+            return key;
+        }).catch((error) => {
+            // A failed claim is retried by the next call; only a claim that succeeded is kept.
+            claims.delete(identity);
+            throw error;
+        });
+        claims.set(identity, claim);
+    }
+    return claim;
+}
+export async function controlCall(call, params = {}, timeoutMs = 120_000, signal) {
+    const connection = connectionFromEnv();
+    const control = await claimTerminalControl(connection);
+    return signal ? socketCall(connection, call, params, timeoutMs, control, signal) : socketCall(connection, call, params, timeoutMs, control);
+}