@vincemakes/kiso-code 0.1.13 → 0.1.15

package/dist/body.d.ts

@@ -0,0 +1,118 @@
+/**
+ * v2d — the body renderer: ONE writer for the stdout scroll region.
+ *
+ * The v2b/v2c body writes streamed directly (each event wrote its bytes),
+ * so the tool lines, thinking folds, and text deltas could interleave in
+ * the same frame — and a tool's life was scattered across several writes
+ * (the "leak"). v2d: every event handler ONLY mutates cell state; the
+ * Body's render loop is the only thing that writes the region.
+ *
+ * Frozen semantics: a completed cell prints its final form into the
+ * scroll region ONCE and is never touched again. The ACTIVE TAIL — the
+ * unfinished cells — renders at the region's bottom (between the frozen
+ * area and the dock) and redraws in place, CSI 2026 wrapped. State
+ * changes coalesce to ≥16ms frames; a 200ms heartbeat drives the running
+ * spinners and elapsed timers. An over-height tail (rare) overflows to
+ * freeze by completion order.
+ *
+ * Pipes / NO_COLOR: the Body runs in PASSTHROUGH — every mutation writes
+ * the v2b/v2c line-mode bytes immediately, byte-for-byte (the existing
+ * e2e guards it). The cell renderer never activates.
+ *
+ * The cell model is ours (UserCell / ThinkingCell / ToolCell / TextCell /
+ * NoticeCell / raw block) — deliberately NOT pi's Component interface
+ * shape (ADR-0040).
+ */
+/** One completed-or-active body line. The renderer's only state. */
+export type BodyCell = {
+    kind: "user";
+    text: string;
+    done: true;
+} | {
+    kind: "thinking";
+    text: string;
+    done: boolean;
+} | {
+    kind: "tool";
+    name: string;
+    input: string;
+    state: "pending" | "approval" | "running" | "done";
+    isError: boolean;
+    resultText: string;
+    startedAt: number | null;
+    doneAt: number | null;
+    done: boolean;
+} | {
+    kind: "text";
+    text: string;
+    done: boolean;
+} | {
+    kind: "notice";
+    text: string;
+    done: true;
+} | {
+    kind: "raw";
+    lines: string[];
+    done: true;
+} | {
+    kind: "terminal";
+    label: string;
+    line: string;
+    done: true;
+};
+export interface BodyOptions {
+    /** Is the cell renderer live? A color TTY with a real size — checked
+     *  per mutation (the TIOCSWINSZ can land after main constructs us). */
+    active: () => boolean;
+    /** The terminal height (rows) — live, for the region geometry. */
+    height: () => number;
+    /** The terminal width (cols) — live, for wrap estimates. */
+    width: () => number;
+    /** The input line's edit column — the render's cursor home. */
+    editCol: () => number;
+    /** The dock's redraw (the bottom three rows) — the body never writes
+     *  below the region, but the frame may call it to re-pin the chrome. */
+    onDock?: () => void;
+    /** The stdout writer — injectable for unit tests (default: stdout). */
+    write?: (s: string) => void;
+}
+export declare class Body {
+    #private;
+    constructor(opts: BodyOptions);
+    /** Teardown — flush a pending frame, stop the timers. */
+    close(): void;
+    /** The last COMPLETE thinking block, for /think. */
+    lastThinking(): string | null;
+    /** The last completed tool call, for /last. */
+    lastTool(): {
+        name: string;
+        input: Record<string, unknown>;
+        result: {
+            content: string;
+            isError: boolean;
+        };
+    } | null;
+    userLine(text: string): void;
+    thinkingAppend(text: string): void;
+    thinkingEnd(): void;
+    toolStart(name: string, callId: string, input: Record<string, unknown>): void;
+    toolApproval(callId: string): void;
+    toolRunning(callId: string): void;
+    toolSucceeded(callId: string): void;
+    toolFailed(callId: string, error: string): void;
+    toolResult(callId: string, result: {
+        content: string;
+        isError: boolean;
+    }): void;
+    textAppend(text: string): void;
+    textEnd(): void;
+    /** The terminal's status line + the rhythm gap (one blank). */
+    terminal(label: string, statusLine: string): void;
+    notice(text: string): void;
+    /** A pre-rendered block (the banner, the session line, slash-command
+     *  outputs) — frozen immediately. */
+    raw(lines: string[]): void;
+    /** The one writer. Frozen cells print once; the tail redraws in place,
+     *  CSI 2026 wrapped; the cursor lands at the input edit column. */
+    render(): void;
+}

package/dist/body.js

@@ -0,0 +1,419 @@
+/**
+ * v2d — the body renderer: ONE writer for the stdout scroll region.
+ *
+ * The v2b/v2c body writes streamed directly (each event wrote its bytes),
+ * so the tool lines, thinking folds, and text deltas could interleave in
+ * the same frame — and a tool's life was scattered across several writes
+ * (the "leak"). v2d: every event handler ONLY mutates cell state; the
+ * Body's render loop is the only thing that writes the region.
+ *
+ * Frozen semantics: a completed cell prints its final form into the
+ * scroll region ONCE and is never touched again. The ACTIVE TAIL — the
+ * unfinished cells — renders at the region's bottom (between the frozen
+ * area and the dock) and redraws in place, CSI 2026 wrapped. State
+ * changes coalesce to ≥16ms frames; a 200ms heartbeat drives the running
+ * spinners and elapsed timers. An over-height tail (rare) overflows to
+ * freeze by completion order.
+ *
+ * Pipes / NO_COLOR: the Body runs in PASSTHROUGH — every mutation writes
+ * the v2b/v2c line-mode bytes immediately, byte-for-byte (the existing
+ * e2e guards it). The cell renderer never activates.
+ *
+ * The cell model is ours (UserCell / ThinkingCell / ToolCell / TextCell /
+ * NoticeCell / raw block) — deliberately NOT pi's Component interface
+ * shape (ADR-0040).
+ */
+import { displayWidth } from "./editor.js";
+import { escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, } from "./render.js";
+/** The spinner glyphs, cycled by the heartbeat. */
+const SPINNER = ["◐", "◓", "◑", "◒"];
+const TOOL_SUMMARY_MAX = 60; // the tool line's parameter summary, chars
+const FRAME_MS = 16; // state changes coalesce to ≥16ms frames
+const HEARTBEAT_MS = 200; // spinner / elapsed cadence
+export class Body {
+    #active;
+    #opts;
+    #cells = [];
+    #nextFrozen = 0; // index of the first not-yet-printed cell
+    #frozenRows = 0; // rows of the region occupied by printed cells
+    #oldTailTop = 0; // the tail's previous first row — for the clear pass
+    #frameTimer = null;
+    #heartbeat = null;
+    #dirty = false;
+    #spinnerI = 0;
+    #lastThinking = null;
+    #lastTool = null;
+    #pendingCalls = new Map();
+    #pipeBuf = ""; // the passthrough's thinking buffer — the cell model needs no buffer
+    #toolCells = new Map(); // callId → cell index (parallel tools)
+    #write;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#write = opts.write ?? ((s) => process.stdout.write(s));
+        this.#active = opts.active();
+        if (this.#isActive()) {
+            this.#heartbeat = setInterval(() => {
+                this.#spinnerI = (this.#spinnerI + 1) % SPINNER.length;
+                this.#dirty = true; // the running cells' glyph/elapsed advance
+                this.#scheduleFrame();
+            }, HEARTBEAT_MS);
+            this.#heartbeat.unref();
+        }
+    }
+    /** Live re-check — a TTY whose size lands after construction flips in. */
+    #isActive() {
+        this.#active = this.#opts.active();
+        return this.#active;
+    }
+    /** Teardown — flush a pending frame, stop the timers. */
+    close() {
+        if (this.#frameTimer !== null) {
+            clearTimeout(this.#frameTimer);
+            this.#frameTimer = null;
+        }
+        if (this.#heartbeat !== null) {
+            clearInterval(this.#heartbeat);
+            this.#heartbeat = null;
+        }
+        if (this.#dirty)
+            this.render();
+    }
+    /** The last COMPLETE thinking block, for /think. */
+    lastThinking() {
+        return this.#lastThinking;
+    }
+    /** The last completed tool call, for /last. */
+    lastTool() {
+        return this.#lastTool;
+    }
+    // ---- mutations (the ONLY way the CLI touches the body) ----
+    userLine(text) {
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            const p = palette();
+            this.#write(`${p.blue}you> ${escapeTerminal(text)}${p.reset}\n`);
+            return;
+        }
+        this.#closeOpenThinking();
+        this.#cells.push({ kind: "user", text, done: true });
+        this.#mark();
+    }
+    thinkingAppend(text) {
+        if (!this.#isActive()) {
+            this.#pipeBuf += text; // buffered; the fold prints at the block's end
+            return;
+        }
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "thinking" && !last.done) {
+            last.text += text;
+        }
+        else {
+            this.#cells.push({ kind: "thinking", text, done: false });
+        }
+        this.#mark();
+    }
+    thinkingEnd() {
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "thinking" && !last.done) {
+            last.done = true;
+            this.#lastThinking = last.text;
+            if (!this.#isActive())
+                process.stdout.write(foldThinking(last.text));
+            this.#mark();
+        }
+    }
+    toolStart(name, callId, input) {
+        const summary = JSON.stringify(input).slice(0, TOOL_SUMMARY_MAX);
+        // Registered BEFORE the passthrough branch — /last and the pipe
+        // summary need the call on BOTH paths.
+        this.#pendingCalls.set(callId, { name, input, result: { content: "", isError: false } });
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            process.stdout.write(`→ ${escapeTerminal(name)}(${escapeTerminal(JSON.stringify(input).slice(0, 200))})\n`);
+            return;
+        }
+        this.#toolCells.set(callId, this.#cells.length);
+        this.#cells.push({ kind: "tool", name, input: summary, state: "pending", isError: false, resultText: "", startedAt: null, doneAt: null, done: false });
+        this.#mark();
+    }
+    toolApproval(callId) {
+        if (!this.#isActive())
+            return;
+        const cell = this.#toolCell(callId);
+        if (cell !== null && cell.kind === "tool" && !cell.done)
+            cell.state = "approval";
+        this.#mark();
+    }
+    toolRunning(callId) {
+        if (!this.#isActive()) {
+            const p = palette();
+            process.stdout.write(`${p.dim}  running…${p.reset}\n`);
+            return;
+        }
+        const cell = this.#toolCell(callId);
+        if (cell !== null && cell.kind === "tool" && !cell.done) {
+            cell.state = "running";
+            cell.startedAt = Date.now();
+        }
+        this.#mark();
+    }
+    toolSucceeded(callId) {
+        if (!this.#isActive()) {
+            process.stdout.write(`  ok\n`);
+        }
+    }
+    toolFailed(callId, error) {
+        if (!this.#isActive()) {
+            const p = palette();
+            process.stdout.write(`${p.red}  failed: ${escapeTerminal(error.slice(0, 160))}${p.reset}\n`);
+        }
+    }
+    toolResult(callId, result) {
+        const call = this.#pendingCalls.get(callId);
+        if (call !== undefined) {
+            call.result = result;
+            this.#lastTool = { name: call.name, input: call.input, result };
+            this.#pendingCalls.delete(callId);
+        }
+        if (!this.#isActive()) {
+            // The v2b/v2c pipe bytes: the summary line + the [result] line.
+            const p = palette();
+            process.stdout.write(`${renderToolSummary(call?.name ?? "?", call?.input ?? {}, result)}\n` +
+                `${p.dim}${result.isError ? p.red : p.dim}  [result${result.isError ? " ✗" : ""}] ${foldResult(result.content)}${p.reset}\n`);
+            return;
+        }
+        const cell = this.#toolCell(callId);
+        this.#toolCells.delete(callId);
+        if (cell !== null && cell.kind === "tool" && !cell.done) {
+            cell.state = "done";
+            cell.isError = result.isError;
+            cell.resultText = result.content;
+            cell.doneAt = Date.now();
+            cell.done = true;
+        }
+        this.#mark();
+    }
+    textAppend(text) {
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            process.stdout.write(escapeTerminal(text));
+            return;
+        }
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "text" && !last.done) {
+            last.text += text;
+        }
+        else {
+            this.#closeOpenThinking();
+            this.#cells.push({ kind: "text", text, done: false });
+        }
+        this.#mark();
+    }
+    textEnd() {
+        if (!this.#isActive()) {
+            process.stdout.write("\n");
+            return;
+        }
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "text" && !last.done)
+            last.done = true;
+        this.#mark();
+    }
+    /** The terminal's status line + the rhythm gap (one blank). */
+    terminal(label, statusLine) {
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            // the v2c bytes: the terminal label (\ndone\n) + the status gap.
+            process.stdout.write(label + renderTerminalGap(statusLine));
+            return;
+        }
+        this.#closeOpenThinking();
+        this.#cells.push({ kind: "terminal", label: label.trim(), line: statusLine, done: true });
+        this.#mark();
+    }
+    notice(text) {
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            process.stdout.write(`${text}\n`);
+            return;
+        }
+        this.#closeOpenThinking();
+        this.#cells.push({ kind: "notice", text, done: true });
+        this.#mark();
+    }
+    /** A pre-rendered block (the banner, the session line, slash-command
+     *  outputs) — frozen immediately. */
+    raw(lines) {
+        if (!this.#isActive()) {
+            this.#closeOpenThinking();
+            for (const line of lines)
+                process.stdout.write(`${line}\n`);
+            return;
+        }
+        this.#closeOpenThinking();
+        this.#cells.push({ kind: "raw", lines, done: true });
+        this.#mark();
+    }
+    // ---- rendering ----
+    #mark() {
+        if (!this.#isActive())
+            return;
+        this.#dirty = true;
+        this.#scheduleFrame();
+    }
+    #scheduleFrame() {
+        if (this.#frameTimer !== null)
+            return;
+        this.#frameTimer = setTimeout(() => {
+            this.#frameTimer = null;
+            if (this.#dirty) {
+                this.#dirty = false;
+                this.render();
+            }
+        }, FRAME_MS);
+        this.#frameTimer.unref();
+    }
+    /** The one writer. Frozen cells print once; the tail redraws in place,
+     *  CSI 2026 wrapped; the cursor lands at the input edit column. */
+    render() {
+        if (!this.#isActive())
+            return;
+        const H = this.#opts.height();
+        const W = this.#opts.width();
+        const regionBottom = H - 3;
+        if (regionBottom < 1)
+            return;
+        const out = [];
+        out.push("\x1b[?2026h");
+        // 1. freeze completed cells — print their final form at the frozen
+        // area's next rows. The terminal scrolls the region when full.
+        while (this.#nextFrozen < this.#cells.length && this.#cells[this.#nextFrozen].done) {
+            const cell = this.#cells[this.#nextFrozen];
+            const lines = this.#cellLines(cell, W);
+            for (const line of lines) {
+                const row = Math.min(this.#frozenRows + 1, regionBottom);
+                out.push(`\x1b[${row};1H\x1b[0K${line}`);
+                if (this.#frozenRows + 1 > regionBottom) {
+                    out.push("\n"); // the region scrolls — the frozen rows shift up
+                }
+                else {
+                    this.#frozenRows += 1;
+                }
+            }
+            this.#nextFrozen += 1;
+        }
+        // 2. the active tail — clear its old area, draw the cells.
+        const tail = this.#cells.slice(this.#nextFrozen);
+        const tailHeight = tail.reduce((n, c) => n + this.#cellHeight(c, W), 0);
+        const tailTop = Math.max(1, regionBottom - tailHeight + 1);
+        const clearFrom = Math.min(this.#oldTailTop === 0 ? tailTop : this.#oldTailTop, tailTop);
+        for (let row = clearFrom; row <= regionBottom; row += 1) {
+            out.push(`\x1b[${row};1H\x1b[0K`);
+        }
+        let row = tailTop;
+        for (const cell of tail) {
+            for (const line of this.#cellLines(cell, W)) {
+                out.push(`\x1b[${row};1H${line}`);
+                row += 1;
+            }
+        }
+        this.#oldTailTop = tailTop;
+        // 3. the cursor home — the input line's edit column.
+        out.push(`\x1b[${H};${this.#opts.editCol()}H`);
+        out.push("\x1b[?2026l");
+        this.#write(out.join(""));
+    }
+    // ---- cell → lines ----
+    #cellLines(cell, W) {
+        const p = palette();
+        switch (cell.kind) {
+            case "user":
+                return [`${p.blue}you> ${escapeTerminal(cell.text)}${p.reset}`];
+            case "thinking": {
+                const block = cell.text;
+                const trimmed = escapeTerminal(block.trim());
+                if (trimmed.length <= 100)
+                    return [`${p.dim}…${trimmed}${p.reset}`];
+                return [`${p.dim}…${trimmed.slice(0, 100)} (… ${block.length} chars · /think shows full)${p.reset}`];
+            }
+            case "tool": {
+                const name = escapeTerminal(cell.name);
+                const summary = escapeTerminal(cell.input);
+                if (cell.state === "done") {
+                    const elapsed = cell.startedAt !== null && cell.doneAt !== null ? ((cell.doneAt - cell.startedAt) / 1000).toFixed(1) : "?";
+                    if (cell.isError) {
+                        const err = escapeTerminal(cell.resultText.split("\n")[0].slice(0, 60));
+                        return [`${p.red}✗ ${name} (${err}, ${elapsed}s)${p.reset}`];
+                    }
+                    return [`${p.blue}✓ ${name}${p.reset} (${summary}, ${elapsed}s)`];
+                }
+                if (cell.state === "approval")
+                    return [`→ ${name} ${summary} ${p.blue}⏸${p.reset}`];
+                if (cell.state === "running") {
+                    const elapsed = cell.startedAt !== null ? Math.max(1, Math.round((Date.now() - cell.startedAt) / 1000)) : 1;
+                    return [`→ ${name} ${summary} ${p.blue}${SPINNER[this.#spinnerI % SPINNER.length]}${p.reset} ${elapsed}s`];
+                }
+                return [`→ ${name} ${summary}`];
+            }
+            case "text": {
+                const text = escapeTerminal(cell.text);
+                const wrapped = this.#wrap(text, W);
+                return wrapped.length > 0 ? wrapped : [""];
+            }
+            case "notice":
+                return [escapeTerminal(cell.text)];
+            case "raw":
+                return cell.lines.map((l) => escapeTerminal(l));
+            case "terminal":
+                // the honest label (done / aborted / error) + the status + the
+                // rhythm gap blank
+                return [cell.label, cell.line, ""];
+        }
+    }
+    #cellHeight(cell, W) {
+        const lines = this.#cellLines(cell, W);
+        return Math.max(1, lines.length);
+    }
+    /** Wrap a body text by display width (the terminal's own wrapping,
+     *  approximated — documented; the region clamp keeps the dock safe). */
+    #wrap(text, W) {
+        if (W < 4)
+            return [text];
+        const out = [];
+        let current = "";
+        let width = 0;
+        for (const ch of text) {
+            const cw = displayWidth(ch);
+            if (ch === "\n" || width + cw > W) {
+                out.push(current);
+                current = "";
+                width = 0;
+                if (ch === "\n")
+                    continue;
+            }
+            current += ch;
+            width += cw;
+        }
+        out.push(current);
+        return out;
+    }
+    #toolCell(callId) {
+        const i = this.#toolCells.get(callId);
+        return i === undefined ? null : (this.#cells[i] ?? null);
+    }
+    /** Close an open thinking cell when a new cell starts (the block's
+     *  fold freezes at the transition). */
+    #closeOpenThinking() {
+        if (!this.#isActive() && this.#pipeBuf !== "") {
+            this.#lastThinking = this.#pipeBuf;
+            process.stdout.write(foldThinking(this.#pipeBuf));
+            this.#pipeBuf = "";
+            return;
+        }
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "thinking" && !last.done) {
+            last.done = true;
+            this.#lastThinking = last.text;
+        }
+    }
+}

package/dist/dock.d.ts

@@ -1,14 +1,18 @@
 /**
- * v2b — the bottom-anchored UI (TTY + color only). Borrows pi-tui's IDEA —
- * a DECSTBM scroll region with a reserved bottom — without its
+ * v2b/v2c — the bottom-anchored UI (TTY + color only). Borrows pi-tui's
+ * IDEA — a DECSTBM scroll region with a reserved bottom — without its
  * implementation: zero dependencies, line-level ANSI, no differential
  * renderer.
  *
  * Layout (H = terminal height): rows 1..H-3 = the scroll region (the body
  * streams and scrolls here, never touching the bottom), row H-2 = the dim
- * separator, row H-1 = the live status bar (or a takeover question), row
- * H = the input line (blue you> + readline). Bottom redraws are wrapped in
- * CSI 2026 (synchronized output) to avoid flicker — the pi trick.
+ * dotted separator (╌), row H-1 = the live status bar (or a takeover
+ * question), row H = the input line (the blue brick ▌you> + the v2c
+ * editor's row — readline is gone from the TTY path). Bottom redraws are
+ * wrapped in CSI 2026 (synchronized output) to avoid flicker — the pi
+ * trick. The visual identity is the kiso brick motif — ▌ half-block,
+ * dotted separator — deliberately NOT the CC rounded frame nor the pi
+ * editor (ADR-0039 Amendment 2).
  *
  * Pipes / NO_COLOR: the dock never activates; the v2a line mode stays
  * byte-for-byte (the existing e2e assertions guard it).
@@ -36,10 +40,24 @@ export declare class Dock {
     onResize(): void;
     /** Body output: position the cursor inside the scroll region at the
      *  body's tracked position, write, and hand the cursor back to the
-     *  input line. The row/col tracking is approximate for width-wrapped
-     *  and wide-char lines (documented) — the region clamp keeps the
-     *  bottom rows safe regardless. */
+     *  input line's EDIT position. The row/col tracking is approximate for
+     *  width-wrapped and wide-char lines (documented) — the region clamp
+     *  keeps the bottom rows safe regardless.
+     *
+     *  The edit-position return is a correctness requirement, not
+     *  cosmetics: readline tracks its cursor internally and NEVER
+     *  re-syncs after an external move — a body write that left the
+     *  cursor at column 1 made the next keystroke overwrite the prompt
+     *  (probe-confirmed; the dock's redraw self-repaired ~200ms later,
+     *  which read the user as cursor drift). */
     writeBody(text: string): void;
+    /** The input line's edit column — prompt width + cursor + 1. The
+     *  dock's redraw and the body's cursor return both end here, so the
+     *  ACTUAL cursor always equals what the editor tracks. The width is
+     *  DISPLAY width (the editor's cursor column is already width-based —
+     *  the CJK drift root cause, editor.ts). v2d: public — the Body's
+     *  render loop ends at this column. */
+    editCol(): number;
     /** The status bar's base text (usage, ctx, session, …). */
     setStatus(text: string): void;
     /** The live tail — the spinner glyph or "running <tool> Ns". */
@@ -50,6 +68,9 @@ export declare class Dock {
     clearQuestion(): void;
     /** The bottom three rows, wrapped in CSI 2026 (synchronized output —
      *  the pi trick against flicker). The cursor ends at the input line's
-     *  edit position. */
+     *  edit position. v2c: the separator is the dim dotted ╌ (a weaker
+     *  presence than the solid ─), the status line is dim (blue accents
+     *  inside come from the CLI's composition), the input row is the blue
+     *  brick ▌you> + the editor's visible slice. */
     redraw(): void;
 }