agent-sh 0.5.0 → 0.7.0

package/dist/utils/floating-panel.js

@@ -0,0 +1,590 @@
+/**
+ * Floating panel utility for overlay extensions.
+ *
+ * Provides a composited floating box rendered over the terminal using
+ * an alternate screen buffer. Handles the full overlay lifecycle:
+ * stdout hold/release, input routing, compositing, scroll, and
+ * screen restore.
+ *
+ * Rendering is fully customizable via the handler/advise pattern:
+ *
+ *   // Replace the entire frame renderer
+ *   panel.handlers.define("panel:render-frame", (ctx) => {
+ *     // ctx has geo, content, bgLines, phase, title, footer, border
+ *     return { rows: myCustomRows, cursorSeq: "" };
+ *   });
+ *
+ *   // Or advise individual pieces
+ *   panel.handlers.advise("panel:render-border-top", (next, ctx) => {
+ *     return `┏━ ${ctx.title} ${"━".repeat(ctx.geo.boxW - ctx.title.length - 5)}┓`;
+ *   });
+ *
+ *   panel.handlers.advise("panel:composite-row", (next, boxLine, bgLine, ...) => {
+ *     // custom compositing (e.g. no dimming, blur effect, etc.)
+ *     return next(boxLine, bgLine, ...);
+ *   });
+ *
+ * When @xterm/headless is needed (for dimmed background compositing):
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Usage from extensions:
+ *   import { FloatingPanel } from "agent-sh/utils/floating-panel.js";
+ */
+import { stripAnsi } from "./ansi.js";
+import { LineEditor } from "./line-editor.js";
+import { TerminalBuffer } from "./terminal-buffer.js";
+import { HandlerRegistry } from "./handler-registry.js";
+// ── ANSI constants ──────────────────────────────────────────────
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+const INVERSE = "\x1b[7m";
+const SYNC_START = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+// ── Border characters ───────────────────────────────────────────
+const BORDERS = {
+    rounded: { tl: "\u256d", tr: "\u256e", bl: "\u2570", br: "\u256f", h: "\u2500", v: "\u2502" },
+    square: { tl: "\u250c", tr: "\u2510", bl: "\u2514", br: "\u2518", h: "\u2500", v: "\u2502" },
+    double: { tl: "\u2554", tr: "\u2557", bl: "\u255a", br: "\u255d", h: "\u2550", v: "\u2551" },
+    heavy: { tl: "\u250f", tr: "\u2513", bl: "\u2517", br: "\u251b", h: "\u2501", v: "\u2503" },
+};
+// ── Trigger sequence helpers ────────────────────────────────────
+// Programs like vim enable xterm's modifyOtherKeys or the kitty
+// keyboard protocol, which encode Ctrl+key as CSI sequences instead
+// of raw control bytes.  We pre-compute every encoding of the
+// trigger so it works regardless of what the foreground process has
+// negotiated with the terminal.
+function buildTriggerSequences(trigger) {
+    const seqs = [trigger];
+    if (trigger.length === 1) {
+        const code = trigger.charCodeAt(0);
+        if (code < 32) {
+            // Ctrl+key: base codepoint is code | 0x40 (e.g. 0x1c → 0x5c = '\')
+            const base = code | 0x40;
+            // xterm modifyOtherKeys mode 2: ESC[27;5;<base>~
+            seqs.push(`\x1b[27;5;${base}~`);
+            // kitty keyboard protocol: ESC[<base>;5u
+            seqs.push(`\x1b[${base};5u`);
+        }
+    }
+    return seqs;
+}
+// ── FloatingPanel ───────────────────────────────────────────────
+export class FloatingPanel {
+    // ── Configuration ───────────────────────────────────────────
+    config;
+    bus;
+    border;
+    externalBuffer;
+    prefix;
+    /**
+     * Handler registry for this panel. Extensions use `handlers.advise()`
+     * to customize rendering and behavior.
+     *
+     * Registered handlers:
+     *   - `{prefix}:render-content(ctx: RenderContext) -> RenderResult`
+     *   - `{prefix}:render-frame(ctx: FrameContext) -> FrameResult`
+     *   - `{prefix}:render-border-top(ctx: FrameContext) -> string`
+     *   - `{prefix}:render-border-bottom(ctx: FrameContext) -> string`
+     *   - `{prefix}:composite-row(content: string, bgLine: string|null, boxLeft: number, boxW: number, cols: number) -> string`
+     *   - `{prefix}:submit(query: string) -> void`
+     *   - `{prefix}:dismiss() -> void`
+     *   - `{prefix}:input(data: string) -> boolean`
+     *   - `{prefix}:build-row(content: string, width: number) -> string`
+     */
+    handlers;
+    // ── Headless terminal (lazy, optional) ──────────────────────
+    buffer = null;
+    bufferInitialized = false;
+    // ── Trigger sequences ───────────────────────────────────────
+    /** All byte sequences that should be recognized as the trigger key. */
+    triggerSeqs;
+    // ── State ───────────────────────────────────────────────────
+    phase = "idle";
+    editor = new LineEditor();
+    contentLines = [];
+    currentPartialLine = "";
+    scrollOffset = 0;
+    title = "";
+    footer = "";
+    renderTimer = null;
+    autoDismissTimer = null;
+    resizeHandler = null;
+    prevFrame = [];
+    suppressNextRedraw = false;
+    ptyBuffer = ""; // PTY output accumulated while overlay is open
+    usedAltScreen = false; // whether we entered our own alt screen
+    constructor(bus, config, handlers) {
+        this.bus = bus;
+        this.externalBuffer = config.terminalBuffer;
+        this.prefix = config.handlerPrefix ?? "panel";
+        this.handlers = handlers ?? new HandlerRegistry();
+        this.config = {
+            trigger: config.trigger,
+            width: config.width ?? "80%",
+            maxWidth: config.maxWidth ?? 100,
+            height: config.height ?? "60%",
+            minHeight: config.minHeight ?? 6,
+            borderStyle: config.borderStyle ?? "rounded",
+            dimBackground: config.dimBackground ?? true,
+            autoDismissMs: config.autoDismissMs ?? 0,
+            promptIcon: config.promptIcon ?? "\u276f",
+            handlerPrefix: this.prefix,
+        };
+        this.border = BORDERS[this.config.borderStyle];
+        this.triggerSeqs = buildTriggerSequences(config.trigger);
+        this.registerDefaultHandlers();
+        this.wireEvents();
+    }
+    // ── Default handler registration ───────────────────────────
+    registerDefaultHandlers() {
+        const p = this.prefix;
+        // Default content renderer: uses built-in appendText/appendLine buffer
+        this.handlers.define(`${p}:render-content`, (ctx) => {
+            if (ctx.phase === "input") {
+                return {
+                    lines: [`\x1b[36m${this.config.promptIcon}${RESET} ${ctx.inputBuffer}`],
+                    cursor: { row: 0, col: this.config.promptIcon.length + 1 + ctx.inputCursor },
+                };
+            }
+            const all = [...ctx.contentLines, ...(ctx.partialLine ? [ctx.partialLine] : [])];
+            // Auto-scroll
+            let offset = ctx.scrollOffset;
+            if (all.length > ctx.height) {
+                offset = all.length - ctx.height;
+            }
+            else {
+                offset = 0;
+            }
+            this.scrollOffset = offset;
+            return { lines: all.slice(offset, offset + ctx.height) };
+        });
+        // Default submit: no-op (extension overrides)
+        this.handlers.define(`${p}:submit`, (_query) => { });
+        // Default dismiss: no-op
+        this.handlers.define(`${p}:dismiss`, () => { });
+        // Default custom input handler: don't consume
+        this.handlers.define(`${p}:input`, (_data) => false);
+        // Default row builder: truncate and pad
+        this.handlers.define(`${p}:build-row`, (content, width) => {
+            const plain = stripAnsi(content);
+            const display = plain.length > width
+                ? content.slice(0, width - 1) + "\u2026"
+                : content;
+            const pad = Math.max(0, width - stripAnsi(display).length);
+            return display + " ".repeat(pad);
+        });
+        // Default border-top renderer
+        this.handlers.define(`${p}:render-border-top`, (ctx) => {
+            const { geo, border: b } = ctx;
+            const titleText = ctx.title || (ctx.phase === "input" ? "input" : ctx.phase === "done" ? "done" : "...");
+            const titleStr = ` ${INVERSE} ${titleText} ${RESET} `;
+            const titleVisLen = titleText.length + 4;
+            const dashCount = Math.max(0, geo.boxW - titleVisLen - 3);
+            return `${b.tl}${b.h}${titleStr}${b.h.repeat(dashCount)}${b.tr}`;
+        });
+        // Default border-bottom renderer
+        this.handlers.define(`${p}:render-border-bottom`, (ctx) => {
+            const { geo, border: b } = ctx;
+            if (ctx.footer) {
+                const footerPad = Math.max(0, geo.boxW - ctx.footer.length - 3);
+                return `${b.bl}${b.h.repeat(footerPad)}${DIM}${ctx.footer}${RESET}${b.h}${b.br}`;
+            }
+            return `${b.bl}${b.h.repeat(geo.boxW - 2)}${b.br}`;
+        });
+        // Default composite-row: merge content on top of dimmed background
+        this.handlers.define(`${p}:composite-row`, (boxLine, bgLine, boxLeft, boxW, cols) => {
+            if (bgLine !== null) {
+                const bg = bgLine.padEnd(cols);
+                return `${DIM}${bg.slice(0, boxLeft)}${RESET}${boxLine}${DIM}${bg.slice(boxLeft + boxW)}${RESET}`;
+            }
+            return boxLine;
+        });
+        // Default frame renderer: assembles borders, content rows, and background
+        this.handlers.define(`${p}:render-frame`, (ctx) => {
+            const { geo, content, bgLines, border: b } = ctx;
+            const visibleContent = [...(content.lines ?? [])];
+            while (visibleContent.length < geo.contentH)
+                visibleContent.push("");
+            const composite = (boxLine, bg) => this.handlers.call(`${p}:composite-row`, boxLine, bg, geo.boxLeft, geo.boxW, geo.cols);
+            const buildRow = (c, w) => this.handlers.call(`${p}:build-row`, c, w);
+            const frame = [];
+            for (let row = 0; row < geo.rows; row++) {
+                const relRow = row - geo.boxTop;
+                const bg = bgLines?.[row] ?? null;
+                if (relRow < 0 || relRow >= geo.boxH) {
+                    // Outside box
+                    if (bgLines) {
+                        frame.push(`${DIM}${(bgLines[row] || "").padEnd(geo.cols).slice(0, geo.cols)}${RESET}\x1b[K`);
+                    }
+                    else {
+                        frame.push("\x1b[2K");
+                    }
+                }
+                else if (relRow === 0) {
+                    frame.push(composite(this.handlers.call(`${p}:render-border-top`, ctx), bg));
+                }
+                else if (relRow === geo.boxH - 1) {
+                    frame.push(composite(this.handlers.call(`${p}:render-border-bottom`, ctx), bg));
+                }
+                else {
+                    const raw = visibleContent[relRow - 1] || "";
+                    const boxLine = `${b.v} ${buildRow(raw, geo.contentW)} ${b.v}`;
+                    frame.push(composite(boxLine, bg));
+                }
+            }
+            let cursorSeq = "";
+            if (content.cursor) {
+                const cursorRow = geo.boxTop + 1 + content.cursor.row;
+                const cursorCol = geo.boxLeft + 2 + content.cursor.col;
+                cursorSeq = `\x1b[${cursorRow + 1};${cursorCol + 1}H`;
+            }
+            return { rows: frame, cursorSeq };
+        });
+    }
+    // ── Bus event wiring ───────────────────────────────────────
+    wireEvents() {
+        // Buffer PTY output while overlay is open so we can replay it on dismiss.
+        // Alt screen restore discards anything written while it was active.
+        this.bus.on("shell:pty-data", ({ raw }) => {
+            if (this.phase !== "idle")
+                this.ptyBuffer += raw;
+        });
+        this.bus.onPipe("input:intercept", (payload) => this.handleIntercept(payload));
+        this.bus.onPipe("shell:redraw-prompt", (payload) => {
+            if (this.phase !== "idle") {
+                return { ...payload, handled: true };
+            }
+            // After dismiss, suppress one redraw — restoreScreen already
+            // restored the terminal content, so freshPrompt's \n is unwanted.
+            if (this.suppressNextRedraw) {
+                this.suppressNextRedraw = false;
+                return { ...payload, handled: true };
+            }
+            return payload;
+        });
+    }
+    /** Check whether data matches any encoding of the trigger key. */
+    isTrigger(data) {
+        return this.triggerSeqs.includes(data);
+    }
+    // ── Lazy terminal buffer setup ──────────────────────────────
+    ensureBuffer() {
+        if (this.bufferInitialized)
+            return this.buffer;
+        this.bufferInitialized = true;
+        if (!this.config.dimBackground)
+            return null;
+        if (this.externalBuffer) {
+            this.buffer = this.externalBuffer;
+        }
+        else {
+            this.buffer = TerminalBuffer.createWired(this.bus);
+        }
+        return this.buffer;
+    }
+    // ── Public lifecycle ────────────────────────────────────────
+    get active() {
+        return this.phase !== "idle";
+    }
+    get terminalBuffer() {
+        return this.buffer;
+    }
+    open() {
+        if (this.phase !== "idle")
+            return;
+        this.ensureBuffer();
+        this.phase = "input";
+        this.editor.clear();
+        this.contentLines = [];
+        this.currentPartialLine = "";
+        this.scrollOffset = 0;
+        this.title = "";
+        this.footer = "";
+        this.prevFrame = [];
+        this.ptyBuffer = "";
+        this.bus.emit("shell:stdout-hold", {});
+        // If a foreground program (vim, htop) is already on alt screen,
+        // don't enter a second alt screen — it doesn't nest.  Instead,
+        // render directly on the current screen and restore from the
+        // xterm buffer on dismiss.
+        this.usedAltScreen = !(this.buffer?.altScreen);
+        if (this.usedAltScreen) {
+            process.stdout.write("\x1b[?1049h");
+        }
+        this.resizeHandler = () => { this.prevFrame = []; this.render(); };
+        process.stdout.on("resize", this.resizeHandler);
+        this.render();
+    }
+    dismiss() {
+        if (this.phase === "idle")
+            return;
+        if (this.renderTimer) {
+            clearTimeout(this.renderTimer);
+            this.renderTimer = null;
+        }
+        if (this.autoDismissTimer) {
+            clearTimeout(this.autoDismissTimer);
+            this.autoDismissTimer = null;
+        }
+        if (this.resizeHandler) {
+            process.stdout.off("resize", this.resizeHandler);
+            this.resizeHandler = null;
+        }
+        this.suppressNextRedraw = true;
+        this.phase = "idle";
+        this.editor.clear();
+        this.prevFrame = [];
+        this.restoreScreen();
+        // Replay any PTY output that arrived while the overlay was open.
+        // Alt screen restore discarded it, but it represents real work
+        // the agent did (commands run, output produced).
+        if (this.ptyBuffer) {
+            process.stdout.write(this.ptyBuffer);
+            this.ptyBuffer = "";
+        }
+        // Reset any accumulated stdout-show refs, then release hold.
+        this.bus.emit("shell:stdout-hide", {});
+        this.bus.emit("shell:stdout-release", {});
+        this.handlers.call(`${this.prefix}:dismiss`);
+    }
+    // ── Public content API ──────────────────────────────────────
+    appendText(text) {
+        for (const ch of text) {
+            if (ch === "\n") {
+                this.contentLines.push(this.currentPartialLine);
+                this.currentPartialLine = "";
+            }
+            else {
+                this.currentPartialLine += ch;
+            }
+        }
+        this.scheduleRender();
+    }
+    appendLine(line) {
+        if (this.currentPartialLine) {
+            this.contentLines.push(this.currentPartialLine);
+            this.currentPartialLine = "";
+        }
+        this.contentLines.push(line);
+        this.scheduleRender();
+    }
+    updateLastLine(fn) {
+        if (this.contentLines.length > 0) {
+            this.contentLines[this.contentLines.length - 1] = fn(this.contentLines[this.contentLines.length - 1]);
+        }
+        this.scheduleRender();
+    }
+    clearContent() {
+        this.contentLines = [];
+        this.currentPartialLine = "";
+        this.scrollOffset = 0;
+        this.scheduleRender();
+    }
+    setTitle(title) {
+        this.title = title;
+        this.scheduleRender();
+    }
+    setFooter(footer) {
+        this.footer = footer;
+        this.scheduleRender();
+    }
+    setActive() {
+        this.phase = "active";
+    }
+    setDone() {
+        this.phase = "done";
+        this.render();
+        if (this.config.autoDismissMs > 0) {
+            this.autoDismissTimer = setTimeout(() => {
+                if (this.phase === "done")
+                    this.dismiss();
+            }, this.config.autoDismissMs);
+        }
+    }
+    getInput() {
+        return this.editor.buffer;
+    }
+    requestRender() {
+        this.scheduleRender();
+    }
+    // ── Input handling ──────────────────────────────────────────
+    handleIntercept(payload) {
+        const consumed = { ...payload, consumed: true };
+        const { data } = payload;
+        switch (this.phase) {
+            case "done":
+                this.dismiss();
+                return consumed;
+            case "input":
+                this.handleInputKey(data);
+                return consumed;
+            case "active":
+                if (data === "\x03")
+                    this.bus.emit("agent:cancel-request", {});
+                else if (data === "\x1b" || this.isTrigger(data))
+                    this.dismiss();
+                else
+                    this.handlers.call(`${this.prefix}:input`, data);
+                return consumed;
+            default: // idle
+                if (this.isTrigger(data)) {
+                    this.open();
+                    return consumed;
+                }
+                return payload;
+        }
+    }
+    handleInputKey(data) {
+        // Check full data string against trigger sequences (may be multi-byte)
+        if (this.isTrigger(data)) {
+            this.dismiss();
+            return;
+        }
+        for (let i = 0; i < data.length; i++) {
+            const ch = data[i];
+            if (ch === "\x1b" && data[i + 1] == null) {
+                this.dismiss();
+                return;
+            }
+            if (ch.charCodeAt(0) === 0x03) {
+                this.dismiss();
+                return;
+            }
+        }
+        const actions = this.editor.feed(data);
+        for (const action of actions) {
+            switch (action.action) {
+                case "submit": {
+                    const query = this.editor.buffer.trim();
+                    if (!query) {
+                        this.dismiss();
+                        return;
+                    }
+                    this.phase = "active";
+                    this.editor.clear();
+                    this.handlers.call(`${this.prefix}:submit`, query);
+                    return;
+                }
+                case "cancel":
+                    this.dismiss();
+                    return;
+                case "changed":
+                case "tab":
+                case "shift+tab":
+                case "arrow-up":
+                case "arrow-down":
+                case "delete-empty":
+                    this.render();
+                    break;
+            }
+        }
+    }
+    // ── Geometry ───────────────────────────────────────────────
+    /** Compute box geometry from config + current terminal size. */
+    computeGeometry() {
+        const cols = process.stdout.columns || 80;
+        const rows = process.stdout.rows || 24;
+        const boxW = Math.min(this.resolveSize(this.config.width, cols - 4), this.config.maxWidth);
+        const boxH = Math.min(this.resolveSize(this.config.height, rows - 4), Math.max(this.config.minHeight + 2, rows - 4));
+        const boxTop = Math.floor((rows - boxH) / 2);
+        const boxLeft = Math.floor((cols - boxW) / 2);
+        return { cols, rows, boxW, boxH, boxTop, boxLeft, contentW: boxW - 4, contentH: boxH - 2 };
+    }
+    // ── Frame building ────────────────────────────────────────
+    buildFrame() {
+        const geo = this.computeGeometry();
+        // Call render-content handler
+        const renderCtx = {
+            width: geo.contentW,
+            height: geo.contentH,
+            phase: this.phase,
+            inputBuffer: this.editor.buffer,
+            inputCursor: this.editor.cursor,
+            scrollOffset: this.scrollOffset,
+            contentLines: this.contentLines,
+            partialLine: this.currentPartialLine,
+        };
+        const content = this.handlers.call(`${this.prefix}:render-content`, renderCtx);
+        // Get background
+        const bgLines = this.buffer?.getScreenLines(geo.rows) ?? null;
+        // Build frame context and delegate to render-frame handler
+        const frameCtx = {
+            geo,
+            content,
+            bgLines,
+            phase: this.phase,
+            title: this.title,
+            footer: this.footer,
+            border: this.border,
+        };
+        return this.handlers.call(`${this.prefix}:render-frame`, frameCtx);
+    }
+    // ── Rendering ─────────────────────────────────────────────
+    scheduleRender() {
+        if (this.renderTimer)
+            return;
+        this.renderTimer = setTimeout(() => {
+            this.renderTimer = null;
+            this.render();
+        }, 32);
+    }
+    render() {
+        if (this.phase === "idle")
+            return;
+        const { rows: frame, cursorSeq } = this.buildFrame();
+        // Differential write — only send rows that changed
+        const out = [SYNC_START];
+        let dirty = false;
+        for (let i = 0; i < frame.length; i++) {
+            if (frame[i] !== this.prevFrame[i]) {
+                out.push(`\x1b[${i + 1};1H`);
+                out.push(frame[i]);
+                dirty = true;
+            }
+        }
+        for (let i = frame.length; i < this.prevFrame.length; i++) {
+            out.push(`\x1b[${i + 1};1H\x1b[2K`);
+            dirty = true;
+        }
+        if (cursorSeq)
+            out.push(cursorSeq);
+        out.push(SYNC_END);
+        if (this.prevFrame.length === 0 || dirty) {
+            process.stdout.write(out.join(""));
+        }
+        this.prevFrame = frame;
+    }
+    // ── Screen helpers ────────────────────────────────────────
+    restoreScreen() {
+        if (this.usedAltScreen) {
+            // Leave alt screen — the terminal restores the saved main buffer.
+            process.stdout.write("\x1b[?1049l");
+        }
+        else {
+            // We were already on alt screen (vim, htop, etc.) so we didn't
+            // enter our own.  Restore by rewriting the screen content from
+            // the xterm buffer, which mirrors what the foreground program
+            // had rendered.
+            const raw = this.buffer?.serialize() ?? "";
+            const rows = process.stdout.rows || 24;
+            const lines = raw.split("\n");
+            const out = [SYNC_START];
+            for (let i = 0; i < rows; i++) {
+                out.push(`\x1b[${i + 1};1H\x1b[2K`);
+                if (i < lines.length)
+                    out.push(lines[i]);
+            }
+            out.push(SYNC_END);
+            process.stdout.write(out.join(""));
+        }
+    }
+    resolveSize(spec, available) {
+        if (typeof spec === "number")
+            return Math.min(spec, available);
+        if (typeof spec === "string" && spec.endsWith("%")) {
+            const pct = parseInt(spec, 10) / 100;
+            return Math.floor(available * pct);
+        }
+        return available;
+    }
+}

package/dist/utils/markdown.d.ts

@@ -15,6 +15,7 @@ export declare class MarkdownRenderer {
     private buffer;
     private contentWidth;
     private firstLine;
+    private lastLineBlank;
     private pendingLines;
     private width;
     private tableRows;

package/dist/utils/markdown.js

@@ -83,6 +83,7 @@ export class MarkdownRenderer {
     buffer = "";
     contentWidth;
     firstLine = true;
+    lastLineBlank = false;
     pendingLines = [];
     width;
     tableRows = [];
@@ -192,6 +193,9 @@ export class MarkdownRenderer {
         }
         // Render rows
         const hasHeader = sepIdx.includes(1) && dataRows.length > 1;
+        // Top border
+        const topBorder = colWidths.map((w) => "─".repeat(w)).join(`─┬─`);
+        this.writeLine(`${p.dim}┌─${topBorder}─┐${p.reset}`);
         for (let i = 0; i < dataRows.length; i++) {
             const row = dataRows[i];
             const isHeader = hasHeader && i === 0;
@@ -207,6 +211,9 @@ export class MarkdownRenderer {
                 this.writeLine(`${p.dim}├─${sep}─┤${p.reset}`);
             }
         }
+        // Bottom border
+        const bottomBorder = colWidths.map((w) => "─".repeat(w)).join(`─┴─`);
+        this.writeLine(`${p.dim}└─${bottomBorder}─┘${p.reset}`);
     }
     renderLine(line) {
         if (line.trim() === "")
@@ -232,6 +239,16 @@ export class MarkdownRenderer {
         const bq = line.match(/^>\s?(.*)/);
         if (bq)
             return `${p.muted}│${p.reset} ${p.dim}${p.italic}${this.renderInline(bq[1] || "")}${p.reset}`;
+        // Task list (checkbox items) — must come before generic unordered list
+        const task = line.match(/^(\s*)[*\-+]\s+\[([ xX])\]\s+(.*)/);
+        if (task) {
+            const indent = task[1] || "";
+            const checked = task[2] !== " ";
+            const box = checked
+                ? `${p.success}☑${p.reset}`
+                : `${p.dim}☐${p.reset}`;
+            return `${indent}  ${box} ${this.renderInline(task[3] || "")}`;
+        }
         // Unordered list
         const ul = line.match(/^(\s*)[*\-+]\s+(.*)/);
         if (ul) {
@@ -268,9 +285,14 @@ export class MarkdownRenderer {
      * The line is accumulated internally — call drainLines() to extract.
      */
     writeLine(text) {
-        if (this.firstLine && visibleLen(text) === 0)
+        const isBlank = visibleLen(text) === 0;
+        if (this.firstLine && isBlank)
+            return;
+        // Collapse consecutive blank lines to a single one
+        if (isBlank && this.lastLineBlank)
             return;
         this.firstLine = false;
+        this.lastLineBlank = isBlank;
         this.pendingLines.push(`  ${text}`);
     }
 }

package/dist/utils/output-writer.d.ts

@@ -5,12 +5,26 @@
  * process.stdout.write directly.  This enables testing (BufferWriter),
  * alternative frontends, and a single point of control for output.
  */
+/** Simple ref-counted counter. Increment/decrement never goes below zero. */
+export declare class RefCounter {
+    private count;
+    increment(): void;
+    decrement(): void;
+    reset(): void;
+    get active(): boolean;
+    get value(): number;
+}
 export interface OutputWriter {
     write(text: string): void;
     get columns(): number;
 }
 /** Default writer that forwards to process.stdout. */
 export declare class StdoutWriter implements OutputWriter {
+    /** When > 0, all writes are silently dropped. Ref-counted. */
+    private readonly _hold;
+    hold(): void;
+    release(): void;
+    get held(): boolean;
     write(text: string): void;
     get columns(): number;
 }