@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/controller.js

@@ -0,0 +1,579 @@
+// One `pi` command running in a terminal, as the harness sees it. The terminal itself belongs
+// to whoever embeds the harness; this follows the native process through its extension's
+// telemetry (never by reading the screen), turns each native turn into a run, and answers the
+// extension's questions about policy, approvals, and what to do next.
+import { createHash, randomUUID } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { isActiveStatus, runStatusSchema } from "../sessions/contracts.js";
+import { briefTitle } from "../sessions/subagents.js";
+import { MAIN_PROFILE, SubagentMonitor } from "./subagentMonitor.js";
+import { STALL_CHECK_MS, childStalled, replyStalled, waitingOnChildren } from "../sessions/stallWatch.js";
+/** Stop codes the native extension may report for a reply it settled itself. */
+const SETTLED_CODES = new Set(['slice_budget', 'compaction_thrash', 'needs_person', 'unfinished']);
+function monitorRun(record, relation, profile, runtime) {
+    return {
+        id: record.id,
+        parentRunId: record.parentRunId,
+        relation,
+        title: record.title ?? (briefTitle(record.goal) || (relation === 'main' ? 'Main agent' : '')),
+        goal: record.goal,
+        status: runStatusSchema.parse(record.status),
+        startedAt: record.startedAt,
+        endedAt: record.endedAt,
+        profile: relation === 'main' ? MAIN_PROFILE : profile,
+        ...runtime
+    };
+}
+const READY_TIMEOUT_MS = 90_000;
+const ACK_TIMEOUT_MS = 25_000;
+export class TerminalController {
+    hooks;
+    run = null;
+    lastRunId = null;
+    pending = new Map();
+    pendingRevision = 0;
+    pendingWaiters = new Set();
+    subagents = new SubagentMonitor();
+    subagentParentRunId = null;
+    ready = false;
+    disposed = false;
+    dirty = false;
+    multilineDraft = false;
+    startupError = null;
+    startupPhase = 'Waiting for the native extension';
+    delivery = null;
+    nativeId;
+    seen = new Map();
+    commands = [];
+    /** When the reply last produced something other than a heartbeat; silence is what a stall is. */
+    progressAt = 0;
+    runningTools = new Map();
+    /** Each live subagent's own clock: its last real event and the tools it is inside. */
+    children = new Map();
+    stallRequested = null;
+    stallTimer = null;
+    constructor(hooks) {
+        this.hooks = hooks;
+        this.nativeId = hooks.nativeSessionId;
+    }
+    pendingChanged() {
+        this.pendingRevision += 1;
+        for (const wake of this.pendingWaiters)
+            wake();
+    }
+    setPending(key, value) {
+        this.pending.set(key, value);
+        this.pendingChanged();
+    }
+    deletePending(key) {
+        if (this.pending.delete(key))
+            this.pendingChanged();
+    }
+    async waitPending(revision) {
+        if (revision === this.pendingRevision && !this.disposed) {
+            await new Promise(resolve => {
+                const wake = () => { clearTimeout(timer); this.pendingWaiters.delete(wake); resolve(); };
+                const timer = setTimeout(wake, 20_000);
+                this.pendingWaiters.add(wake);
+            });
+        }
+        return { revision: this.pendingRevision, requests: [...this.pending.values()] };
+    }
+    get nativeSessionId() {
+        return this.nativeId;
+    }
+    get activeRun() {
+        return this.run && !this.run.finished ? this.run : null;
+    }
+    /** The run this terminal is showing, or the last one it finished: `/context` reads it after a reply. */
+    get lastRun() {
+        return this.activeRun?.runId ?? this.lastRunId;
+    }
+    state() {
+        return { ready: this.ready, dirty: this.dirty, active: !!this.activeRun || !!this.delivery };
+    }
+    requestId(nativeId) {
+        return createHash('sha256').update(`${this.hooks.sessionId}:${this.run?.runId}:${nativeId}`).digest('hex');
+    }
+    begin(nativeTurnId, text, launch = {}) {
+        if (this.startupError)
+            throw new Error(this.startupError);
+        this.dirty = false;
+        this.multilineDraft = false;
+        if (this.run && !this.run.finished)
+            return this.run;
+        const delivery = this.delivery;
+        if (delivery && text && delivery.text !== text)
+            throw new Error('The native prompt did not match the reserved delivery. Inspect the terminal before continuing.');
+        const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text, ...launch });
+        this.run = run;
+        this.lastRunId = run.runId;
+        this.subagentParentRunId = run.runId;
+        this.watchProgress();
+        this.subagents.begin(run.runId);
+        run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }));
+        if (text)
+            run.emit('message.completed', { messageId: nativeTurnId, role: 'user', text });
+        delivery?.resolve();
+        this.delivery = null;
+        return run;
+    }
+    finish(outcome, message, reason, code) {
+        this.stopStallWatch();
+        this.run?.finish(outcome, message ? { code: code === 'provider_error' ? 'provider_error' : 'terminal_attention', message } : undefined, reason, code);
+        this.run = null;
+        this.seen.clear();
+        if (this.pending.size) {
+            this.pending.clear();
+            this.pendingChanged();
+        }
+    }
+    watchProgress() {
+        this.progressAt = Date.now();
+        this.runningTools.clear();
+        this.children.clear();
+        this.stallRequested = null;
+        if (this.stallTimer)
+            clearInterval(this.stallTimer);
+        this.stallTimer = setInterval(() => this.checkStall(), STALL_CHECK_MS);
+        this.stallTimer.unref?.();
+    }
+    stopStallWatch() {
+        if (this.stallTimer)
+            clearInterval(this.stallTimer);
+        this.stallTimer = null;
+        this.stallRequested = null;
+        this.runningTools.clear();
+        this.children.clear();
+    }
+    /**
+     * Ends a reply its native turn can no longer finish: the process is alive and keeps reporting, but
+     * the reply produced nothing for the whole window (a model request that never came back). A person
+     * may already be answering an approval, and a tool may still be working, so neither is cut short.
+     * A reply that is only waiting for subagents is judged by them: a quiet child is ended on its own
+     * clock, which returns the wait and lets the reply carry on without anyone stepping in.
+     */
+    checkStall() {
+        const run = this.activeRun;
+        if (!run || this.pending.size)
+            return;
+        const now = Date.now();
+        const children = [...this.children.values()].map((child) => ({ progressAt: child.progressAt, runningTools: [...child.tools.values()], stopRequestedAt: child.stopRequestedAt }));
+        for (const [id, child] of this.children) {
+            if (!childStalled(now, { progressAt: child.progressAt, runningTools: [...child.tools.values()], stopRequestedAt: child.stopRequestedAt }))
+                continue;
+            child.stopRequestedAt = now;
+            this.hooks.telemetry('stall');
+            void this.hooks.interrupt?.(id, { reason: 'stalled', code: 'stalled' }).catch(() => { });
+        }
+        if (this.stallRequested)
+            return;
+        const tools = [...this.runningTools.values()];
+        if (waitingOnChildren(now, tools.map((tool) => tool.name), children))
+            return;
+        if (!replyStalled({ now, progressAt: this.progressAt, runningTools: tools.map((tool) => tool.at) }))
+            return;
+        this.stallRequested = run.runId;
+        this.hooks.telemetry('stall');
+        this.commands.push({ type: 'interrupt' });
+    }
+    /** Hands the native process an instruction and waits until it acknowledges the prompt. */
+    async send(runId, text) {
+        if (this.disposed)
+            throw new HarnessError('terminal_not_ready', 'Reopen the terminal before sending instructions.');
+        if (this.activeRun || this.delivery)
+            throw new HarnessError('session_busy', 'This terminal has an active task or delivery.');
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        while (!this.ready && !this.startupError && !this.disposed && Date.now() < deadline)
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        if (this.disposed)
+            throw new HarnessError('terminal_not_ready', 'The terminal stopped during initialization.');
+        if (this.startupError)
+            throw new HarnessError('terminal_not_ready', this.startupError);
+        if (!this.ready)
+            throw new HarnessError('terminal_not_ready', `The native telemetry handshake is missing (${this.startupPhase}). Inspect the terminal sign-in or trust screen.`);
+        if (this.dirty)
+            throw new HarnessError('terminal_has_draft', 'The terminal contains user input. Submit or clear it before handing back control.');
+        let timer;
+        const ack = new Promise((resolve, reject) => {
+            timer = setTimeout(() => reject(new HarnessError('delivery_uncertain', 'The native prompt acknowledgement was not received. Inspect the terminal; this instruction will not be resent.')), ACK_TIMEOUT_MS);
+            this.delivery = { runId, text, resolve, reject };
+        });
+        // Delivery can fail while the native process is still starting the turn. Observe it immediately.
+        void ack.catch(() => { });
+        try {
+            this.commands.push({ type: 'send', text });
+            await ack;
+        }
+        catch (error) {
+            this.ready = false;
+            this.startupError = error instanceof Error ? error.message : String(error);
+            this.delivery = null;
+            this.commands.length = 0;
+            this.commands.push({ type: 'interrupt' });
+            this.finish('failed', this.startupError);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** What the person typed into the terminal, so an instruction is never sent over their draft. */
+    onInput(data) {
+        if (!this.ready || this.activeRun || data === '\u0003')
+            return;
+        if (data.includes('\n') || data.includes('\r'))
+            this.multilineDraft = true;
+        this.dirty = data !== '\u0015' || this.multilineDraft;
+    }
+    /** The native process hung up while it was waiting for a decision. */
+    disconnected() {
+        if (this.disposed)
+            return;
+        this.ready = false;
+        this.commands.push({ type: 'interrupt' });
+        this.finish('failed', 'The native decision callback disconnected. Inspect the terminal before continuing.');
+    }
+    /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
+    observe(event, descendant = false) {
+        if (this.disposed || !this.activeRun || (!descendant && event.runId !== this.activeRun.runId))
+            return;
+        if (event.type === 'question.requested') {
+            const payload = event.payload;
+            this.setPending(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId });
+        }
+        else if (event.type === 'approval.requested') {
+            const payload = event.payload;
+            if (!payload.automatic && (descendant || payload.target === 'workspace-write')) {
+                this.setPending(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId });
+            }
+        }
+        else if (event.type === 'approval.resolved') {
+            this.deletePending(String(event.payload.approvalId));
+        }
+        else if (event.type === 'question.answered') {
+            this.deletePending(String(event.payload.questionId));
+        }
+    }
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId, run, event, profile = null, runtime = {}) {
+        if (this.disposed || this.activeRun?.runId !== parentRunId || run.relation !== 'subagent')
+            return;
+        this.subagents.observe(parentRunId, monitorRun(run, 'subagent', profile, runtime), event);
+        this.trackChild(run, event);
+    }
+    /** Folds a child's event into its own stall clock; a heartbeat only proves the process lives. */
+    trackChild(run, event) {
+        const status = event.payload.status;
+        const settled = event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && typeof status === 'string' && !isActiveStatus(status));
+        if (settled || !isActiveStatus(run.status)) {
+            this.children.delete(run.id);
+            return;
+        }
+        const child = this.children.get(run.id) ?? { progressAt: Date.now(), tools: new Map(), stopRequestedAt: null };
+        if (event.type !== 'heartbeat')
+            child.progressAt = Date.now();
+        const toolCallId = String(event.payload.toolCallId ?? '');
+        if (event.type === 'tool.started' && toolCallId)
+            child.tools.set(toolCallId, Date.now());
+        else if (event.type === 'tool.completed')
+            child.tools.delete(toolCallId);
+        this.children.set(run.id, child);
+    }
+    /** An event of the tracked parent run itself, shown as the `main` row; it outlives settlement. */
+    observeMain(run, event, runtime = {}) {
+        if (this.disposed || this.subagentParentRunId !== run.id || run.relation)
+            return;
+        this.subagents.observe(run.id, monitorRun(run, 'main', null, runtime), event);
+    }
+    /** Shows a saved parent run and its descendants, as they ended, until another run begins. */
+    restoreMonitor(parent, children) {
+        if (this.disposed || this.activeRun || this.delivery)
+            return;
+        this.subagentParentRunId = parent.record.id;
+        this.subagents.restore(parent.record.id, [
+            { run: monitorRun(parent.record, 'main', null, parent.runtime ?? {}), events: parent.events },
+            ...children.map((child) => ({ run: monitorRun(child.record, 'subagent', child.profile ?? null, child.runtime ?? {}), events: child.events }))
+        ]);
+    }
+    /** Read-only child activity for the latest parent run, retained until another run begins. */
+    subagentSnapshot() {
+        return this.subagentParentRunId ? this.subagents.snapshot(this.subagentParentRunId) : [];
+    }
+    /** The socket grants this interface only to the process that owns terminal input. */
+    async control(call, data) {
+        if (this.disposed)
+            throw new HarnessError('terminal_not_ready', 'This terminal has ended.');
+        if (call === 'terminal.draft') {
+            this.dirty = data.dirty === true;
+            this.multilineDraft = false;
+            return {};
+        }
+        if (call === 'terminal.pending')
+            return { requests: [...this.pending.values()] };
+        if (call === 'terminal.pending.wait')
+            return this.waitPending(data.revision);
+        if (call === 'terminal.interrupt') {
+            const run = this.activeRun;
+            if (!run || !this.hooks.interrupt)
+                return {};
+            // Pi's abort reports through here as a person's Esc does; one the stall watch asked for is a stall.
+            return this.hooks.interrupt(run.runId, this.stallRequested === run.runId ? { reason: 'stalled', code: 'stalled' } : undefined);
+        }
+        if (call === 'terminal.policy') {
+            const run = this.activeRun;
+            if (!run || typeof data.tool !== 'string' || !data.tool)
+                throw new HarnessError('invalid_request', 'An active run and tool name are required.');
+            return this.hooks.policy(run, data.tool, data.args ?? {});
+        }
+        if (call === 'terminal.workspaceBoundaryBypass') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash')
+                throw new HarnessError('invalid_request', 'An active run and Bash command are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { bypass: await this.hooks.workspaceBoundaryBypass(run, 'bash', args) };
+        }
+        if (call === 'terminal.workspaceEscape') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash' || typeof data.reason !== 'string' || !data.reason)
+                throw new HarnessError('invalid_request', 'An active run, Bash command, and outside-scope request are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { approved: await this.hooks.workspaceEscape(run, 'bash', args, data.reason) };
+        }
+        if (call === 'terminal.approval')
+            return this.requestNativeApproval(data);
+        if (call === 'terminal.answers' && this.hooks.answerQuestions) {
+            const run = this.activeRun;
+            const batchId = String(data.batchId ?? '');
+            const requests = [...this.pending.values()].filter(request => request.batchId === batchId);
+            if (!run || !batchId || !requests.length || !Array.isArray(data.answers))
+                throw new HarnessError('invalid_request', 'This question batch is no longer pending.');
+            this.hooks.answerQuestions(String(requests[0].runId ?? run.runId), batchId, data.answers);
+            return {};
+        }
+        const requestId = String(data.requestId ?? '');
+        const request = this.pending.get(requestId);
+        const run = this.activeRun;
+        if (!request || !run)
+            throw new HarnessError('invalid_request', 'This terminal decision is no longer pending.');
+        if (call === 'terminal.approve' && request.type === 'approval' && this.hooks.resolveApproval) {
+            if (data.decision !== 'approved' && data.decision !== 'denied')
+                throw new HarnessError('invalid_request', 'Choose approve or deny.');
+            const alwaysAllow = data.alwaysAllow === true;
+            if (alwaysAllow && request.rememberable !== true)
+                throw new HarnessError('invalid_request', 'This approval cannot be remembered for other sessions.');
+            let decision = data.decision;
+            if (decision === 'approved' && request.direct === true) {
+                const operation = request.operation;
+                const tool = typeof operation?.tool === 'string' ? operation.tool : '';
+                const current = await this.hooks.policy(run, tool, operation?.args ?? {});
+                if (!current.allowed && !current.requiresApproval)
+                    decision = 'denied';
+                if (alwaysAllow && current.rememberable !== true) {
+                    request.rememberable = false;
+                    throw new HarnessError('invalid_request', 'This tool can no longer be allowed across sessions. Review the approval again.');
+                }
+            }
+            if (decision === 'approved' && alwaysAllow)
+                this.hooks.allowToolGlobally(String(request.target ?? ''));
+            this.hooks.resolveApproval(String(request.runId ?? run.runId), requestId, decision);
+            return {};
+        }
+        if (call === 'terminal.answer' && request.type === 'question' && this.hooks.answerQuestion) {
+            if (!data.answer || !Array.isArray(data.answer.selected))
+                throw new HarnessError('invalid_request', 'A question answer is required.');
+            this.hooks.answerQuestion(String(request.runId ?? run.runId), requestId, data.answer);
+            return {};
+        }
+        throw new HarnessError('unknown_method', `Unknown terminal control ${call}.`);
+    }
+    async requestNativeApproval(data) {
+        const run = this.activeRun;
+        const requestId = typeof data.requestId === 'string' ? data.requestId : '';
+        const tool = typeof data.tool === 'string' ? data.tool : '';
+        if (!run || !requestId || !tool)
+            throw new HarnessError('invalid_request', 'An active run, request id, and tool name are required.');
+        const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+        const policy = await this.hooks.policy(run, tool, args);
+        if (!policy.allowed && !policy.requiresApproval)
+            return { decision: 'denied' };
+        if (policy.allowed && !policy.requiresApproval)
+            return { decision: 'approved' };
+        const key = this.requestId(`approval:${requestId}`);
+        const existing = this.seen.get(key);
+        if (existing)
+            return { decision: await existing };
+        const action = JSON.stringify(args);
+        const operation = { tool, args };
+        const response = run.requestApproval({
+            requestId: key,
+            target: tool,
+            action,
+            operation,
+            rememberable: policy.rememberable === true,
+            standing: policy.standing
+        });
+        this.setPending(key, {
+            type: 'approval', requestId: key, runId: run.runId, target: tool, action,
+            operation, rememberable: policy.rememberable === true, direct: true
+        });
+        this.seen.set(key, response);
+        try {
+            return { decision: await response };
+        }
+        finally {
+            this.deletePending(key);
+        }
+    }
+    async accept(event, data) {
+        if (this.disposed)
+            throw new Error('This terminal controller was disposed.');
+        // Streamed reply text is frequent and only feeds run events; it is not host telemetry.
+        if (event !== 'poll' && event !== 'delta')
+            this.hooks.telemetry(event);
+        if (event === 'startup') {
+            this.startupPhase = String(data.phase);
+            return {};
+        }
+        if (event === 'startupFailed') {
+            this.startupError = String(data.reason ?? 'The native extension could not initialize.');
+            this.ready = false;
+            this.finish('failed', this.startupError);
+            return {};
+        }
+        if (event === 'poll')
+            return { command: this.commands.shift() ?? null };
+        // A heartbeat proves the turn is alive, not that it is working; only real events restart the clock.
+        if (event !== 'heartbeat')
+            this.progressAt = Date.now();
+        if (event === 'ready') {
+            if (!this.ready) {
+                this.dirty = false;
+                this.multilineDraft = false;
+            }
+            this.ready = true;
+            if (typeof data.nativeSessionId === 'string' && data.nativeSessionId) {
+                if (this.nativeId !== data.nativeSessionId) {
+                    this.subagents.clear();
+                    this.subagentParentRunId = null;
+                }
+                this.nativeId = data.nativeSessionId;
+                this.hooks.native(data.nativeSessionId);
+            }
+            const owners = Array.isArray(data.owners) ? data.owners.filter((id) => typeof id === 'string') : [];
+            if (!this.activeRun && !this.delivery && this.hooks.hydrate)
+                this.hooks.hydrate(owners);
+            return {};
+        }
+        if (event === 'begin') {
+            const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''), {
+                model: typeof data.model === 'string' && data.model ? data.model : null,
+                effort: typeof data.effort === 'string' && data.effort ? data.effort : null
+            });
+            await this.hooks.afterBegin?.(run, String(data.text ?? '')).catch(() => { });
+            return { runId: run.runId, workspaceRoot: this.hooks.workspaceRoot(run) };
+        }
+        if (event === 'shutdown') {
+            this.ready = false;
+            this.finish('interrupted', undefined, undefined, 'terminal_closed');
+            return {};
+        }
+        if (event === 'settled') {
+            // A reply that stopped at its work-slice boundary is interrupted, not completed: the record
+            // says `slice_complete` (or `stalled`) so a host can continue it (PROP-0041). So is one that
+            // ended with open todo items: `needs_person` or `unfinished` (ADR-0069).
+            const stalled = this.stallRequested !== null && this.stallRequested === this.run?.runId;
+            const reason = data.error ? undefined : stalled ? 'stalled' : typeof data.reason === 'string' ? data.reason : undefined;
+            const outcome = data.error ? 'failed' : data.aborted || reason ? 'interrupted' : 'completed';
+            const code = data.error ? data.errorCode === 'provider_error' ? 'provider_error' : undefined : stalled ? 'stalled' : SETTLED_CODES.has(data.code) ? data.code : data.aborted ? 'user_abort' : undefined;
+            this.finish(outcome, data.error ? String(data.error) : undefined, reason, code);
+            return {};
+        }
+        const run = this.run;
+        if (!run)
+            throw new Error('Native telemetry arrived without an active turn.');
+        if (event === 'policy')
+            return this.hooks.policy(run, String(data.tool), data.args ?? {});
+        if (event === 'questions') {
+            if (!Array.isArray(data.questions) || !data.questions.length || data.questions.length > 5)
+                throw new HarnessError('invalid_request', 'Ask between one and five questions.');
+            const questions = data.questions.map(question => ({ ...question, requestId: randomUUID() }));
+            return run.requestAnswers(questions);
+        }
+        if (event === 'approval' || event === 'question') {
+            const key = this.requestId(`${event}:${String(data.requestId ?? JSON.stringify(data))}`);
+            const existing = this.seen.get(key);
+            if (existing)
+                return event === 'approval' ? { decision: await existing } : existing;
+            if (event === 'question') {
+                const summary = typeof data.summary === 'string' && data.summary.trim() ? data.summary.trim() : undefined;
+                const sketchMode = data.uiSketch === undefined ? {} : { uiSketch: data.uiSketch };
+                const response = run.requestAnswer({ requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
+                this.setPending(key, { type: 'question', requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
+                this.seen.set(key, response);
+                return response.finally(() => this.deletePending(key));
+            }
+            const response = run.requestApproval({
+                requestId: key,
+                target: String(data.target ?? 'Native action'),
+                action: String(data.action ?? '{}'),
+                operation: { tool: String(data.tool ?? data.target), args: data.args ?? {} },
+                rememberable: false
+            });
+            this.setPending(key, { type: 'approval', requestId: key, target: String(data.target ?? 'Action'), action: String(data.action ?? '{}') });
+            this.seen.set(key, response);
+            try {
+                return { decision: await response };
+            }
+            finally {
+                this.deletePending(key);
+            }
+        }
+        if (event === 'usage')
+            run.emit('usage.updated', data);
+        else if (event === 'refusal')
+            run.emit('tool.refused', data);
+        else if (event === 'compaction.started' || event === 'compaction.ended')
+            run.emit(event, data);
+        else if (event === 'heartbeat')
+            run.emit('heartbeat', data);
+        else if (event === 'todo' || event === 'checklist')
+            run.emit('todo.updated', { items: data.items });
+        else if (event === 'checkpoint')
+            run.emit('checkpoint', data);
+        else if (event === 'notice')
+            run.emit('extension.notice', data);
+        else if (event === 'file')
+            run.emit('file.changed', data);
+        else if (event === 'delta')
+            run.emit('message.delta', { messageId: String(data.id ?? ''), text: String(data.text ?? '') });
+        else if (event === 'message')
+            run.emit('message.completed', { messageId: data.id ?? randomUUID(), role: data.role ?? 'assistant', text: String(data.text) });
+        else if (event === 'tool') {
+            if (data.phase === 'start')
+                this.runningTools.set(String(data.id), { name: String(data.name ?? ''), at: Date.now() });
+            else
+                this.runningTools.delete(String(data.id));
+            run.emit(data.phase === 'start' ? 'tool.started' : 'tool.completed', {
+                toolCallId: String(data.id),
+                name: String(data.name),
+                ...(data.phase === 'start'
+                    ? { summary: String(data.summary ?? ''), ...(typeof data.input === 'string' ? { input: data.input.slice(0, 24_000) } : {}) }
+                    : { ok: data.ok !== false, ...(typeof data.durationMs === 'number' ? { durationMs: data.durationMs } : {}), ...(typeof data.resultChars === 'number' ? { resultChars: data.resultChars } : {}), ...(typeof data.output === 'string' ? { output: data.output.slice(0, 24_000) } : {}), ...(data.outputTruncated === true ? { outputTruncated: true } : {}) })
+            });
+        }
+        return {};
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.pendingChanged();
+        this.ready = false;
+        this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'));
+        this.delivery = null;
+        this.finish('interrupted', undefined, undefined, 'terminal_closed');
+        this.subagents.clear();
+        this.subagentParentRunId = null;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { CredentialStore } from '@earendil-works/pi-ai';
+type Call = <T>(call: string, params?: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal) => Promise<T>;
+export declare function terminalCredentialStore(call?: Call): CredentialStore;
+export {};

package/dist/sdk/terminal/credentialStore.js

@@ -0,0 +1,33 @@
+import { controlCall } from "./control.js";
+/** Long enough to wait for another holder's lease and the lock, as the host bounds both. */
+const LEASE_CALL_MS = 60_000;
+export function terminalCredentialStore(call = controlCall) {
+    return {
+        async read(providerId, options) {
+            const result = await call('accounts.credentials.read', { provider: providerId }, undefined, options?.signal);
+            return result.credential ?? undefined;
+        },
+        async list(options) {
+            const result = await call('accounts.credentials.list', {}, undefined, options?.signal);
+            return result.credentials ?? [];
+        },
+        async modify(providerId, fn, options) {
+            // The host holds the provider's lock from the lease until the commit, so this read-modify-write
+            // (a refresh or a sign-in) is serialized with every other process on the account.
+            const lease = await call('accounts.credentials.lease', { provider: providerId }, LEASE_CALL_MS, options?.signal);
+            let next;
+            try {
+                next = await fn(lease.current ?? undefined);
+            }
+            catch (error) {
+                await call('accounts.credentials.commit', { leaseId: lease.leaseId }).catch(() => undefined);
+                throw error;
+            }
+            const result = await call('accounts.credentials.commit', { leaseId: lease.leaseId, ...(next === undefined ? {} : { credential: next }) });
+            return result.credential ?? undefined;
+        },
+        async delete(providerId, options) {
+            await call('accounts.credentials.delete', { provider: providerId }, undefined, options?.signal);
+        }
+    };
+}

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

@@ -0,0 +1,44 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { InteractiveProfile } from "../core/interactiveProfile.js";
+import { type HarnessClient } from "../server/socket.js";
+import { type StandaloneDependencies, type StandalonePaths } from "./standalone.js";
+import type { DetachedTerminal } from "./terminals.js";
+export interface DaemonFiles {
+    socket: string;
+    lock: string;
+    log: string;
+}
+export declare function daemonFiles(stateDir: string): DaemonFiles;
+interface LockRecord {
+    pid: number;
+    startedAt: string;
+    socket: string;
+}
+/** The running daemon's lock record, or null when none is running (a stale lock is not one). */
+export declare function daemonRecord(stateDir: string): LockRecord | null;
+/** Takes the state folder's lock for this process, or refuses when another daemon holds it. */
+export declare function acquireDaemonLock(stateDir: string): () => void;
+/** Runs the long-lived harness in this process until it is stopped. */
+export declare function runDaemon(paths: StandalonePaths, profile: InteractiveProfile, dependencies?: Pick<StandaloneDependencies, 'createHarness' | 'hostSecretStore'>): Promise<number>;
+/** Connects to the daemon for these folders, starting it first when `start` is set and none runs. */
+export declare function connectDaemon(paths: StandalonePaths, options?: {
+    start: boolean;
+    spawn?: typeof nodeSpawn;
+    timeoutMs?: number;
+}): Promise<HarnessClient>;
+export interface DaemonTerminalOptions {
+    paths: StandalonePaths;
+    profile: InteractiveProfile;
+    cwd: string;
+    spawn?: typeof nodeSpawn;
+    createSessionId?: () => string;
+    /** Reattach to this detached session instead of starting a new one. */
+    attach?: DetachedTerminal;
+}
+/** `xagent --daemon` and `xagent attach`: a terminal window on the long-lived harness. */
+export declare function runDaemonTerminal(options: DaemonTerminalOptions): Promise<number>;
+/** `xagent attach [session id]`: reconnects a window to a reply that kept running. */
+export declare function runAttach(paths: StandalonePaths, profile: InteractiveProfile, sessionId: string | undefined, cwd: string): Promise<number>;
+/** `xagent daemon <start | stop | status | run>`. */
+export declare function runDaemonCommand(subcommand: string | undefined, paths: StandalonePaths, profile: InteractiveProfile): Promise<number>;
+export {};