@cruxy/cli 0.6.0 → 0.8.0

package/dist/plan/submit-plan.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/**
+ * The `submit_plan` tool (C.31): the agent's only way to propose a plan. It is a
+ * normal tool on the same loop seam as everything else — no hidden control flow.
+ * During the propose phase this is the *only* non-read-only tool registered, so
+ * the agent structurally cannot act before approval.
+ *
+ * Validation is fail-loud: a malformed or empty plan returns `{ok:false}` so the
+ * model sees the error and retries, exactly like any other tool.
+ */
+const stepSchema = z.object({
+    title: z.string().min(1).describe("One-line imperative title for the step."),
+    rationale: z
+        .string()
+        .min(1)
+        .describe("Why this step exists / what it accomplishes."),
+    kind: z
+        .enum(["read", "mutate", "destructive"])
+        .describe("Risk estimate: read (no side effects), mutate (reversible file writes), " +
+        "destructive (shell, deletes, PR-open). Advisory — the approval gate re-checks each action."),
+});
+const parameters = z.object({
+    steps: z
+        .array(stepSchema)
+        .min(1)
+        .describe("Ordered steps that fully accomplish the task."),
+});
+/** Build a `submit_plan` tool bound to `holder`, which captures the last plan. */
+export function makeSubmitPlanTool(holder) {
+    return {
+        name: "submit_plan",
+        description: "Propose an ordered, step-by-step plan for the user to approve before you act. " +
+            "Call this first (and only this) in plan mode; do not take any other action until the plan is approved.",
+        parameters,
+        async execute(input) {
+            // zod already guarantees ≥1 step with non-empty fields; this is the
+            // fail-loud belt-and-suspenders for an empty array slipping through.
+            if (input.steps.length === 0) {
+                return { ok: false, error: "a plan must have at least one step" };
+            }
+            const steps = input.steps.map((s, i) => ({
+                id: String(i + 1),
+                title: s.title.trim(),
+                rationale: s.rationale.trim(),
+                kind: s.kind,
+                status: "pending",
+            }));
+            const plan = { steps };
+            holder.plan = plan;
+            return {
+                ok: true,
+                output: `Plan received (${steps.length} step${steps.length === 1 ? "" : "s"}) and shown to the user for approval. ` +
+                    "Do not take any further action now — end your turn.",
+            };
+        },
+    };
+}

package/dist/plan/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+/**
+ * The agent's risk *estimate* for a step, used only to render intent and shape
+ * the approval copy. It is NOT authoritative: the real U.3 gate re-classifies
+ * every concrete action at execution time (a step the agent calls "mutate" whose
+ * action turns out destructive still confirms).
+ */
+export type PlanStepKind = "read" | "mutate" | "destructive";
+/** Live execution status of a step. */
+export type PlanStepStatus = "pending" | "running" | "done" | "failed";
+export interface PlanStep {
+    /** Stable 1-based id assigned on submit (e.g. "1"). */
+    readonly id: string;
+    /** One-line imperative title. */
+    readonly title: string;
+    /** Why this step exists / what it accomplishes. */
+    readonly rationale: string;
+    /** The agent's risk estimate (advisory; see {@link PlanStepKind}). */
+    readonly kind: PlanStepKind;
+    /** Mutated in place as execution progresses. */
+    status: PlanStepStatus;
+}
+export interface Plan {
+    readonly steps: PlanStep[];
+}
+/**
+ * The user's decision at the plan-approval prompt.
+ * - `approve` — execute; every action still hits the U.3 gate.
+ * - `approve-grant` — execute AND auto-allow the safe (read/mutate, grantable)
+ *   steps for this run; destructive/ungrantable actions still confirm.
+ * - `revise` — send `feedback` back to the agent for a revised plan.
+ * - `abort` — cancel; nothing executes (also the default-deny for EOF/Ctrl-C).
+ */
+export type PlanDecision = {
+    readonly kind: "approve";
+} | {
+    readonly kind: "approve-grant";
+} | {
+    readonly kind: "revise";
+    readonly feedback: string;
+} | {
+    readonly kind: "abort";
+};
+/** Outcome of executing an approved plan. */
+export interface PlanExecutionResult {
+    /** True if every step reached `done`. */
+    readonly completed: boolean;
+    /** True if a step failed and the user chose to abort the run. */
+    readonly halted: boolean;
+    /** The id of the step that failed, when halted. */
+    readonly failedStepId?: string;
+}
+/** A mutable holder the `submit_plan` tool writes the captured plan into. */
+export interface PlanHolder {
+    plan: Plan | null;
+}

package/dist/plan/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+export {};

package/dist/render/capabilities.d.ts

@@ -0,0 +1,12 @@
+import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -0,0 +1,27 @@
+import { shouldUseColor } from "../errors/index.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export function detectCapabilities(stream = process.stdout, env = process.env) {
+    const tty = Boolean(stream.isTTY);
+    const dumb = env.TERM === "dumb";
+    const cursor = tty && !dumb;
+    return {
+        tty,
+        color: shouldUseColor(stream, env) && !dumb,
+        cursor,
+        // Same set-and-non-empty convention as NO_COLOR: any value disables.
+        spinner: cursor &&
+            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        width: typeof stream.columns === "number" && stream.columns > 0
+            ? stream.columns
+            : 80,
+    };
+}

package/dist/render/diff.d.ts

@@ -0,0 +1,19 @@
+import pc from "picocolors";
+import type { ActionPreview } from "../tools/types.js";
+/**
+ * The one diff/action-preview renderer (U.2). The approval prompt, PR preview,
+ * and the streaming render path all draw diffs through here — there is no
+ * second implementation to drift. Pure data → string; color is gated on a
+ * picocolors instance, so NO_COLOR/non-TTY callers get symbol-only `+`/`-`
+ * lines from the exact same code path.
+ */
+/** The picocolors instance type (colorless or not), from createColors. */
+export type Colors = ReturnType<typeof pc.createColors>;
+/** Cap on rendered preview lines before collapsing the rest. */
+export declare const PREVIEW_MAX_LINES = 40;
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export declare function renderActionPreview(preview: ActionPreview | undefined, c: Colors): string;

package/dist/render/diff.js

@@ -0,0 +1,80 @@
+/** Cap on rendered preview lines before collapsing the rest. */
+export const PREVIEW_MAX_LINES = 40;
+function diffLines(oldStr, newStr, c) {
+    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
+    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
+    return [...removed, ...added];
+}
+function renderPatchFiles(files, c) {
+    const out = [];
+    for (const file of files) {
+        if (file.op === "delete") {
+            out.push(c.red(`delete ${file.path}`));
+        }
+        else if (file.op === "create") {
+            out.push(c.green(`create ${file.path}`));
+            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
+            if (file.omittedLines > 0)
+                out.push(c.dim(`  ...${file.omittedLines} more lines`));
+        }
+        else {
+            out.push(c.yellow(`update ${file.path}`));
+            for (const hunk of file.hunks)
+                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
+        }
+    }
+    return out;
+}
+/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
+function renderPrPreview(preview, c) {
+    const out = [];
+    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
+    out.push("");
+    out.push(c.bold("commit"));
+    out.push(`  ${preview.commitSubject}`);
+    for (const line of bodyLines(preview.commitBody))
+        out.push(c.dim(`  ${line}`));
+    out.push("");
+    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
+    for (const line of bodyLines(preview.prBody))
+        out.push(c.dim(`  ${line}`));
+    return out;
+}
+/** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
+function bodyLines(body) {
+    const lines = body.replace(/\s+$/, "").split("\n");
+    return lines.length === 1 && lines[0] === "" ? [] : lines;
+}
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export function renderActionPreview(preview, c) {
+    if (!preview)
+        return "";
+    let lines;
+    if (preview.type === "edit") {
+        lines = diffLines(preview.oldStr, preview.newStr, c);
+    }
+    else if (preview.type === "patch") {
+        lines = renderPatchFiles(preview.files, c);
+    }
+    else if (preview.type === "pr") {
+        lines = renderPrPreview(preview, c);
+    }
+    else {
+        const header = preview.exists
+            ? c.yellow("OVERWRITE existing")
+            : c.green("create");
+        const body = preview.lines.map((l) => `  ${l}`);
+        if (preview.omittedLines > 0)
+            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
+        lines = [header, ...body];
+    }
+    if (lines.length > PREVIEW_MAX_LINES) {
+        const hidden = lines.length - PREVIEW_MAX_LINES;
+        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
+    }
+    return lines.map((l) => `  ${l}`).join("\n");
+}

package/dist/render/highlight.d.ts

@@ -0,0 +1,47 @@
+import type { Colors } from "./diff.js";
+/**
+ * Best-effort, bounded syntax highlighting for fenced code blocks in streamed
+ * markdown (U.2). Priorities, in order: never crash the stream, never hold the
+ * stream back, then look nice.
+ *
+ * - Prose passes through immediately, byte for byte. The only hold-back is a
+ *   line that is still a plausible fence opener (a leading backtick run), held
+ *   until disambiguated — bounded by one short line, never a block.
+ * - Inside a fence, lines are highlighted incrementally: each line is emitted
+ *   the moment its newline arrives, so latency is one line, and committed
+ *   output is never repainted.
+ * - Unknown language → plain text. A tokenizer throw → that line plain. The
+ *   tokenizer is hand-rolled (no highlighter dependency, in the same spirit as
+ *   the hand-rolled HTTP client) and colors only what it is sure about:
+ *   comments, strings, keywords, numbers.
+ */
+/** Cross-line tokenizer state (block comments / multi-line strings). */
+export interface HighlightCarry {
+    /** Inside a block comment (`/* … *``/`). */
+    blockComment: boolean;
+    /** Inside a multi-line string; the delimiter that will close it. */
+    stringDelim: string | null;
+}
+/** One line of code → styled line + the carry for the next line. */
+export type LineHighlighter = (line: string, lang: string | null, carry: HighlightCarry) => {
+    text: string;
+    carry: HighlightCarry;
+};
+/** Incremental highlighter for one streamed text segment. */
+export interface StreamHighlighter {
+    /** Feed a delta; returns the styled text that is safe to emit now. */
+    push(delta: string): string;
+    /** Return whatever is still held (segment end); resets to prose state. */
+    flush(): string;
+}
+/**
+ * Create the per-segment streaming highlighter. `highlightLine` is injectable
+ * for tests (e.g. to prove a throwing tokenizer degrades to plain text).
+ */
+export declare function createStreamHighlighter(c: Colors, highlightLine?: LineHighlighter): StreamHighlighter;
+/**
+ * Build the default per-line tokenizer over `c`. A plain left-to-right scan:
+ * comments dim, strings green, keywords magenta, numbers yellow, everything
+ * else untouched. Unknown language → identity.
+ */
+export declare function defaultLineHighlighter(c: Colors): LineHighlighter;

package/dist/render/highlight.js

@@ -0,0 +1,265 @@
+const FRESH_CARRY = { blockComment: false, stringDelim: null };
+/** A fence opener: ``` or longer, optional language word. */
+const FENCE_OPEN = /^(`{3,})([\w+#.-]*)\s*$/;
+/** A line that could still grow into a fence opener. */
+const FENCE_PLAUSIBLE = /^(?:`{1,2}|`{3,}[\w+#.-]*\s*)$/;
+/**
+ * Create the per-segment streaming highlighter. `highlightLine` is injectable
+ * for tests (e.g. to prove a throwing tokenizer degrades to plain text).
+ */
+export function createStreamHighlighter(c, highlightLine = defaultLineHighlighter(c)) {
+    let mode = "prose";
+    let atLineStart = true;
+    let lineBuf = "";
+    let lang = null;
+    let carry = FRESH_CARRY;
+    /** Highlight one completed code line; any tokenizer throw → plain text. */
+    const styleCodeLine = (line) => {
+        try {
+            const res = highlightLine(line, lang, carry);
+            carry = res.carry;
+            return res.text;
+        }
+        catch {
+            carry = FRESH_CARRY; // state is suspect after a throw; start clean
+            return line;
+        }
+    };
+    const push = (delta) => {
+        let out = "";
+        for (const ch of delta) {
+            if (mode === "prose") {
+                if (atLineStart && ch === "`") {
+                    mode = "maybe-fence";
+                    lineBuf = ch;
+                }
+                else {
+                    out += ch;
+                    atLineStart = ch === "\n";
+                }
+            }
+            else if (mode === "maybe-fence") {
+                if (ch === "\n") {
+                    const m = FENCE_OPEN.exec(lineBuf);
+                    if (m) {
+                        lang = m[2] ? m[2].toLowerCase() : null;
+                        carry = FRESH_CARRY;
+                        mode = "code";
+                        out += c.dim(lineBuf) + "\n";
+                    }
+                    else {
+                        mode = "prose";
+                        out += lineBuf + "\n";
+                    }
+                    lineBuf = "";
+                    atLineStart = true;
+                }
+                else {
+                    lineBuf += ch;
+                    if (!FENCE_PLAUSIBLE.test(lineBuf)) {
+                        // Can no longer become a fence (e.g. inline `code`) — release it.
+                        mode = "prose";
+                        out += lineBuf;
+                        lineBuf = "";
+                        atLineStart = false;
+                    }
+                }
+            }
+            else {
+                // code
+                if (ch === "\n") {
+                    if (/^`{3,}\s*$/.test(lineBuf)) {
+                        mode = "prose";
+                        out += c.dim(lineBuf) + "\n";
+                    }
+                    else {
+                        out += styleCodeLine(lineBuf) + "\n";
+                    }
+                    lineBuf = "";
+                    atLineStart = true;
+                }
+                else {
+                    lineBuf += ch;
+                }
+            }
+        }
+        return out;
+    };
+    const flush = () => {
+        // Segment ended mid-line: release the held text as-is (highlighted when we
+        // know it's code — styled *before* the language resets) and start the next
+        // segment back in prose state.
+        const out = lineBuf === "" ? "" : mode === "code" ? styleCodeLine(lineBuf) : lineBuf;
+        mode = "prose";
+        lineBuf = "";
+        atLineStart = true;
+        lang = null;
+        carry = FRESH_CARRY;
+        return out;
+    };
+    return { push, flush };
+}
+const JS_KEYWORDS = "abstract as async await break case catch class const continue debugger default delete do else enum export extends false finally for from function get if implements import in instanceof interface let new null of private protected public readonly return satisfies set static super switch this throw true try type typeof undefined var void while with yield";
+const PY_KEYWORDS = "and as assert async await break class continue def del elif else except False finally for from global if import in is lambda None nonlocal not or pass raise return True try while with yield match case self";
+const SH_KEYWORDS = "if then else elif fi for while until do done case esac function in select time coproc break continue return exit export local readonly declare set unset shift trap source alias cd echo printf read test";
+const GO_KEYWORDS = "break case chan const continue default defer else fallthrough for func go goto if import interface map nil package range return select struct switch true false type var";
+const RUST_KEYWORDS = "as async await break const continue crate dyn else enum extern false fn for if impl in let loop match mod move mut pub ref return self Self static struct super trait true type unsafe use where while";
+const words = (list) => new Set(list.split(" "));
+const JS_DEF = {
+    keywords: words(JS_KEYWORDS),
+    lineComment: "//",
+    blockComment: ["/*", "*/"],
+    quotes: ['"', "'", "`"],
+    multiline: ["`"],
+};
+const LANGS = {
+    js: JS_DEF,
+    jsx: JS_DEF,
+    ts: JS_DEF,
+    tsx: JS_DEF,
+    javascript: JS_DEF,
+    typescript: JS_DEF,
+    json: {
+        keywords: words("true false null"),
+        quotes: ['"'],
+        multiline: [],
+    },
+    py: {
+        keywords: words(PY_KEYWORDS),
+        lineComment: "#",
+        quotes: ['"', "'", '"""', "'''"],
+        multiline: ['"""', "'''"],
+    },
+    sh: {
+        keywords: words(SH_KEYWORDS),
+        lineComment: "#",
+        quotes: ['"', "'"],
+        multiline: [],
+    },
+    go: {
+        keywords: words(GO_KEYWORDS),
+        lineComment: "//",
+        blockComment: ["/*", "*/"],
+        quotes: ['"', "'", "`"],
+        multiline: ["`"],
+    },
+    rust: {
+        keywords: words(RUST_KEYWORDS),
+        lineComment: "//",
+        blockComment: ["/*", "*/"],
+        quotes: ['"'],
+        multiline: [],
+    },
+};
+// Aliases.
+LANGS.python = LANGS.py;
+LANGS.bash = LANGS.sh;
+LANGS.shell = LANGS.sh;
+LANGS.zsh = LANGS.sh;
+LANGS.golang = LANGS.go;
+LANGS.rs = LANGS.rust;
+/** Word characters for keyword/identifier scanning. */
+const WORD = /[A-Za-z0-9_$]/;
+/**
+ * Build the default per-line tokenizer over `c`. A plain left-to-right scan:
+ * comments dim, strings green, keywords magenta, numbers yellow, everything
+ * else untouched. Unknown language → identity.
+ */
+export function defaultLineHighlighter(c) {
+    return (line, lang, carry) => {
+        const def = lang ? LANGS[lang] : undefined;
+        if (!def)
+            return { text: line, carry };
+        // Longest quote first so `"""` wins over `"` in python.
+        const quotes = [...def.quotes].sort((a, b) => b.length - a.length);
+        let out = "";
+        let i = 0;
+        let next = { ...carry };
+        // Resume a multi-line construct from the previous line.
+        if (next.blockComment && def.blockComment) {
+            const close = line.indexOf(def.blockComment[1]);
+            if (close === -1)
+                return { text: c.dim(line), carry: next };
+            const end = close + def.blockComment[1].length;
+            out += c.dim(line.slice(0, end));
+            i = end;
+            next.blockComment = false;
+        }
+        else if (next.stringDelim) {
+            const close = findStringEnd(line, 0, next.stringDelim);
+            if (close === -1)
+                return { text: c.green(line), carry: next };
+            out += c.green(line.slice(0, close));
+            i = close;
+            next.stringDelim = null;
+        }
+        while (i < line.length) {
+            const rest = line.slice(i);
+            if (def.lineComment && rest.startsWith(def.lineComment)) {
+                out += c.dim(rest);
+                i = line.length;
+                break;
+            }
+            if (def.blockComment && rest.startsWith(def.blockComment[0])) {
+                const close = line.indexOf(def.blockComment[1], i + def.blockComment[0].length);
+                if (close === -1) {
+                    out += c.dim(rest);
+                    next = { ...next, blockComment: true };
+                    i = line.length;
+                    break;
+                }
+                const end = close + def.blockComment[1].length;
+                out += c.dim(line.slice(i, end));
+                i = end;
+                continue;
+            }
+            const quote = quotes.find((q) => rest.startsWith(q));
+            if (quote) {
+                const close = findStringEnd(line, i + quote.length, quote);
+                if (close === -1) {
+                    out += c.green(rest);
+                    if (def.multiline.includes(quote))
+                        next = { ...next, stringDelim: quote };
+                    i = line.length;
+                    break;
+                }
+                out += c.green(line.slice(i, close));
+                i = close;
+                continue;
+            }
+            const ch = line[i];
+            if (WORD.test(ch)) {
+                let j = i + 1;
+                while (j < line.length && WORD.test(line[j]))
+                    j++;
+                const word = line.slice(i, j);
+                if (def.keywords.has(word))
+                    out += c.magenta(word);
+                else if (/^\d/.test(word))
+                    out += c.yellow(word);
+                else
+                    out += word;
+                i = j;
+                continue;
+            }
+            out += ch;
+            i++;
+        }
+        return { text: out, carry: next };
+    };
+}
+/**
+ * Index just past the closing `delim` starting the scan at `from`, honoring
+ * backslash escapes; -1 when the string does not close on this line.
+ */
+function findStringEnd(line, from, delim) {
+    for (let i = from; i < line.length; i++) {
+        if (line[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (line.startsWith(delim, i))
+            return i + delim.length;
+    }
+    return -1;
+}

package/dist/render/index.d.ts

@@ -0,0 +1,14 @@
+import type { RenderStream, StreamRenderer } from "./types.js";
+export type { RenderCapabilities, RenderStream, StreamRenderer, } from "./types.js";
+export { detectCapabilities } from "./capabilities.js";
+export { renderActionPreview, PREVIEW_MAX_LINES, type Colors } from "./diff.js";
+export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
+export { PlainRenderer } from "./plain-renderer.js";
+export { TtyRenderer } from "./tty-renderer.js";
+/**
+ * Build the renderer for the detected environment: the managed-live-region
+ * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
+ * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
+ * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ */
+export declare function createRenderer(out?: RenderStream, err?: RenderStream, env?: NodeJS.ProcessEnv): StreamRenderer;

package/dist/render/index.js

@@ -0,0 +1,20 @@
+import { detectCapabilities } from "./capabilities.js";
+import { PlainRenderer } from "./plain-renderer.js";
+import { TtyRenderer } from "./tty-renderer.js";
+export { detectCapabilities } from "./capabilities.js";
+export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
+export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
+export { PlainRenderer } from "./plain-renderer.js";
+export { TtyRenderer } from "./tty-renderer.js";
+/**
+ * Build the renderer for the detected environment: the managed-live-region
+ * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
+ * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
+ * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ */
+export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
+    const caps = detectCapabilities(out, env);
+    return caps.cursor
+        ? new TtyRenderer(caps, out)
+        : new PlainRenderer(caps, out, err);
+}

package/dist/render/plain-renderer.d.ts

@@ -0,0 +1,32 @@
+import type { ActionPreview } from "../tools/types.js";
+import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.js";
+/**
+ * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
+ * cursor-control sequences ever, and no color unless the capabilities say so
+ * (FORCE_COLOR); with color off, not a single ANSI byte leaves this class.
+ *
+ * Assistant text goes to `out` verbatim (beyond the per-turn leading-newline
+ * trim) so piped stdout stays pure model output; chrome (`note`) goes to `err`,
+ * matching the logger's stdout/stderr split. Transient `status` has no meaning
+ * in an append-only medium and is dropped — the loop reports anything durable
+ * via `note`.
+ */
+export declare class PlainRenderer implements StreamRenderer {
+    readonly caps: RenderCapabilities;
+    private readonly out;
+    private readonly err;
+    private readonly colors;
+    /** Per-turn leading-newline trim; also tells endSegment whether to newline. */
+    private print;
+    private wroteInSegment;
+    constructor(caps: RenderCapabilities, out: RenderStream, err: RenderStream);
+    private newPrinter;
+    beginTurn(): void;
+    write(delta: string): void;
+    endSegment(): void;
+    note(text: string): void;
+    preview(preview: ActionPreview): void;
+    status(): void;
+    endTurn(): void;
+    close(): void;
+}