@vincemakes/kiso-tui-cells 0.16.8 → 0.17.0

package/dist/components.d.ts

@@ -283,6 +283,86 @@ export declare function exploreRows(parts: readonly {
 /** Does this tool's fold term count distinct targets rather than calls? */
 export declare function foldCountsObjects(name: string): boolean;
 export declare function foldTerms(reads: number, edits: number, others: readonly [string, number][]): string[];
+/**
+ * R3i — THE STRETCH LINE: the turn's one working row, in three phases.
+ *
+ * A STRETCH is the run of thinking and tool calls between two blocks of
+ * the model's prose. While it runs it is this line plus a bounded act
+ * window; when it closes it commits as this same line, frozen, with its
+ * key. The contract in one sentence: **the line you watch is the line
+ * you keep** — the settle changes the mark, the tense and the key, and
+ * nothing else.
+ *
+ *   thinking   ✧ thinking 4s
+ *   acting     ✶ reading 6 files · running 4 shell commands
+ *   settled    ✦ thought 9s · read 6 files · ran 4 shell commands · ctrl+r
+ *
+ * THE GIVE-WAY LADDER, in order, because at some width everything
+ * cannot fit:
+ *
+ *   1. the human's WORDS (the A9 chip on a quiet turn) — they are on
+ *      screen above, in the chip band;
+ *   2. the NOUNS compact, cheapest word first, and stop as soon as the
+ *      row fits — buying one cell must not spend every substitution;
+ *   3. the COUNTS cut, with the honest "…";
+ *   4. the TROUBLE CLAUSE cuts. The design first said it never gives
+ *      way, and that was unimplementable: a long clause overflows after
+ *      the counts have already cut to a bare "…", and invariant ①
+ *      throws on that row;
+ *   5. the KEY gives way NEVER. A fold with no key is the turn's work
+ *      behind a line with no way back to it, which is the one thing
+ *      this row must not be.
+ *
+ * `…` in this file means CUT HERE and nothing else — which is why the
+ * live phases carry no trailing ellipsis for in-flight, though the
+ * reference implementation uses one. The moving mark and the present
+ * tense already say it twice.
+ */
+/**
+ * R3i phase 5 — THE ANSWERED QUESTION'S BLOCK.
+ *
+ * A settled `ask_user` used to render `  ask_user  (3 lines, 41.2s)` —
+ * an empty target and the answers discarded, though the tool_result
+ * already carried them. The owner asked for this block by pointing at
+ * one: after they answer, there is a display for that too.
+ *
+ *   asked 2 questions (answered, 41.2s)
+ *   │ deploy target → staging
+ *   │ retry policy → give up after 3 attempts (typed)
+ *
+ * The question is dim, the join is dim, the ANSWER is at body strength
+ * — strip every escape and every fact is still there (law 1.2: colour
+ * is emphasis, never information). A typed answer says `(typed)`,
+ * because where an answer came from is a fact about it.
+ *
+ * It is WORDS, not work (law 1.7): it never folds into a stretch line,
+ * because the one thing a summary must not do is speak for the human.
+ *
+ * A result that is not the ask's own JSON yields NOTHING. This renderer
+ * reads a payload it did not write, and a guess about what it means
+ * would be a row the product cannot stand behind.
+ */
+export declare function askedBlock(resultText: string, seconds: number, W: number): string[];
+export interface StretchTerms {
+    /** the segment's OWN measured thinking seconds; 0 drops the term */
+    readonly thoughtSeconds: number;
+    /** the segment's calls as [tool name, count], in first-call order.
+     *  Object-counting tools are deduped by target upstream (R3h). */
+    readonly calls: readonly (readonly [string, number])[];
+    /** the targets acted on — read only when the stretch made exactly
+     *  ONE call, where naming the target says everything the two rows it
+     *  replaces said (see the one-call rule below). */
+    readonly targets: readonly string[];
+    /** the trouble the stretch met: [kind, count, what it was]. */
+    readonly trouble: readonly (readonly ["failed" | "denied" | "interrupted", number, string])[];
+    /** A9 — the human's words, on a QUIET turn's fold only. */
+    readonly words?: string;
+    /** the live mark; the caller passes the spinner's current frame. */
+    readonly mark?: string;
+}
+export declare function stretchLine(t: StretchTerms & {
+    readonly phase: "thinking" | "acting" | "settled";
+}, W: number): string[];
 export declare function turnFold(t: {
     words: string;
     thoughtSeconds: number;

package/dist/components.js

@@ -593,6 +593,18 @@ class ToolExecution {
             return out;
         }
         if (c.state === "done") {
+            // R3i phase 5: an answered (or declined) ask_user renders its
+            // OWN block — the questions and what the human said. The row
+            // it replaces was `  ask_user  (3 lines, 41.2s)`: an empty
+            // target and the answers thrown away, though the result
+            // already carried them. `askedBlock` returns [] for anything
+            // that is not the ask's own JSON, so a payload this renderer
+            // did not write can never be guessed at.
+            if (c.name === "ask_user" && c.reason === null && !c.isError) {
+                const asked = askedBlock(c.resultText, c.startedAt !== null && c.doneAt !== null ? (c.doneAt - c.startedAt) / 1000 : 0, W);
+                if (asked.length > 0)
+                    return asked;
+            }
             // W19: the pinned deny — the claimed shape verbatim: the FULL
             // call name (the denial names the call), the target, the reason
             // in the W4 parentheses idiom, no timing (the call never ran).
@@ -1013,14 +1025,29 @@ function countTerm(n, singular, plural) {
  * commands". A tool with no entry says `3 × <verb>`, which counts calls
  * without inventing a noun for them.
  */
-const FOLD_TERM = {
-    read_file: ["read", "file", "files"],
-    edit_file: ["edited", "file", "files"],
-    write_file: ["wrote", "file", "files"],
-    list_dir: ["listed", "directory", "directories"],
-    search_text: ["ran", "search", "searches"],
-    shell: ["ran", "shell command", "shell commands"],
+/**
+ * R3i — ONE TERM TABLE, TWO TENSES: [past, progressive, singular, plural].
+ *
+ * The stretch line is the same row at every instant of a turn: while
+ * the work runs it says what it is DOING, and at the settle it says
+ * what it DID. That sentence is only true if both tenses come from one
+ * table. The v9 review found the alternative already happening on a
+ * hand-written prototype — `searching 1 pattern` live against `ran 1
+ * search` settled, the NOUN swapping at the settle, and `running 4
+ * shells`, which is verbatim the R3g defect the previous round removed.
+ *
+ * FOLD_TERM below is derived from this, so the settled vocabulary
+ * cannot drift from the live one by construction.
+ */
+const TERM = {
+    read_file: ["read", "reading", "file", "files"],
+    edit_file: ["edited", "editing", "file", "files"],
+    write_file: ["wrote", "writing", "file", "files"],
+    list_dir: ["listed", "listing", "directory", "directories"],
+    search_text: ["ran", "running", "search", "searches"],
+    shell: ["ran", "running", "shell command", "shell commands"],
 };
+const FOLD_TERM = Object.fromEntries(Object.entries(TERM).map(([name, [past, , singular, plural]]) => [name, [past, singular, plural]]));
 /**
  * R3h (fable, 2026-08-29) — WHICH TERMS COUNT OBJECTS.
  *
@@ -1058,6 +1085,167 @@ export function foldTerms(reads, edits, others) {
     }
     return parts;
 }
+/**
+ * R3i — THE STRETCH LINE: the turn's one working row, in three phases.
+ *
+ * A STRETCH is the run of thinking and tool calls between two blocks of
+ * the model's prose. While it runs it is this line plus a bounded act
+ * window; when it closes it commits as this same line, frozen, with its
+ * key. The contract in one sentence: **the line you watch is the line
+ * you keep** — the settle changes the mark, the tense and the key, and
+ * nothing else.
+ *
+ *   thinking   ✧ thinking 4s
+ *   acting     ✶ reading 6 files · running 4 shell commands
+ *   settled    ✦ thought 9s · read 6 files · ran 4 shell commands · ctrl+r
+ *
+ * THE GIVE-WAY LADDER, in order, because at some width everything
+ * cannot fit:
+ *
+ *   1. the human's WORDS (the A9 chip on a quiet turn) — they are on
+ *      screen above, in the chip band;
+ *   2. the NOUNS compact, cheapest word first, and stop as soon as the
+ *      row fits — buying one cell must not spend every substitution;
+ *   3. the COUNTS cut, with the honest "…";
+ *   4. the TROUBLE CLAUSE cuts. The design first said it never gives
+ *      way, and that was unimplementable: a long clause overflows after
+ *      the counts have already cut to a bare "…", and invariant ①
+ *      throws on that row;
+ *   5. the KEY gives way NEVER. A fold with no key is the turn's work
+ *      behind a line with no way back to it, which is the one thing
+ *      this row must not be.
+ *
+ * `…` in this file means CUT HERE and nothing else — which is why the
+ * live phases carry no trailing ellipsis for in-flight, though the
+ * reference implementation uses one. The moving mark and the present
+ * tense already say it twice.
+ */
+/**
+ * R3i phase 5 — THE ANSWERED QUESTION'S BLOCK.
+ *
+ * A settled `ask_user` used to render `  ask_user  (3 lines, 41.2s)` —
+ * an empty target and the answers discarded, though the tool_result
+ * already carried them. The owner asked for this block by pointing at
+ * one: after they answer, there is a display for that too.
+ *
+ *   asked 2 questions (answered, 41.2s)
+ *   │ deploy target → staging
+ *   │ retry policy → give up after 3 attempts (typed)
+ *
+ * The question is dim, the join is dim, the ANSWER is at body strength
+ * — strip every escape and every fact is still there (law 1.2: colour
+ * is emphasis, never information). A typed answer says `(typed)`,
+ * because where an answer came from is a fact about it.
+ *
+ * It is WORDS, not work (law 1.7): it never folds into a stretch line,
+ * because the one thing a summary must not do is speak for the human.
+ *
+ * A result that is not the ask's own JSON yields NOTHING. This renderer
+ * reads a payload it did not write, and a guess about what it means
+ * would be a row the product cannot stand behind.
+ */
+export function askedBlock(resultText, seconds, W) {
+    let parsed;
+    try {
+        parsed = JSON.parse(resultText);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return [];
+    const asked = parsed;
+    const p = palette();
+    const head = (n, outcome) => cutLine(`  ${p.bold}asked${p.reset} ${n} ${n === 1 ? "question" : "questions"} ${p.dim}(${outcome}, ${seconds.toFixed(1)}s)${p.reset}`, W);
+    const row = (body) => cutLine(`  ${p.dim}│${p.reset} ${body}`, W);
+    if (Array.isArray(asked.declined) && asked.declined.length > 0) {
+        // the honest decline record: WHAT went unanswered, and what the
+        // choices had been — the panel already computes both.
+        return [head(asked.declined.length, "declined"), ...asked.declined.map((q) => row(`${p.dim}${escapeTerminal(q)}${p.reset}`))];
+    }
+    if (!Array.isArray(asked.answers) || asked.answers.length === 0)
+        return [];
+    return [
+        head(asked.answers.length, "answered"),
+        ...asked.answers.map((a) => {
+            const q = escapeTerminal(String(a.q ?? ""));
+            const typed = typeof a.custom === "string" && a.custom !== "";
+            const value = typed ? a.custom : Array.isArray(a.choices) ? a.choices.join(", ") : String(a.choice ?? "");
+            return row(`${p.dim}${q} →${p.reset} ${escapeTerminal(value)}${typed ? `${p.dim} (typed)${p.reset}` : ""}`);
+        }),
+    ];
+}
+const STRETCH_COMPACT = [
+    ["directories", "dirs"],
+    ["directory", "dir"],
+    ["shell commands", "commands"],
+    ["shell command", "command"],
+];
+/** R3i — a stretch of exactly ONE call names its TARGET instead of its
+ *  count. `thought 2s · read 1 file` replaces two rows — the thinking
+ *  and the call — with a row that says less than either of them did,
+ *  and "thinking plus one call" is the commonest shape a narrating
+ *  model makes. This is the answer to the defect R3d killed R3b's
+ *  per-segment folds over; the "absorbs at least two rows" rule alone
+ *  does not answer it. */
+function stretchTerms(t, live) {
+    const total = t.calls.reduce((n, [, c]) => n + c, 0);
+    if (total === 1 && t.targets.length === 1) {
+        const [name] = t.calls[0];
+        const e = TERM[name];
+        return [`${e === undefined ? name : e[live ? 1 : 0]} ${t.targets[0]}`];
+    }
+    return t.calls
+        .filter(([, n]) => n > 0)
+        .map(([name, n]) => {
+        const e = TERM[name];
+        if (e === undefined)
+            return `${n} × ${displayVerb(name)}`;
+        return `${e[live ? 1 : 0]} ${n} ${n === 1 ? e[2] : e[3]}`;
+    });
+}
+/** R3i — the trouble clause: which call, and what happened, in WORDS.
+ *  Law 1.3 says an outcome is stated in words, "the only form that
+ *  survives a pipe"; the colour on this clause is emphasis over those
+ *  words, never the fact itself. */
+function troubleClause(t) {
+    return t.trouble
+        .filter(([, n]) => n > 0)
+        .map(([kind, n, what]) => (what === "" || kind === "interrupted" ? `${n} ${kind}` : `${n} ${kind}: ${what}`))
+        .join(" · ");
+}
+export function stretchLine(t, W) {
+    const p = palette();
+    const live = t.phase !== "settled";
+    const mark = t.phase === "settled" ? `${p.bold}✦${p.reset}` : `${p.dim}${t.mark ?? "✧"}${p.reset}`;
+    const key = t.phase === "settled" ? " · ctrl+r" : "";
+    const lead = t.phase === "thinking" ? [`thinking ${t.thoughtSeconds}s`] : t.phase === "settled" && t.thoughtSeconds > 0 ? [`thought ${t.thoughtSeconds}s`] : [];
+    const clauseText = troubleClause(t);
+    let meta = [...lead, ...(t.phase === "thinking" ? [] : stretchTerms(t, live))].join(" · ");
+    let clause = clauseText === "" ? "" : ` · ${clauseText}`;
+    let words = t.words === undefined || t.words === "" ? "" : ` ${escapeTerminal(t.words).replace(/\s+/g, " ")} `;
+    const width = () => 2 + (words === "" ? 0 : visibleWidth(words) + 3) + visibleWidth(meta) + visibleWidth(clause) + visibleWidth(key);
+    const trim = (text, room, floor) => (room >= floor ? `${widthCut(text, room)}…` : "");
+    if (words !== "" && width() > W)
+        words = trim(words, W - (width() - visibleWidth(words)) - 1, 4);
+    if (width() > W) {
+        for (const [long, short] of STRETCH_COMPACT) {
+            meta = meta.replaceAll(long, short);
+            if (width() <= W)
+                break;
+        }
+    }
+    if (width() > W) {
+        const room = W - (width() - visibleWidth(meta)) - 1;
+        meta = room >= 2 ? `${widthCut(meta, room)}…` : "…";
+    }
+    if (width() > W && clause !== "")
+        clause = trim(clause, W - (width() - visibleWidth(clause)) - 1, 5);
+    // the degenerate floor: below the width where even the mark and one
+    // character fit, the row is a hard cut of what it would have said.
+    const row = `${mark}${words === "" ? "" : ` ${p.rv}${words}${p.rvEnd}${p.dim} ·${p.reset}`} ${meta}${clause === "" ? "" : `${p.red}${clause}${p.reset}`}${key === "" ? "" : `${p.dim}${key}${p.reset}`}`;
+    return [visibleWidth(row) <= W ? row : cutLine(row, W)];
+}
 export function turnFold(t, W) {
     const p = palette();
     // R3b (owner, 2026-08-27): ZERO TERMS ARE DROPPED. W14 always wrote

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui-cells",
-	"version": "0.16.8",
+	"version": "0.17.0",
 	"description": "kiso tui-cells — the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
 	"type": "module",
 	"license": "MIT",