@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/terminal/piExtension.js

@@ -0,0 +1,377 @@
+import { Type } from 'typebox';
+import { QUESTION_SKETCH_MAX_LENGTH, QUESTION_SKETCH_PATTERN, questionSketchError } from "../sessions/contracts.js";
+import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
+import { controlCall } from "./control.js";
+import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { askUserTool } from "../tools/askUser.js";
+import { checklistTool } from "../tools/checklist.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);
+    }
+}
+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();
+        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 };
+        }
+    });
+    // The checklist is recorded on the harness run; the shared tool validates and the socket carries the event.
+    let recorded = Promise.resolve();
+    const checklist = checklistTool({ emit: (_type, payload) => { recorded = terminalCall('checklist', payload); } });
+    pi.registerTool({
+        name: checklist.name, label: checklist.label, description: checklist.description,
+        parameters: Type.Unsafe(checklist.parameters(Type)),
+        async execute(_id, input) {
+            recorded = Promise.resolve();
+            const result = await checklist.execute(input);
+            await recorded;
+            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. Include a concise 1–2 word summary label; if omitted, the terminal derives one from the question. 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. When a UI diagram helps compare choices, set uiSketch: true and include a detailed, bounded ASCII wireframe for every choice. Use ASCII tables and panel borders to show the affected element alongside relevant neighboring UI, with readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes, not a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels.',
+        parameters: Type.Object({
+            summary: Type.Optional(Type.String({ description: 'A concise label of one or two words' })),
+            question: Type.String(),
+            uiSketch: Type.Optional(Type.Literal(true, { description: 'Enable an ASCII sketch preview; when true, every choice must include a sketch.' })),
+            options: Type.Array(Type.Object({
+                label: Type.String(),
+                description: Type.Optional(Type.String()),
+                recommended: Type.Optional(Type.Boolean()),
+                sketch: Type.Optional(Type.String({ minLength: 1, maxLength: QUESTION_SKETCH_MAX_LENGTH, pattern: QUESTION_SKETCH_PATTERN, description: 'Literal ASCII UI wireframe: 1–24 LF-separated lines, at most 80 printable ASCII characters per line. Include the affected element and neighboring UI using structured table/panel borders with fixed, matching outer-edge columns on every row. Required for every choice when uiSketch is true.' }))
+            }), {
+                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 sketchError = questionSketchError(input.uiSketch, input.options);
+            if (sketchError)
+                throw new Error(sketchError);
+            const summary = typeof input.summary === 'string' ? input.summary.trim() : '';
+            if (summary && (summary.length > 100 || summary.split(/\s+/u).filter(Boolean).length > 2)) {
+                throw new Error('The question summary must be a concise 1–2 word label of no more than 100 characters.');
+            }
+            const answer = await terminalCall('question', { requestId: id, ...input, ...(summary ? { summary } : {}) });
+            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,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>;
+}