@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/liveTerminal.js

@@ -0,0 +1,436 @@
+// The terminal as a client of the harness (ADR-0083, phase 2). The terminal frontend no longer runs
+// Pi: each turn it sends is a `sessions.run { live: true }` of this terminal's conversation, and the
+// frontend draws from the live session's native events and its own read of the history file.
+// These are protected session-socket routes (INV-TUI-4): the account, folder, variant and caller come
+// from preparation, never from the request.
+import { randomUUID } from 'node:crypto';
+import { HarnessError, invalid } from "../core/errors.js";
+import { loadRun, pendingDecisions, readEvents, recordedSubagents } from "../sessions/runStore.js";
+import { rename as renameHistory } from "../sessions/control.js";
+/** Pi's own tools a terminal session has active, as the in-process terminal has them. */
+export const TERMINAL_NATIVE_TOOLS = ['read', 'bash', 'edit', 'write'];
+/** Native events kept for a client that reads late; older ones are dropped and the client resyncs. */
+const JOURNAL = 4000;
+const WAIT_MS = 20_000;
+/** Pi's names for the commands of loaded extensions: a name two extensions share gets `:2`, `:3`. */
+export function registeredCommands(extensions) {
+    const all = extensions.flatMap((extension) => [...extension.commands.values()].map((command) => ({ command, source: command.sourceInfo ?? extension.sourceInfo })));
+    const counts = new Map();
+    for (const { command } of all)
+        counts.set(command.name, (counts.get(command.name) ?? 0) + 1);
+    const seen = new Map();
+    const taken = new Set();
+    return all.map(({ command, source }) => {
+        const occurrence = (seen.get(command.name) ?? 0) + 1;
+        seen.set(command.name, occurrence);
+        let invocationName = (counts.get(command.name) ?? 0) > 1 ? `${command.name}:${occurrence}` : command.name;
+        let suffix = occurrence;
+        while (taken.has(invocationName))
+            invocationName = `${command.name}:${++suffix}`;
+        taken.add(invocationName);
+        return { name: command.name, invocationName, description: command.description ?? '', sourceInfo: source ?? null };
+    });
+}
+export class LiveTerminal {
+    context;
+    sessions;
+    runs;
+    journal = [];
+    seq = 0;
+    waiters = new Set();
+    pendingRevision = 0;
+    pendingWaiters = new Set();
+    activeRunId = null;
+    lastRunId = null;
+    stops = [];
+    disposed = false;
+    settledListeners = new Set();
+    constructor(context, sessions, runs) {
+        this.context = context;
+        this.sessions = sessions;
+        this.runs = runs;
+        this.stops.push(sessions.live.watch(context.sessionId, (event) => this.append(event)));
+        this.stops.push(runs.listen((event) => {
+            // A follow-up the harness started after the last reply is this terminal's reply now.
+            const liveActive = sessions.live.status(context.sessionId)?.activeRunId ?? null;
+            if (liveActive && liveActive === event.runId && this.activeRunId !== liveActive)
+                this.started(liveActive);
+            if (event.runId !== this.activeRunId && !this.isOwnChild(event.runId))
+                return;
+            if (['approval.requested', 'approval.resolved', 'question.requested', 'question.answered'].includes(event.type))
+                this.bumpPending();
+            // A plugin's dialog is shown by the window itself; its question stays answerable from anywhere.
+            if (event.type === 'question.requested' && event.payload.dialog) {
+                this.append({ type: 'harness_dialog', runId: event.runId, request: { ...event.payload, requestId: event.payload.questionId } });
+            }
+            if (event.type === 'question.answered')
+                this.append({ type: 'harness_dialog_done', requestId: event.payload.questionId });
+            // What a plugin shows (a notice, a status line, a widget) reaches the window with the reply's own events.
+            if (event.type === 'extension.notice')
+                this.append({ type: 'harness_notice', notice: event.payload });
+            // A reply that fails says why in the window, as an in-process prompt's error does.
+            if (event.type === 'failed' && event.runId === this.activeRunId) {
+                const message = event.payload.message;
+                if (typeof message === 'string' && message)
+                    this.append({ type: 'harness_notice', notice: { kind: 'error', text: message } });
+            }
+            const ended = event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && event.payload.status === 'interrupted');
+            if (ended && event.runId === this.activeRunId) {
+                // The window learns that the reply is over even when Pi's loop never started (a command that failed).
+                // A goal run says where its goal stands, so the window's /goal shows the harness's own state.
+                let goalMode = null;
+                try {
+                    goalMode = loadRun(this.context.root, event.runId).goalMode ?? null;
+                }
+                catch {
+                    // No record to read.
+                }
+                const live = this.sessions.live.status(this.context.sessionId);
+                this.append({ type: 'harness_settled', runId: event.runId, status: event.type === 'completed' ? 'completed' : event.type === 'failed' ? 'failed' : 'interrupted', goalMode, sessionFile: live?.sessionFile ?? null, nativeSessionId: live?.nativeSessionId ?? null });
+                this.activeRunId = null;
+                this.bumpPending();
+                // A follow-up the harness queued starts in the same turn of the event loop; settle after it.
+                setImmediate(() => {
+                    if (this.activeRunId || this.disposed)
+                        return;
+                    for (const settled of this.settledListeners)
+                        settled();
+                });
+            }
+        }));
+    }
+    /** The subagents of the active reply: their approvals and questions are this terminal's too. */
+    children() {
+        if (!this.activeRunId)
+            return [];
+        try {
+            return recordedSubagents(this.context.root, this.activeRunId);
+        }
+        catch {
+            return [];
+        }
+    }
+    isOwnChild(runId) {
+        return this.children().includes(runId);
+    }
+    append(event) {
+        const type = event?.type;
+        const last = this.journal.at(-1);
+        // A streaming update carries the whole message so far, so a newer one replaces one not yet read.
+        if (type === 'message_update' && last?.event?.type === 'message_update')
+            this.journal.pop();
+        this.journal.push({ seq: ++this.seq, event });
+        if (this.journal.length > JOURNAL)
+            this.journal.splice(0, this.journal.length - JOURNAL);
+        for (const wake of this.waiters)
+            wake();
+    }
+    bumpPending() {
+        this.pendingRevision += 1;
+        for (const wake of this.pendingWaiters)
+            wake();
+    }
+    async wait(set, ms) {
+        await new Promise((resolve) => {
+            const wake = () => { clearTimeout(timer); set.delete(wake); resolve(); };
+            const timer = setTimeout(wake, ms);
+            timer.unref?.();
+            set.add(wake);
+        });
+    }
+    known = { nativeSessionId: null, sessionFile: null };
+    /** Pi's id of this terminal's conversation, as its harness runs record it. */
+    get nativeSessionId() {
+        const live = this.sessions.live.status(this.context.sessionId);
+        if (live)
+            this.known = { nativeSessionId: live.nativeSessionId, sessionFile: live.sessionFile ?? this.known.sessionFile };
+        return this.known.nativeSessionId;
+    }
+    /** The history file of this terminal's conversation, once it has one. */
+    get sessionFile() {
+        void this.nativeSessionId;
+        return this.known.sessionFile;
+    }
+    /** The reply running now, if one is. */
+    get activeRun() {
+        return this.activeRunId;
+    }
+    /** Called each time the terminal's replies have all settled and nothing else is queued. */
+    onSettled(listener) {
+        this.settledListeners.add(listener);
+        return () => { this.settledListeners.delete(listener); };
+    }
+    /** The run this terminal is showing, or the last one it finished. */
+    get lastRun() {
+        return this.activeRunId ?? this.lastRunId;
+    }
+    async call(call, params) {
+        if (this.disposed)
+            throw new HarnessError('run_not_active', 'This terminal session has closed.');
+        switch (call) {
+            case 'terminal.live.state': return this.state();
+            case 'terminal.live.events': return this.events(params);
+            case 'terminal.live.run': return this.run(params);
+            case 'terminal.live.steer': {
+                const text = this.text(params);
+                if (!this.activeRunId)
+                    throw new HarnessError('run_not_active', 'No reply is running to steer.');
+                await this.runs.steer(this.activeRunId, text);
+                return { runId: this.activeRunId };
+            }
+            case 'terminal.live.followUp': {
+                const result = await this.sessions.followUp(this.context.sessionId, this.text(params));
+                if ('runId' in result)
+                    this.started(result.runId);
+                return result;
+            }
+            case 'terminal.live.followUp.clear': return { removed: this.sessions.live.clearQueue(this.context.sessionId) };
+            case 'terminal.live.interrupt': {
+                const runId = this.activeRunId;
+                // The run is stopped and recorded at once; Pi's own abort finishes after the reply returns, so
+                // the window never waits on a provider stream that is slow to close.
+                if (runId)
+                    void this.runs.interrupt(runId).catch(() => undefined);
+                return { runId };
+            }
+            case 'terminal.live.close': {
+                void this.nativeSessionId;
+                // A new or switched conversation: what this terminal knows comes from its next run.
+                if (params.forget === true)
+                    this.known = { nativeSessionId: null, sessionFile: null };
+                if (params.reload === true)
+                    this.listed = null;
+                return this.sessions.closeLive(this.context.sessionId);
+            }
+            case 'terminal.live.rename': {
+                const name = this.text(params).trim().slice(0, 200);
+                // The live session writes its own history; a saved one is renamed in place.
+                const session = this.sessions.live.session(this.context.sessionId);
+                if (session?.setSessionName && !this.activeRunId) {
+                    session.setSessionName(name);
+                    return { name };
+                }
+                if (this.activeRunId)
+                    throw new HarnessError('session_busy', 'Rename the conversation after the reply settles.');
+                const file = typeof params.sessionFile === 'string' ? params.sessionFile : undefined;
+                return renameHistory({ sessionDir: this.context.sessionDir, ...(file ? { sessionFile: file } : {}), cwd: this.context.cwd, name });
+            }
+            case 'terminal.live.pending': return { revision: this.pendingRevision, requests: this.pending(params.ownDialogs === true) };
+            case 'terminal.live.pending.wait': {
+                if (params.revision === this.pendingRevision)
+                    await this.wait(this.pendingWaiters, WAIT_MS);
+                return { revision: this.pendingRevision, requests: this.pending(params.ownDialogs === true) };
+            }
+            case 'terminal.live.approve': return this.approve(params);
+            case 'terminal.live.answer': return this.answer(params);
+            case 'terminal.live.answers': return this.answers(params);
+            default: throw invalid(`Unknown live terminal operation ${call}.`);
+        }
+    }
+    text(params) {
+        if (typeof params.text !== 'string' || !params.text.trim())
+            throw invalid('Text is required.');
+        return params.text;
+    }
+    listed = null;
+    async state() {
+        const live = this.sessions.live.status(this.context.sessionId);
+        const session = this.sessions.live.session(this.context.sessionId);
+        const view = session ? sessionView(session) : null;
+        // Before the first turn there is no live session to ask; the trusted extensions are listed instead.
+        const commands = view ? view.commands : await (this.listed ??= (this.context.commands?.() ?? Promise.resolve([])).catch((error) => {
+            this.listed = null;
+            throw error;
+        }));
+        return {
+            seq: this.seq,
+            activeRunId: this.activeRunId,
+            lastRunId: this.lastRunId,
+            live,
+            session: view,
+            commands
+        };
+    }
+    async events(params) {
+        const after = typeof params.after === 'number' && Number.isFinite(params.after) ? params.after : 0;
+        const read = () => {
+            const first = this.journal[0]?.seq ?? this.seq + 1;
+            // Events the client missed were dropped: it must read the session again.
+            const reset = after > 0 && after < first - 1;
+            return { seq: this.seq, events: this.journal.filter((entry) => entry.seq > after), reset };
+        };
+        let result = read();
+        if (!result.events.length && params.wait !== false) {
+            await this.wait(this.waiters, typeof params.waitMs === 'number' ? Math.min(Math.max(params.waitMs, 0), WAIT_MS) : WAIT_MS);
+            result = read();
+        }
+        return result;
+    }
+    started(runId) {
+        this.activeRunId = runId;
+        this.lastRunId = runId;
+        this.bumpPending();
+    }
+    async run(params) {
+        const { context } = this;
+        if (this.activeRunId)
+            throw new HarnessError('session_busy', 'A reply is running. Steer it, or queue the message as a follow-up.');
+        const text = typeof params.text === 'string' ? params.text : '';
+        const command = params.command;
+        if (!text.trim() && !command)
+            throw invalid('Text is required.');
+        const images = Array.isArray(params.images) ? params.images.filter((image) => !!image && typeof image.mediaType === 'string' && typeof image.data === 'string') : undefined;
+        const resume = params.resume && typeof params.resume === 'object'
+            ? { sessionFile: typeof params.resume.sessionFile === 'string' ? params.resume.sessionFile : null,
+                nativeSessionId: typeof params.resume.nativeSessionId === 'string' ? params.resume.nativeSessionId : null }
+            : null;
+        const runId = randomUUID();
+        const native = context.readOnly ? TERMINAL_NATIVE_TOOLS.filter((name) => !['bash', 'edit', 'write'].includes(name)) : TERMINAL_NATIVE_TOOLS;
+        const allow = [...new Set([...native, ...(await context.tools?.() ?? [])])];
+        const input = {
+            run: { id: runId, sessionId: context.sessionId, sessionType: 'terminal', mode: 'code' },
+            accountId: context.accountId,
+            model: typeof params.model === 'string' ? params.model : null,
+            effort: typeof params.effort === 'string' ? params.effort : null,
+            cwd: context.cwd,
+            sessionDir: context.sessionDir,
+            ...(resume?.sessionFile ? { resume } : {}),
+            ...(params.newHistory === true && !resume?.sessionFile ? { newHistory: true } : {}),
+            text: command ? `/${command.name}` : text,
+            ...(images?.length ? { images } : {}),
+            ...(typeof params.initialBashCommand === 'string' ? { initialBashCommand: params.initialBashCommand } : {}),
+            caller: context.caller,
+            variant: context.variant,
+            launch: context.launch,
+            tools: { allow, gated: [] },
+            connections: context.connections,
+            ...(context.subagents !== undefined ? { subagents: context.subagents } : {}),
+            // The terminal sends a plan only the tools it may use, as the in-process terminal does.
+            ...(params.plan === true ? { plan: true, planTools: 'active' } : {}),
+            ...(params.goal && typeof params.goal === 'object' ? { goal: params.goal } : {}),
+            ...(Array.isArray(params.hiddenNotes) && params.hiddenNotes.length ? { hiddenNotes: params.hiddenNotes } : {}),
+            ...(command ? { command } : { live: true })
+        };
+        this.started(runId);
+        try {
+            const result = await this.sessions.run(input);
+            if (!result.nativeSessionId)
+                this.activeRunId = null;
+            return result;
+        }
+        catch (error) {
+            this.activeRunId = null;
+            this.bumpPending();
+            throw error;
+        }
+    }
+    /** The decisions waiting; `ownDialogs` leaves out plugin dialogs the window shows itself. */
+    pending(ownDialogs = false) {
+        const runId = this.activeRunId;
+        if (!runId)
+            return [];
+        return [runId, ...this.children()].flatMap((id) => {
+            try {
+                return pendingDecisions(readEvents(this.context.root, id)).filter((decision) => !ownDialogs || !decision.payload.dialog).map((decision) => ({
+                    ...decision.payload,
+                    type: decision.kind,
+                    requestId: decision.id,
+                    runId: id
+                }));
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    decision(params, kind) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : '';
+        const request = this.pending().find((entry) => entry.requestId === requestId && entry.type === kind);
+        if (!request)
+            throw new HarnessError('invalid_request', 'This terminal decision is no longer pending.');
+        return request;
+    }
+    approve(params) {
+        const request = this.decision(params, 'approval');
+        const decision = params.decision === 'approved' ? 'approved' : params.decision === 'denied' ? 'denied' : null;
+        if (!decision)
+            throw invalid('A decision must be approved or denied.');
+        if (decision === 'approved' && params.alwaysAllow === true) {
+            if (request.rememberable !== true || typeof request.target !== 'string')
+                throw invalid('This action cannot be always allowed.');
+            this.context.allowTool(request.target);
+        }
+        this.runs.resolveApproval(String(request.runId), String(request.requestId), decision);
+        return {};
+    }
+    answer(params) {
+        const request = this.decision(params, 'question');
+        this.runs.answerQuestion(String(request.runId), String(request.requestId), params.answer);
+        return {};
+    }
+    answers(params) {
+        const batch = this.pending().find((entry) => entry.batchId === params.batchId);
+        if (!batch || typeof params.batchId !== 'string' || !Array.isArray(params.answers))
+            throw invalid('This question batch is no longer pending.');
+        this.runs.answerQuestions(String(batch.runId), params.batchId, params.answers);
+        return {};
+    }
+    /** A message from another surface of this terminal (remote control): a new reply, or a follow-up. */
+    async send(text) {
+        if (this.activeRunId)
+            return this.sessions.followUp(this.context.sessionId, text);
+        const state = this.sessions.live.status(this.context.sessionId);
+        const result = await this.run({ text, ...(state?.sessionFile ? { resume: { sessionFile: state.sessionFile, nativeSessionId: state.nativeSessionId } } : {}) });
+        return { runId: result.runId };
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.activeRunId)
+            await this.runs.interrupt(this.activeRunId).catch(() => undefined);
+        for (const stop of this.stops.splice(0))
+            stop();
+        this.sessions.closeLive(this.context.sessionId);
+        for (const wake of [...this.waiters, ...this.pendingWaiters])
+            wake();
+    }
+}
+function sessionView(session) {
+    const commands = (() => {
+        try {
+            return (session.extensionRunner?.getRegisteredCommands() ?? []).map((command) => ({
+                name: command.name,
+                invocationName: command.invocationName ?? command.name,
+                description: command.description ?? '',
+                sourceInfo: command.sourceInfo ?? null
+            }));
+        }
+        catch {
+            return [];
+        }
+    })();
+    const usage = (() => {
+        try {
+            return session.getContextUsage?.() ?? null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return {
+        sessionId: session.sessionId,
+        sessionFile: session.sessionFile ?? null,
+        sessionName: session.sessionName ?? null,
+        systemPrompt: session.systemPrompt ?? '',
+        model: session.model ? { id: session.model.id, provider: session.model.provider, name: session.model.name ?? session.model.id, reasoning: !!session.model.reasoning, contextWindow: session.model.contextWindow ?? 0, input: session.model.input ?? ['text'] } : null,
+        thinkingLevel: session.thinkingLevel ?? null,
+        isStreaming: !!session.isStreaming,
+        activeTools: session.getActiveToolNames?.() ?? [],
+        tools: (session.getAllTools?.() ?? []).map((tool) => ({ name: tool.name, description: tool.description ?? '' })),
+        steering: [...(session.getSteeringMessages?.() ?? [])],
+        followUp: [...(session.getFollowUpMessages?.() ?? [])],
+        context: usage ? { percent: usage.percent ?? null, window: usage.contextWindow ?? 0 } : null,
+        commands
+    };
+}

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/ansi.d.ts

@@ -0,0 +1,25 @@
+export interface AnsiStyle {
+    fg?: string;
+    bg?: string;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+}
+export interface AnsiSpan {
+    text: string;
+    style: AnsiStyle;
+}
+export interface AnsiLine {
+    spans: AnsiSpan[];
+}
+export declare function ansi256Color(index: number): string;
+/**
+ * Parses SGR styled lines. Non-style escape sequences, including Pi's cursor markers, are removed;
+ * an OSC 8 hyperlink keeps its visible label.
+ */
+export declare function parseAnsi(text: string): AnsiLine[];
+export declare function ansiPlain(text: string): string;
+/** A short single-line form for labels and tool summaries. */
+export declare function ansiLabel(text: string, limit?: number): string;