@vincemakes/kiso-code 0.8.0 → 0.9.0

package/dist/chat.d.ts

@@ -45,6 +45,10 @@ export interface UsageDelta {
      *  recovers on the next known event). */
     readonly total: number | null;
     readonly missed: number | null;
+    /** TUI2-R1 (E): the CANONICAL cost of this request — null when the
+     *  pricing table has no rate for the route (the R5b-④c absent stamp).
+     *  Null is carried, never zeroed: a missing rate is not a free call. */
+    readonly costUsd: number | null;
 }
 /**
  * The CLI's usage consumer (E2 1.3.0, the R2a-1 ruling 2026-08-13) — the
@@ -76,6 +80,7 @@ export declare function usageFromEvent(route: string | undefined, ev: import("@v
  *  is gone) — docked only, 200ms rotation between the request and the
  *  first event. */
 export declare function startStatusSpinner(onTick: (glyph: string) => void): () => void;
+export declare function startShellTail(sessionId: string, callId: string, command: string, startedAt: number): () => void;
 /**
  * Consume a run, answering approval pauses as they arrive. `resumeMode`
  * marks a session.resume() continuation. `faux` picks the status line's
@@ -84,7 +89,7 @@ export declare function startStatusSpinner(onTick: (glyph: string) => void): ()
  * echo is UI, the chip is the record; the momentary double-render is
  * the design's explicit point).
  */
-export declare function consumeRun(session: AgentSession, run: Run, input: LineInput, turnNo: number, faux: boolean, statusCb: ((usage: RunUsage, ctxRatio: number) => void) | null, 
+export declare function consumeRun(session: AgentSession, run: Run, input: LineInput, turnNo: number, faux: boolean, statusCb: ((usage: RunUsage, ctxRatio: number, costUsd?: number | null) => void) | null, 
 /** W21: the amend words ("Yes + feedback") ride the NEXT user turn —
  *  threaded from chat's submitTurn; absent in the recovery flow
  *  (resume) where a dropped amend is noticed instead. */

package/dist/chat.js

@@ -4,10 +4,10 @@
  * approval-moment mini-diff, the status spinner, and the context
  * estimates. All bodies moved verbatim from index.ts.
  */
-import { readFileSync } from "node:fs";
-import { escapeTerminal, idleStatus, palette, renderEvent, renderRecap, runningStatus, toolTarget, STATUS_GLYPHS, } from "@vincemakes/kiso-tui";
+import { readFileSync, statSync } from "node:fs";
+import { escapeTerminal, cacheHitPct, idleStatus, palette, renderEvent, renderRecap, runningStatus, toolTarget, STATUS_GLYPHS, } from "@vincemakes/kiso-tui";
 import { editFileDiff, writeFileDiff } from "@vincemakes/kiso-tui";
-import { canonicalTargetPath } from "@vincemakes/kiso-tools-node";
+import { canonicalTargetPath, shellProgressPath } from "@vincemakes/kiso-tools-node";
 import { canonicalizeUsage } from "@vincemakes/kiso-runtime";
 import { dispatch } from "./dispatch.js";
 import { agentModel, body, bodyLog, configuredWindow, dock } from "./state.js";
@@ -89,7 +89,7 @@ export function usageFromEvent(route, ev, prevTotal) {
         const m = Math.min(prevTotal, total) - c.cacheRead;
         missed = m > CACHE_MISS_FLOOR ? m : null;
     }
-    return { usage: { in: c.input, out: c.output, cache: c.cacheRead, known: ev.known }, total, missed };
+    return { usage: { in: c.input, out: c.output, cache: c.cacheRead, known: ev.known }, total, missed, costUsd: c.costUsd };
 }
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
@@ -105,6 +105,45 @@ export function startStatusSpinner(onTick) {
     timer.unref();
     return () => clearInterval(timer);
 }
+/**
+ * TUI2-R1 (C) — the shell tailer: the READER half of the progress
+ * sidecar (the writer is the shell tool, tools-node).
+ *
+ * The CLI is the only place that holds both facts the derived key needs
+ * — the session's id and the running call's command — so the tail is
+ * read here and handed to the cell. A poll, not a watcher: fs.watch's
+ * behaviour on a file being appended to differs by platform, and the
+ * one thing this must never do is misbehave in a way that costs the run.
+ *
+ * THE FRESHNESS GUARD is the part that makes a kill -9 leftover
+ * harmless. A sidecar the writer never got to remove keeps its old
+ * mtime; a tail is read only from a file modified AT OR AFTER the call
+ * started. A ghost from a previous process cannot be shown as this
+ * call's output — and since the tail is display-only, showing nothing is
+ * always the safe answer.
+ */
+const TAIL_POLL_MS = 250;
+const TAIL_BYTES = 4096; // the last lines are all the window can hold
+export function startShellTail(sessionId, callId, command, startedAt) {
+    const path = shellProgressPath(sessionId, command);
+    const read = () => {
+        try {
+            const stat = statSync(path);
+            if (stat.mtimeMs + 1000 < startedAt)
+                return; // a ghost from a killed run — never this call's
+            const text = readFileSync(path, "utf8");
+            body.toolProgress(callId, text.slice(-TAIL_BYTES).trimEnd());
+        }
+        catch {
+            // no sidecar yet, removed at settle, or unreadable — the tail
+            // is an observation, and its absence is never an error
+        }
+    };
+    read();
+    const timer = setInterval(read, TAIL_POLL_MS);
+    timer.unref();
+    return () => clearInterval(timer);
+}
 /** v2e: the approval-moment mini-diff — edit_file/write_file changes as
  *  ± lines; other tools get null (no diff, no cost). The file read is
  *  best-effort: an unreadable file yields NO diff, never a failure —
@@ -128,7 +167,9 @@ function approvalDiff(name, input) {
             const replace = typeof input.replace === "string" ? input.replace : "";
             if (search === "")
                 return null;
-            return editFileDiff(oldContent ?? "", search, replace);
+            // TUI2-R1.5 ② (VD-2): the path rides along so a miss can name the
+            // file in its honest note instead of fabricating a diff.
+            return editFileDiff(oldContent ?? "", search, replace, path);
         }
         const content = typeof input.content === "string" ? input.content : "";
         return writeFileDiff(oldContent, content);
@@ -268,6 +309,16 @@ submitTurn) {
     // at the first non-thinking event (the fold needs the seconds).
     let thoughtSeconds = 0;
     let thinkingSince = null;
+    // TUI2-R1 (C): the shell commands seen this run, and the tailers
+    // running for them. A tailer is started when the execution starts and
+    // stopped at the call's result — and the finally below stops any that
+    // an abort left behind, so a poller can never outlive its run.
+    const shellCommands = new Map();
+    const tailers = new Map();
+    const stopTail = (callId) => {
+        tailers.get(callId)?.();
+        tailers.delete(callId);
+    };
     try {
         for await (const ev of run) {
             last = ev;
@@ -295,10 +346,18 @@ submitTurn) {
                     if (ev.name === "edit_file")
                         editCount += 1;
                     body.toolStart(ev.name, ev.callId, ev.input ?? {});
+                    // TUI2-R1 (C): the command is the sidecar key's other half —
+                    // remembered here, used when the execution actually starts.
+                    if (ev.name === "shell" && typeof ev.input?.command === "string")
+                        shellCommands.set(ev.callId, ev.input.command);
                     break;
-                case "tool_execution_started":
+                case "tool_execution_started": {
                     body.toolRunning(ev.callId);
+                    const command = shellCommands.get(ev.callId);
+                    if (command !== undefined)
+                        tailers.set(ev.callId, startShellTail(session.id, ev.callId, command, Date.now()));
                     break;
+                }
                 case "tool_execution_succeeded":
                     body.toolSucceeded(ev.callId);
                     break;
@@ -306,6 +365,9 @@ submitTurn) {
                     body.toolFailed(ev.callId, ev.error);
                     break;
                 case "tool_result": {
+                    // TUI2-R1 (C): the observation window closes the instant the
+                    // real result exists — the tail must never race it.
+                    stopTail(ev.callId);
                     const text = typeof ev.content === "string" ? ev.content : "";
                     // W19: a DENIED call carries its reason — extracted from the
                     // result's "[Permission denied] " prefix, keyed on the
@@ -340,7 +402,9 @@ submitTurn) {
                     usage = delta.usage;
                     prevTotal = delta.total;
                     missed = delta.missed;
-                    statusCb?.(usage, estimateCtxRatio(session));
+                    // TUI2-R1 (E): the request's canonical cost rides the same
+                    // callback the usage does — one settled request, one addition.
+                    statusCb?.(usage, estimateCtxRatio(session), delta.costUsd);
                     break;
                 }
                 case "uncertain_pending":
@@ -471,6 +535,11 @@ submitTurn) {
         body.thinkingEnd(); // a trailing thinking block folds at the run's end
     }
     finally {
+        // TUI2-R1 (C): an abort or a throw leaves the loop without a
+        // tool_result — every tailer stops here regardless, so no poller
+        // outlives the run that started it.
+        for (const callId of [...tailers.keys()])
+            stopTail(callId);
     }
     return last;
 }
@@ -639,6 +708,11 @@ export async function chat(session, faux, input, autoCompact) {
     // glyph (▖▘▝▗ — the spinner drives it) + wall seconds + ↓ out tokens
     // + the interrupt hint. ctx left is the live estimate everywhere.
     let runUsage = { in: null, out: null, cache: null, known: false };
+    // TUI2-R1 (E): the session's spend so far — the CANONICAL cost of every
+    // request this process has seen, summed. Null stays null: a route with
+    // no rate in the pricing table contributes nothing and the row shows no
+    // $ at all, because a partial total presented as a total is a lie.
+    let spentUsd = null;
     let runGlyph = "▖";
     let runStart = Date.now();
     // KC2 §5: the STATE (the glyph, the run's start, the usage, the dock)
@@ -651,13 +725,29 @@ export async function chat(session, faux, input, autoCompact) {
     // parentheses idiom names the read-only constraint. The tier is the
     // CALLER's word (the recovery flow passes the bare mode).
     const paintIdle = () => {
-        if (dock.active)
-            dock.setStatus(idleStatus(getMode() === "plan" ? "plan (read-only)" : getMode(), agentModel, estimateCtxRatio(session)));
+        if (!dock.active)
+            return;
+        // TUI2-R1 (E): the meter rides the idle row — both fields omitted
+        // when unknown, so a session that has not called the model paints
+        // exactly the pre-round row.
+        dock.setStatus(idleStatus(getMode() === "plan" ? "plan (read-only)" : getMode(), agentModel, estimateCtxRatio(session), {
+            cacheHitPct: cacheHitPct(runUsage),
+            costUsd: spentUsd,
+        }));
     };
-    const statusCb = (u, ctx) => {
+    const statusCb = (u, ctx, costUsd) => {
         runUsage = u;
+        addCost(costUsd ?? null);
         paintRunning();
     };
+    // TUI2-R1 (E): the canonical cost of one settled request, added to the
+    // session's running total. A null cost (no rate for the route) adds
+    // nothing and leaves the total as it was.
+    const addCost = (usd) => {
+        if (usd === null)
+            return;
+        spentUsd = (spentUsd ?? 0) + usd;
+    };
     const submitTurn = (line) => {
         const slot = { line, cancelled: false };
         pendingTurns.push(slot);
@@ -717,6 +807,7 @@ export async function chat(session, faux, input, autoCompact) {
         paintIdle,
         submitTurn,
         estimateCtx: () => estimateCtxRatio(session),
+        contextWindow: () => contextWindowTokens(),
     };
     // the ergonomics batch C8: the auto-compact check — the /compact FULL path via the
     // shared dispatch (same notices, same chain ordering, same mid-run
@@ -756,6 +847,15 @@ export async function chat(session, faux, input, autoCompact) {
         const recoveryRun = session.resume();
         currentRun = recoveryRun;
         turnNo += 1;
+        // TUI2-R1.5 ③ (VD-3 family): stamp the run's start AT the run's
+        // entry. Every other run path does; this one inherited the value
+        // from the process's own startup, so its "working Ns" was the
+        // session's age rather than the recovery's. The drift is small
+        // today (recovery follows startup closely) and unbounded in
+        // principle — a slow MCP connect is seconds the recovery never
+        // spent, reported as seconds it did.
+        runStart = Date.now();
+        runUsage = { in: null, out: null, cache: null, known: false };
         const last = await consumeRun(session, recoveryRun, input, turnNo, faux, statusCb, submitTurn);
         currentRun = null;
         failOnFauxExhaustion(last, faux, input);

package/dist/dispatch.d.ts

@@ -22,6 +22,9 @@ export interface DispatchCtx {
     readonly submitTurn: (line: string) => void;
     /** the /status context estimate. */
     readonly estimateCtx: () => number;
+    /** TUI2-R1 (E): the model's context window, as the session is
+     *  configured — the /context ledger's denominator. */
+    readonly contextWindow: () => number;
 }
 /** The ONE dispatcher — slash commands, exit, and turns. The recovery
  *  replay routes through it too — a queued "/last" must never become a

package/dist/dispatch.js

@@ -3,10 +3,10 @@
  * turns. The bodies moved verbatim from chat()'s closure; chat provides
  * the context (the chain, the run state, the prompt arming).
  */
-import { escapeTerminal, helpRows, kUnit, palette } from "@vincemakes/kiso-tui";
+import { contextRows, contextUnavailableRows, escapeTerminal, helpRows, kUnit, palette } from "@vincemakes/kiso-tui";
 import { buildAdapter } from "@vincemakes/kiso-runtime/internal";
 import { MODES, getMode, setMode } from "./mode.js";
-import { agentModel, body, bodyLog, configModels, dock, setAgentModel, setCurrentModelName } from "./state.js";
+import { agentModel, body, bodyLog, configModels, dock, readContextLedger, setAgentModel, setCurrentModelName } from "./state.js";
 import { directWriteProfile, profileAvailable } from "./config.js";
 /** The ONE dispatcher — slash commands, exit, and turns. The recovery
  *  replay routes through it too — a queued "/last" must never become a
@@ -23,8 +23,10 @@ export function dispatch(line, ctx) {
         // the last one still carries its own \n, so `exit` and `keys`
         // land as two rows from one call (bodyLog splits on \n).
         ctx.chainRef.current = ctx.chainRef.current.then(async () => {
+            // TUI2-R1.5 9 (VD-10): /help is sentences for a human — the keys
+            // row in particular is one long line that hard-folded mid-word.
             for (const row of helpRows())
-                bodyLog(row);
+                bodyLog(row, "words");
             ctx.input.prompt();
         });
         return;
@@ -92,6 +94,30 @@ export function dispatch(line, ctx) {
         ctx.chainRef.current = ctx.chainRef.current.then(land);
         return;
     }
+    if (trimmed === "/context") {
+        // TUI2-R1 (E): the rent-ledger attribution — where the context went,
+        // read from the session's TRACE SIDECAR (the observation file E1/E3
+        // already write, per request).
+        //
+        // THE PURITY GATE IS UNTOUCHED and this is why: the trace surface is
+        // an OBSERVATION surface (ADR-0051 §6, ruling R7) and correctness
+        // never reads it. /context is a DISPLAY command — nothing it reads
+        // reaches a recovery plan, a projection, or a request. The read is
+        // best-effort by construction: a missing, partial or unparseable
+        // ledger renders the honest fallback, never an error and never a
+        // guess. recovery-purity.test.ts's probes are unaffected: the
+        // derivation still does zero I/O and still ignores trace-shaped data.
+        ctx.chainRef.current = ctx.chainRef.current.then(async () => {
+            const ledger = readContextLedger(ctx.session.id, ctx.contextWindow());
+            for (const row of ledger === null
+                ? contextUnavailableRows("the ledger is written per request — run a turn, then ask again")
+                : contextRows(ledger)) {
+                bodyLog(row);
+            }
+            ctx.input.prompt();
+        });
+        return;
+    }
     if (trimmed === "/status") {
         // B area: session id, durable event count, and the ~ context
         // estimate — all read straight from the live session, nothing

package/dist/index.js

@@ -199,6 +199,7 @@ function makeLineInput() {
         editor.bindAtItems(atFiles); // KC3 §5: the file source — listed per OPEN
         dock.bindAt(() => editor.atState()); // KC3 §4: the picker's band
         dock.bindApproval(() => editor.panelState()); // W21: the panel's bound state
+        dock.bindSheet(() => editor.sheetOpen()); // TUI2-R1 (D): the ? keys sheet
         return editorInput(editor);
     }
     return readlineInput(createInterface({ input: process.stdin, output: process.stdout }));

package/dist/state.d.ts

@@ -15,6 +15,22 @@ export declare function kisoHome(): string;
 export declare function sessionsDir(): string;
 /** E1: the extension scan directory — KISO_EXTENSIONS_DIR overrides. */
 export declare function extensionsDir(): string;
+/**
+ * TUI2-R1 (E) — the /context ledger, read from the session's TRACE
+ * SIDECAR (<sessions>/traces/<id>.jsonl).
+ *
+ * THE PURITY GATE (ADR-0051 §6, ruling R7) IS UNTOUCHED. The trace
+ * surface is an observation surface; correctness never reads it, and
+ * this reader is on the DISPLAY path only — nothing it returns reaches a
+ * recovery plan, a projection or a request. The proof of that is the
+ * shape of this function: it is best-effort end to end, and its failure
+ * mode is `null`, which renders a sentence rather than a number.
+ *
+ * The LAST request line is the one that matters: rent is per request,
+ * and what the reader wants to know is what the NEXT request will cost,
+ * which is what the previous one cost.
+ */
+export declare function readContextLedger(sessionId: string, window: number): import("@vincemakes/kiso-tui").ContextLedger | null;
 /**
  * KC3 §5 — the @ picker's file source. Computed PER OPEN: no index, no
  * daemon, no watcher, nothing to invalidate and nothing to go stale.
@@ -90,7 +106,7 @@ export declare let body: Body;
 export declare function setBody(value: Body): void;
 /** v2d: body output routes through the cell renderer — the single writer.
  *  bodyLog adds the trailing newline; internal newlines are preserved. */
-export declare function bodyLog(text: string): void;
+export declare function bodyLog(text: string, wrap?: "words"): void;
 /** The model name for the status bar — set by makeAgent. */
 export declare let agentModel: string;
 export declare function setAgentModel(value: string): void;

package/dist/state.js

@@ -25,6 +25,71 @@ export function sessionsDir() {
 export function extensionsDir() {
     return process.env.KISO_EXTENSIONS_DIR ?? join(kisoHome(), "extensions");
 }
+/**
+ * TUI2-R1 (E) — the /context ledger, read from the session's TRACE
+ * SIDECAR (<sessions>/traces/<id>.jsonl).
+ *
+ * THE PURITY GATE (ADR-0051 §6, ruling R7) IS UNTOUCHED. The trace
+ * surface is an observation surface; correctness never reads it, and
+ * this reader is on the DISPLAY path only — nothing it returns reaches a
+ * recovery plan, a projection or a request. The proof of that is the
+ * shape of this function: it is best-effort end to end, and its failure
+ * mode is `null`, which renders a sentence rather than a number.
+ *
+ * The LAST request line is the one that matters: rent is per request,
+ * and what the reader wants to know is what the NEXT request will cost,
+ * which is what the previous one cost.
+ */
+export function readContextLedger(sessionId, window) {
+    let last = null;
+    try {
+        const text = readFileSync(join(sessionsDir(), "traces", `${sessionId}.jsonl`), "utf8");
+        for (const line of text.split("\n")) {
+            if (line === "")
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.kind === "request")
+                    last = parsed;
+            }
+            catch {
+                // a torn last line (the writer was mid-append) — the ledger is
+                // an observation, and a partial one is simply not the answer
+            }
+        }
+    }
+    catch {
+        return null; // no sidecar — a session that has not called the model
+    }
+    if (last === null)
+        return null;
+    const rent = Array.isArray(last.rent) ? last.rent : [];
+    if (rent.length === 0)
+        return null; // a v1/v2 sidecar carries no rent block (R2-1)
+    const sum = (pred) => rent.filter((l) => typeof l.surface === "string" && pred(l.surface)).reduce((a, l) => a + (l.estTokens ?? 0), 0);
+    const count = (pred) => rent.filter((l) => typeof l.surface === "string" && pred(l.surface)).length;
+    // the skills index is broken out: it is an INDEX of workspace content,
+    // not an instruction, and it is the one append whose size is the
+    // reader's own doing.
+    const isSkills = (s) => s === "system:ext:skills";
+    const manifest = Array.isArray(last.contextManifest) ? last.contextManifest : [];
+    const turnSegments = manifest.filter((s) => s.role === "turn" || s.role === "current_turn");
+    return {
+        window,
+        systemPrompt: sum((s) => s === "system:base" || (s.startsWith("system:ext:") && !isSkills(s))),
+        systemBase: sum((s) => s === "system:base"),
+        appends: count((s) => s.startsWith("system:ext:") && !isSkills(s)),
+        toolTable: sum((s) => s.startsWith("tool:")),
+        tools: count((s) => s.startsWith("tool:")),
+        skillsIndex: sum(isSkills),
+        // the ledger records the SURFACE, never its contents — the number
+        // of skills is not in it, and 0 tells the renderer to say so.
+        skills: 0,
+        envelope: sum((s) => s === "envelope"),
+        messages: turnSegments.reduce((a, s) => a + (s.estTokens ?? 0), 0),
+        turns: turnSegments.length,
+    };
+}
 /**
  * KC3 §5 — the @ picker's file source. Computed PER OPEN: no index, no
  * daemon, no watcher, nothing to invalidate and nothing to go stale.
@@ -95,8 +160,8 @@ export function setBody(value) {
 }
 /** v2d: body output routes through the cell renderer — the single writer.
  *  bodyLog adds the trailing newline; internal newlines are preserved. */
-export function bodyLog(text) {
-    body.raw(text.split("\n"));
+export function bodyLog(text, wrap) {
+    body.raw(text.split("\n"), wrap);
 }
 /** The model name for the status bar — set by makeAgent. */
 export let agentModel = "faux";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-code",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "kiso CLI — the durable coding agent that survives kill -9: kiso chat / kiso resume / kiso sessions.",
   "type": "module",
   "license": "MIT",
@@ -18,19 +18,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-ask-ext": "0.8.0",
-    "@vincemakes/kiso-core": "0.8.0",
-    "@vincemakes/kiso-evals": "0.8.0",
-    "@vincemakes/kiso-mcp-ext": "0.8.0",
-    "@vincemakes/kiso-provider-anthropic": "0.8.0",
-    "@vincemakes/kiso-provider-openai": "0.8.0",
-    "@vincemakes/kiso-runtime": "0.8.0",
-    "@vincemakes/kiso-skills-ext": "0.8.0",
-    "@vincemakes/kiso-subagent-ext": "0.8.0",
-    "@vincemakes/kiso-task-ext": "0.8.0",
-    "@vincemakes/kiso-tools-node": "0.8.0",
-    "@vincemakes/kiso-tui": "0.8.0",
-    "@vincemakes/kiso-tui-cells": "0.8.0"
+    "@vincemakes/kiso-ask-ext": "0.9.0",
+    "@vincemakes/kiso-core": "0.9.0",
+    "@vincemakes/kiso-evals": "0.9.0",
+    "@vincemakes/kiso-mcp-ext": "0.9.0",
+    "@vincemakes/kiso-provider-anthropic": "0.9.0",
+    "@vincemakes/kiso-provider-openai": "0.9.0",
+    "@vincemakes/kiso-runtime": "0.9.0",
+    "@vincemakes/kiso-skills-ext": "0.9.0",
+    "@vincemakes/kiso-subagent-ext": "0.9.0",
+    "@vincemakes/kiso-task-ext": "0.9.0",
+    "@vincemakes/kiso-tools-node": "0.9.0",
+    "@vincemakes/kiso-tui": "0.9.0",
+    "@vincemakes/kiso-tui-cells": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",