@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/terminal/controller.js

@@ -0,0 +1,383 @@
+// 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 { runStatusSchema } from "../sessions/contracts.js";
+import { briefTitle } from "../sessions/subagents.js";
+import { SubagentMonitor } from "./subagentMonitor.js";
+const READY_TIMEOUT_MS = 90_000;
+const ACK_TIMEOUT_MS = 25_000;
+export class TerminalController {
+    hooks;
+    run = null;
+    pending = new Map();
+    subagents = new SubagentMonitor();
+    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;
+        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) {
+        const runId = this.run?.runId;
+        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined);
+        this.subagents.clear(runId);
+        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));
+        }
+    }
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId, run, event, profile = null) {
+        if (this.disposed || this.activeRun?.runId !== parentRunId || run.relation !== 'subagent')
+            return;
+        this.subagents.observe(parentRunId, {
+            id: run.id,
+            parentRunId: run.parentRunId,
+            relation: 'subagent',
+            title: run.title ?? briefTitle(run.goal),
+            goal: run.goal,
+            status: runStatusSchema.parse(run.status),
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            profile
+        }, event);
+    }
+    /** Read-only child activity for the active run. */
+    subagentSnapshot() {
+        const run = this.activeRun;
+        return run ? this.subagents.snapshot(run.runId) : [];
+    }
+    /** 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 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.pending.set(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.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 === 'checklist')
+            run.emit('checklist.updated', { items: data.items });
+        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/opentui/subagentsWidget.d.ts

@@ -0,0 +1,28 @@
+import { type TerminalSubagentActivity } from "../subagentMonitor.js";
+export type SubagentTone = 'success' | 'warning' | 'error' | 'muted' | 'accent';
+/** One roster row: status mark, profile, session name, checklist progress, in that order. */
+export interface SubagentRowView {
+    id: string;
+    mark: string;
+    tone: SubagentTone;
+    /** The profile name, or `subagent` for a copy of the parent. */
+    profile: string;
+    /** The profile's colour name (PROP-0029); null for a copy of the parent. */
+    color: string | null;
+    title: string;
+    /** `n of m tasks`, or null when the child wrote no checklist. */
+    tasks: string | null;
+}
+export interface SubagentRosterView {
+    rows: SubagentRowView[];
+    /** `+N more · /subagents` when rows were left out. */
+    overflow: string | null;
+}
+export declare function subagentTasks(checklist: TerminalSubagentActivity['checklist']): string | null;
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export declare function subagentRoster(items: readonly TerminalSubagentActivity[], width: number, frame?: string): SubagentRosterView | null;
+/** A row as plain text, the way it reads on screen. */
+export declare function subagentRowText(row: SubagentRowView): string;

package/dist/sdk/terminal/opentui/subagentsWidget.js

@@ -0,0 +1,52 @@
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { ACTIVE_SUBAGENT_STATUSES } from "../subagentMonitor.js";
+import { getWorkingSpinnerFrames } from "../tui/workingStatus.js";
+const MAX_VISIBLE_ROWS = 3;
+const GAP = '  ';
+/** Cuts plain text to a width; the cut adds no styling codes. */
+function cut(text, width) {
+    return stripTerminalSequences(truncateToWidth(text, width, '…'));
+}
+function safe(text) {
+    return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function mark(status, frame) {
+    switch (status) {
+        case 'completed': return { mark: '✓', tone: 'success' };
+        case 'failed': return { mark: '✕', tone: 'error' };
+        case 'interrupted': return { mark: '!', tone: 'muted' };
+        case 'queued': return { mark: '○', tone: 'muted' };
+        case 'waiting_for_approval':
+        case 'waiting_for_input': return { mark: '●', tone: 'accent' };
+        case 'running': return { mark: frame, tone: 'warning' };
+    }
+}
+export function subagentTasks(checklist) {
+    return checklist && checklist.total > 0 ? `${checklist.done} of ${checklist.total} tasks` : null;
+}
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export function subagentRoster(items, width, frame = getWorkingSpinnerFrames()[0] ?? '') {
+    if (!items.length || width < 1)
+        return null;
+    const ordered = [...items].sort((left, right) => {
+        const active = Number(ACTIVE_SUBAGENT_STATUSES.has(right.status)) - Number(ACTIVE_SUBAGENT_STATUSES.has(left.status));
+        return active || left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id);
+    });
+    const rows = ordered.slice(0, MAX_VISIBLE_ROWS).map((item) => {
+        const status = mark(item.status, frame);
+        const profile = cut(safe(item.profile?.name ?? '') || 'subagent', Math.max(1, Math.min(24, width - 2)));
+        const tasks = subagentTasks(item.checklist);
+        const used = 2 + visibleWidth(profile) + GAP.length + (tasks ? GAP.length + tasks.length : 0);
+        const title = cut(safe(item.title) || 'Subagent', Math.max(1, width - used));
+        return { id: item.id, mark: status.mark, tone: status.tone, profile, color: item.profile?.color ?? null, title, tasks };
+    });
+    const overflow = ordered.length - rows.length;
+    return { rows, overflow: overflow > 0 ? cut(`+${overflow} more · /subagents`, width) : null };
+}
+/** A row as plain text, the way it reads on screen. */
+export function subagentRowText(row) {
+    return [`${row.mark} ${row.profile}`, row.title, row.tasks].filter(Boolean).join(GAP);
+}

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>;