@xingular/harness 0.1.7 → 1.0.0

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

@@ -0,0 +1,4 @@
+import { type SocketConnection } from "./client.js";
+/** A process owns the claim across native session replacement; it never enters the environment. */
+export declare function claimTerminalControl(connection?: SocketConnection): Promise<string>;
+export declare function controlCall<T = unknown>(call: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;

package/dist/sdk/terminal/control.js

@@ -0,0 +1,25 @@
+import { connectionFromEnv, socketCall } from "./client.js";
+const claims = new Map();
+/** A process owns the claim across native session replacement; it never enters the environment. */
+export function claimTerminalControl(connection = connectionFromEnv()) {
+    const identity = JSON.stringify([connection.socket, connection.token]);
+    let claim = claims.get(identity);
+    if (!claim) {
+        claim = socketCall(connection, 'control.claim', {}, 15_000).then(({ key }) => {
+            if (!key)
+                throw new Error('The terminal controller returned no control key.');
+            return key;
+        }).catch((error) => {
+            // A failed claim is retried by the next call; only a claim that succeeded is kept.
+            claims.delete(identity);
+            throw error;
+        });
+        claims.set(identity, claim);
+    }
+    return claim;
+}
+export async function controlCall(call, params = {}, timeoutMs = 120_000) {
+    const connection = connectionFromEnv();
+    const control = await claimTerminalControl(connection);
+    return socketCall(connection, call, params, timeoutMs, control);
+}

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

@@ -0,0 +1,72 @@
+import type { RunEvent } from "../sessions/contracts.js";
+import type { ActiveRun, ApprovalDecision, QuestionAnswer } from "../sessions/registry.js";
+export interface PolicyReply {
+    allowed: boolean;
+    reason?: string | null;
+    requiresApproval?: boolean;
+    rememberable?: boolean;
+    standing?: 'full' | 'switch' | 'none';
+}
+export interface ControllerHooks {
+    sessionId: string;
+    nativeSessionId: string | null;
+    /** Reserves or creates the run for a native turn and starts tracking it. */
+    begin(input: {
+        reservedRunId: string | null;
+        nativeTurnId: string;
+        text: string;
+    }): ActiveRun;
+    /** Whether a native tool call may run. */
+    policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>;
+    /** Saves a user-selected tool grant in the shared local approval store. */
+    allowToolGlobally(target: string): void;
+    /** The native conversation identity changed. */
+    native(nativeSessionId: string): void;
+    telemetry(event: string): void;
+    interrupt?(runId: string): Promise<void>;
+    resolveApproval?(runId: string, requestId: string, decision: ApprovalDecision): void;
+    answerQuestion?(runId: string, requestId: string, answer: QuestionAnswer): void;
+    answerQuestions?(runId: string, batchId: string, answers: Array<{
+        questionId: string;
+        answer: QuestionAnswer;
+    }>): void;
+}
+export declare class TerminalController {
+    private readonly hooks;
+    private run;
+    private readonly pending;
+    private ready;
+    private disposed;
+    private dirty;
+    private multilineDraft;
+    private startupError;
+    private startupPhase;
+    private delivery;
+    private nativeId;
+    private readonly seen;
+    private readonly commands;
+    constructor(hooks: ControllerHooks);
+    get nativeSessionId(): string | null;
+    get activeRun(): ActiveRun | null;
+    state(): {
+        ready: boolean;
+        dirty: boolean;
+        active: boolean;
+    };
+    private requestId;
+    private begin;
+    private finish;
+    /** Hands the native process an instruction and waits until it acknowledges the prompt. */
+    send(runId: string, text: string): Promise<void>;
+    /** What the person typed into the terminal, so an instruction is never sent over their draft. */
+    onInput(data: string): void;
+    /** The native process hung up while it was waiting for a decision. */
+    disconnected(): void;
+    /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
+    observe(event: RunEvent, descendant?: boolean): void;
+    /** The socket grants this interface only to the process that owns terminal input. */
+    control(call: string, data: Record<string, any>): Promise<unknown>;
+    private requestNativeApproval;
+    accept(event: string, data: Record<string, any>): Promise<unknown>;
+    dispose(): void;
+}

package/dist/sdk/terminal/controller.js

@@ -0,0 +1,351 @@
+// 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";
+const READY_TIMEOUT_MS = 90_000;
+const ACK_TIMEOUT_MS = 25_000;
+export class TerminalController {
+    hooks;
+    run = null;
+    pending = new Map();
+    ready = false;
+    disposed = false;
+    dirty = false;
+    multilineDraft = false;
+    startupError = null;
+    startupPhase = 'Waiting for the native extension';
+    delivery = null;
+    nativeId;
+    seen = new Map();
+    commands = [];
+    constructor(hooks) {
+        this.hooks = hooks;
+        this.nativeId = hooks.nativeSessionId;
+    }
+    get nativeSessionId() {
+        return this.nativeId;
+    }
+    get activeRun() {
+        return this.run && !this.run.finished ? this.run : null;
+    }
+    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) {
+        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 });
+        this.run = run;
+        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) {
+        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined);
+        this.run = null;
+        this.seen.clear();
+        this.pending.clear();
+    }
+    /** 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.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId });
+        }
+        else if (descendant && event.type === 'approval.requested') {
+            const payload = event.payload;
+            if (!payload.automatic)
+                this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId });
+        }
+        else if (event.type === 'approval.resolved') {
+            this.pending.delete(String(event.payload.approvalId));
+        }
+        else if (event.type === 'question.answered') {
+            this.pending.delete(String(event.payload.questionId));
+        }
+    }
+    /** 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.interrupt')
+            return this.activeRun && this.hooks.interrupt ? this.hooks.interrupt(this.activeRun.runId) : {};
+        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.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.pending.set(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.pending.delete(key);
+        }
+    }
+    async accept(event, data) {
+        if (this.disposed)
+            throw new Error('This terminal controller was disposed.');
+        if (event !== 'poll')
+            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 };
+        if (event === 'ready') {
+            if (!this.ready) {
+                this.dirty = false;
+                this.multilineDraft = false;
+            }
+            this.ready = true;
+            if (typeof data.nativeSessionId === 'string' && data.nativeSessionId) {
+                this.nativeId = data.nativeSessionId;
+                this.hooks.native(data.nativeSessionId);
+            }
+            return {};
+        }
+        if (event === 'begin') {
+            const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''));
+            return { runId: run.runId };
+        }
+        if (event === 'shutdown') {
+            this.ready = false;
+            this.finish('interrupted');
+            return {};
+        }
+        if (event === 'settled') {
+            this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined);
+            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 response = run.requestAnswer({ requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
+                this.pending.set(key, { type: 'question', requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
+                this.seen.set(key, response);
+                return response.finally(() => this.pending.delete(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.pending.set(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.pending.delete(key);
+            }
+        }
+        if (event === 'usage')
+            run.emit('usage.updated', data);
+        else if (event === 'file')
+            run.emit('file.changed', data);
+        else if (event === 'message')
+            run.emit('message.completed', { messageId: data.id ?? randomUUID(), role: data.role ?? 'assistant', text: String(data.text) });
+        else if (event === 'tool') {
+            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.ready = false;
+        this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'));
+        this.delivery = null;
+        this.finish('interrupted');
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { HubOverview } from "../hub/schema.js";
+import type { MenuCall, MenuUi } from "./pluginMenu.js";
+type HubEntry = HubOverview['entries'][number];
+/** What the person is told before installing: the entry, who published it, and what installing does. */
+export declare function hubSummary(entry: HubEntry): string;
+/** Asks, then installs exactly this version. A refusal or a failure is reported and changes nothing. */
+export declare function installHubEntry(ui: MenuUi, call: MenuCall, entry: HubEntry): Promise<void>;
+/** The terminal's catalog uses the same exact-version installer as embedding applications. */
+export declare function runHubMenu(ui: MenuUi, call: MenuCall): Promise<void>;
+export {};

package/dist/sdk/terminal/hubMenu.js

@@ -0,0 +1,34 @@
+/** What the person is told before installing: the entry, who published it, and what installing does. */
+export function hubSummary(entry) {
+    return `${entry.description}\n\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\n\n${entry.delivery.kind === 'document' ? 'Saved as data for a compatible application. Nothing is created or enabled.' : 'Installed switched off. Code remains untrusted and approvals remain unchanged.'}`;
+}
+/** Asks, then installs exactly this version. A refusal or a failure is reported and changes nothing. */
+export async function installHubEntry(ui, call, entry) {
+    if (!await ui.confirm(`Install ${entry.title} ${entry.version}?`, hubSummary(entry)))
+        return;
+    try {
+        const receipt = await call('hub.install', { id: entry.id, version: entry.version });
+        ui.notify(receipt.document ? 'Saved in this library for a compatible application.' : 'Installed, switched off. Use /plugins to review and attach it. Changes apply after restarting the session.', 'info');
+    }
+    catch (error) {
+        ui.notify(error instanceof Error ? error.message : String(error), 'error');
+    }
+}
+/** The terminal's catalog uses the same exact-version installer as embedding applications. */
+export async function runHubMenu(ui, call) {
+    for (;;) {
+        const catalog = await call('hub.list');
+        const labels = catalog.entries.map((entry) => `${entry.title} · ${entry.category} · ${entry.id}@${entry.version}`);
+        const picked = await ui.select('Hub', [...labels, 'Refresh catalog', 'Done']);
+        if (picked === 'Refresh catalog') {
+            const refreshed = await call('hub.list', { refresh: true });
+            if (refreshed.error)
+                ui.notify(`${refreshed.error} Using ${refreshed.origin} content.`, 'warning');
+            continue;
+        }
+        const entry = catalog.entries[labels.indexOf(picked ?? '')];
+        if (!entry)
+            return;
+        await installHubEntry(ui, call, entry);
+    }
+}

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

@@ -0,0 +1,5 @@
+/** Files Pi's Git Bash shell and native Windows shells use to call Harness subcommands. */
+export declare function terminalCommandFiles(platform: NodeJS.Platform, node: string, cli: string, name: string, mode: string): Array<{
+    name: string;
+    content: string;
+}>;

package/dist/sdk/terminal/launch.js

@@ -0,0 +1,27 @@
+function bashPath(path) {
+    const drive = /^([a-z]):[\\/](.*)$/i.exec(path);
+    if (drive)
+        return `/${drive[1].toLowerCase()}/${drive[2].replaceAll('\\', '/')}`;
+    if (path.startsWith('\\\\'))
+        return `//${path.slice(2).replaceAll('\\', '/')}`;
+    return path;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Files Pi's Git Bash shell and native Windows shells use to call Harness subcommands. */
+export function terminalCommandFiles(platform, node, cli, name, mode) {
+    const shellNode = platform === 'win32' ? bashPath(node) : node;
+    const shellCli = platform === 'win32' ? bashPath(cli) : cli;
+    const files = [{
+            name,
+            content: `#!/bin/sh\nexec ${shellQuote(shellNode)} ${shellQuote(shellCli)} ${mode} "$@"\n`
+        }];
+    if (platform === 'win32') {
+        files.push({
+            name: `${name}.cmd`,
+            content: `@echo off\r\n"%XINGULAR_HARNESS_NODE%" "%XINGULAR_HARNESS_CLI%" ${mode} %*\r\nexit /b %ERRORLEVEL%\r\n`
+        });
+    }
+    return files;
+}

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

@@ -0,0 +1,14 @@
+export declare const LOG_READ_CHUNK_BYTES: number;
+export interface HarnessLogInfo {
+    size: number | null;
+}
+export interface HarnessLogChunk {
+    data: string;
+    nextOffset: number;
+}
+/** Captures the byte length of the host-owned diagnostics file; callers never supply a path. */
+export declare function harnessLogInfo(stateDir: string): HarnessLogInfo;
+/** Reads one bounded range from the file size captured by `harnessLogInfo`. */
+export declare function readHarnessLogChunk(stateDir: string, snapshotSize: number, offset: number): HarnessLogChunk;
+/** Collects a fixed-size snapshot while keeping each socket reply bounded. */
+export declare function readHarnessLogSnapshot(info: () => Promise<HarnessLogInfo>, chunk: (snapshotSize: number, offset: number) => Promise<HarnessLogChunk>): Promise<string>;

package/dist/sdk/terminal/logs.js

@@ -0,0 +1,59 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const LOG_READ_CHUNK_BYTES = 32 * 1024;
+/** Captures the byte length of the host-owned diagnostics file; callers never supply a path. */
+export function harnessLogInfo(stateDir) {
+    try {
+        const stat = statSync(join(stateDir, 'harness.log'));
+        if (!stat.isFile())
+            throw new Error('The Harness diagnostics path is not a regular file.');
+        return { size: stat.size };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { size: null };
+        throw error;
+    }
+}
+/** Reads one bounded range from the file size captured by `harnessLogInfo`. */
+export function readHarnessLogChunk(stateDir, snapshotSize, offset) {
+    if (!Number.isSafeInteger(snapshotSize) || snapshotSize < 0 || !Number.isSafeInteger(offset) || offset < 0 || offset >= snapshotSize) {
+        throw new Error('The Harness diagnostics snapshot range is invalid.');
+    }
+    const path = join(stateDir, 'harness.log');
+    const current = statSync(path);
+    if (!current.isFile() || current.size < snapshotSize)
+        throw new Error('The Harness diagnostics file changed while it was being read.');
+    const length = Math.min(LOG_READ_CHUNK_BYTES, snapshotSize - offset);
+    const buffer = Buffer.allocUnsafe(length);
+    const descriptor = openSync(path, 'r');
+    try {
+        const bytesRead = readSync(descriptor, buffer, 0, length, offset);
+        if (bytesRead !== length)
+            throw new Error('The Harness diagnostics file changed while it was being read.');
+        return { data: buffer.toString('base64'), nextOffset: offset + bytesRead };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/** Collects a fixed-size snapshot while keeping each socket reply bounded. */
+export async function readHarnessLogSnapshot(info, chunk) {
+    const { size } = await info();
+    if (size === null || size === 0)
+        return '';
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error('The Harness returned an invalid diagnostics file size.');
+    const buffers = [];
+    let offset = 0;
+    while (offset < size) {
+        const page = await chunk(size, offset);
+        const buffer = Buffer.from(page.data, 'base64');
+        if (!buffer.length || page.nextOffset !== offset + buffer.length || page.nextOffset > size) {
+            throw new Error('The Harness returned an invalid diagnostics file page.');
+        }
+        buffers.push(buffer);
+        offset = page.nextOffset;
+    }
+    return Buffer.concat(buffers).toString('utf8');
+}

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

@@ -0,0 +1,6 @@
+import type { AgentSession, ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export interface TerminalPlanRunState {
+    active: boolean;
+    allowedTools: ReadonlySet<string>;
+}
+export default function (pi: ExtensionAPI, planRun?: TerminalPlanRunState, getSession?: () => AgentSession): Promise<void>;