@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/terminal/piExtension.js

@@ -0,0 +1,392 @@
+import { Type } from 'typebox';
+import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
+import { runAccountsMenu } from "./accountsMenu.js";
+import { runPluginsMenu } from "./pluginMenu.js";
+import { runHubMenu } from "./hubMenu.js";
+import { claimTerminalControl, controlCall } from "./control.js";
+import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { askUserTool } from "../tools/askUser.js";
+import { sessionNameTool } from "../tools/sessionName.js";
+import { PLAN_INSTRUCTIONS, planRefusal } from "../sessions/planMode.js";
+import { pruneToolImages } from "../world/images.js";
+/** How much text a tool handed back to the model. */
+function resultSize(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return typeof result === 'string' ? result.length : null;
+    return content.reduce((total, part) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0);
+}
+async function withParentCancellation(signal, work) {
+    const stop = () => { void controlCall('terminal.interrupt').catch(() => { }); };
+    if (signal?.aborted)
+        stop();
+    signal?.addEventListener('abort', stop, { once: true });
+    try {
+        return await work();
+    }
+    finally {
+        signal?.removeEventListener('abort', stop);
+    }
+}
+/** /hub, /plugins and /accounts are pages: the owned terminal fills the screen, and Pi's own dialogs ignore the field. */
+const PAGE = { page: true };
+export default async function (pi, planRun, getSession) {
+    await terminalCall('startup', { phase: 'Pi extension loaded' });
+    let context = null;
+    let nativeSubagents = false;
+    let subagentParent = false;
+    let timer = null;
+    let polling = false;
+    let failure;
+    const emptyUsage = () => ({ inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, requests: 0, costUsd: 0 });
+    let usage = emptyUsage();
+    let reasoningTokens;
+    let costReported = false;
+    let requestStartedAt = null;
+    const toolStartedAt = new Map();
+    const fileTools = new Map();
+    // The harness's own tools for this session (connected apps and what the application offers).
+    let stage = 'Tool discovery';
+    try {
+        await terminalCall('startup', { phase: stage });
+        const connection = connectionFromEnv();
+        // Claimed here, before the model has run anything, and kept in this process's memory: a
+        // command the model runs can read the session token from its environment, never this key.
+        const control = await claimTerminalControl(connection).catch(() => null);
+        pi.registerCommand('hub', {
+            description: 'Browse and install reviewed skills, plugins, and reusable documents',
+            handler: async (_args, ctx) => {
+                if (!control)
+                    return ctx.ui.notify('This session cannot install hub items.', 'warning');
+                await runHubMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 300_000, control));
+            }
+        });
+        pi.registerCommand('plugins', {
+            description: 'See what this session loads, and switch a plugin on or off or trust its code',
+            handler: async (_args, ctx) => {
+                if (!control)
+                    return ctx.ui.notify('This session cannot change plugins.', 'warning');
+                const { projectId } = await socketCall(connection, 'plugins.session', {}, 15_000, control).catch(() => ({ projectId: null }));
+                await runPluginsMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 60_000, control), projectId);
+            }
+        });
+        pi.registerCommand('accounts', {
+            description: 'Add, sign in to, check, switch, or remove the Pi accounts this harness uses',
+            handler: async (_args, ctx) => {
+                if (!control)
+                    return ctx.ui.notify('This session cannot manage accounts.', 'warning');
+                const session = await socketCall(connection, 'accounts.session', {}, 15_000, control).catch(() => null);
+                if (!session)
+                    return ctx.ui.notify('This session has no account to manage.', 'warning');
+                const outcome = await runAccountsMenu({
+                    select: (title, options) => ctx.ui.select(title, options, PAGE),
+                    confirm: (title, message) => ctx.ui.confirm(title, message),
+                    input: (title, placeholder) => ctx.ui.input(title, placeholder),
+                    notify: (message, level) => ctx.ui.notify(message, level)
+                }, (method, params) => socketCall(connection, method, params ?? {}, 120_000, control), session);
+                // The session restarts on the account it chose: Pi ends here, and the launcher starts it again.
+                if (outcome === 'relaunch')
+                    ctx.shutdown();
+            }
+        });
+        const { tools } = await socketCall(connection, 'tools.list', {}, 15_000);
+        stage = 'Tool registration';
+        for (const tool of tools) {
+            pi.registerTool({
+                name: tool.name,
+                label: tool.label,
+                description: tool.description,
+                parameters: Type.Unsafe(tool.parameters),
+                async execute(_id, input) {
+                    const result = await socketCall(connection, 'tools.call', { name: tool.name, input: input }, 1_230_000);
+                    const images = (result.images ?? []).map((image) => ({ type: 'image', data: image.data, mimeType: image.mimeType }));
+                    return { content: [{ type: 'text', text: result.text }, ...images], details: result.details };
+                }
+            });
+        }
+        const native = await controlCall('terminal.subagents.tools');
+        nativeSubagents = native.tools.length > 0;
+        for (const tool of native.tools)
+            pi.registerTool({
+                name: tool.name, label: tool.label, description: tool.description, parameters: Type.Unsafe(tool.parameters),
+                execute: async (_id, input, signal) => {
+                    const result = await withParentCancellation(signal, () => controlCall('terminal.subagents.call', { name: tool.name, input }, 2_147_483_647));
+                    return { content: [{ type: 'text', text: result.text }], details: result.details ?? {} };
+                }
+            });
+    }
+    catch (error) {
+        await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => { });
+        throw error;
+    }
+    // Only the latest screenshots stay in what the model sees (world/images.ts).
+    pi.on('context', (event) => {
+        const messages = pruneToolImages(event.messages);
+        return messages === event.messages ? undefined : { messages: messages };
+    });
+    pi.on('session_start', async (_event, ctx) => {
+        context = ctx;
+        if (timer)
+            clearInterval(timer);
+        await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile() });
+        timer = setInterval(() => {
+            if (polling || !context)
+                return;
+            polling = true;
+            void terminalCall('poll', {}, 5_000)
+                .then(({ command }) => {
+                if (command?.type === 'interrupt')
+                    context?.abort();
+                else if (command?.type === 'send') {
+                    if (context?.ui.getEditorText().trim())
+                        throw new Error('The terminal contains a user draft.');
+                    // Pi 1.2 needs deliverAs while a run is busy; a message sent then waits for that run to finish.
+                    pi.sendUserMessage(command.text, context?.isIdle() === false ? { deliverAs: 'followUp' } : undefined);
+                }
+            })
+                .catch(() => {
+                context?.abort();
+                if (timer)
+                    clearInterval(timer);
+            })
+                .finally(() => {
+                polling = false;
+            });
+        }, 100);
+    });
+    pi.on('before_agent_start', async (event, ctx) => {
+        context = ctx;
+        failure = undefined;
+        usage = emptyUsage();
+        reasoningTokens = undefined;
+        costReported = false;
+        // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
+        const begun = await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' });
+        if (nativeSubagents) {
+            pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
+            await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
+            subagentParent = true;
+        }
+        if (planRun && event.messageType === 'user') {
+            if (planRun.active)
+                event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
+            else
+                delete event.systemPromptOptions.sections.plan;
+        }
+        const bang = event.messageType === 'user' ? /^\s*!\s*([\s\S]+)$/u.exec(event.prompt) : null;
+        if (!bang)
+            return;
+        const command = bang[1];
+        const id = `initial-bash:${begun.runId}`;
+        const started = Date.now();
+        await terminalCall('tool', { phase: 'start', id, name: 'bash', summary: command.slice(0, 200), input: JSON.stringify({ command }) });
+        let refusal;
+        let result;
+        if (planRun?.active) {
+            refusal = 'Bash commands are disabled while a plan request is running.';
+        }
+        else {
+            try {
+                const policy = await terminalCall('policy', { tool: 'bash', args: { command } });
+                if (policy.requiresApproval) {
+                    const approval = await terminalCall('approval', { requestId: id, tool: 'bash', args: { command } });
+                    if (approval.decision !== 'approved')
+                        refusal = 'The user denied this Bash command.';
+                }
+                else if (!policy.allowed) {
+                    refusal = policy.reason ?? 'This Bash command is outside what the terminal allows.';
+                }
+                if (!refusal) {
+                    const session = getSession?.();
+                    if (!session)
+                        refusal = 'The native session is unavailable.';
+                    else
+                        result = await session.executeBash(command, undefined, { id });
+                }
+            }
+            catch (error) {
+                refusal = error instanceof Error ? error.message : 'The Bash policy or command failed.';
+            }
+        }
+        const output = result?.output ?? refusal ?? 'The command did not complete.';
+        const outputTruncated = output.length > 24_000;
+        await terminalCall('tool', {
+            phase: 'end', id, name: 'bash', ok: !refusal && result?.exitCode === 0 && !result.cancelled,
+            durationMs: Date.now() - started, resultChars: output.length,
+            output: outputTruncated ? `${output.slice(0, 23_987)}\n…[truncated]` : output,
+            ...(outputTruncated ? { outputTruncated: true } : {})
+        });
+        const instruction = refusal
+            ? `The user's initial Bash command was not run. Reason: ${refusal}. Do not claim that it ran; explain the limitation and ask how to proceed.`
+            : 'The user’s initial Bash command has already run. Read its native Bash result and explain what it shows. Do not run the same command again unless the user explicitly asks.';
+        return { message: { customType: 'xingular-initial-bash', content: instruction, display: false, details: {} } };
+    });
+    const deliverChildren = async (event, ctx, settle) => {
+        if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted)
+            return;
+        const result = await withParentCancellation(ctx.signal, () => controlCall('terminal.subagents.delivery', { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2_147_483_647));
+        if (!result)
+            return;
+        return { entries: [...event.entries, { type: 'custom_message', customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true };
+    };
+    pi.on('turn_end', (event, ctx) => deliverChildren(event, ctx, false));
+    pi.on('agent_before_settle', (event, ctx) => deliverChildren(event, ctx, true));
+    pi.on('message_end', async (event) => {
+        if (event.message.role !== 'assistant')
+            return;
+        if (event.message.stopReason === 'error' || event.message.stopReason === 'aborted')
+            failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`;
+        const text = event.message.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+        if (text)
+            await terminalCall('message', { text });
+        if (event.message.usage) {
+            const reported = event.message.usage;
+            usage.inputTokens += reported.input ?? 0;
+            usage.outputTokens += reported.output ?? 0;
+            usage.cacheReadTokens += reported.cacheRead ?? 0;
+            usage.cacheWriteTokens += reported.cacheWrite ?? 0;
+            usage.requests += 1;
+            if (typeof reported.reasoning === 'number')
+                reasoningTokens = (reasoningTokens ?? 0) + reported.reasoning;
+            const cost = reported.cost?.total;
+            if (typeof cost === 'number') {
+                usage.costUsd += cost;
+                costReported = true;
+            }
+            const identity = { model: event.message.model, provider: event.message.provider };
+            const { costUsd, ...tokens } = usage;
+            await terminalCall('usage', {
+                ...tokens,
+                ...(costReported ? { costUsd, costSource: 'harness' } : {}),
+                ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+                contextTokens: (reported.input ?? 0) + (reported.cacheRead ?? 0) + (reported.cacheWrite ?? 0),
+                ...(context?.model?.contextWindow ? { contextWindow: context.model.contextWindow } : {}),
+                ...identity,
+                request: {
+                    index: usage.requests,
+                    ...identity,
+                    responseId: event.message.responseId,
+                    inputTokens: reported.input ?? 0,
+                    cacheReadTokens: reported.cacheRead ?? 0,
+                    cacheWriteTokens: reported.cacheWrite ?? 0,
+                    outputTokens: reported.output ?? 0,
+                    ...(typeof reported.reasoning === 'number' ? { reasoningTokens: reported.reasoning } : {}),
+                    ...(typeof cost === 'number' ? { costUsd: cost, costSource: 'harness' } : {}),
+                    ...(requestStartedAt === null ? {} : { durationMs: Date.now() - requestStartedAt }),
+                    stopReason: event.message.stopReason
+                }
+            });
+            requestStartedAt = null;
+        }
+    });
+    pi.on('turn_start', async () => {
+        requestStartedAt = Date.now();
+    });
+    pi.on('tool_call', async (event) => {
+        if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+            const reason = planRefusal(event.toolName, new Set()) ?? `Plan mode is research-only: ${event.toolName} is not available in this session.`;
+            return { block: true, reason };
+        }
+        try {
+            const policy = await controlCall('terminal.policy', { tool: event.toolName, args: event.input });
+            if (policy.requiresApproval) {
+                const approval = await controlCall('terminal.approval', { requestId: event.toolCallId, tool: event.toolName, args: event.input });
+                if (approval.decision === 'approved')
+                    return;
+                return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' };
+            }
+            if (!policy.allowed)
+                return { block: true, reason: policy.reason ?? 'Outside what this session may do.' };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return { block: true, reason: `The terminal controller is unavailable: ${detail}` };
+        }
+    });
+    pi.on('tool_execution_start', async (event) => {
+        if (['edit', 'write'].includes(event.toolName) && typeof event.args.path === 'string')
+            fileTools.set(event.toolCallId, event.args.path);
+        toolStartedAt.set(event.toolCallId, Date.now());
+        await terminalCall('tool', { phase: 'start', id: event.toolCallId, name: event.toolName, summary: JSON.stringify(event.args).slice(0, 200) });
+    });
+    pi.on('tool_execution_end', async (event) => {
+        const started = toolStartedAt.get(event.toolCallId);
+        toolStartedAt.delete(event.toolCallId);
+        const resultChars = resultSize(event.result);
+        await terminalCall('tool', { phase: 'end', id: event.toolCallId, name: event.toolName, ok: !event.isError, ...(started === undefined ? {} : { durationMs: Date.now() - started }), ...(resultChars === null ? {} : { resultChars }) });
+        const path = fileTools.get(event.toolCallId);
+        fileTools.delete(event.toolCallId);
+        if (!event.isError && path)
+            await terminalCall('file', { path, change: 'modified' });
+    });
+    pi.on('agent_settled', async (event, ctx) => {
+        if (subagentParent && !event.aborted && !failure) {
+            try {
+                await controlCall('terminal.subagents.verify', { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2_147_483_647);
+            }
+            catch (error) {
+                failure = error instanceof Error ? error.message : String(error);
+            }
+        }
+        subagentParent = false;
+        await terminalCall('settled', { error: failure, aborted: event.aborted });
+    });
+    pi.on('user_bash', async () => {
+        throw new Error('Use the ! command composer so this action can be checked.');
+    });
+    pi.on('session_shutdown', async () => {
+        if (timer)
+            clearInterval(timer);
+        timer = null;
+        context = null;
+        // This clears the controller's readiness while the next native session binds. The
+        // process-level control claim survives replacement; only the session poller stops.
+        await terminalCall('shutdown').catch(() => { });
+    });
+    const naming = sessionNameTool(() => ({
+        get sessionName() { return pi.getSessionName(); },
+        setSessionName: name => pi.setSessionName(name)
+    }));
+    pi.registerTool({
+        name: naming.name, label: naming.label, description: naming.description,
+        parameters: Type.Unsafe(naming.parameters(Type)),
+        async execute(_id, input) {
+            const result = await naming.execute(input);
+            return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+        }
+    });
+    const ask = askUserTool({ requestAnswers: questions => terminalCall('questions', { questions }, 1_230_000) });
+    pi.registerTool({
+        name: ask.name, label: ask.label, description: ask.description,
+        parameters: Type.Unsafe(ask.parameters(Type)),
+        async execute(_id, input) {
+            const result = await ask.execute(input);
+            return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+        }
+    });
+    pi.registerTool({
+        name: 'ask_user_question',
+        label: 'Ask a question',
+        description: 'Ask the user a question and wait for their answer. Every question must include at least one choice and at least one choice must be recommended. Recommendations are visual only and never preselect answers; submitted choices keep their labels. Mark at most one choice recommended for single-choice questions or several when multiSelect is true.',
+        parameters: Type.Object({
+            question: Type.String(),
+            options: Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()), recommended: Type.Optional(Type.Boolean()) }), {
+                minItems: 1,
+                contains: Type.Object({ recommended: Type.Literal(true) })
+            }),
+            multiSelect: Type.Optional(Type.Boolean())
+        }),
+        async execute(id, input) {
+            if (!Array.isArray(input.options) || input.options.length === 0)
+                throw new Error('Every question needs at least one choice.');
+            const recommendedCount = input.options.filter(option => option.recommended).length;
+            if (recommendedCount === 0)
+                throw new Error('Every question needs at least one recommended choice.');
+            if (!input.multiSelect && recommendedCount > 1)
+                throw new Error('A single-choice question may recommend at most one option.');
+            const answer = await terminalCall('question', { requestId: id, ...input });
+            return { content: [{ type: 'text', text: JSON.stringify(answer) }], details: undefined };
+        }
+    });
+    await terminalCall('startup', { phase: 'Pi hooks registered' });
+}

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,70 @@
+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>;
+}
+/**
+ * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
+ * machine-wide namespace. A random name keeps another local process from guessing it and standing
+ * in front of the session; 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>;
+}