@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/piExtension.js

@@ -0,0 +1,847 @@
+// Loaded by the `pi` command in a terminal session (`--extension`). It reports what the native
+// session does to the harness, asks before each tool call, takes instructions the harness
+// queues for it, and gives the session the harness's own tools. It runs in the `pi` process,
+// so everything it knows about the harness comes through the session socket.
+import { readFileSync } from 'node:fs';
+import { createBashTool, createEditTool, createEditToolDefinition, createPowerShellTool, createWriteTool, createWriteToolDefinition } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { bodyOf } from "../core/frontmatter.js";
+import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
+import { controlCall } from "./control.js";
+import { SPAWN_SUBAGENT, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { PLAN_RESEARCH_TOOLS } from "../agents/planResearch.js";
+import { askUserTool } from "../tools/askUser.js";
+import { TODO_WRITE, todoTool } from "../tools/todo.js";
+import { goalStopOutcome, handoffFields, stopCheckpointReason, stopSummary } from "../sessions/goalStop.js";
+import { launchSwitchOff, sessionCheckModel } from "../sessions/completionCheck.js";
+import { GOAL_STATE_ENTRY, GOAL_TOOLS, goalTools } from "../sessions/goal.js";
+import { GOAL_EXTENSION, goalLoop, goalNotice } from "../sessions/goalLoop.js";
+import { activeToolBeat, createSliceState, DEFAULT_SLICE_POLICY, parseWorkSlice, sliceContinuation, workSliceGuard, WORK_SLICE_EXTENSION } from "../sessions/workSlice.js";
+import { DEFAULT_COMMAND_TIMEOUT_SECONDS, withCommandBudget } from "../core/commandBudget.js";
+import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
+import { CAPABILITY_DISCOVERY, describeCapabilities } from "../tools/getCapabilities.js";
+import { PLAN_INSTRUCTIONS, PLAN_REPAIR_CUSTOM_TYPE, PLAN_REPAIR_INSTRUCTIONS, parsePlanOutcome, planRefusal } from "../sessions/planMode.js";
+import { compactionCheckpoint } from "../sessions/compactionCheckpoint.js";
+import { requiredSkillsText, sessionStateText } from "../prompt/compile.js";
+import { pruneToolImages } from "../world/images.js";
+import { parseInitialBashCommand } from "../sessions/initialBash.js";
+import { skillInvocations } from "./tui/skillInvocation.js";
+import { inspectWorkspaceWrite } from "../sessions/workspaceBoundary.js";
+import { createWorkspaceShellTool } from "../core/workspaceBashTool.js";
+import { createWorkspaceBashOperations, runWithWorkspaceWriteScope } from "../core/workspaceSandbox.js";
+import { createWorkspaceFileTools } from "../core/workspaceWriteOperations.js";
+import { BUDGET_GUARD, OUTPUT_TRIM, budgetGuard, outputTrim } from "../plugins/firstParty.js";
+/** How long reply text gathers before it is sent on to a paired phone. */
+const STREAM_FLUSH_MS = 150;
+/** 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, goal) {
+    await terminalCall('startup', { phase: 'Pi extension loaded' });
+    let context = null;
+    let nativeSubagents = false;
+    let subagentParent = false;
+    let stoppedChildren = null;
+    let timer = null;
+    let heartbeat = null;
+    let turnStartedAt = 0;
+    let polling = false;
+    let failure;
+    let failureCode;
+    let messageAborted = false;
+    let turnActive = false;
+    let lastContextTokens;
+    let planRepairAttempted = false;
+    let lastPlanText = '';
+    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;
+    let pendingRefusals = [];
+    const toolStartedAt = new Map();
+    const toolsInFlight = new Map();
+    const fileTools = new Map();
+    const writeAuthorizations = new Map();
+    let workspaceRoot = null;
+    let sessionState = null;
+    let stateDelivered = false;
+    let autoNameTried = false;
+    let lastTodo = [];
+    // 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 };
+                }
+            });
+        }
+        // The harness's own extensions a person switched on, as a structured session loads them inline.
+        const own = await socketCall(connection, 'firstParty.list', {}, 15_000)
+            .then((reply) => reply?.plugins ?? [], () => []);
+        for (const plugin of own) {
+            if (plugin.id === OUTPUT_TRIM)
+                outputTrim(plugin.settings)(pi);
+            if (plugin.id === BUDGET_GUARD)
+                budgetGuard(plugin.settings)(pi);
+        }
+        const native = await controlCall('terminal.subagents.tools');
+        nativeSubagents = native.tools.length > 0;
+        if (planRun && native.profiles)
+            planRun.subagentProfiles = native.profiles;
+        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;
+    }
+    pi.registerTool({
+        ...CAPABILITY_DISCOVERY,
+        parameters: Type.Unsafe(CAPABILITY_DISCOVERY.parameters),
+        async execute(_id, input) {
+            const active = pi.getActiveTools();
+            const tools = pi.getAllTools();
+            const selected = planRun?.active ? [...planRun.allowedTools] : active;
+            const name = input && typeof input === 'object' && typeof input.tool === 'string'
+                ? input.tool
+                : undefined;
+            const text = JSON.stringify(describeCapabilities({
+                capabilities: { version: 1, tools: selected, connectors: planRun?.connectors ?? [], contributions: [] },
+                active,
+                registered: tools
+            }, name));
+            return { content: [{ type: 'text', text }], details: undefined };
+        }
+    });
+    const workspaceBash = createWorkspaceBashOperations(() => workspaceRoot, {
+        bypassWorkspaceBoundary: async (request) => {
+            const result = await controlCall('terminal.workspaceBoundaryBypass', { tool: 'bash', args: { command: request.command, cwd: request.cwd, workspaceRoot: request.workspaceRoot } });
+            return result.bypass;
+        },
+        requestWorkspaceWriteScope: async (request) => {
+            const result = await controlCall('terminal.workspaceEscape', { tool: 'bash', args: { command: request.command, workspaceWriteScope: 'outside' }, reason: request.reason });
+            return result.approved;
+        },
+        workspaceWriteScope: () => planRun?.active ? 'read-only' : undefined
+    });
+    pi.registerTool(createWorkspaceShellTool({ createBashTool, createPowerShellTool }, process.cwd(), workspaceBash));
+    const nativeFileTools = createWorkspaceFileTools({ createWriteTool, createWriteToolDefinition, createEditTool, createEditToolDefinition }, process.cwd(), writeAuthorizations);
+    pi.registerTool(nativeFileTools.write);
+    pi.registerTool(nativeFileTools.edit);
+    // The current name and this run's todo ride with each request; they never change the stable prefix.
+    pi.on('context', (event) => {
+        if (!sessionState || stateDelivered)
+            return;
+        stateDelivered = true;
+        return {
+            messages: [...event.messages, {
+                    role: 'custom',
+                    customType: 'xingular-session-state',
+                    content: sessionState,
+                    display: false,
+                    timestamp: Date.now()
+                }]
+        };
+    });
+    compactionCheckpoint({ planInstructions: () => planRun?.active ? PLAN_INSTRUCTIONS : null })(pi);
+    // A terminal reply is bounded like any other (PROP-0041): a checkpoint at each boundary, and the
+    // reply continues in place up to the policy's slice cap (ADR-0070) before the person decides.
+    let slicePolicy;
+    try {
+        slicePolicy = parseWorkSlice(undefined);
+    }
+    catch (error) {
+        slicePolicy = { ...DEFAULT_SLICE_POLICY };
+        console.error(`${error instanceof Error ? error.message : String(error)} Using the default work slices.`);
+    }
+    const sliceState = createSliceState(slicePolicy);
+    // `XINGULAR_WORK_SLICE=off` at launch leaves terminal replies unbounded, as before PROP-0041.
+    // A goal-claim check's model request counts with the reply's usage, like any other request.
+    const recordCheckUsage = (raw) => {
+        const message = raw;
+        const reported = message.usage;
+        if (!reported)
+            return;
+        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: message.model, provider: message.provider };
+        const { costUsd, ...tokens } = usage;
+        void terminalCall('usage', {
+            ...tokens,
+            ...(costReported ? { costUsd, costSource: 'harness' } : {}),
+            ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+            ...identity,
+            request: {
+                index: usage.requests,
+                ...identity,
+                responseId: 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' } : {}),
+                ...(typeof message.durationMs === 'number' ? { durationMs: message.durationMs } : {}),
+                stopReason: message.stopReason
+            }
+        }).catch(() => undefined);
+    };
+    if (slicePolicy.enabled)
+        workSliceGuard({
+            policy: slicePolicy,
+            state: sliceState,
+            onRefuse: (event, reason) => { pendingRefusals.push(terminalCall('refusal', { toolCallId: event.toolCallId, name: event.toolName, code: 'work_slice', reason: reason.slice(0, 2_000) }).catch(() => { })); }
+        })(pi);
+    // 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;
+        sessionState = null;
+        stateDelivered = false;
+        autoNameTried = false;
+        lastTodo = [];
+        if (timer)
+            clearInterval(timer);
+        // The branch's parent runs let the controller show the latest one's rows again on reopen.
+        await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile(), owners: subagentHistory(ctx.sessionManager.getBranch?.() ?? []).owners });
+        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;
+        failureCode = undefined;
+        messageAborted = false;
+        lastContextTokens = undefined;
+        planRepairAttempted = false;
+        lastPlanText = '';
+        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 : '', model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel?.() ?? null });
+        turnActive = true;
+        workspaceRoot = typeof begun.workspaceRoot === 'string' ? begun.workspaceRoot : null;
+        if (!workspaceRoot)
+            throw new Error('The active project workspace could not be resolved; the turn was not started.');
+        // Every turn marks its run on the branch, so a reopened conversation finds its latest one.
+        pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
+        // A live reply reports progress so a person and the watchdog can tell a long turn from a wedged
+        // one; a turn that stops producing anything is settled with reason `stalled` (INV-RUN-14).
+        turnStartedAt = Date.now();
+        toolsInFlight.clear();
+        if (heartbeat)
+            clearInterval(heartbeat);
+        heartbeat = setInterval(() => {
+            void terminalCall('heartbeat', {
+                steps: sliceState.steps,
+                elapsedMs: Date.now() - turnStartedAt,
+                lastTool: sliceState.lastTool,
+                compactions: sliceState.compactions,
+                slice: sliceState.slice,
+                maxToolCalls: slicePolicy.enabled ? slicePolicy.maxToolCalls : 0,
+                ...activeToolBeat(toolsInFlight)
+            }, 10_000).catch(() => { });
+        }, 30_000);
+        heartbeat.unref?.();
+        stoppedChildren = null;
+        if (nativeSubagents) {
+            const snapshot = await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), plan: planRun?.active === true, history: subagentHistory(ctx.sessionManager.getBranch()) });
+            if (planRun && Array.isArray(snapshot.connectors))
+                planRun.connectors = snapshot.connectors;
+            if (planRun && snapshot.subagentProfiles)
+                planRun.subagentProfiles = snapshot.subagentProfiles;
+            stoppedChildren = snapshot.notice ?? null;
+            subagentParent = true;
+        }
+        if (planRun && event.messageType === 'user') {
+            if (planRun.active)
+                event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
+            else
+                delete event.systemPromptOptions.sections.plan;
+            if (planRun.subagentProfiles)
+                event.systemPromptOptions.sections.subagents = planRun.active ? planRun.subagentProfiles.plan : planRun.subagentProfiles.normal;
+        }
+        const bang = event.messageType === 'user' ? /^\s*!\s*([\s\S]+)$/u.exec(event.prompt) : null;
+        if (!bang)
+            return;
+        const initial = parseInitialBashCommand(bang[1]);
+        const command = initial.command;
+        const args = { command, ...(initial.workspaceWriteScope === 'outside' ? { workspaceWriteScope: 'outside' } : {}) };
+        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(args) });
+        let refusal;
+        let refusalCode;
+        let result;
+        if (!command) {
+            refusal = 'Enter a Bash command after !outside.';
+        }
+        else if (planRun?.active) {
+            refusal = 'Bash commands are disabled while a plan request is running.';
+            refusalCode = 'plan_mode';
+        }
+        else {
+            let checkingGate = true;
+            try {
+                const policy = await terminalCall('policy', { tool: 'bash', args });
+                if (policy.requiresApproval) {
+                    const approval = await terminalCall('approval', { requestId: id, tool: 'bash', args });
+                    if (approval.decision !== 'approved') {
+                        refusal = 'The user denied this Bash command.';
+                        refusalCode = 'approval_denied';
+                    }
+                }
+                else if (!policy.allowed) {
+                    refusal = policy.reason ?? 'This Bash command is outside what the terminal allows.';
+                    refusalCode = 'policy';
+                }
+                checkingGate = false;
+                if (!refusal) {
+                    const session = getSession?.();
+                    if (!session)
+                        refusal = 'The native session is unavailable.';
+                    else
+                        result = await runWithWorkspaceWriteScope(initial.workspaceWriteScope, () => withCommandBudget(() => session.executeBash(command, undefined, { id, operations: workspaceBash }), () => session.abortBash(), DEFAULT_COMMAND_TIMEOUT_SECONDS));
+                }
+            }
+            catch (error) {
+                refusal = error instanceof Error ? error.message : 'The Bash policy or command failed.';
+                if (checkingGate)
+                    refusalCode = 'controller_unavailable';
+            }
+        }
+        if (refusal && refusalCode)
+            await terminalCall('refusal', { toolCallId: id, name: 'bash', code: refusalCode, reason: refusal.slice(0, 2_000) }).catch(() => { });
+        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: {} } };
+    });
+    // A second handler, so the notice joins any initial-Bash message rather than replacing it.
+    pi.on('before_agent_start', async () => {
+        const notice = stoppedChildren;
+        stoppedChildren = null;
+        if (notice)
+            return { message: { customType: SUBAGENT_RESULTS, content: notice.text, display: false, details: { [SUBAGENT_RECEIPT]: notice.receipt } } };
+    });
+    // A `$name` anywhere in the message makes that skill required for this request. The skill's text is
+    // delivered as a hidden request-scoped message, so the person's own wording reaches the model unchanged.
+    pi.on('before_agent_start', async (event) => {
+        if (event.messageType !== 'user' || /^\s*!/u.test(event.prompt))
+            return;
+        if (pi.getSettings?.().enableSkillCommands === false)
+            return;
+        const skills = (pi.getCommands?.() ?? [])
+            .filter((command) => command.source === 'skill')
+            .map((command) => ({
+            name: command.name.replace(/^skill:/, ''),
+            path: command.sourceInfo.path,
+            ...(command.sourceInfo.baseDir ? { baseDir: command.sourceInfo.baseDir } : {})
+        }));
+        if (!skills.length)
+            return;
+        const names = skillInvocations(event.prompt, new Set(skills.map((skill) => skill.name)));
+        if (!names.length)
+            return;
+        const entries = names.map((name) => {
+            const skill = skills.find((candidate) => candidate.name === name);
+            try {
+                return { name, path: skill.path, baseDir: skill.baseDir, body: bodyOf(readFileSync(skill.path, 'utf8')) };
+            }
+            catch {
+                return { name, path: skill.path, body: '' };
+            }
+        });
+        const content = requiredSkillsText(entries);
+        return content ? { message: { customType: 'xingular-required-skills', content, display: false, details: { skills: names } } } : undefined;
+    });
+    // A new user turn starts with an empty todo. The previous list is context, not this run's list.
+    // A substantive first turn also gets a provisional name when the terminal policy allows it.
+    pi.on('before_agent_start', async (event, ctx) => {
+        if (event.messageType !== 'user')
+            return;
+        const branch = ctx.sessionManager.getBranch?.() ?? [];
+        const hasUser = branch.some((entry) => entry.type === 'message' && entry.message?.role === 'user');
+        let name = typeof pi.getSessionName === 'function' ? pi.getSessionName() ?? null : null;
+        if (!name && !autoNameTried && pi.setSessionName) {
+            const candidate = deriveSessionName(event.prompt);
+            if (candidate) {
+                autoNameTried = true;
+                try {
+                    const policy = await controlCall('terminal.policy', { tool: SESSION_NAME, args: { name: candidate } });
+                    if (policy.allowed && !policy.requiresApproval) {
+                        pi.setSessionName(candidate);
+                        name = candidate;
+                    }
+                }
+                catch {
+                    // Session naming is metadata; a refused or failed name never fails the turn.
+                }
+            }
+        }
+        const state = {
+            name,
+            todo: [],
+            ...(lastTodo.length ? { previousTodo: lastTodo } : {}),
+            firstTurn: !hasUser
+        };
+        lastTodo = [];
+        const active = typeof pi.getActiveTools === 'function' ? pi.getActiveTools() : null;
+        sessionState = sessionStateText(state, {
+            name: active ? active.includes(SESSION_NAME) : true,
+            todo: active ? active.includes(TODO_WRITE) : true
+        });
+        stateDelivered = false;
+    });
+    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('agent_before_settle', (event, ctx) => {
+        if (!planRun?.active || planRepairAttempted || event.outcome !== 'completed' || event.continue || ctx.signal?.aborted || failure || sliceState.endedBy || parsePlanOutcome(lastPlanText).kind !== 'invalid')
+            return;
+        planRepairAttempted = true;
+        return {
+            entries: [...event.entries, { type: 'custom_message', customType: PLAN_REPAIR_CUSTOM_TYPE, content: PLAN_REPAIR_INSTRUCTIONS, display: false, details: { reason: 'invalid_plan_outcome' } }],
+            continue: true
+        };
+    });
+    // The stop gate is gone (ADR-0075): a reply the model ends settles as it ends, and the todo list
+    // is progress, not a gate. A /goal (ADR-0072) is the only layer that continues a reply: while one
+    // is active, a reply that would end continues in place; its claim check is the only completion
+    // check.
+    if (goal) {
+        for (const spec of goalTools(() => goal))
+            pi.registerTool({
+                name: spec.name,
+                label: spec.label,
+                description: spec.description,
+                parameters: spec.parameters(Type),
+                async execute(_id, input) {
+                    const result = await spec.execute(input);
+                    return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+                }
+            });
+        // The goal's tools are offered to the model only while a goal exists.
+        const syncGoalTools = (state) => {
+            const active = pi.getActiveTools();
+            const wanted = state !== null && state.status !== 'complete';
+            const has = GOAL_TOOLS.some((name) => active.includes(name));
+            if (wanted && !GOAL_TOOLS.every((name) => active.includes(name)))
+                pi.setActiveTools([...active, ...GOAL_TOOLS.filter((name) => !active.includes(name))]);
+            else if (!wanted && has)
+                pi.setActiveTools(active.filter((name) => !GOAL_TOOLS.includes(name)));
+        };
+        const unsubscribe = goal.subscribe((state) => {
+            try {
+                pi.appendEntry(GOAL_STATE_ENTRY, { goal: state });
+                syncGoalTools(state);
+            }
+            catch {
+                // The session is closing; the next one restores from its own branch.
+            }
+        });
+        pi.on('session_shutdown', () => { unsubscribe(); });
+        pi.on('session_start', (_event, ctx) => {
+            // A goal is restored from the branch, and waits for the person: nothing resumes by itself.
+            const entries = (ctx.sessionManager.getBranch?.() ?? []);
+            const saved = [...entries].reverse().find((entry) => entry.type === 'custom' && entry.customType === GOAL_STATE_ENTRY)?.data?.goal ?? null;
+            goal.restore(saved && (saved.status === 'active') ? { ...saved, status: 'paused', claimed: false } : saved);
+            syncGoalTools(goal.get());
+        });
+        goalLoop({
+            controller: goal,
+            check: launchSwitchOff('XINGULAR_COMPLETION_CHECK') ? null : sessionCheckModel,
+            active: () => !planRun?.active,
+            sliceEnded: () => sliceState.endedBy !== null,
+            failed: () => Boolean(failure),
+            recordUsage: recordCheckUsage,
+            onEvent: (event) => {
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: GOAL_EXTENSION, text: goalNotice(event) }).catch(() => undefined);
+            }
+        })(pi);
+    }
+    // A reply that did work and reached its budget continues as the next slice of the same run
+    // (ADR-0070).
+    if (slicePolicy.enabled)
+        sliceContinuation({
+            policy: slicePolicy,
+            state: sliceState,
+            active: () => !planRun?.active,
+            failed: () => Boolean(failure),
+            blocked: () => goal?.get()?.status === 'blocked',
+            goalActive: () => goal?.active() === true,
+            todo: () => lastTodo,
+            next: () => handoffFields(lastTodo, goal?.get() ?? null).next,
+            onContinue: (ended) => {
+                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: WORK_SLICE_EXTENSION, text: `Work slice ${ended.slice} reached ${ended.limit ?? 'its limit'}; continuing with slice ${ended.slice + 1} of up to ${slicePolicy.maxSlices}.` }).catch(() => undefined);
+            }
+        })(pi);
+    // Reply text as it streams, batched, for a paired phone (remote control). The completed message
+    // carries the same id and replaces whatever streamed.
+    let streamId = null;
+    let streamText = '';
+    let streamTimer = null;
+    let streamCount = 0;
+    const flushStream = () => {
+        streamTimer = null;
+        if (!streamId || !streamText)
+            return;
+        const text = streamText;
+        streamText = '';
+        void terminalCall('delta', { id: streamId, text }).catch(() => undefined);
+    };
+    pi.on('message_update', (event) => {
+        const update = event.assistantMessageEvent;
+        if (event.message.role !== 'assistant' || update.type !== 'text_delta' || !update.delta)
+            return;
+        streamId ??= `${Date.now().toString(36)}-${++streamCount}`;
+        streamText += update.delta;
+        streamTimer ??= setTimeout(flushStream, STREAM_FLUSH_MS);
+    });
+    pi.on('message_end', async (event) => {
+        if (event.message.role !== 'assistant')
+            return;
+        const messageId = streamId;
+        if (streamTimer)
+            clearTimeout(streamTimer);
+        streamTimer = null;
+        streamText = '';
+        streamId = null;
+        if (event.message.stopReason === 'error') {
+            failure = event.message.errorMessage || 'Pi stopped: error';
+            failureCode = 'provider_error';
+        }
+        if (event.message.stopReason === 'aborted')
+            messageAborted = true;
+        const text = event.message.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+        lastPlanText = text;
+        if (text)
+            await terminalCall('message', messageId ? { id: messageId, text } : { text });
+        if (event.message.usage) {
+            const reported = event.message.usage;
+            lastContextTokens = (reported.input ?? 0) + (reported.cacheRead ?? 0) + (reported.cacheWrite ?? 0);
+            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('session_before_compact', async (event, ctx) => {
+        if (!turnActive)
+            return;
+        await terminalCall('compaction.started', { reason: event.reason, ...(lastContextTokens === undefined ? {} : { contextTokens: lastContextTokens }), ...(ctx.model?.contextWindow ? { contextWindow: ctx.model.contextWindow } : {}) });
+    });
+    pi.on('session_compact', async (event) => {
+        if (!turnActive)
+            return;
+        sliceState.compactions += 1;
+        const summary = event.compactionEntry.summary;
+        const chars = Array.from(summary);
+        const marker = '\n…[truncated]';
+        const truncated = chars.length > 24_000;
+        await terminalCall('compaction.ended', { reason: event.reason, aborted: false, tokensBefore: event.compactionEntry.tokensBefore, willRetry: event.willRetry, ...(summary ? { summary: truncated ? `${chars.slice(0, 24_000 - Array.from(marker).length).join('')}${marker}` : summary, ...(truncated ? { summaryTruncated: true } : {}) } : {}) });
+    });
+    pi.on('session_compact_failed', async (event) => {
+        if (!turnActive)
+            return;
+        sliceState.compactions += 1;
+        await terminalCall('compaction.ended', { reason: event.reason, aborted: event.aborted, willRetry: event.willRetry, ...(event.errorMessage ? { error: event.errorMessage.slice(0, 1_000) } : {}) });
+    });
+    pi.on('turn_start', async () => {
+        requestStartedAt = Date.now();
+    });
+    pi.on('tool_call', async (event, ctx) => {
+        const refuse = async (code, reason) => {
+            await terminalCall('refusal', { toolCallId: event.toolCallId, name: event.toolName, code, reason: reason.slice(0, 2_000) }).catch(() => { });
+            return { block: true, reason };
+        };
+        if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+            const reason = planRefusal(event.toolName, new Set(), event.input) ?? `Plan mode is research-only: ${event.toolName} is not available in this session.`;
+            return refuse('plan_mode', reason);
+        }
+        if (planRun?.active && event.toolName === SPAWN_SUBAGENT) {
+            try {
+                const eligibility = await controlCall('terminal.subagents.planSafe', { input: event.input });
+                if (!eligibility.allowed)
+                    return refuse('plan_mode', eligibility.reason ?? 'This profile is not eligible for plan-mode research.');
+            }
+            catch (error) {
+                return refuse('controller_unavailable', `Plan-mode research eligibility could not be verified: ${error instanceof Error ? error.message : 'controller unavailable'}`);
+            }
+        }
+        else if (planRun?.active) {
+            const reason = planRefusal(event.toolName, new Set(PLAN_RESEARCH_TOOLS), event.input);
+            if (reason)
+                return refuse('plan_mode', reason);
+        }
+        let authorization;
+        if ((event.toolName === 'edit' || event.toolName === 'write') && typeof event.input.path === 'string') {
+            try {
+                if (!workspaceRoot)
+                    throw new Error('The active project workspace is unavailable.');
+                const inspection = inspectWorkspaceWrite(workspaceRoot, ctx.cwd, event.toolName, event.input);
+                Object.assign(event.input, inspection.input);
+                if (!inspection.path)
+                    throw new Error('The native file-write target could not be verified.');
+                authorization = {
+                    workspaceRoot,
+                    cwd: ctx.cwd,
+                    path: inspection.path,
+                    outside: inspection.outside,
+                    authorized: false
+                };
+            }
+            catch (error) {
+                return refuse('workspace', error instanceof Error ? error.message : 'The active project workspace could not be verified.');
+            }
+        }
+        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 refuse('approval_denied', 'The user denied this action. Do not repeat it or ask for permission in a message; choose another approach or report what is blocked.');
+            }
+            else if (!policy.allowed) {
+                return refuse('policy', policy.reason ?? 'Outside what this session may do.');
+            }
+            if (authorization) {
+                authorization.authorized = true;
+                writeAuthorizations.set(event.toolCallId, authorization);
+            }
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return refuse('controller_unavailable', `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());
+        toolsInFlight.set(event.toolCallId, { name: event.toolName, at: 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);
+        toolsInFlight.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) => {
+        await Promise.all(pendingRefusals);
+        pendingRefusals = [];
+        if (heartbeat)
+            clearInterval(heartbeat);
+        heartbeat = null;
+        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;
+        // A reply that stopped at its work-slice boundary is not a completed task: the record says so,
+        // so a host can offer the continuation instead of treating it as done (PROP-0041).
+        // An ordinary reply settles as it ends (ADR-0075); only a goal that was blocked, paused or hit
+        // a limit stops it for the person, and the checkpoint carries what is left.
+        const aborted = event.aborted || messageAborted;
+        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? goalStopOutcome(lastTodo, goal?.get() ?? null) : null;
+        if (stop) {
+            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
+        }
+        else if (sliceState.endedBy && !failure && !aborted) {
+            // The guard ended the reply and promised the model the harness would keep its state.
+            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
+        }
+        const reason = sliceState.endedBy ? 'slice_complete' : stop?.code;
+        const code = sliceState.endedBy === 'compaction-thrash' ? 'compaction_thrash' : sliceState.endedBy === 'budget' ? 'slice_budget' : stop?.code;
+        await terminalCall('settled', { error: failure, ...(failureCode ? { errorCode: failureCode } : {}), aborted, ...(reason ? { reason } : {}), ...(code ? { code } : {}) });
+        turnActive = false;
+    });
+    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;
+        if (heartbeat)
+            clearInterval(heartbeat);
+        heartbeat = null;
+        context = null;
+        turnActive = false;
+        sessionState = null;
+        stateDelivered = false;
+        autoNameTried = false;
+        lastTodo = [];
+        // 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 todo list is recorded on the harness run; the shared tool validates and the socket carries the event.
+    let recorded = Promise.resolve();
+    const todo = todoTool({ emit: (_type, payload) => { recorded = terminalCall('todo', payload); } });
+    pi.registerTool({
+        name: todo.name, label: todo.label, description: todo.description,
+        parameters: Type.Unsafe(todo.parameters(Type)),
+        async execute(_id, input) {
+            recorded = Promise.resolve();
+            const result = await todo.execute(input);
+            await recorded;
+            const items = input.items;
+            if (Array.isArray(items))
+                lastTodo = items;
+            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 };
+        }
+    });
+    // One question tool, as in every structured session: the terminal has no ask_user_question alias (PROP-0039).
+    await terminalCall('startup', { phase: 'Pi hooks registered' });
+}