@vincemakes/kiso-code 0.1.48 → 0.2.0

package/dist/chat.d.ts

@@ -32,6 +32,46 @@ export declare function contextWindowTokens(): number;
  * the model window. Marked ~ everywhere it is shown; no counting API.
  */
 export declare function estimateCtxRatio(session: AgentSession): number;
+/** E2 (1.3.0) — the CLI's usage consumer: one event in, the RunUsage the
+ *  status line and recap render plus the miss estimate. `total` is the
+ *  carrier for the NEXT turn's miss estimate — the overlap of consecutive
+ *  prompts is a total-side quantity, never a fresh delta. */
+export interface UsageDelta {
+    readonly usage: RunUsage;
+    /** The canonical total (fresh + cache) — the miss estimate's carrier.
+     *  null when the event carried no usage (the canonical total of an
+     *  unknown event is 0, and a 0 carrier keeps the estimate below the
+     *  floor — the old consumer's carrier stayed null forever; this one
+     *  recovers on the next known event). */
+    readonly total: number | null;
+    readonly missed: number | null;
+}
+/**
+ * The CLI's usage consumer (E2 1.3.0, the R2a-1 ruling 2026-08-13) — the
+ * HEAL: the mixed-convention consumer is now CANONICAL at the route (the
+ * accounting boundary), the same derivation the trace block carries.
+ *
+ * EXISTING-BEHAVIOR CHANGE — declared, never a silent side-fix:
+ *  - openai-compat: `in` was the provider-raw TOTAL (fresh + cache); it is
+ *    now the canonical FRESH count. The >100% cache-ratio disease: raw
+ *    {input 111, cacheRead 1024} previously rendered "in 111" and the
+ *    recap's cache % (then cache/in) read 923%; now "in 0" and the recap
+ *    divides cache by the TOTAL (in + cache — T5) — never > 100%.
+ *  - the miss estimate is numerically IDENTICAL on openai-compat: its old
+ *    `in` WAS the total, and the carrier is the canonical total
+ *    (input + cacheRead), which equals the raw total by construction.
+ *  - anthropic: `in` was already fresh — unchanged; the miss estimate was
+ *    min-of-fresh-deltas − cacheRead (always below the floor — silent);
+ *    it is now min-of-totals, the semantics the openai-compat side always
+ *    had (a fix, and it can fire).
+ *  - the unknown-usage carrier: the old consumer's null carrier killed the
+ *    miss signal forever; the canonical total of an unknown event is 0, so
+ *    the signal recovers on the next known event.
+ * The route key mirrors the trace path's fallback by construction: an
+ * absent provider resolves like the tracer's "adapter" identity — the
+ * total convention (INPUT_CONVENTIONS), never a crash.
+ */
+export declare function usageFromEvent(route: string | undefined, ev: import("@vincemakes/kiso-core").Usage, prevTotal: number | null): UsageDelta;
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
  *  first event. */

package/dist/chat.js

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { escapeTerminal, kUnit, palette, renderEvent, renderRecap, toolTarget, } from "@vincemakes/kiso-tui";
 import { editFileDiff, writeFileDiff } from "@vincemakes/kiso-tui";
 import { canonicalTargetPath } 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";
 import { addDontAskAgainRule, askPanel, fixHintFor, pendingAsk, resolveUncertains } from "./trust-ui.js";
@@ -47,6 +48,49 @@ export function estimateCtxRatio(session) {
     const chars = JSON.stringify(projected).length;
     return chars / 4 / contextWindowTokens();
 }
+/** R-C item 4: the per-turn cache miss — the overlap with the previous
+ *  prompt that SHOULD have been cached but was re-sent uncached:
+ *  missed = min(prevIn, in) − cacheRead. Below the 1024-token floor
+ *  (Anthropic's minimum cacheable block) it is noise — not surfaced. */
+const CACHE_MISS_FLOOR = 1024;
+/**
+ * The CLI's usage consumer (E2 1.3.0, the R2a-1 ruling 2026-08-13) — the
+ * HEAL: the mixed-convention consumer is now CANONICAL at the route (the
+ * accounting boundary), the same derivation the trace block carries.
+ *
+ * EXISTING-BEHAVIOR CHANGE — declared, never a silent side-fix:
+ *  - openai-compat: `in` was the provider-raw TOTAL (fresh + cache); it is
+ *    now the canonical FRESH count. The >100% cache-ratio disease: raw
+ *    {input 111, cacheRead 1024} previously rendered "in 111" and the
+ *    recap's cache % (then cache/in) read 923%; now "in 0" and the recap
+ *    divides cache by the TOTAL (in + cache — T5) — never > 100%.
+ *  - the miss estimate is numerically IDENTICAL on openai-compat: its old
+ *    `in` WAS the total, and the carrier is the canonical total
+ *    (input + cacheRead), which equals the raw total by construction.
+ *  - anthropic: `in` was already fresh — unchanged; the miss estimate was
+ *    min-of-fresh-deltas − cacheRead (always below the floor — silent);
+ *    it is now min-of-totals, the semantics the openai-compat side always
+ *    had (a fix, and it can fire).
+ *  - the unknown-usage carrier: the old consumer's null carrier killed the
+ *    miss signal forever; the canonical total of an unknown event is 0, so
+ *    the signal recovers on the next known event.
+ * The route key mirrors the trace path's fallback by construction: an
+ * absent provider resolves like the tracer's "adapter" identity — the
+ * total convention (INPUT_CONVENTIONS), never a crash.
+ */
+export function usageFromEvent(route, ev, prevTotal) {
+    const c = canonicalizeUsage(route ?? "adapter", ev);
+    const total = c.input + c.cacheRead + (c.cacheWrite ?? 0);
+    let missed = null;
+    // R-C item 4: min(prevTotal, total) is the part that could have been
+    // cached; what cacheRead did NOT cover is the miss. A below-floor or
+    // non-positive difference is noise — not surfaced.
+    if (prevTotal !== null) {
+        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 };
+}
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
  *  first event. */
@@ -212,12 +256,7 @@ export async function consumeRun(session, run, input, turnNo, faux, statusCb,
 submitTurn) {
     let last;
     let usage = { in: null, out: null, cache: null, known: false };
-    // R-C item 4: the per-turn cache miss — the overlap with the previous
-    // prompt that SHOULD have been cached but was re-sent uncached:
-    // missed = min(prevIn, in) − cacheRead. Below the 1024-token floor
-    // (Anthropic's minimum cacheable block) it is noise — not surfaced.
-    const CACHE_MISS_FLOOR = 1024;
-    let prevIn = null;
+    let prevTotal = null;
     let missed = null;
     // v3 §02: the recap line derives ENTIRELY from the local event stream
     // (zero tokens) — wall seconds, tool/edit counts, usage, ctx left.
@@ -297,14 +336,10 @@ submitTurn) {
                     body.textEnd();
                     break;
                 case "usage": {
-                    usage = { in: ev.inputTokens, out: ev.outputTokens, cache: ev.cacheRead, known: ev.known };
-                    // R-C item 4: min(prevIn, in) is the part that could have been
-                    // cached; what cacheRead did NOT cover is the miss.
-                    if (usage.in !== null && usage.cache !== null && prevIn !== null) {
-                        const m = Math.min(prevIn, usage.in) - usage.cache;
-                        missed = m > CACHE_MISS_FLOOR ? m : null;
-                    }
-                    prevIn = usage.in;
+                    const delta = usageFromEvent(session.provider, ev, prevTotal);
+                    usage = delta.usage;
+                    prevTotal = delta.total;
+                    missed = delta.missed;
                     statusCb?.(usage, estimateCtxRatio(session));
                     break;
                 }
@@ -443,6 +478,23 @@ submitTurn) {
 export async function chat(session, faux, input, autoCompact) {
     let currentRun = null;
     let cancelled = false;
+    // E group (the graceful-exit gate ③, R-G 0.1.48): the terminal can
+    // close MID-run — the stream 'end' fires while currentRun is set, so
+    // the EOT callback defers. eotSeen remembers it; each run's end
+    // re-evaluates the exit condition (the safe point), so the release
+    // always runs.
+    let eotSeen = false;
+    /** The exit condition, shared by the EOT callback and the deferred
+     *  re-check: no pending ask, an empty line. currentRun is checked by
+     *  the callers (the callback when 'end' fires; the run-end re-checks
+     *  run only after currentRun was nulled). */
+    const exitAtEmptyPrompt = () => {
+        if (pendingAsk !== null || input.line() !== "")
+            return;
+        cancelled = true;
+        console.log("\n[exit requested]");
+        input.close();
+    };
     const turn = (text) => new Promise((resolve, reject) => {
         queued = Math.max(0, queued - 1); // a queued turn starts
         const run = session.run(text);
@@ -471,6 +523,11 @@ export async function chat(session, faux, input, autoCompact) {
                 // chat to main's finally/catch, never an orphaned
                 // unhandled rejection from the IIFE.
                 failOnFauxExhaustion(last, faux, input);
+                // E group (the graceful-exit gate ③): the fd may have closed
+                // mid-run — the run's end is the safe point for the deferred
+                // exit, so the release always runs.
+                if (eotSeen)
+                    exitAtEmptyPrompt();
                 // round 8: after EVERY turn the prompt is re-armed — the human
                 // never types blind after the first turn.
                 input.prompt();
@@ -517,11 +574,11 @@ export async function chat(session, faux, input, autoCompact) {
         }
     });
     input.onEot(() => {
-        if (!currentRun && pendingAsk === null && input.line() === "") {
-            cancelled = true;
-            console.log("\n[exit requested]");
-            input.close();
-        }
+        // E group (the graceful-exit gate ③): the 'end' may fire MID-run —
+        // the exit defers to the run's end (the re-checks below).
+        eotSeen = true;
+        if (!currentRun)
+            exitAtEmptyPrompt();
     });
     input.onEscape(() => {
         if (currentRun) {
@@ -662,6 +719,10 @@ export async function chat(session, faux, input, autoCompact) {
         const last = await consumeRun(session, recoveryRun, input, turnNo, faux, statusCb, submitTurn);
         currentRun = null;
         failOnFauxExhaustion(last, faux, input);
+        // E group (the graceful-exit gate ③): the same deferred re-check
+        // as the turn path — the recovery run's end is also a safe point.
+        if (eotSeen)
+            exitAtEmptyPrompt();
         maybeAutoCompact(); // the ergonomics batch C8: the recovery run ended too — same check (awaited by the exit re-await)
     }
     if (cancelled) {

package/dist/diff.d.ts

@@ -0,0 +1,32 @@
+/**
+ * v2e — the diff renderer: edit/write changes as inline ± lines, zero
+ * dependencies, no syntax highlighting (the spec's scope line). Shown at
+ * the approval moment ONLY — the frozen summary stays one line (v2d's
+ * anti-leak principle), /last has the full data.
+ *
+ * edit_file diffs IN PLACE (the search→replace windows are known — no
+ * general engine needed); write_file does a row-level LCS over the old
+ * file (small files are the target). Context: 2 rows each side. The
+ * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
+ * from the full diff.
+ */
+/** The diff block's per-row kind. */
+export type DiffLine = {
+    kind: "-" | "+" | " ";
+    text: string;
+};
+export interface DiffResult {
+    /** The FULL diff (with context, not truncated) — the display truncates. */
+    lines: DiffLine[];
+    added: number;
+    removed: number;
+}
+/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
+export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
+/** edit_file: the search→replace windows replace in place — the changed
+ *  region is KNOWN, so the diff is the old window vs the new window,
+ *  context from the surrounding file. */
+export declare function editFileDiff(oldContent: string, search: string, replace: string): DiffResult;
+/** write_file: a new file is all +; an existing file diffs row-level
+ *  against its old content. */
+export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;

package/dist/diff.js

@@ -0,0 +1,122 @@
+/**
+ * v2e — the diff renderer: edit/write changes as inline ± lines, zero
+ * dependencies, no syntax highlighting (the spec's scope line). Shown at
+ * the approval moment ONLY — the frozen summary stays one line (v2d's
+ * anti-leak principle), /last has the full data.
+ *
+ * edit_file diffs IN PLACE (the search→replace windows are known — no
+ * general engine needed); write_file does a row-level LCS over the old
+ * file (small files are the target). Context: 2 rows each side. The
+ * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
+ * from the full diff.
+ */
+/** A line-level LCS diff — the classic two-row DP, ~small inputs. */
+function lcsDiff(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i][j] = oldLines[i] === newLines[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (oldLines[i] === newLines[j]) {
+            out.push({ kind: " ", text: oldLines[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            out.push({ kind: "-", text: oldLines[i] });
+            i += 1;
+        }
+        else {
+            out.push({ kind: "+", text: newLines[j] });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        out.push({ kind: "-", text: oldLines[i] });
+        i += 1;
+    }
+    while (j < m) {
+        out.push({ kind: "+", text: newLines[j] });
+        j += 1;
+    }
+    return out;
+}
+/** Keep 2 context rows around each change — the unified-style window. */
+function withContext(diff) {
+    const out = [];
+    let lastAdded = -10;
+    for (let k = 0; k < diff.length; k += 1) {
+        if (diff[k].kind === " ")
+            continue;
+        const from = Math.max(0, k - 2);
+        const to = Math.min(diff.length - 1, k + 2);
+        for (let c = from; c <= to; c += 1) {
+            if (c > lastAdded) {
+                out.push(diff[c]);
+                lastAdded = c;
+            }
+        }
+        lastAdded = to;
+    }
+    return out;
+}
+const MAX_DIFF_LINES = 40; // the RENDERED cap
+const TRUNCATE_KEEP = 18;
+/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
+export function truncateDiff(diff) {
+    if (diff.length <= MAX_DIFF_LINES)
+        return diff;
+    const omitted = diff.length - 2 * TRUNCATE_KEEP;
+    return [
+        ...diff.slice(0, TRUNCATE_KEEP),
+        { kind: " ", text: `… ${omitted} lines (/last for full)` },
+        ...diff.slice(diff.length - TRUNCATE_KEEP),
+    ];
+}
+function stats(diff) {
+    let added = 0;
+    let removed = 0;
+    for (const d of diff) {
+        if (d.kind === "+")
+            added += 1;
+        else if (d.kind === "-")
+            removed += 1;
+    }
+    return { added, removed };
+}
+/** edit_file: the search→replace windows replace in place — the changed
+ *  region is KNOWN, so the diff is the old window vs the new window,
+ *  context from the surrounding file. */
+export function editFileDiff(oldContent, search, replace) {
+    const oldLines = oldContent.split("\n");
+    const searchLines = search.split("\n");
+    const replaceLines = replace.split("\n");
+    // Locate the search window (the first occurrence — the edit tool's own
+    // semantics); no occurrence → the whole file is the old side.
+    let at = -1;
+    for (let i = 0; i + searchLines.length <= oldLines.length; i += 1) {
+        if (oldLines.slice(i, i + searchLines.length).join("\n") === search) {
+            at = i;
+            break;
+        }
+    }
+    const lines = at < 0 ? withContext(lcsDiff(oldLines, replaceLines)) : withContext(lcsDiff(oldLines, [...oldLines.slice(0, at), ...replaceLines, ...oldLines.slice(at + searchLines.length)]));
+    return { lines, ...stats(lines) };
+}
+/** write_file: a new file is all +; an existing file diffs row-level
+ *  against its old content. */
+export function writeFileDiff(oldContent, newContent) {
+    if (oldContent === null) {
+        const lines = newContent.split("\n").map((text) => ({ kind: "+", text }));
+        return { lines, added: lines.length, removed: 0 };
+    }
+    const lines = withContext(lcsDiff(oldContent.split("\n"), newContent.split("\n")));
+    return { lines, ...stats(lines) };
+}

package/dist/dispatch.d.ts

@@ -3,7 +3,7 @@
  * turns. The bodies moved verbatim from chat()'s closure; chat provides
  * the context (the chain, the run state, the prompt arming).
  */
-import { type AgentSession } from "@vincemakes/kiso-runtime";
+import type { AgentSession } from "@vincemakes/kiso-runtime";
 import { type LineInput } from "./state.js";
 /** Everything dispatch touches that chat() owns. */
 export interface DispatchCtx {

package/dist/dispatch.js

@@ -4,7 +4,7 @@
  * the context (the chain, the run state, the prompt arming).
  */
 import { escapeTerminal, kUnit, palette } from "@vincemakes/kiso-tui";
-import { buildAdapter } from "@vincemakes/kiso-runtime";
+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 { directWriteProfile, profileAvailable } from "./config.js";

package/dist/index.js

@@ -395,6 +395,15 @@ async function makeAgent(sessionId, input, modelFlag) {
     return createAgent(definition);
 }
 async function main() {
+    // E group (the graceful-exit gate ③, R-G 0.1.48): a terminal closing
+    // turns the in-flight stdout/stderr writes into EIO, and node's
+    // unhandled 'error' event on the WriteStream kills the process —
+    // mid-exit the release never runs (the 60-byte residue the gate
+    // caught). The bytes are undeliverable anyway (the terminal is
+    // gone): the error must never abort the exit sequence. The listener
+    // swallows it — the standard "the stream may die under me" idiom.
+    process.stdout.on("error", () => { });
+    process.stderr.on("error", () => { });
     // Modes: --mode <name> wins over KISO_MODE — both applied before the
     // first makeAgent (the tier extensions read `current` live). The flag
     // is stripped from the positional args, so it works in any position.
@@ -493,7 +502,15 @@ async function main() {
                 break;
             }
             case "sessions": {
-                agent = await makeAgent(undefined, undefined, modelFlag);
+                // R-I-p2 audit (the argument-consistency mandate): the
+                // read-only listing NEVER writes through the input, but the
+                // trust gate lives inside makeAgent and ASKS through it — on
+                // a TTY with a first-discovery .kiso, the undefined input
+                // crashed identically to the bare command (finding R-I-p-2,
+                // "reading 'question'" on the dock-less branch). The input
+                // exists so the gate's ask can be answered; the listing
+                // itself never touches it.
+                agent = await makeAgent(undefined, input, modelFlag);
                 for (const meta of agent.sessions()) {
                     console.log(renderSessionLine(meta));
                 }
@@ -516,7 +533,13 @@ async function main() {
                 // chat — the first argument is the session id.
                 const id = command ?? new Date().toISOString().replace(/[:.]/g, "-").slice(0, 16);
                 dock.enter();
-                agent = await makeAgent(id);
+                // R-I-p2 (finding R-I-p-2): the bare command passes the SAME
+                // input source and model flag as chat/resume — the pre-patch
+                // call dropped both, and the first-run trust gate read
+                // through the undefined input: "Cannot read properties of
+                // undefined" at the ask (panelAsk with the dock, question on
+                // the dock-less fallback).
+                agent = await makeAgent(id, input, modelFlag);
                 const session = await agent.session({ id });
                 bodyLog(`session ${id}\n`);
                 extensionsBanner(recentSessions(id, agent));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-code",
-  "version": "0.1.48",
+  "version": "0.2.0",
   "description": "kiso CLI — the coding-agent reference product: kiso chat / kiso resume / kiso sessions.",
   "type": "module",
   "license": "MIT",
@@ -18,18 +18,18 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.1.35",
-    "@vincemakes/kiso-evals": "0.1.36",
-    "@vincemakes/kiso-mcp-ext": "0.1.48",
-    "@vincemakes/kiso-provider-anthropic": "0.1.36",
-    "@vincemakes/kiso-provider-openai": "0.1.36",
-    "@vincemakes/kiso-runtime": "0.1.38",
-    "@vincemakes/kiso-skills-ext": "0.1.48",
-    "@vincemakes/kiso-subagent-ext": "0.1.48",
-    "@vincemakes/kiso-task-ext": "0.1.48",
-    "@vincemakes/kiso-tools-node": "0.1.36",
-    "@vincemakes/kiso-tui": "0.1.42",
-    "@vincemakes/kiso-tui-cells": "0.1.42"
+    "@vincemakes/kiso-core": "0.2.0",
+    "@vincemakes/kiso-evals": "0.2.0",
+    "@vincemakes/kiso-mcp-ext": "0.2.0",
+    "@vincemakes/kiso-provider-anthropic": "0.2.0",
+    "@vincemakes/kiso-provider-openai": "0.2.0",
+    "@vincemakes/kiso-runtime": "0.2.0",
+    "@vincemakes/kiso-skills-ext": "0.2.0",
+    "@vincemakes/kiso-subagent-ext": "0.2.0",
+    "@vincemakes/kiso-task-ext": "0.2.0",
+    "@vincemakes/kiso-tools-node": "0.2.0",
+    "@vincemakes/kiso-tui": "0.2.0",
+    "@vincemakes/kiso-tui-cells": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",