@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,34 @@
+import type { Plugin } from "../plugins/types.js";
+export interface MenuUi {
+    select(title: string, options: string[]): Promise<string | undefined>;
+    confirm(title: string, message: string): Promise<boolean>;
+    notify(message: string, level?: 'info' | 'warning' | 'error'): void;
+}
+/** `plugins.list`, `plugins.attach`, `plugins.detach`, `plugins.trust`, `plugins.untrust`. */
+export type MenuCall = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
+export interface MenuRow {
+    /** The plugin's id, or one contribution's. */
+    id: string;
+    label: string;
+    on: boolean;
+    /** The plugin it is, or belongs to. */
+    plugin: Plugin;
+    /** Set when the row is the whole plugin. */
+    whole: boolean;
+    /** The title of the plugin, or the name of the contribution. */
+    name: string;
+    /** Trust or kind, in words: `code not trusted`, `runs code`, `skill in Notes`. */
+    note: string;
+}
+/** What can be switched or trusted from here: each found or installed plugin, and each item of the rest that has a switch. */
+export declare function menuRows(plugins: readonly Plugin[], projectId: string | null): MenuRow[];
+export declare const BACK = "Back";
+/** What a person can do with one row. A whole plugin whose code waits for trust can be trusted here. */
+export declare function rowActions(row: MenuRow, projectId: string | null): string[];
+/** Applies one chosen action to a row; says whether something changed. Trusting code asks once more with the files in view. */
+export declare function applyPluginAction(ui: MenuUi, call: MenuCall, row: MenuRow, action: string): Promise<boolean>;
+/**
+ * Runs the command: list, pick a row, pick what to do, until the person is done. Nothing changes
+ * without a choice made here, and trusting code asks once more with the files in view.
+ */
+export declare function runPluginsMenu(ui: MenuUi, call: MenuCall, projectId: string | null): Promise<void>;

package/dist/sdk/terminal/pluginMenu.js

@@ -0,0 +1,101 @@
+const here = (attachment, projectId) => {
+    if (projectId && attachment.on.projectIds.includes(projectId))
+        return true;
+    if (projectId && attachment.off.projectIds.includes(projectId))
+        return false;
+    return attachment.global;
+};
+const mark = (on) => (on ? '●' : '○');
+/** What can be switched or trusted from here: each found or installed plugin, and each item of the rest that has a switch. */
+export function menuRows(plugins, projectId) {
+    const rows = [];
+    for (const plugin of plugins) {
+        if (plugin.attachment) {
+            const on = here(plugin.attachment, projectId);
+            const note = plugin.trust === 'untrusted' ? 'code not trusted' : plugin.runsCode ? 'runs code' : '';
+            rows.push({ id: plugin.id, plugin, whole: true, on, name: plugin.title, note, label: `${mark(on)} ${plugin.title}${note ? ` · ${note}` : ''}` });
+            continue;
+        }
+        if (plugin.trust !== 'none') {
+            const note = plugin.trust === 'trusted' ? 'code trusted' : 'code not trusted';
+            rows.push({ id: plugin.id, plugin, whole: true, on: plugin.trust === 'trusted', name: plugin.title, note, label: `${mark(plugin.trust === 'trusted')} ${plugin.title} · ${note}` });
+        }
+        for (const entry of plugin.contributions) {
+            if (!entry.attachment)
+                continue;
+            const note = `${kindWord(entry)} in ${plugin.title}`;
+            rows.push({ id: entry.id, plugin, whole: false, on: entry.state === 'on', name: entry.name, note, label: `${mark(entry.state === 'on')} ${entry.name} · ${note}` });
+        }
+    }
+    return rows;
+}
+const kindWord = (entry) => (entry.kind === 'connection' ? 'connected app' : entry.kind === 'code' ? 'extension' : entry.kind);
+const SWITCH_OFF_PROJECT = 'Switch off for this project';
+const SWITCH_ON_PROJECT = 'Switch on for this project';
+const SWITCH_OFF_EVERYWHERE = 'Switch off everywhere';
+const SWITCH_ON_EVERYWHERE = 'Switch on everywhere';
+const TRUST = 'Trust its code';
+const UNTRUST = 'Stop trusting its code';
+export const BACK = 'Back';
+const DONE = 'Done';
+/** What a person can do with one row. A whole plugin whose code waits for trust can be trusted here. */
+export function rowActions(row, projectId) {
+    const switchable = row.whole ? row.plugin.attachment !== null : true;
+    const actions = [];
+    if (switchable) {
+        if (projectId)
+            actions.push(row.on ? SWITCH_OFF_PROJECT : SWITCH_ON_PROJECT);
+        actions.push(row.on ? SWITCH_OFF_EVERYWHERE : SWITCH_ON_EVERYWHERE);
+    }
+    if (row.whole && row.plugin.code)
+        actions.push(row.plugin.trust === 'untrusted' ? TRUST : UNTRUST);
+    return [...actions, BACK];
+}
+/** Applies one chosen action to a row; says whether something changed. Trusting code asks once more with the files in view. */
+export async function applyPluginAction(ui, call, row, action) {
+    try {
+        if (action === TRUST || action === UNTRUST) {
+            const code = row.plugin.code;
+            if (action === TRUST) {
+                const sure = await ui.confirm('Trust this code?', `${code.files.join('\n')}\n\nFingerprint ${code.hash.slice(0, 12)}. It runs inside the session and can do anything this app can, including reading your files and credentials.`);
+                if (!sure)
+                    return false;
+            }
+            await call(action === TRUST ? 'plugins.trust' : 'plugins.untrust', { hash: code.hash });
+        }
+        else {
+            const on = action === SWITCH_ON_PROJECT || action === SWITCH_ON_EVERYWHERE;
+            await call(on ? 'plugins.attach' : 'plugins.detach', { id: row.id, everywhere: action === SWITCH_ON_EVERYWHERE || action === SWITCH_OFF_EVERYWHERE });
+        }
+        return true;
+    }
+    catch (error) {
+        ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        return false;
+    }
+}
+/**
+ * Runs the command: list, pick a row, pick what to do, until the person is done. Nothing changes
+ * without a choice made here, and trusting code asks once more with the files in view.
+ */
+export async function runPluginsMenu(ui, call, projectId) {
+    let changed = false;
+    for (;;) {
+        const rows = menuRows(await call('plugins.list'), projectId);
+        if (!rows.length) {
+            ui.notify('There is nothing to switch or trust here yet.', 'info');
+            return;
+        }
+        const picked = await ui.select(`Plugins${changed ? ' (changes apply when this session restarts)' : ''}`, [...rows.map((row) => row.label), DONE]);
+        const row = rows.find((candidate) => candidate.label === picked);
+        if (!row)
+            break;
+        const action = await ui.select(`${row.plugin.title}: ${row.plugin.description || 'No description.'}`, rowActions(row, projectId));
+        if (!action || action === BACK)
+            continue;
+        if (await applyPluginAction(ui, call, row, action))
+            changed = true;
+    }
+    if (changed)
+        ui.notify('Saved. It applies when this session restarts.', 'info');
+}

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

@@ -0,0 +1,73 @@
+import type { BrokerSession } from "../mcp/service.js";
+import type { CallerContext } from "../core/caller.js";
+/** What a token stands for. */
+export interface SocketGrant {
+    sessionId: string;
+    /** Who memory, Wiki, and recall calls are made as. The run is filled in while a turn is live. */
+    caller: () => CallerContext;
+    /** The session's connected-apps grant, when it has one. */
+    broker: BrokerSession | null;
+    /** Telemetry from the native process, and what to do when it hangs up mid-request. */
+    terminal?: {
+        accept(event: string, data: Record<string, unknown>): Promise<unknown>;
+        disconnected(): void;
+        control?(call: string, data: Record<string, unknown>): unknown;
+    };
+}
+export interface SocketHandlers {
+    /** `wiki.*`, `skill.*`, `recall.*`, `trajectory.*`. */
+    memory(caller: CallerContext, call: string, params: Record<string, unknown>): string;
+    /** `mcp.list`, `mcp.call`, `mcp.revision`, `tools.list`, `tools.call`. */
+    apps(session: BrokerSession, call: string, params: Record<string, unknown>): Promise<unknown>;
+    /**
+     * `plugins.*`. `control` is true only for the session's own extension, which holds a key the
+     * session's shell never sees; anything that changes what loads needs it.
+     */
+    plugins?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>;
+    /** `accounts.*`. Every call needs `control`: adding, signing in, or removing an account is a person's choice. */
+    accounts?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>;
+}
+/**
+ * Each Harness process listens on its own path. Windows has no socket files for Node's `net`: it
+ * listens on a named pipe in a machine-wide namespace, and a random name keeps another local process
+ * from guessing it. On Unix the file is named for this process, because several Harness processes
+ * may share one state folder: closing a server removes its socket file, so a shared name would let
+ * one process delete, and the next one take over, the path another's sessions still call. The token
+ * still decides what a caller may do.
+ */
+export declare function socketPath(stateDir: string): string;
+export declare class SessionSocket {
+    private readonly handlers;
+    private server;
+    private listening;
+    private socketPathValue;
+    private readonly grants;
+    /**
+     * A second key per token, handed out once. The token is in the session's environment, where a
+     * command the model runs can read it; this key is claimed by the session's extension as it
+     * loads, before any model turn, and kept in its memory only.
+     */
+    private readonly controls;
+    private readonly clients;
+    constructor(path: string, handlers: SocketHandlers);
+    get path(): string;
+    issue(grant: SocketGrant): string;
+    revoke(token: string): void;
+    revokeSession(sessionId: string): void;
+    /** Runs one request line and returns the reply line's object. */
+    handle(line: string, connection?: {
+        waiting: (grant: SocketGrant | null) => void;
+        keep?: (keep: boolean) => void;
+    }): Promise<{
+        result: unknown;
+    } | {
+        error: unknown;
+    }>;
+    private serve;
+    private bind;
+    /** Binds the usual path, or an instance-specific path if another Harness owns it. */
+    private bindAvailablePath;
+    /** Binds the socket once; later calls wait for the same bind. */
+    listen(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/sdk/terminal/socket.js

@@ -0,0 +1,287 @@
+// The session socket: how a process the harness did not start in-process (the `pi` command in
+// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
+// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON.
+// A connection carries one request unless the request asks to `keep` it open, in which case the
+// reply leaves it open for the next request. Each terminal session holds a random token bound to
+// its caller, its connected-apps grant, and its controller; the token stops working when the
+// terminal ends.
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { log } from "../core/bus.js";
+import { HarnessError, toErrorShape } from "../core/errors.js";
+import { newId } from "../core/fs.js";
+const MAX_REQUEST_BYTES = 1024 * 1024;
+/** macOS refuses a socket path longer than 103 bytes. */
+const MAX_SOCKET_PATH = 100;
+/**
+ * Each Harness process listens on its own path. Windows has no socket files for Node's `net`: it
+ * listens on a named pipe in a machine-wide namespace, and a random name keeps another local process
+ * from guessing it. On Unix the file is named for this process, because several Harness processes
+ * may share one state folder: closing a server removes its socket file, so a shared name would let
+ * one process delete, and the next one take over, the path another's sessions still call. The token
+ * still decides what a caller may do.
+ */
+export function socketPath(stateDir) {
+    if (process.platform === 'win32')
+        return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`;
+    const path = join(stateDir, 'run', `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+    if (Buffer.byteLength(path) <= MAX_SOCKET_PATH)
+        return path;
+    return join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+}
+const OWN_SOCKET = /^harness-(\d+)-[0-9a-f]+\.sock$/;
+/** Removes socket files left in `folder` by Harness processes that are no longer running. */
+function pruneDeadSockets(folder) {
+    let names;
+    try {
+        names = readdirSync(folder);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const pid = Number(OWN_SOCKET.exec(name)?.[1]);
+        if (!pid || pid === process.pid || isRunning(pid))
+            continue;
+        rmSync(join(folder, name), { force: true });
+    }
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function alternateSocketPath(path) {
+    const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+    return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+}
+/** A named pipe has no folder, file mode, or owner to check or clean up. */
+const isPipePath = (path) => path.startsWith('\\\\.\\pipe\\');
+/** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
+function refusedBind(path, error) {
+    const code = error?.code;
+    if (code !== 'EACCES' && code !== 'EPERM')
+        return error;
+    if (isPipePath(path)) {
+        return new HarnessError('session_socket_denied', `The session pipe ${path} could not be created (${code}).`, 'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.');
+    }
+    let folder;
+    try {
+        const stat = statSync(dirname(path));
+        folder = `${dirname(path)} is owned by uid ${stat.uid} with mode ${(stat.mode & 0o777).toString(8)}`;
+    }
+    catch {
+        folder = `${dirname(path)} could not be read`;
+    }
+    const uid = process.getuid?.() ?? 'unknown';
+    return new HarnessError('session_socket_denied', `The session socket ${path} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`, 'Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state.');
+}
+export class SessionSocket {
+    handlers;
+    server = null;
+    listening = null;
+    socketPathValue;
+    grants = new Map();
+    /**
+     * A second key per token, handed out once. The token is in the session's environment, where a
+     * command the model runs can read it; this key is claimed by the session's extension as it
+     * loads, before any model turn, and kept in its memory only.
+     */
+    controls = new Map();
+    clients = new Set();
+    constructor(path, handlers) {
+        this.handlers = handlers;
+        this.socketPathValue = path;
+    }
+    get path() { return this.socketPathValue; }
+    issue(grant) {
+        const token = `${newId()}${newId()}`.replaceAll('-', '');
+        this.grants.set(token, grant);
+        return token;
+    }
+    revoke(token) {
+        this.grants.delete(token);
+        this.controls.delete(token);
+    }
+    revokeSession(sessionId) {
+        for (const [token, grant] of this.grants)
+            if (grant.sessionId === sessionId)
+                this.revoke(token);
+    }
+    /** Runs one request line and returns the reply line's object. */
+    async handle(line, connection) {
+        try {
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                throw new HarnessError('invalid_request', 'The request is not JSON.');
+            }
+            connection?.keep?.(request.keep === true);
+            const token = typeof request.token === 'string' ? request.token : '';
+            const grant = this.grants.get(token);
+            if (!grant)
+                throw new HarnessError('unauthorized', 'This session token is not valid. It ends when its terminal session ends.');
+            if (typeof request.event === 'string') {
+                if (!grant.terminal)
+                    throw new HarnessError('unknown_method', 'This session has no terminal controller.');
+                connection?.waiting(grant);
+                try {
+                    return { result: (await grant.terminal.accept(request.event, (request.data ?? {}))) ?? {} };
+                }
+                finally {
+                    connection?.waiting(null);
+                }
+            }
+            const call = typeof request.call === 'string' ? request.call : '';
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            if (['wiki.', 'skill.', 'recall.', 'trajectory.'].some((prefix) => call.startsWith(prefix)))
+                return { result: this.handlers.memory(grant.caller(), call, params) };
+            if (call === 'tools.list' && !grant.broker)
+                return { result: { tools: [] } };
+            if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
+                if (!grant.broker)
+                    throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.');
+                return { result: await this.handlers.apps(grant.broker, call, params) };
+            }
+            if (call === 'control.claim') {
+                if (this.controls.has(token))
+                    throw new HarnessError('unauthorized', "This session's control key was already claimed.");
+                const key = `${newId()}${newId()}`.replaceAll('-', '');
+                this.controls.set(token, key);
+                return { result: { key } };
+            }
+            if (call.startsWith('terminal.') && grant.terminal?.control) {
+                const key = this.controls.get(token);
+                if (!key || request.control !== key)
+                    throw new HarnessError('unauthorized', 'Only a person at this terminal can answer decisions or change its draft state.');
+                return { result: await grant.terminal.control(call, params) };
+            }
+            if ((call.startsWith('plugins.') || call.startsWith('hub.')) && this.handlers.plugins) {
+                const key = this.controls.get(token);
+                return { result: await this.handlers.plugins(grant, call, params, key !== undefined && request.control === key) };
+            }
+            if (call.startsWith('accounts.') && this.handlers.accounts) {
+                const key = this.controls.get(token);
+                return { result: await this.handlers.accounts(grant, call, params, key !== undefined && request.control === key) };
+            }
+            throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+        catch (error) {
+            return { error: toErrorShape(error) };
+        }
+    }
+    serve(client) {
+        let buffer = '';
+        let busy = false;
+        let ended = false;
+        let waiting = null;
+        this.clients.add(client);
+        client.on('error', () => { });
+        client.once('close', () => {
+            this.clients.delete(client);
+            // A decision the native process was waiting on can no longer reach it.
+            waiting?.terminal?.disconnected();
+        });
+        // Requests on one connection run one at a time, in order.
+        const next = () => {
+            if (busy || ended)
+                return;
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            busy = true;
+            client.pause();
+            let keep = false;
+            void this.handle(line, { waiting: (grant) => void (waiting = grant), keep: (value) => void (keep = value) }).then((reply) => {
+                busy = false;
+                const text = `${JSON.stringify(reply)}\n`;
+                if (!keep || client.destroyed) {
+                    ended = true;
+                    client.end(text);
+                    return;
+                }
+                client.write(text);
+                client.resume();
+                next();
+            });
+        };
+        client.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
+                client.destroy();
+                return;
+            }
+            next();
+        });
+    }
+    bind(path) {
+        return new Promise((resolve, reject) => {
+            const server = createServer((client) => this.serve(client));
+            server.once('error', reject);
+            server.listen(path, () => {
+                if (!isPipePath(path)) {
+                    try {
+                        chmodSync(path, 0o600);
+                    }
+                    catch (error) {
+                        log('session socket permissions', error instanceof Error ? error.message : String(error));
+                    }
+                }
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    /** Binds the usual path, or an instance-specific path if another Harness owns it. */
+    async bindAvailablePath() {
+        if (!isPipePath(this.path)) {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            pruneDeadSockets(dirname(this.path));
+        }
+        try {
+            await this.bind(this.path);
+        }
+        catch (error) {
+            if (isPipePath(this.path) || error.code !== 'EADDRINUSE')
+                throw refusedBind(this.path, error);
+            this.socketPathValue = alternateSocketPath(this.path);
+            try {
+                await this.bind(this.path);
+            }
+            catch (alternateError) {
+                throw refusedBind(this.path, alternateError);
+            }
+        }
+    }
+    /** Binds the socket once; later calls wait for the same bind. */
+    listen() {
+        this.listening ??= this.bindAvailablePath().catch(error => {
+            this.listening = null;
+            throw error;
+        });
+        return this.listening;
+    }
+    async close() {
+        this.grants.clear();
+        const server = this.server;
+        this.server = null;
+        this.listening = null;
+        for (const client of this.clients)
+            client.destroy();
+        if (server)
+            await new Promise((resolve) => server.close(() => resolve()));
+        if (!isPipePath(this.path))
+            rmSync(this.path, { force: true });
+    }
+}

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

@@ -0,0 +1,52 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type SecretStore } from "../accounts/secrets.js";
+import { type InteractiveProfile, type SecretBackendDescriptor } from "../core/interactiveProfile.js";
+import { type Harness, type HarnessOptions } from "../harness.js";
+import type { TerminalLaunch } from "./terminals.js";
+export interface StandalonePaths {
+    dataRoot: string;
+    stateDir: string;
+    /**
+     * `--account-state <dir>`: sign in as the accounts kept in that state directory. A launch that
+     * shares it and the state's `secrets.json` sees the same sign-in, so one sign-in serves both.
+     */
+    accountState?: string | null;
+    /** `--worktree [name]`: start in a new managed worktree (true) or the named one. */
+    worktree?: string | true | null;
+    /** `--variant <scope>`: run on that scope's head, as a host's agent of that scope does. */
+    variant?: string | null;
+    /** `--remote-control`, `--rc`: turn on `/remote-control` as the terminal opens. */
+    remoteControl?: boolean;
+    /**
+     * `--daemon`: run in the long-lived harness for these folders, starting it when it is not running,
+     * so a reply outlives this window (ADR-0083). The frontend is then a client of the harness.
+     */
+    daemon?: boolean;
+}
+export interface StandaloneDependencies {
+    home?: string;
+    cwd?: string;
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+    createSessionId?: () => string;
+    createHarness?: (options: HarnessOptions) => Harness;
+    hostSecretStore?: (descriptor: Extract<SecretBackendDescriptor, {
+        kind: 'host';
+    }>) => SecretStore | Promise<SecretStore>;
+    spawn?: typeof nodeSpawn;
+}
+export declare function standaloneArguments(argv: string[]): string[] | null;
+export interface ResolvedStandaloneOptions {
+    paths: StandalonePaths;
+    profile: InteractiveProfile;
+}
+export declare function resolveStandaloneOptions(argv: string[], home?: string, cwd?: string): ResolvedStandaloneOptions;
+/** The harness a standalone launch, or the long-lived harness for the same folders, runs. */
+export declare function createStandaloneHarness(paths: StandalonePaths, profile: InteractiveProfile, dependencies?: Pick<StandaloneDependencies, 'createHarness' | 'hostSecretStore'>): Promise<Harness>;
+/** What every launch needs before its first terminal: the profile's default variant and an account. */
+export declare function ensureStandaloneDefaults(harness: Harness, paths: StandalonePaths, profile: InteractiveProfile): string;
+/** Where a terminal in `cwd` keeps its compiled instructions and native history. */
+export declare function terminalSessionFolder(dataRoot: string, cwd: string): string;
+export declare function parseStandaloneOptions(argv: string[], home?: string, cwd?: string): StandalonePaths;
+export declare function spawnFrontend(launch: TerminalLaunch, cwd: string, spawn?: typeof nodeSpawn): Promise<number>;
+export declare function runStandaloneTerminal(argv: string[], dependencies?: StandaloneDependencies): Promise<number>;