@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/terminal/controller.js

@@ -6,7 +6,21 @@ 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";
+import { MAIN_PROFILE, SubagentMonitor } from "./subagentMonitor.js";
+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 {
@@ -14,6 +28,7 @@ export class TerminalController {
     run = null;
     pending = new Map();
     subagents = new SubagentMonitor();
+    subagentParentRunId = null;
     ready = false;
     disposed = false;
     dirty = false;
@@ -40,7 +55,7 @@ export class TerminalController {
     requestId(nativeId) {
         return createHash('sha256').update(`${this.hooks.sessionId}:${this.run?.runId}:${nativeId}`).digest('hex');
     }
-    begin(nativeTurnId, text) {
+    begin(nativeTurnId, text, launch = {}) {
         if (this.startupError)
             throw new Error(this.startupError);
         this.dirty = false;
@@ -50,8 +65,9 @@ export class TerminalController {
         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 });
+        const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text, ...launch });
         this.run = run;
+        this.subagentParentRunId = run.runId;
         this.subagents.begin(run.runId);
         run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }));
         if (text)
@@ -60,10 +76,8 @@ export class TerminalController {
         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);
+    finish(outcome, message, reason) {
+        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined, reason);
         this.run = null;
         this.seen.clear();
         this.pending.clear();
@@ -133,10 +147,11 @@ export class TerminalController {
             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') {
+        else if (event.type === 'approval.requested') {
             const payload = event.payload;
-            if (!payload.automatic)
+            if (!payload.automatic && (descendant || payload.target === 'workspace-write')) {
                 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));
@@ -146,25 +161,30 @@ export class TerminalController {
         }
     }
     /** A child event that belongs to the active terminal parent run. */
-    observeSubagent(parentRunId, run, event, profile = null) {
+    observeSubagent(parentRunId, run, event, profile = null, runtime = {}) {
         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);
+        this.subagents.observe(parentRunId, monitorRun(run, 'subagent', profile, runtime), event);
+    }
+    /** 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);
     }
-    /** Read-only child activity for the active run. */
+    /** 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() {
-        const run = this.activeRun;
-        return run ? this.subagents.snapshot(run.runId) : [];
+        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) {
@@ -185,6 +205,20 @@ export class TerminalController {
                 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) {
@@ -294,14 +328,24 @@ export class TerminalController {
             }
             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 ?? ''));
-            return { runId: run.runId };
+            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
+            });
+            return { runId: run.runId, workspaceRoot: this.hooks.workspaceRoot(run) };
         }
         if (event === 'shutdown') {
             this.ready = false;
@@ -309,7 +353,11 @@ export class TerminalController {
             return {};
         }
         if (event === 'settled') {
-            this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined);
+            // 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).
+            const reason = typeof data.reason === 'string' ? data.reason : undefined;
+            const outcome = data.error ? 'failed' : data.aborted || reason ? 'interrupted' : 'completed';
+            this.finish(outcome, data.error ? String(data.error) : undefined, reason);
             return {};
         }
         const run = this.run;
@@ -354,8 +402,10 @@ export class TerminalController {
         }
         if (event === 'usage')
             run.emit('usage.updated', data);
-        else if (event === 'checklist')
-            run.emit('checklist.updated', { items: data.items });
+        else if (event === 'todo' || event === 'checklist')
+            run.emit('todo.updated', { items: data.items });
+        else if (event === 'checkpoint')
+            run.emit('checkpoint', data);
         else if (event === 'file')
             run.emit('file.changed', data);
         else if (event === 'message')
@@ -379,5 +429,7 @@ export class TerminalController {
         this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'));
         this.delivery = null;
         this.finish('interrupted');
+        this.subagents.clear();
+        this.subagentParentRunId = null;
     }
 }

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;

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

@@ -0,0 +1,192 @@
+// Pi components and trusted extensions render ANSI text, not OpenTUI nodes. This module turns
+// that text into the small style model OpenTUI can draw, and never executes anything in it.
+const BASE_COLORS = [
+    '#000000', '#cd0000', '#00cd00', '#cdcd00', '#0000ee', '#cd00cd', '#00cdcd', '#e5e5e5',
+    '#7f7f7f', '#ff0000', '#00ff00', '#ffff00', '#5c5cff', '#ff00ff', '#00ffff', '#ffffff'
+];
+const CUBE = [0, 95, 135, 175, 215, 255];
+export function ansi256Color(index) {
+    if (!Number.isFinite(index))
+        return BASE_COLORS[7];
+    const value = Math.max(0, Math.min(255, Math.trunc(index)));
+    if (value < 16)
+        return BASE_COLORS[value];
+    if (value < 232) {
+        const n = value - 16;
+        const r = CUBE[Math.floor(n / 36) % 6];
+        const g = CUBE[Math.floor(n / 6) % 6];
+        const b = CUBE[n % 6];
+        return hex(r, g, b);
+    }
+    const grey = 8 + (value - 232) * 10;
+    return hex(grey, grey, grey);
+}
+function hex(r, g, b) {
+    const part = (value) => Math.max(0, Math.min(255, Math.trunc(value))).toString(16).padStart(2, '0');
+    return `#${part(r)}${part(g)}${part(b)}`;
+}
+function defaultStyle() {
+    return {};
+}
+function applySgr(style, params) {
+    const next = { ...style };
+    const parts = params === '' ? ['0'] : params.split(';');
+    for (let index = 0; index < parts.length; index += 1) {
+        const raw = parts[index];
+        const value = raw === '' ? 0 : Number.parseInt(raw, 10);
+        if (!Number.isFinite(value))
+            continue;
+        if (value === 0) {
+            for (const key of Object.keys(next))
+                delete next[key];
+        }
+        else if (value === 1)
+            next.bold = true;
+        else if (value === 2)
+            next.dim = true;
+        else if (value === 3)
+            next.italic = true;
+        else if (value === 4)
+            next.underline = true;
+        else if (value === 7)
+            next.inverse = true;
+        else if (value === 22) {
+            next.bold = false;
+            next.dim = false;
+        }
+        else if (value === 23)
+            next.italic = false;
+        else if (value === 24)
+            next.underline = false;
+        else if (value === 27)
+            next.inverse = false;
+        else if (value >= 30 && value <= 37)
+            next.fg = BASE_COLORS[value - 30];
+        else if (value >= 90 && value <= 97)
+            next.fg = BASE_COLORS[value - 90 + 8];
+        else if (value >= 40 && value <= 47)
+            next.bg = BASE_COLORS[value - 40];
+        else if (value >= 100 && value <= 107)
+            next.bg = BASE_COLORS[value - 100 + 8];
+        else if (value === 39)
+            delete next.fg;
+        else if (value === 49)
+            delete next.bg;
+        else if (value === 38 || value === 48) {
+            const target = value === 38 ? 'fg' : 'bg';
+            const mode = parts[index + 1];
+            if (mode === '5') {
+                const color = Number.parseInt(parts[index + 2] ?? '', 10);
+                if (Number.isFinite(color))
+                    next[target] = ansi256Color(color);
+                index += 2;
+            }
+            else if (mode === '2') {
+                const r = Number.parseInt(parts[index + 2] ?? '', 10);
+                const g = Number.parseInt(parts[index + 3] ?? '', 10);
+                const b = Number.parseInt(parts[index + 4] ?? '', 10);
+                if ([r, g, b].every(Number.isFinite))
+                    next[target] = hex(r, g, b);
+                index += 4;
+            }
+        }
+    }
+    return next;
+}
+/** Consumes a CSI sequence at `start`; returns the index after it. */
+function csiEnd(text, start) {
+    let index = start + 2;
+    while (index < text.length) {
+        const code = text.charCodeAt(index);
+        if (code >= 0x40 && code <= 0x7e)
+            return index + 1;
+        index += 1;
+    }
+    return text.length;
+}
+/** Consumes an OSC or APC sequence at `start`; returns the index after its terminator. */
+function stringSequenceEnd(text, start) {
+    let index = start + 2;
+    while (index < text.length) {
+        const code = text.charCodeAt(index);
+        if (code === 0x07)
+            return index + 1;
+        if (code === 0x1b && text.charCodeAt(index + 1) === 0x5c)
+            return index + 2;
+        index += 1;
+    }
+    return text.length;
+}
+function stripControl(text) {
+    return text.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+/**
+ * Parses SGR styled lines. Non-style escape sequences, including Pi's cursor markers, are removed;
+ * an OSC 8 hyperlink keeps its visible label.
+ */
+export function parseAnsi(text) {
+    const lines = [];
+    let spans = [];
+    let style = defaultStyle();
+    let buffer = '';
+    const flush = () => {
+        if (!buffer)
+            return;
+        spans.push({ text: stripControl(buffer), style: { ...style } });
+        buffer = '';
+    };
+    const newline = () => {
+        flush();
+        lines.push({ spans });
+        spans = [];
+    };
+    for (let index = 0; index < text.length;) {
+        const char = text[index];
+        if (char === '\n') {
+            newline();
+            index += 1;
+            continue;
+        }
+        if (char === '\r') {
+            index += 1;
+            continue;
+        }
+        if (char === '\t') {
+            buffer += '  ';
+            index += 1;
+            continue;
+        }
+        if (char !== '\x1b') {
+            buffer += char;
+            index += 1;
+            continue;
+        }
+        const next = text[index + 1];
+        if (next === '[') {
+            const end = csiEnd(text, index);
+            const body = text.slice(index + 2, end);
+            if (body.endsWith('m')) {
+                flush();
+                style = applySgr(style, body.slice(0, -1));
+            }
+            index = end;
+            continue;
+        }
+        if (next === ']' || next === '_' || next === 'P' || next === '^') {
+            index = stringSequenceEnd(text, index);
+            continue;
+        }
+        index += next === undefined ? 1 : 2;
+    }
+    flush();
+    lines.push({ spans });
+    return lines;
+}
+export function ansiPlain(text) {
+    return parseAnsi(text).map(line => line.spans.map(span => span.text).join('')).join('\n');
+}
+/** A short single-line form for labels and tool summaries. */
+export function ansiLabel(text, limit = 120) {
+    const plain = ansiPlain(text).replace(/\s+/g, ' ').trim();
+    return plain.length > limit ? `${plain.slice(0, Math.max(0, limit - 1))}…` : plain;
+}

package/dist/sdk/terminal/opentui/model.d.ts

@@ -0,0 +1,163 @@
+import { type AgentSession } from '@earendil-works/pi-coding-agent';
+import type { TerminalCommandHelpGroup } from "../commandHelp.js";
+export type ToolStatus = 'running' | 'ok' | 'error' | 'pending';
+export interface UserItem {
+    kind: 'user';
+    id: string;
+    text: string;
+    images: number;
+    timestamp: number;
+}
+export interface AssistantItem {
+    kind: 'assistant';
+    id: string;
+    text: string;
+    model?: string;
+    streaming: boolean;
+    timestamp: number;
+}
+export interface ThinkingItem {
+    kind: 'thinking';
+    id: string;
+    text: string;
+    streaming: boolean;
+}
+export interface ToolItem {
+    kind: 'tool';
+    id: string;
+    toolCallId: string;
+    name: string;
+    summary: string;
+    status: ToolStatus;
+    output: string;
+    durationMs?: number;
+}
+export interface ImageResultItem {
+    kind: 'image-result';
+    id: string;
+    text: string;
+    imageCount: number;
+    images: {
+        data: string;
+        mimeType: string;
+    }[];
+    showImages: boolean;
+}
+export interface NoticeItem {
+    kind: 'notice';
+    id: string;
+    text: string;
+    level: string;
+}
+export interface CommandHelpItem {
+    kind: 'command-help';
+    id: string;
+    groups: readonly TerminalCommandHelpGroup[];
+}
+export interface BashItem {
+    kind: 'bash';
+    id: string;
+    command: string;
+    timestamp: number;
+    output: string;
+    running: boolean;
+    exitCode?: number;
+    cancelled: boolean;
+}
+export interface CustomItem {
+    kind: 'custom';
+    id: string;
+    label: string;
+    text: string;
+}
+export interface SummaryItem {
+    kind: 'summary';
+    id: string;
+    label: string;
+    text: string;
+}
+export interface CompactionItem {
+    kind: 'compaction';
+    id: string;
+    summary: string;
+    tokensBefore?: number;
+}
+/** A `todo_write` call, shown as the list it wrote rather than as a tool row. */
+export interface TodoTranscriptItem {
+    kind: 'todo';
+    id: string;
+    /** Set for a tool call; absent for a `/todo` snapshot. */
+    toolCallId?: string;
+    /** Set for a tool call; a command snapshot has no status mark. */
+    status?: ToolStatus;
+    origin: 'tool' | 'command';
+    items: readonly TodoEntry[];
+}
+export interface TodoEntry {
+    text: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+/** A proposed plan block from a plan-mode reply, shown as a card. */
+export interface PlanItem {
+    kind: 'plan';
+    id: string;
+    title: string;
+    body: string;
+    streaming: boolean;
+}
+export type TranscriptItem = UserItem | AssistantItem | ThinkingItem | ToolItem | ImageResultItem | NoticeItem | CommandHelpItem | BashItem | CustomItem | SummaryItem | CompactionItem | PlanItem | TodoTranscriptItem;
+export interface TranscriptView {
+    items: readonly TranscriptItem[];
+    hasUserMessages: boolean;
+    hasMultilineNotice: boolean;
+}
+/** The items of a `todo_write` (or pre-rename `checklist_write`) call, or null when they are not a todo list. */
+export declare function todoEntries(args: unknown): TodoEntry[] | null;
+export declare class TranscriptModel {
+    private session?;
+    /** Items derived from a finished message, reused while its position and tool results stay the same. */
+    private messageItems;
+    private hideThinking;
+    private showImages;
+    private expanded;
+    private notices;
+    private nextNotice;
+    private liveBash?;
+    private cachedView?;
+    private readonly cachedItems;
+    /** What a compaction took out of Pi's message list, rebuilt from the session history on bind. */
+    private history?;
+    bind(session: AgentSession): void;
+    clear(): void;
+    invalidate(): void;
+    beginBash(command: string): void;
+    appendBashOutput(id: string, delta: string): boolean;
+    finishBash(): void;
+    clearNotices(): void;
+    setThinkingHidden(hidden: boolean): void;
+    setImagesShown(shown: boolean): void;
+    setExpanded(expanded: boolean): void;
+    get isExpanded(): boolean;
+    notice(text: string, level?: string): void;
+    commandHelp(groups: readonly TerminalCommandHelpGroup[]): void;
+    /** A `/todo` snapshot: the list at the moment the command ran, with no tool row. */
+    todo(items: readonly TodoEntry[]): void;
+    private addNotice;
+    /**
+     * Notices in the order they appear, each with the message index it goes before. Compaction
+     * replaces the message list with a shorter one, so a notice follows the message it was posted
+     * after; a notice whose message was summarized goes right after the compaction card.
+     */
+    private placedNotices;
+    view(): TranscriptView;
+    /**
+     * Pi's list after a compaction starts with the summary and the kept messages. The transcript
+     * shows the whole conversation instead: everything before the compaction from the session
+     * history, the summary, then what came after.
+     */
+    private displayMessages;
+    /** What a message's items depend on besides the message itself. */
+    private messageKey;
+    private messageItemsFor;
+    private stabilize;
+}