@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/terminal/terminals.js

@@ -0,0 +1,767 @@
+// A host owns the PTY and process supervision; Harness owns the terminal application inside it.
+// This service prepares the isolated account, compiled context, trusted resource selection and
+// socket bridge. The default launch runs our frontend with Pi's persistent SDK runtime.
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Type } from 'typebox';
+import { freezeRun } from "../capabilities/runSnapshot.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
+import { subagentTools } from "../tools/spawnSubagent.js";
+import { configDir, launchEnv } from "../accounts/env.js";
+import { readAudit } from "../accounts/store.js";
+import { log } from "../core/bus.js";
+import { HarnessError, invalid } from "../core/errors.js";
+import { newId, now } from "../core/fs.js";
+import { prependSearchPath, searchPath } from "../core/path.js";
+import { dispatch } from "../tools/dispatch.js";
+import { materialise } from "../variant/materialise.js";
+import * as componentLibrary from "../variant/components.js";
+import * as variantStore from "../variant/store.js";
+import { compile, copyToRun, record, render, saveForSession } from "../prompt/compile.js";
+import { isActiveStatus } from "../sessions/contracts.js";
+import { findRun, loadRun, saveRun, updateRun } from "../sessions/runStore.js";
+import { SESSION_NAME } from "../tools/sessionName.js";
+import { contributionId } from "../plugins/identity.js";
+import { APPS_COMMAND, WIKI_COMMAND } from "./cli.js";
+import { SOCKET_ENV, TOKEN_ENV } from "./client.js";
+import { TerminalController } from "./controller.js";
+import { terminalCommandFiles } from "./launch.js";
+import { SessionSocket, socketPath } from "./socket.js";
+import { harnessLogInfo, readHarnessLogChunk } from "./logs.js";
+import { listTerminalTrajectoryRuns, readTerminalTrajectory } from "./trajectory.js";
+/** Identity of the exact resource decision that this terminal was prepared with. */
+function resourceIdentity(loading) {
+    if (!loading)
+        return 'null';
+    return JSON.stringify({
+        extensions: loading.extensionPaths, builtins: loading.builtins, skills: loading.skillPaths,
+        prompts: loading.promptPaths, themes: loading.themePaths, detached: loading.detached,
+        project: loading.projectCode, packages: loading.packageCode
+    });
+}
+/** Where the package's own build puts them. An application that bundles the harness passes its own. */
+export function defaultAssets() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const dist = [here, join(here, '..', '..'), join(here, '..', '..', 'dist'), join(here, '..', 'dist')].find((folder) => existsSync(join(folder, 'terminal-pi.js'))) ?? here;
+    return {
+        node: process.execPath,
+        cli: join(dist, 'cli.js'),
+        piExtension: join(dist, 'terminal-pi.js'),
+        openTui: join(dist, 'terminal-opentui.js')
+    };
+}
+const READ_ONLY_TOOLS = new Set(['read', 'grep', 'find', 'ls']);
+export class Terminals {
+    options;
+    sessions = new Map();
+    diagnosticOwners = new Map();
+    /** The variant each live session runs, for loading its skills. */
+    variantDirs = new Map();
+    /** The world tools each session was given, so a call can only reach one of them. */
+    worldNames = new Map();
+    worldReadOnly = new Set();
+    socket;
+    assets;
+    /** A session's `/accounts` switch, taken once its Pi process has ended. */
+    relaunches = new Map();
+    constructor(options) {
+        this.options = options;
+        this.assets = options.assets ?? defaultAssets();
+        options.runs.listen(event => {
+            this.sessions.get(event.sessionId)?.controller.observe(event);
+            const record = findRun(options.env.root, event.runId);
+            if (record?.relation !== 'subagent')
+                return;
+            let parentId = record.parentRunId;
+            const seen = new Set();
+            while (parentId && !seen.has(parentId)) {
+                seen.add(parentId);
+                const parent = findRun(options.env.root, parentId);
+                if (!parent)
+                    break;
+                const owner = this.sessions.get(parent.sessionId);
+                if (owner?.controller.activeRun?.runId === parent.id) {
+                    owner.controller.observe(event, true);
+                    break;
+                }
+                parentId = parent.parentRunId;
+            }
+        });
+        this.socket = new SessionSocket(socketPath(options.stateDir), {
+            memory: (caller, call, params) => dispatch(options.env, caller, call, params, { variantDir: (caller.sessionId && this.variantDirs.get(caller.sessionId)) || null }),
+            apps: (session, call, params) => this.appsCall(session, call, params),
+            plugins: (grant, call, params, control) => this.pluginsCall(grant.sessionId, call, params, control),
+            accounts: (grant, call, params, control) => this.accountsCall(grant.sessionId, call, params, control)
+        });
+    }
+    /** The commands a terminal session finds on PATH. Rewritten only when they change. */
+    ensureCommands() {
+        const bin = join(this.options.stateDir, 'run', 'bin');
+        mkdirSync(bin, { recursive: true });
+        for (const name of ['agentx-wiki', 'agentx-mcp', 'agentx-wiki.cmd', 'agentx-mcp.cmd']) {
+            const path = join(bin, name);
+            try {
+                if (lstatSync(path).isFile())
+                    unlinkSync(path);
+            }
+            catch {
+                // These names belonged to the previous generated wrappers.
+            }
+        }
+        for (const [name, mode] of [[WIKI_COMMAND, 'wiki'], [APPS_COMMAND, 'mcp']]) {
+            for (const file of terminalCommandFiles(process.platform, this.assets.node, this.assets.cli, name, mode)) {
+                const path = join(bin, file.name);
+                let current = null;
+                try {
+                    current = readFileSync(path, 'utf8');
+                }
+                catch {
+                    current = null;
+                }
+                if (current !== file.content) {
+                    writeFileSync(path, file.content);
+                    chmodSync(path, 0o755);
+                }
+            }
+        }
+        return bin;
+    }
+    /** The broker's tools, then the world tools whose plugins are on for this session. */
+    async tools(session, listing) {
+        const brokered = this.options.apps.brokerTools(session);
+        const live = this.sessions.get(session.sessionId);
+        const { world } = this.options;
+        if (!world || !live)
+            return brokered;
+        const context = { run: live.controller.activeRun, caller: live.caller, attended: true, subagent: false, sessionKey: session.sessionId, cwd: live.input.cwd };
+        if (!listing)
+            return [...brokered, ...world.tools(context, (_plugin, tool) => this.worldNames.get(session.sessionId)?.has(tool) ?? false)];
+        const on = await this.worldOn(live);
+        const tools = world.tools(context, (plugin, tool) => on(plugin, tool));
+        this.worldNames.set(session.sessionId, new Set(tools.map((tool) => tool.name)));
+        for (const tool of tools)
+            if (tool.readOnly)
+                this.worldReadOnly.add(tool.name);
+        return [...brokered, ...tools];
+    }
+    /** The world tools a new session will have, named in its instructions. */
+    async worldToolNames(input, account) {
+        const { world } = this.options;
+        if (!world || input.connections === false)
+            return [];
+        const list = this.options.pluginControl?.list;
+        const plugins = list ? await list({ cwd: input.cwd, accountId: account.id, projectId: input.projectId ?? null }) : null;
+        const on = plugins ? new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id))) : null;
+        return world.plugins.flatMap((plugin) => (plugin.tools ?? []).map((tool) => tool.name).filter((name) => !on || on.has(contributionId(plugin.id, 'tool', name))));
+    }
+    /** Whether a world tool's plugin is switched on for a session's folder, account and project. */
+    async worldOn(live) {
+        const list = this.options.pluginControl?.list;
+        if (!list)
+            return () => true;
+        const plugins = await list({ cwd: live.input.cwd, accountId: live.account.id, projectId: live.input.projectId ?? null });
+        const on = new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id)));
+        return (plugin, tool) => on.has(contributionId(plugin, 'tool', tool));
+    }
+    async appsCall(session, call, params) {
+        const { apps } = this.options;
+        switch (call) {
+            case 'mcp.list':
+                return apps.list(session);
+            case 'mcp.call':
+                return apps.invoke(session, String(params.name ?? ''), (params.args && typeof params.args === 'object' ? params.args : {}));
+            case 'mcp.revision':
+                return apps.revision(session);
+            case 'tools.list': {
+                const { Type } = await import('typebox');
+                return { tools: (await this.tools(session, true)).map((tool) => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
+            }
+            case 'tools.call': {
+                const tool = (await this.tools(session, false)).find((candidate) => candidate.name === params.name);
+                if (!tool)
+                    throw new HarnessError('unknown_method', `Unknown tool ${String(params.name)}.`);
+                const result = await tool.execute((params.input && typeof params.input === 'object' ? params.input : {}));
+                if (typeof result === 'string')
+                    return { text: result };
+                const images = [...(result.image ? [result.image] : []), ...(result.images ?? [])];
+                return { text: result.text, ...(images.length ? { images } : {}), ...(result.details ? { details: result.details } : {}) };
+            }
+            default:
+                throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+    }
+    /**
+     * `/plugins` in a terminal. Listing is open to the session. A change is taken only from the
+     * session's own extension, which asks the person in the terminal first: the model can reach
+     * this socket from a shell command, and must not be able to trust code or switch it on.
+     */
+    async pluginsCall(sessionId, call, params, control) {
+        const api = this.options.pluginControl;
+        const live = this.sessions.get(sessionId);
+        if (!api || !live)
+            throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        const projectId = live.input.projectId ?? null;
+        const scope = { cwd: live.input.cwd, accountId: live.account.id, projectId };
+        if (call === 'hub.list' && this.options.hub)
+            return this.options.hub.list(params.refresh === true);
+        if (call === 'hub.install' && this.options.hub) {
+            if (!control)
+                throw new HarnessError('unauthorized', 'Only a person at this terminal can install items. Type /hub.');
+            if (typeof params.id !== 'string' || typeof params.version !== 'string')
+                throw invalid('An item id and version are required.');
+            return this.options.hub.install(params.id, params.version);
+        }
+        if (call === 'plugins.list')
+            return api.list(scope);
+        if (call === 'plugins.session')
+            return { projectId };
+        if (!control)
+            throw new HarnessError('unauthorized', 'Only a person at this terminal can change plugins. Type /plugins.');
+        const text = (name) => {
+            if (typeof params[name] !== 'string' || !params[name])
+                throw invalid(`${name} is required.`);
+            return params[name];
+        };
+        switch (call) {
+            case 'plugins.attach':
+            case 'plugins.detach':
+                return api.attach({ ...scope, id: text('id'), scope: params.everywhere === true || !projectId ? {} : { projectId } }, call === 'plugins.attach');
+            case 'plugins.trust':
+                return api.trust({ ...scope, hash: text('hash') });
+            case 'plugins.untrust':
+                return api.untrust({ ...scope, hash: text('hash') });
+            case 'plugins.configure': {
+                const settings = params.settings && typeof params.settings === 'object' && !Array.isArray(params.settings) ? params.settings : {};
+                return api.configure({ ...scope, pluginId: text('pluginId'), settings });
+            }
+            default:
+                throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+    }
+    /**
+     * `/accounts` in a terminal. Every call needs the session's control key: adding, signing in,
+     * or removing an account is a person's choice, never the model's shell command.
+     */
+    async accountsCall(sessionId, call, params, control) {
+        const { accounts } = this.options;
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        if (!control)
+            throw new HarnessError('unauthorized', 'Only a person at this terminal can manage accounts. Type /accounts.');
+        const text = (name) => {
+            if (typeof params[name] !== 'string' || !params[name])
+                throw invalid(`${name} is required.`);
+            return params[name];
+        };
+        const optional = (name) => (typeof params[name] === 'string' ? params[name] : null);
+        switch (call) {
+            case 'accounts.deviceId':
+                return accounts.installationDeviceId();
+            case 'accounts.list':
+                return accounts.overview();
+            case 'accounts.session':
+                return { accountId: live.account.id, label: live.account.label };
+            case 'accounts.create':
+                return accounts.create(text('label'), optional('authKind') ?? 'subscription');
+            case 'accounts.rename':
+                return accounts.rename(text('accountId'), text('label'));
+            case 'accounts.setDefault':
+                return accounts.setDefault(text('accountId'));
+            case 'accounts.remove': {
+                const accountId = text('accountId');
+                // Every terminal in this process counts, this session's own included. Another process's terminals are not visible here.
+                if (accounts.terminalCount(accountId) > 0)
+                    throw new HarnessError('account_in_use', 'A running terminal is using this account, this one included.', 'Switch this session to another account first, then remove it.');
+                return accounts.remove(accountId);
+            }
+            case 'accounts.refresh':
+                return accounts.refresh(optional('accountId'));
+            case 'accounts.providers':
+                return accounts.providers();
+            // A terminal reads and writes only its own account's choices, never the id a caller names.
+            case 'accounts.choices.get':
+                return accounts.choices(live.account.id);
+            case 'accounts.choices.set':
+                return accounts.choose(live.account.id, text('mode'), {
+                    ...(typeof params.model === 'string' ? { model: params.model } : {}),
+                    ...(typeof params.effort === 'string' ? { effort: params.effort } : {})
+                });
+            case 'accounts.loginStart':
+                return accounts.loginStart(text('accountId'), text('provider'), optional('method'));
+            case 'accounts.loginStatus':
+                return accounts.loginStatus(text('accountId'));
+            case 'accounts.loginRespond':
+                accounts.loginRespond(text('loginId'), text('promptId'), optional('value'));
+                return {};
+            case 'accounts.loginCancel':
+                accounts.loginCancel(text('accountId'), optional('loginId'));
+                return {};
+            case 'accounts.setApiKey':
+                return accounts.setApiKey(text('accountId'), text('key'), text('provider'));
+            case 'accounts.removeProvider':
+                return accounts.removeProvider(text('accountId'), text('provider'));
+            case 'accounts.signOut':
+                return accounts.signOut(text('accountId'));
+            case 'accounts.savePool': {
+                const pool = params.pool;
+                if (!pool || typeof pool.label !== 'string' || !Array.isArray(pool.accountIds) || !pool.accountIds.every((id) => typeof id === 'string'))
+                    throw invalid('A pool needs a label and its account ids.');
+                return accounts.savePool({ id: typeof pool.id === 'string' ? pool.id : undefined, label: pool.label, accountIds: pool.accountIds });
+            }
+            case 'accounts.removePool':
+                return accounts.removePool(text('poolId'));
+            case 'accounts.audit':
+                return readAudit(accounts.dir, optional('accountId'), typeof params.limit === 'number' ? params.limit : 100);
+            case 'accounts.relaunch': {
+                // Checked here so a bad choice is refused before the session is asked to end.
+                const target = accounts.resolve(text('accountId'));
+                this.relaunches.set(sessionId, { accountId: target.id, nativeSessionId: live.controller.nativeSessionId });
+                return { accountId: target.id, label: target.label };
+            }
+            default:
+                throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+    }
+    /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
+    takeRelaunch(sessionId) {
+        const request = this.relaunches.get(sessionId) ?? null;
+        this.relaunches.delete(sessionId);
+        return request;
+    }
+    live(sessionId) {
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            throw new HarnessError('terminal_not_ready', 'The terminal controller is unavailable. Reopen this session.');
+        return live;
+    }
+    historyDir(input) {
+        return join(input.sessionFolder, 'pi');
+    }
+    runRecord(live, runId, text) {
+        const { input } = live;
+        return {
+            resumedFromRunId: null,
+            parentRunId: null,
+            relation: null,
+            terminalReason: null,
+            agentId: null,
+            trigger: null,
+            id: runId,
+            projectId: input.projectId ?? null,
+            mode: input.run?.mode ?? 'code',
+            harness: 'pi',
+            sessionType: 'terminal',
+            sessionId: input.sessionId,
+            nativeSessionId: live.controller.nativeSessionId,
+            workingDirectory: input.cwd,
+            worktreeId: input.run?.worktreeId ?? null,
+            goal: text,
+            attachmentCount: 0,
+            startedAt: now(),
+            endedAt: null,
+            status: 'queued',
+            exitCode: null,
+            handoffId: null,
+            accountId: live.account.id
+        };
+    }
+    /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
+    begin(live, reservedRunId, text) {
+        const { root } = this.options.env;
+        const { sessionId } = live.input;
+        if (this.options.runs.activeForSession(sessionId))
+            throw new HarnessError('session_busy', 'A native turn already owns this session.');
+        let runId = reservedRunId;
+        if (runId) {
+            const reserved = loadRun(root, runId);
+            if (reserved.sessionId !== sessionId || reserved.status !== 'queued')
+                throw invalid('Delivery does not own this queued run.');
+        }
+        else {
+            runId = newId();
+            saveRun(root, this.runRecord(live, runId, text || null));
+            copyToRun(root, live.input.sessionFolder, runId);
+        }
+        return this.options.runs.start(sessionId, runId);
+    }
+    async decide(live, run, tool, args) {
+        const record = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(record.status))
+            throw invalid(`The run is no longer active (its status is ${record.status}).`);
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args };
+        const { policy } = this.options;
+        if (policy.scope) {
+            const scope = await policy.scope(call);
+            if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+                return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' };
+            try {
+                await policy.authorize?.(call);
+            }
+            catch (error) {
+                return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' };
+            }
+            const requiresApproval = !!scope.requiresApproval || (scope.allowed && !!scope.humanOnly);
+            return {
+                allowed: scope.allowed,
+                requiresApproval,
+                reason: scope.reason ?? null,
+                rememberable: scope.allowed && !scope.humanOnly,
+                ...(scope.humanOnly ? { standing: scope.allowGlobalApproval ? 'switch' : 'none' } : {})
+            };
+        }
+        // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
+        const name = tool.toLowerCase();
+        if (name === SESSION_NAME || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name))
+            return { allowed: true };
+        if (live.input.readOnly)
+            return { allowed: false, reason: 'This session is read-only.' };
+        return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.' };
+    }
+    async subagentsCall(live, call, params) {
+        const service = this.options.subagents;
+        if (!service || live.input.subagents === null) {
+            if (call === 'terminal.subagents.tools')
+                return { tools: [] };
+            throw invalid('Subagents are disabled for this terminal.');
+        }
+        if (call === 'terminal.subagents.tools')
+            return { tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
+        const run = live.controller.activeRun;
+        if (!run)
+            throw new HarnessError('run_not_active', 'This terminal has no active parent run.');
+        if (call === 'terminal.subagents.register') {
+            if (!Array.isArray(params.tools) || params.tools.some((name) => typeof name !== 'string'))
+                throw invalid('Native tool names are required.');
+            const readOnly = live.input.readOnly === true;
+            const readTools = new Set([...READ_ONLY_TOOLS, SESSION_NAME, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load']);
+            const tools = params.tools.filter((name) => !readOnly || readTools.has(name));
+            const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(live.caller, tools, live.input.cwd) : { version: 1, tools, connectors: [], contributions: [] };
+            freezeRun(this.options.env.root, run.runId, live.caller, capabilities);
+            service.register({
+                run: { id: run.runId, sessionId: live.input.sessionId, mode: live.input.run?.mode ?? 'code', projectId: live.input.projectId, worktreeId: live.input.run?.worktreeId },
+                cwd: live.input.cwd, sessionDir: this.historyDir(live.input), text: '', caller: live.caller,
+                model: typeof params.model === 'string' ? params.model : live.input.model,
+                effort: typeof params.effort === 'string' ? params.effort : null,
+                launch: live.input.launch, tools: { allow: capabilities.tools, gated: capabilities.tools.filter(name => !readTools.has(name)) },
+                connections: live.input.connections === false ? false : { readOnly }, subagents: live.input.subagents,
+                capabilities
+            }, live.account.id, capabilities);
+            service.restore(run.runId, params.history ?? { owners: [], receipts: [] });
+            return { runId: run.runId };
+        }
+        if (call === 'terminal.subagents.verify') {
+            await service.verify(run.runId, params.history);
+            return {};
+        }
+        if (call === 'terminal.subagents.delivery')
+            return service.delivery(run.runId, params.history, params.settle === true);
+        if (call === 'terminal.subagents.call') {
+            const tool = subagentTools(service, run.runId).find(tool => tool.name === params.name);
+            if (!tool)
+                throw invalid('Unknown subagent tool.');
+            const reason = await this.decide(live, run, tool.name, params.input ?? {});
+            if (!reason.allowed)
+                throw new HarnessError('tool_denied', reason.reason ?? 'Subagents are unavailable.');
+            const result = await tool.execute(params.input ?? {});
+            return typeof result === 'string' ? { text: result } : result;
+        }
+        throw invalid('Unknown subagent operation.');
+    }
+    componentsCall(live, call, params) {
+        const root = this.options.env.root;
+        const choice = live.input.variant;
+        const scope = choice && 'scope' in choice ? choice.scope ?? null : null;
+        const head = scope ? variantStore.headVariant(root, scope) : null;
+        const items = componentLibrary.list(root);
+        if (call === 'terminal.components.list') {
+            return {
+                items,
+                addedIds: head ? items.filter(item => componentLibrary.isInVariant(root, head.variant, item.id)).map(item => item.id) : [],
+                writable: Boolean(scope && head),
+                fingerprint: head?.fingerprint ?? null
+            };
+        }
+        if (call === 'terminal.components.add') {
+            if (typeof params.id !== 'string' || !params.id)
+                throw invalid('A component id is required.');
+            if (!scope || !head)
+                throw invalid('This terminal has no writable Harness scope.');
+            const item = items.find(candidate => candidate.id === params.id);
+            if (!item)
+                throw invalid('That component is no longer in the library.');
+            if (item.kind === 'prompts')
+                throw invalid('Prompts stay in the library and cannot be added to a Variant.');
+            if (componentLibrary.isInVariant(root, head.variant, item.id)) {
+                return { fingerprint: head.fingerprint, alreadyPresent: true };
+            }
+            const variant = componentLibrary.addToVariant(root, head.variant, item.id);
+            const record = variantStore.commit(root, scope, variant, {
+                kind: 'edit', note: 'Added library component ' + item.id, components: [item.id]
+            });
+            this.options.bus.emit({ type: 'variants.changed', scope });
+            return { fingerprint: record.fingerprint, alreadyPresent: false };
+        }
+        throw new HarnessError('unknown_method', 'Unknown terminal component operation.');
+    }
+    trajectoryCall(live, call, params) {
+        if (call === 'terminal.trajectory.list') {
+            return { runs: listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId) };
+        }
+        if (call === 'terminal.trajectory.events') {
+            if (typeof params.runId !== 'string' || !params.runId)
+                throw invalid('A run id is required.');
+            const afterSequence = params.afterSequence;
+            if (afterSequence !== undefined && typeof afterSequence !== 'number')
+                throw invalid('The event sequence must be a number.');
+            return readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, params.runId, afterSequence);
+        }
+        throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+    }
+    /** The only terminal frontend: the Bun-run OpenTUI application. */
+    frontendCommand() {
+        return {
+            program: process.env.XINGULAR_HARNESS_BUN || 'bun',
+            // Solid must resolve to its client build for OpenTUI's effects, wherever it is imported.
+            argsPrefix: ['--conditions=browser', this.assets.openTui]
+        };
+    }
+    /**
+     * Prepares an OpenTUI terminal session and returns what to spawn. The caller must report the
+     * process's end with `dispose`, also when it never starts.
+     */
+    async prepare(input) {
+        input = structuredClone(input);
+        const { env, accounts, apps, bus } = this.options;
+        const { root } = env;
+        if (!input?.sessionId || !input.cwd || !input.sessionFolder)
+            throw invalid('A terminal session needs an id, a working folder, and its own folder.');
+        await this.dispose(input.sessionId);
+        const command = this.frontendCommand();
+        // A pinned account is used as it is; it is never exchanged for another one.
+        const account = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null);
+        const launch = launchEnv(accounts.dir, account);
+        const loading = (await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: true, caller: { projectId: input.projectId ?? null } })) ?? null;
+        await this.socket.listen();
+        await accounts.terminalBegin(account);
+        const sessionId = input.sessionId;
+        const caller = { sessionId, projectId: input.projectId ?? null, actor: 'Code', surface: 'cli' };
+        let token = null;
+        try {
+            const broker = input.connections === false ? null : apps.grant({ sessionId, runId: null, caller, readOnly: !!input.readOnly, depth: 0 });
+            // The session keeps these instructions; each of its runs records a copy, and a memory
+            // block that changes later is sent along as a note.
+            const variant = input.variant ? materialise(root, input.variant, { trust: this.options.trust ?? null }) : null;
+            if (variant)
+                this.variantDirs.set(sessionId, variant.dir);
+            const worldTools = await this.worldToolNames(input, account);
+            const launchTools = [...new Set([...(input.launch?.tools ?? []), SESSION_NAME, ...worldTools])];
+            const pack = compile(env, caller, { ...input.launch, tools: launchTools }, variant);
+            record(root, pack);
+            mkdirSync(this.historyDir(input), { recursive: true });
+            saveForSession(input.sessionFolder, pack);
+            const live = {
+                input,
+                account,
+                broker,
+                caller,
+                token: '',
+                controller: new TerminalController({
+                    sessionId,
+                    nativeSessionId: input.nativeSessionId ?? null,
+                    begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
+                    policy: (run, tool, args) => this.decide(live, run, tool, args),
+                    allowToolGlobally: target => { this.options.approvals.allowTool('pi', target); },
+                    native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
+                    telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
+                    interrupt: runId => this.options.runs.interrupt(runId),
+                    resolveApproval: (runId, id, decision) => this.options.runs.resolveApproval(runId, id, decision),
+                    answerQuestion: (runId, id, answer) => this.options.runs.answerQuestion(runId, id, answer),
+                    answerQuestions: (runId, batchId, answers) => this.options.runs.answerQuestions(runId, batchId, answers)
+                })
+            };
+            token = this.socket.issue({
+                sessionId,
+                caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
+                broker,
+                terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
+                        if (call.startsWith('terminal.doctor.')) {
+                            const doctor = this.options.doctor;
+                            if (!doctor)
+                                throw invalid('Diagnostics are unavailable in this host.');
+                            if (call === 'terminal.doctor.start') {
+                                const model = typeof params.model === 'string' ? params.model : live.input.model ?? null;
+                                const tools = [...new Set([
+                                        ...(Array.isArray(params.tools) ? params.tools.filter((name) => typeof name === 'string') : []),
+                                        ...await this.worldToolNames(live.input, live.account)
+                                    ])];
+                                const variantDir = this.variantDirs.get(sessionId);
+                                const report = doctor.start({
+                                    context: { caller: live.caller, cwd: live.input.cwd, accountId: live.account.id, model, tools,
+                                        variant: variantDir ? { dir: variantDir, scope: live.input.variant?.scope } : null },
+                                    mode: params.mode === 'live' ? 'live' : 'local',
+                                    checks: Array.isArray(params.checks) ? params.checks.filter((id) => typeof id === 'string') : [],
+                                    confirmed: params.confirmed === true
+                                });
+                                this.diagnosticOwners.set(report.id, sessionId);
+                                return report;
+                            }
+                            const id = typeof params.id === 'string' ? params.id : '';
+                            if (this.diagnosticOwners.get(id) !== sessionId)
+                                throw invalid('This diagnostic job belongs to another terminal.');
+                            if (call === 'terminal.doctor.read')
+                                return doctor.read(id);
+                            if (call === 'terminal.doctor.cancel')
+                                return doctor.cancel(id);
+                            throw invalid('Unknown diagnostic operation.');
+                        }
+                        if (call.startsWith('terminal.subagents.'))
+                            return this.subagentsCall(live, call, params);
+                        if (call === 'terminal.logs.info')
+                            return harnessLogInfo(this.options.stateDir);
+                        if (call === 'terminal.logs.read') {
+                            const { snapshotSize, offset } = params;
+                            if (typeof snapshotSize !== 'number' || !Number.isSafeInteger(snapshotSize) || snapshotSize < 0 || typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0 || offset >= snapshotSize) {
+                                throw invalid('A valid diagnostics snapshot size and byte offset are required.');
+                            }
+                            const current = harnessLogInfo(this.options.stateDir).size;
+                            if (current === null || snapshotSize > current)
+                                throw invalid('The diagnostics snapshot is no longer available.');
+                            return readHarnessLogChunk(this.options.stateDir, snapshotSize, offset);
+                        }
+                        if (call.startsWith('terminal.components.'))
+                            return this.componentsCall(live, call, params);
+                        if (call.startsWith('terminal.trajectory.'))
+                            return this.trajectoryCall(live, call, params);
+                        if (call === 'terminal.permissions.get') {
+                            const policy = this.options.approvals.read();
+                            return { full: this.options.approvals.isAuto('pi'), globalTools: policy.globalTools.pi ?? [] };
+                        }
+                        if (call === 'terminal.permissions.setFull') {
+                            if (typeof params.enabled !== 'boolean')
+                                throw invalid('A boolean permission state is required.');
+                            return { full: this.options.approvals.setAuto('pi', params.enabled).auto.pi === true };
+                        }
+                        if (call === 'terminal.permissions.setTool') {
+                            if (typeof params.tool !== 'string' || !params.tool.trim() || typeof params.allowed !== 'boolean')
+                                throw invalid('A tool name and boolean permission state are required.');
+                            const policy = params.allowed
+                                ? this.options.approvals.allowTool('pi', params.tool)
+                                : this.options.approvals.revokeTool('pi', params.tool);
+                            return { globalTools: policy.globalTools.pi ?? [] };
+                        }
+                        if (call !== 'terminal.resources')
+                            return live.controller.control(call, params);
+                        const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
+                        if (resourceIdentity(current) !== resourceIdentity(loading))
+                            throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.');
+                        return {};
+                    } }
+            });
+            live.token = token;
+            this.sessions.set(sessionId, live);
+            const args = [...command.argsPrefix, '--append-system-prompt', render(env, pack)];
+            if (input.model)
+                args.push('--model', input.model);
+            if (loading) {
+                // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
+                args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes');
+                for (const path of [...loading.extensionPaths, ...loading.builtins, ...(variant?.extensionPaths ?? [])])
+                    args.push('--extension', path);
+                for (const path of [...(variant?.skillPaths ?? []), ...loading.skillPaths])
+                    args.push('--skill', path);
+                for (const path of loading.promptPaths)
+                    args.push('--prompt-template', path);
+                for (const path of loading.themePaths)
+                    args.push('--theme', path);
+            }
+            // Last, so its gate sees a tool call as every other extension left it.
+            args.push('--extension', this.assets.piExtension, '--session-dir', this.historyDir(input));
+            if (input.nativeSessionId)
+                args.push('--session', input.nativeSessionId);
+            return {
+                program: command.program,
+                args,
+                env: {
+                    ...launch,
+                    XINGULAR_HARNESS_NAME: env.productName,
+                    ...(process.platform === 'win32' ? { XINGULAR_HARNESS_NODE: this.assets.node, XINGULAR_HARNESS_CLI: this.assets.cli } : {}),
+                    ...prependSearchPath(this.ensureCommands(), searchPath()),
+                    [SOCKET_ENV]: this.socket.path,
+                    [TOKEN_ENV]: token
+                },
+                accountId: account.id,
+                nativeSessionId: input.nativeSessionId ?? null
+            };
+        }
+        catch (error) {
+            if (token)
+                this.socket.revoke(token);
+            this.sessions.delete(sessionId);
+            apps.revokeSession(sessionId);
+            await accounts.terminalEnd(account).catch(() => undefined);
+            throw error;
+        }
+    }
+    /** Hands the terminal an instruction as a new run. Resolves once the native session has taken it. */
+    async send(input) {
+        const { env } = this.options;
+        const { root } = env;
+        if (!input.text?.trim())
+            throw invalid('Message is empty.');
+        const live = this.live(input.sessionId);
+        if (this.options.runs.activeForSession(input.sessionId) || live.controller.state().active)
+            throw new HarnessError('session_busy', 'This session is still working.');
+        const runId = input.runId || newId();
+        if (findRun(root, runId))
+            throw invalid('This run already exists.');
+        saveRun(root, this.runRecord(live, runId, input.text));
+        copyToRun(root, live.input.sessionFolder, runId);
+        try {
+            await live.controller.send(runId, input.text);
+        }
+        catch (error) {
+            updateRun(root, runId, (run) => {
+                if (!isActiveStatus(run.status))
+                    return;
+                run.status = 'failed';
+                run.endedAt = now();
+            });
+            throw error;
+        }
+        return { runId };
+    }
+    /** What the person typed into the terminal. */
+    input(sessionId, data) {
+        this.sessions.get(sessionId)?.controller.onInput(data);
+    }
+    state(sessionId) {
+        return this.live(sessionId).controller.state();
+    }
+    has(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /** The terminal process ended (or never started): its turn, tokens, and written credentials go with it. */
+    async dispose(sessionId) {
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            return;
+        for (const [id, owner] of this.diagnosticOwners)
+            if (owner === sessionId) {
+                this.options.doctor?.cancel(id);
+                this.diagnosticOwners.delete(id);
+            }
+        this.sessions.delete(sessionId);
+        this.worldNames.delete(sessionId);
+        void this.options.world?.release(sessionId).catch(() => undefined);
+        live.controller.dispose();
+        this.socket.revoke(live.token);
+        this.options.apps.revokeSession(sessionId);
+        await this.options.accounts.terminalEnd(live.account).catch((error) => log('terminal credentials', error instanceof Error ? error.message : String(error)));
+    }
+    async close() {
+        await Promise.allSettled([...this.sessions.keys()].map((sessionId) => this.dispose(sessionId)));
+        await this.socket.close();
+    }
+}