@xingular/harness 1.2.0 → 1.3.1-unstable.0

package/dist/sdk/sessions/workSlice.js

@@ -8,14 +8,15 @@ export const WORK_SLICE_EXTENSION = 'work-slice';
 /** The foundation defaults: enough for one meaningful step of work, short enough to report. */
 export const DEFAULT_SLICE_POLICY = {
     enabled: true,
-    // Roughly 40 minutes of ordinary work (about 15 s a call), so a checkpoint is a chapter of a
-    // task, not an interruption every few edits. A task still gets eight of them before the cap.
-    maxToolCalls: 160,
-    maxMinutes: 40,
-    // A generous cost ceiling, counted on new input, cache writes and output only: heavy reading at
-    // a large context can add tens of thousands of tokens a request, so a small cap stopped useful
-    // work (see the "Confirm plan model support" thread). 320k is a safety net, not the bound.
-    maxNewTokens: 320_000,
+    // A chapter of a task, not an interruption every few edits: roughly 80 minutes of ordinary work
+    // (about 15 s a call), with 60 minutes of wall clock as the ceiling, whichever comes first. A task
+    // still gets eight slices before it returns to the person.
+    maxToolCalls: 320,
+    maxMinutes: 60,
+    // No token cap: the tool calls and the clock are the bound. Counting new input, cache writes and
+    // output made a few large reads end a reply before useful work (see the "Confirm plan model
+    // support" thread), so a cap is available to whoever asks for one and off unless they do.
+    maxNewTokens: 0,
     maxSlices: 8,
     continue: true
 };
@@ -100,7 +101,7 @@ export function sliceLimitReached(policy, state, now = Date.now()) {
 const HANDOFF_TOOLS = new Set(['checkpoint_write', 'session_name']);
 /** Tools whose repetition is how waiting works, not a loop. */
 const POLLING_TOOLS = new Set(['wait_subagents', 'subagents.list', 'subagents.status']);
-/** Commands that read as a check, for "no progress" and "still failing" rules. */
+/** Commands that read as a check for the repeated-failure rule. */
 export function looksLikeCheck(command) {
     return /\b(test|tests|typecheck|tsc|vitest|jest|cargo|check:|prove|lint|ci|build)\b/u.test(command);
 }
@@ -122,51 +123,78 @@ function canonical(value, depth = 0) {
 /**
  * A call's identity: its name and every argument, hashed so the key stays small even when an
  * argument is a whole file. A changed argument is a different call; only an identical one repeats.
- * Reading a fixed handful of fields made every `checklist_write` look identical, so a reply that
+ * Reading a fixed handful of fields made every `todo_write` look identical, so a reply that
  * reported its progress was told it was repeating work.
  */
 const signature = (name, input) => `${name}\u0000${createHash('sha256').update(canonical(input ?? null)).digest('hex')}`;
 const clip = (value, limit) => (value.length <= limit ? value : `${value.slice(0, limit - 1)}…`);
-function handoffRequest(limit, state) {
-    return clip(`This reply reached its work-slice limit (${limit}; step ${state.steps}). Call checkpoint_write now with what is done, the single next step, anything blocking, the files you touched and the checks that matter. Then tell the user in a few lines where you stopped. Do not call other tools.`, 600);
+function handoffRequest(limit, state, checkpointAvailable = true) {
+    const handoff = checkpointAvailable
+        ? 'Call checkpoint_write now with what is done, the single next step, anything blocking, the files you touched and the checks that matter. Then tell the user in a few lines where you stopped.'
+        : 'Stop using tools and return a concise partial research report with findings, blockers and the next useful research step. The Harness records an evidence-derived checkpoint.';
+    return clip(`This reply reached its work-slice limit (${limit}; step ${state.steps}). ${handoff} Do not call other tools.`, 600);
 }
-function stalledNote(reason) {
-    return clip(`You are repeating work: ${reason}. Do not repeat it. Choose a different approach, read what the earlier attempt returned, or call checkpoint_write with the blocker so the next slice can decide.`, 600);
+function stalledNote(reason, checkpointAvailable = true) {
+    const handoff = checkpointAvailable
+        ? 'Choose a different approach, read what the earlier attempt returned, or call checkpoint_write with the blocker so the next slice can decide.'
+        : 'Do not use more tools. Return concise findings and blockers in your final response; the Harness records an evidence-derived checkpoint.';
+    return clip(`You are repeating work: ${reason}. Do not repeat it. ${handoff}`, 600);
 }
 /**
- * Bounds one reply and names repeated work. The first refusal asks for a checkpoint; a tool call
- * after that refusal ends the reply. A repeated call or failing command is named once, then ends it.
+ * Bounds one reply and names repeated work. Refusals request a checkpoint when available; without
+ * one, they ask for a partial report and prohibit further tools. A repeated call or failing command
+ * is named once, then ends the reply.
  */
 export function workSliceGuard(options) {
     const { policy, state } = options;
     const calls = new Map();
+    const checkCalls = new Set();
     const edits = new Map();
     const failures = new Map();
-    let stepsSinceProgress = 0;
     let nudged = false;
+    const checkpointAvailable = () => typeof options.checkpointAvailable === 'function'
+        ? options.checkpointAvailable()
+        : options.checkpointAvailable !== false;
     /** Repetition is judged inside one reply; the next reply starts from a clean count. */
     const resetRepetition = () => {
         calls.clear();
+        checkCalls.clear();
         edits.clear();
         failures.clear();
-        stepsSinceProgress = 0;
         nudged = false;
     };
     const end = (kind, limit) => {
         state.endedBy = kind;
         state.endedByLimit = limit;
         options.onEnd?.(kind, limit);
+        const canCheckpoint = checkpointAvailable();
         const reason = kind === 'stuck'
-            ? stalledNote(limit)
+            ? stalledNote(limit, canCheckpoint)
             : kind === 'compaction-thrash'
-                ? handoffRequest('three context compactions in one reply', state)
-                : handoffRequest(limit, state);
+                ? handoffRequest('three context compactions in one reply', state, canCheckpoint)
+                : handoffRequest(limit, state, canCheckpoint);
         return { block: true, terminate: true, reason };
     };
+    const nudge = (reason) => {
+        if (nudged)
+            return end('stuck', reason);
+        nudged = true;
+        const canCheckpoint = checkpointAvailable();
+        if (!canCheckpoint) {
+            state.endedBy = 'stuck';
+            state.endedByLimit = reason;
+        }
+        return { block: true, reason: stalledNote(reason, canCheckpoint) };
+    };
     const repeated = (name, input) => {
         if (POLLING_TOOLS.has(name))
             return null;
         const key = signature(name, input);
+        if (name === 'bash') {
+            const command = input && typeof input === 'object' ? String(input.command ?? '') : '';
+            if (command && looksLikeCheck(command))
+                checkCalls.add(key);
+        }
         const count = (calls.get(key) ?? 0) + 1;
         calls.set(key, count);
         if (count < 3)
@@ -197,9 +225,19 @@ export function workSliceGuard(options) {
         pi.on('tool_result', (event) => {
             if (event.toolName === 'checkpoint_write' && !event.isError) {
                 state.checkpointWritten = true;
-                stepsSinceProgress = 0;
                 nudged = false;
             }
+            if ((event.toolName === 'edit' || event.toolName === 'write') && event.isError === false) {
+                const path = event.input && typeof event.input === 'object' ? String(event.input.path ?? '') : '';
+                if (path) {
+                    edits.set(path, (edits.get(path) ?? 0) + 1);
+                    failures.clear();
+                    for (const key of checkCalls)
+                        calls.delete(key);
+                    checkCalls.clear();
+                    nudged = false;
+                }
+            }
             if (event.toolName !== 'bash')
                 return;
             const command = event.input && typeof event.input === 'object' ? String(event.input.command ?? '') : '';
@@ -213,17 +251,21 @@ export function workSliceGuard(options) {
             failures.delete(command);
             edits.clear();
             calls.clear();
-            stepsSinceProgress = 0;
+            checkCalls.clear();
             nudged = false;
         });
         pi.on('tool_call', (event) => {
             const name = event.toolName;
             state.steps += 1;
             state.lastTool = name;
-            const handoff = HANDOFF_TOOLS.has(name);
-            // A handoff is always callable; after the slice ended it is the only thing that is.
+            const canCheckpoint = checkpointAvailable();
+            const handoff = canCheckpoint && HANDOFF_TOOLS.has(name);
+            // A handoff is callable only when checkpoint_write is active; after the slice ended it is the only one.
             if (state.endedBy) {
-                return handoff ? undefined : { block: true, terminate: true, reason: 'This reply is over. Its checkpoint is recorded; nothing else runs.' };
+                const reason = state.checkpointWritten
+                    ? 'This reply is over. Its checkpoint is recorded; nothing else runs.'
+                    : 'This reply is over. The Harness will record an evidence-derived checkpoint; nothing else runs.';
+                return handoff ? undefined : { block: true, terminate: true, reason };
             }
             if (state.compactions >= 3) {
                 if (handoff) {
@@ -240,39 +282,29 @@ export function workSliceGuard(options) {
                 state.endedBy = 'budget';
                 state.endedByLimit = limit;
                 state.refusedAt ??= state.steps;
-                stepsSinceProgress = 0;
-                return handoff ? undefined : { block: true, reason: handoffRequest(limit, state) };
+                return handoff ? undefined : { block: true, reason: handoffRequest(limit, state, canCheckpoint) };
             }
             if (handoff)
                 return undefined;
+            // Todo updates are bookkeeping, not evidence of progress or a stall. They still count above
+            // toward the reply's overall tool-call budget.
+            if (name === 'todo_write')
+                return undefined;
             const edit = name === 'edit' || name === 'write';
             const path = edit && event.input && typeof event.input === 'object' ? String(event.input.path ?? '') : '';
             if (edit && path) {
-                const count = (edits.get(path) ?? 0) + 1;
-                edits.set(path, count);
-                stepsSinceProgress = 0;
+                const count = edits.get(path) ?? 0;
                 if (count >= 4) {
                     const reason = `${path} was edited ${count} times with no passing check between`;
-                    if (nudged)
-                        return end('stuck', reason);
-                    nudged = true;
-                    return { block: true, reason: stalledNote(reason) };
+                    return nudge(reason);
                 }
             }
-            else {
-                stepsSinceProgress += 1;
-            }
             const repeat = repeated(name, event.input);
             const failure = failing(name, event.input);
-            const noProgress = stepsSinceProgress >= 25 ? `${stepsSinceProgress} steps with no file change and no passing check` : null;
-            const reason = repeat ?? failure ?? noProgress;
+            const reason = repeat ?? failure;
             if (!reason)
                 return undefined;
-            if (nudged)
-                return end('stuck', reason);
-            nudged = true;
-            stepsSinceProgress = 0;
-            return { block: true, reason: stalledNote(reason) };
+            return nudge(reason);
         });
     };
 }

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

@@ -1,6 +1,14 @@
 import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
 import type { ActiveRun, ApprovalDecision, QuestionAnswer } from "../sessions/registry.js";
 import { type TerminalSubagentActivity, type TerminalSubagentProfile, type TerminalSubagentRun } from "./subagentMonitor.js";
+type MonitorRuntime = Pick<TerminalSubagentRun, 'accountLabel' | 'model' | 'effort'>;
+/** A saved run to show in the monitor after the conversation is reopened. */
+export interface MonitorEntry {
+    record: RunRecord;
+    events: readonly RunEvent[];
+    profile?: TerminalSubagentProfile | null;
+    runtime?: MonitorRuntime;
+}
 export interface PolicyReply {
     allowed: boolean;
     reason?: string | null;
@@ -17,6 +25,8 @@ export interface ControllerHooks {
         reservedRunId: string | null;
         nativeTurnId: string;
         text: string;
+        model?: string | null;
+        effort?: string | null;
     }): ActiveRun;
     /** Whether a native tool call may run. */
     policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>;
@@ -30,6 +40,11 @@ export interface ControllerHooks {
     allowToolGlobally(target: string): void;
     /** The native conversation identity changed. */
     native(nativeSessionId: string): void;
+    /**
+     * The conversation opened with no turn running: show its latest parent run's rows again. `owners`
+     * are the parent run ids recorded on the native branch, oldest first.
+     */
+    hydrate?(owners: string[]): void;
     telemetry(event: string): void;
     interrupt?(runId: string): Promise<void>;
     resolveApproval?(runId: string, requestId: string, decision: ApprovalDecision): void;
@@ -76,6 +91,10 @@ export declare class TerminalController {
     observe(event: RunEvent, descendant?: boolean): void;
     /** A child event that belongs to the active terminal parent run. */
     observeSubagent(parentRunId: string, run: RunRecord, event: RunEvent, profile?: TerminalSubagentProfile | null, runtime?: Pick<TerminalSubagentRun, 'accountLabel' | 'model' | 'effort'>): void;
+    /** An event of the tracked parent run itself, shown as the `main` row; it outlives settlement. */
+    observeMain(run: RunRecord, event: RunEvent, runtime?: MonitorRuntime): void;
+    /** Shows a saved parent run and its descendants, as they ended, until another run begins. */
+    restoreMonitor(parent: MonitorEntry, children: readonly MonitorEntry[]): void;
     /** Read-only child activity for the latest parent run, retained until another run begins. */
     subagentSnapshot(): TerminalSubagentActivity[];
     /** The socket grants this interface only to the process that owns terminal input. */
@@ -84,3 +103,4 @@ export declare class TerminalController {
     accept(event: string, data: Record<string, any>): Promise<unknown>;
     dispose(): void;
 }
+export {};

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 {
@@ -41,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;
@@ -51,7 +65,7 @@ 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);
@@ -150,18 +164,23 @@ export class TerminalController {
     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,
-            ...runtime
-        }, 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);
+    }
+    /** 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() {
@@ -316,10 +335,16 @@ export class TerminalController {
                 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 ?? ''));
+            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') {
@@ -377,8 +402,8 @@ 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')

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