@vincemakes/kiso-code 0.22.0 → 0.23.0

package/dist/config.d.ts

@@ -52,6 +52,13 @@ export interface KisoConfig {
     readonly contextWindow?: number;
     readonly autoCompact?: AutoCompactConfig;
     readonly projectTrust?: "ask" | "never";
+    /** DC-3 §3 rung 1, persisted. The terminal's light/dark, for terminals
+     *  that answer neither `CSI ? 996 n` nor OSC 11. USER-LEVEL ONLY: a
+     *  terminal is a property of the human sitting at one, not of the
+     *  repository they happen to have open, so the same setting in a
+     *  project file is a LOUD error rather than a silent win. `KISO_THEME`
+     *  still outranks it — the environment is the more local answer. */
+    readonly theme?: "dark" | "light";
 }
 /** The resolved, merged config — project wins over user, both validated. */
 export interface ResolvedConfig {

package/dist/config.js

@@ -51,6 +51,18 @@ export function parseConfig(text, source) {
     const fail = (key, why) => {
         throw new ConfigError(`config ${source}: ${key} — ${why}`);
     };
+    if (obj.theme !== undefined) {
+        // LOUD on both counts: an invalid value, and a valid value in the
+        // wrong file. A theme silently ignored is the worst outcome here —
+        // the human set it precisely because their terminal answers
+        // nothing, so a quiet failure looks exactly like the defect it was
+        // meant to fix.
+        if (obj.theme !== "dark" && obj.theme !== "light")
+            fail("theme", 'expected "dark" or "light"');
+        if (source.startsWith("<cwd>"))
+            fail("theme", "belongs in the USER config — a terminal is a property of the person at it, not of the project");
+        out.theme = obj.theme;
+    }
     if (obj.model !== undefined) {
         if (typeof obj.model !== "string" || obj.model === "")
             fail("model", "expected a profile name or provider/model string");

package/dist/index.js

@@ -40,6 +40,7 @@ import { isFirstRun, scaffoldFirstRun } from "./first-run.js";
 import { fauxSkip, readFauxScript } from "./faux-glue.js";
 import { autoCompactFromEnv, chat, contextWindowTokens, estimateCtxRatio } from "./chat.js";
 import { loadProjectConfig, loadUserConfig, mergeConfigs, resolveAutoCompact, resolveContextWindow, resolveModel } from "./config.js";
+import { checkForUpdate } from "./update-check.js";
 import { resume } from "./resume.js";
 import { resumeTail } from "./resume-tail.js";
 import { armByteTrace } from "./byte-trace.js";
@@ -229,7 +230,23 @@ function editorInput(editor) {
 /** One input source per process: the raw-mode Editor on a TTY (entered
  *  here, bound to the dock once — the trust question, chat, and resume
  *  all read through it), readline elsewhere. */
+/** The user config's `theme`, read the way the mode is (index.ts's
+ *  `loadUserConfig()?.mode`): the ground is settled inside
+ *  `makeLineInput`, which runs long before `mergedConfig` exists, so the
+ *  merged view is not available and the USER file is the only one that
+ *  may carry it anyway (config.ts rejects a project-level theme LOUDLY).
+ *  A broken config is not this function's business to report — the
+ *  loader is LOUD about that on its own path. */
+function userThemeSetting() {
+    try {
+        return loadUserConfig()?.theme;
+    }
+    catch {
+        return undefined;
+    }
+}
 function makeLineInput() {
+    const userTheme = userThemeSetting();
     if (process.stdin.isTTY) {
         const editor = new Editor(() => (dock.active ? dock.redraw() : editor.selfRender()));
         editor.enter();
@@ -254,22 +271,45 @@ function makeLineInput() {
         // exists FOR the terminals without OSC 11, and could only ever be
         // consulted when an OSC reply had arrived and been malformed. With
         // §3.2 recording that rung 2 is unmeasured, that was the mainline.
-        setGround(resolveGround({ theme: process.env.KISO_THEME, colorfgbg: process.env.COLORFGBG }));
-        // the reply, when there is one, re-walks the ladder WITH it — and
-        // `theme` goes in first again, so an explicit answer still wins.
-        editor.onOsc((reply) => {
-            const next = resolveGround({ theme: process.env.KISO_THEME, osc: reply, colorfgbg: process.env.COLORFGBG });
+        // The two answers accumulate here; whichever arrives first is used
+        // at once, and the ladder decides between them when both have.
+        let osc;
+        let colorScheme;
+        const theme = () => process.env.KISO_THEME ?? userTheme;
+        const rewalk = () => {
+            const next = resolveGround({ theme: theme(), colorScheme, osc, colorfgbg: process.env.COLORFGBG });
+            // DC-3/DC-14's model: the first frame never waits for a reply.
+            // A reply that changes nothing repaints nothing — which is also
+            // why two answers that AGREE cost one repaint and not two.
             if (next === currentGround())
                 return;
             setGround(next);
             body.onGroundChange();
+        };
+        setGround(resolveGround({ theme: theme(), colorfgbg: process.env.COLORFGBG }));
+        // the reply, when there is one, re-walks the ladder WITH it — and
+        // `theme` goes in first again, so an explicit answer still wins.
+        editor.onOsc((reply) => {
+            osc = reply;
+            rewalk();
+        });
+        // …and the terminal's OWN account of its scheme, which outranks the
+        // luminance kiso would infer from a background colour (§3 rung 2).
+        editor.onColorScheme((scheme) => {
+            colorScheme = scheme;
+            rewalk();
         });
         // The query is COLOUR machinery, so it obeys the colour gate: a piped
         // stdout and NO_COLOR both carry zero ANSI, and an OSC written into a
         // pipe would be the first byte to break that. `palette().bold` is the
         // same test the dock activates on — one gate, not a second opinion.
+        // Both questions ride ONE write and ONE gate: `CSI ? 996 n` asks the
+        // terminal to report its colour scheme, OSC 11 asks for its
+        // background colour. Neither is waited on (§3.2) — a terminal that
+        // answers neither leaves the ground `unknown`, which is a supported
+        // palette rather than a failure.
         if (palette().bold !== "" && process.stdout.isTTY)
-            process.stdout.write("\x1b]11;?\x07");
+            process.stdout.write("\x1b[?996n\x1b]11;?\x07");
         // W6: the box's prompt goes light — "› " (the box already says
         // "input lives here"; the line-mode path keeps the brick ▌, so
         // pipe bytes do not change)
@@ -318,6 +358,35 @@ function bannerExtensionText() {
  *  W5 resume list as a LIVE banner cell (W1: the tier re-derives on
  *  resize; the resume list re-gates with the tier); off-TTY: the
  *  historical `[N extensions: ...]` standalone line (zero change). */
+/**
+ * The update line, when there is one, appended after the opening.
+ *
+ * It never blocks: the caller does not await it, and the banner is
+ * already drawn when this starts. If the check fails, times out, is
+ * switched off, or finds nothing newer, this does nothing at all and
+ * says nothing about having tried.
+ */
+async function announceUpdate() {
+    try {
+        const line = await checkForUpdate({ kisoHome: kisoHome(), version: VERSION, isTTY: process.stdout.isTTY === true, faux: currentFaux });
+        if (line === null)
+            return;
+        // THE RAW CHANNEL, not `notice`. A notice renders through ErrorLine,
+        // which calls `escapeTerminal` — so every SGR in it is stripped and
+        // the line could only ever be full-strength prose. The raw channel
+        // is the one the banner itself uses: the styling is applied HERE, at
+        // composition, and the fold keeps the span intact (#16b).
+        //
+        // A turn may have started while the request was in flight. A raw
+        // cell is a cell like any other, so it lands at the transcript's
+        // end — never spliced into a frame the reader is mid-way through.
+        bodyLog(`${palette().dim}${line}${palette().reset}`, "words");
+    }
+    catch {
+        // belt and braces: checkForUpdate does not throw, and if it ever
+        // did, a version check is not a reason to disturb a session.
+    }
+}
 function extensionsBanner(resume = []) {
     const text = bannerExtensionText();
     if (!process.stdout.isTTY) {
@@ -654,6 +723,12 @@ async function chatLoop(agent, firstId, input, autoCompact) {
             // throws on profile drift — so one drifted session anywhere in the
             // history stopped kiso from starting at all.
             extensionsBanner();
+            // The one line the opening may gain (§7.10's ruling): "there is
+            // a newer kiso". FIRED AND FORGOTTEN — the banner above is
+            // already on screen and this never delays it. When the answer
+            // arrives it rides `body.notice`, the commit path notices
+            // already use, rather than a second channel into the frame.
+            void announceUpdate();
         }
         else {
             bodyLog(`session ${id} (switched — previous: ${prev}, /resume ${prev} returns)\n`);

package/dist/update-check.d.ts

@@ -0,0 +1,65 @@
+/**
+ * "There is a newer kiso."
+ *
+ * The owner's ruling on the opening (2026-09-02): no logo, the name is
+ * the mark (§7.10 stands), and the banner may gain AT MOST one line
+ * saying a new version exists. This is that one line's machinery, and
+ * almost all of it is about the things it must not do.
+ *
+ * IT IS kiso's ONLY OUTBOUND REQUEST. Everything else kiso sends goes to
+ * the model endpoint the human configured. This one goes to the public
+ * npm registry, carries no identity, no usage and no session data — a
+ * GET of one dist-tags document — and can be switched off entirely with
+ * `KISO_NO_UPDATE_CHECK=1`. That is a real change in what the product
+ * is, which is why it is stated here rather than buried.
+ *
+ * WHAT IT MUST NEVER DO:
+ *
+ *   - block the first frame. The check is fired and forgotten; the
+ *     opening is drawn from local facts and never waits.
+ *   - say anything when it fails. No network, a proxy, a 500, a
+ *     malformed body, a timeout — all of them are silence. A version
+ *     check that interrupts you to report that it could not check is
+ *     worse than no version check.
+ *   - run where it cannot be wanted: a faux session (the test and demo
+ *     path), a non-TTY (a pipe has no banner to append to), or an
+ *     explicit opt-out.
+ *   - ask twice in a day, or nag about a version it has already
+ *     mentioned. Both are remembered in the cache file.
+ */
+export interface UpdateCache {
+    /** epoch ms of the last COMPLETED check, successful or not */
+    readonly checkedAt: number;
+    /** the latest version the registry reported, if the check succeeded */
+    readonly latest?: string;
+    /** the version already mentioned to this human — never mentioned twice */
+    readonly told?: string;
+}
+/**
+ * Semver-ish "is b newer than a", for the shapes this line ever sees:
+ * three numeric parts, optionally a prerelease we treat as older. A
+ * version we cannot parse is never "newer" — the failure direction is
+ * silence, here as everywhere else in this file.
+ */
+export declare function isNewer(current: string, latest: string): boolean;
+/** The one line, when there is one. Words only — a human can read it,
+ *  paste it, and nothing about it needs colour to be understood (§1.2). */
+export declare const updateLine: (latest: string) => string;
+export interface UpdateCheckDeps {
+    readonly kisoHome: string;
+    readonly version: string;
+    readonly isTTY: boolean;
+    readonly faux: boolean;
+    readonly now?: number;
+}
+/**
+ * Should this launch even ask? Pure, so the reasons are testable without
+ * a network, a clock or a terminal.
+ */
+export declare function shouldCheck(deps: UpdateCheckDeps): boolean;
+/**
+ * The check itself: fire, forget, and resolve to the line to show or
+ * null. NEVER throws, never rejects, never blocks a caller who does not
+ * await it.
+ */
+export declare function checkForUpdate(deps: UpdateCheckDeps): Promise<string | null>;

package/dist/update-check.js

@@ -0,0 +1,191 @@
+/**
+ * "There is a newer kiso."
+ *
+ * The owner's ruling on the opening (2026-09-02): no logo, the name is
+ * the mark (§7.10 stands), and the banner may gain AT MOST one line
+ * saying a new version exists. This is that one line's machinery, and
+ * almost all of it is about the things it must not do.
+ *
+ * IT IS kiso's ONLY OUTBOUND REQUEST. Everything else kiso sends goes to
+ * the model endpoint the human configured. This one goes to the public
+ * npm registry, carries no identity, no usage and no session data — a
+ * GET of one dist-tags document — and can be switched off entirely with
+ * `KISO_NO_UPDATE_CHECK=1`. That is a real change in what the product
+ * is, which is why it is stated here rather than buried.
+ *
+ * WHAT IT MUST NEVER DO:
+ *
+ *   - block the first frame. The check is fired and forgotten; the
+ *     opening is drawn from local facts and never waits.
+ *   - say anything when it fails. No network, a proxy, a 500, a
+ *     malformed body, a timeout — all of them are silence. A version
+ *     check that interrupts you to report that it could not check is
+ *     worse than no version check.
+ *   - run where it cannot be wanted: a faux session (the test and demo
+ *     path), a non-TTY (a pipe has no banner to append to), or an
+ *     explicit opt-out.
+ *   - ask twice in a day, or nag about a version it has already
+ *     mentioned. Both are remembered in the cache file.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** The dist-tags document — the smallest thing the registry will tell us
+ *  that answers the question. The full packument is megabytes. */
+const ENDPOINT = "https://registry.npmjs.org/-/package/@vincemakes/kiso-code/dist-tags";
+const TIMEOUT_MS = 1_500;
+const EVERY_MS = 24 * 60 * 60 * 1_000;
+/** The registry, redirectable for tests ONLY. A stub server's URL goes
+ *  here so the suite can drive every branch — a slow answer, no answer,
+ *  a malformed body — without reaching the network. Never documented for
+ *  users: it is not a setting, it is a seam. */
+const endpoint = () => process.env.KISO_UPDATE_ENDPOINT ?? ENDPOINT;
+const cachePath = (kisoHome) => join(kisoHome, "update-check.json");
+function readCache(kisoHome) {
+    try {
+        const raw = JSON.parse(readFileSync(cachePath(kisoHome), "utf8"));
+        if (raw === null || typeof raw !== "object")
+            return null;
+        const c = raw;
+        if (typeof c.checkedAt !== "number")
+            return null;
+        return {
+            checkedAt: c.checkedAt,
+            ...(typeof c.latest === "string" ? { latest: c.latest } : {}),
+            ...(typeof c.told === "string" ? { told: c.told } : {}),
+        };
+    }
+    catch {
+        // a missing, unreadable or corrupt cache is simply no cache
+        return null;
+    }
+}
+function writeCache(kisoHome, c) {
+    try {
+        mkdirSync(dirname(cachePath(kisoHome)), { recursive: true });
+        writeFileSync(cachePath(kisoHome), `${JSON.stringify(c)}\n`, "utf8");
+    }
+    catch {
+        // an unwritable home means we check again next time — the only
+        // cost is a request, and there is nothing here worth a message.
+    }
+}
+/**
+ * Semver-ish "is b newer than a", for the shapes this line ever sees:
+ * three numeric parts, optionally a prerelease we treat as older. A
+ * version we cannot parse is never "newer" — the failure direction is
+ * silence, here as everywhere else in this file.
+ */
+export function isNewer(current, latest) {
+    const parse = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(v.trim());
+        return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+    };
+    const a = parse(current);
+    const b = parse(latest);
+    if (a === null || b === null)
+        return false;
+    // a prerelease of the same numbers is not newer
+    if (a[0] === b[0] && a[1] === b[1] && a[2] === b[2])
+        return false;
+    for (let i = 0; i < 3; i += 1) {
+        if (b[i] > a[i])
+            return true;
+        if (b[i] < a[i])
+            return false;
+    }
+    return false;
+}
+/** The one line, when there is one. Words only — a human can read it,
+ *  paste it, and nothing about it needs colour to be understood (§1.2). */
+export const updateLine = (latest) => `${latest} is out · npm i -g @vincemakes/kiso-code@latest`;
+/**
+ * Should this launch even ask? Pure, so the reasons are testable without
+ * a network, a clock or a terminal.
+ */
+export function shouldCheck(deps) {
+    return reasonNotToCheck(deps) === null;
+}
+/**
+ * WHY a launch does not ask — and the distinction matters, because only
+ * ONE of these reasons permits the line to be shown from cache.
+ *
+ * "recent" means the request is redundant; the human is still someone
+ * who wants to be told. The other three mean the LINE is unwanted: an
+ * opt-out is an answer about the feature, a faux session is a test or a
+ * demo, and a pipe has no banner — worse, an inactive Body writes a
+ * notice straight to stdout, so showing it there would put a row of
+ * kiso's own prose into piped bytes and break pipe identity.
+ */
+function reasonNotToCheck({ kisoHome, isTTY, faux, now = Date.now() }) {
+    if (process.env.KISO_NO_UPDATE_CHECK === "1")
+        return "opt-out";
+    // A faux session is the test and demo path, and the rule it exists for
+    // is "never reaches the network". The redirect below is a TEST SEAM
+    // pointing at a local stub — where it is set there is no network to
+    // reach, and refusing anyway would make the one behaviour worth
+    // showing on a screen unobservable. In production nothing sets it, so
+    // a faux session still never asks.
+    if (faux && process.env.KISO_UPDATE_ENDPOINT === undefined)
+        return "faux";
+    if (!isTTY)
+        return "not-a-tty"; // and never writes a line into a pipe
+    const cached = readCache(kisoHome);
+    if (cached !== null && now - cached.checkedAt < EVERY_MS)
+        return "recent";
+    return null;
+}
+/**
+ * The check itself: fire, forget, and resolve to the line to show or
+ * null. NEVER throws, never rejects, never blocks a caller who does not
+ * await it.
+ */
+export async function checkForUpdate(deps) {
+    const { kisoHome, version, now = Date.now() } = deps;
+    const why = reasonNotToCheck(deps);
+    if (why !== null) {
+        // ONLY a recent check may still speak. The other three reasons are
+        // about the LINE, not about the request, so the cache is no way
+        // around them — an opt-out that still got announced, or a piped
+        // run that gained a row of kiso's prose, would be the feature
+        // ignoring the answer it was given.
+        if (why !== "recent")
+            return null;
+        const cached = readCache(kisoHome);
+        if (cached?.latest !== undefined && cached.told !== cached.latest && isNewer(version, cached.latest)) {
+            writeCache(kisoHome, { ...cached, told: cached.latest });
+            return updateLine(cached.latest);
+        }
+        return null;
+    }
+    let latest;
+    try {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(endpoint(), { signal: ctl.signal, headers: { accept: "application/json" } });
+            if (res.ok) {
+                const body = await res.json();
+                const tag = body?.latest;
+                if (typeof tag === "string" && tag !== "")
+                    latest = tag;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        // every failure is silence — see the header
+    }
+    const prev = readCache(kisoHome);
+    const show = latest !== undefined && isNewer(version, latest) && prev?.told !== latest;
+    // `told` survives a check that learned nothing: forgetting it would
+    // re-announce a version this human has already been told about.
+    const told = show ? latest : prev?.told;
+    writeCache(kisoHome, {
+        checkedAt: now,
+        ...(latest === undefined ? {} : { latest }),
+        ...(told === undefined ? {} : { told }),
+    });
+    return show && latest !== undefined ? updateLine(latest) : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-code",
-	"version": "0.22.0",
+	"version": "0.23.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.22.0",
-		"@vincemakes/kiso-core": "0.22.0",
-		"@vincemakes/kiso-evals": "0.22.0",
-		"@vincemakes/kiso-mcp-ext": "0.22.0",
-		"@vincemakes/kiso-provider-anthropic": "0.22.0",
-		"@vincemakes/kiso-provider-openai": "0.22.0",
-		"@vincemakes/kiso-runtime": "0.22.0",
-		"@vincemakes/kiso-skills-ext": "0.22.0",
-		"@vincemakes/kiso-subagent-ext": "0.22.0",
-		"@vincemakes/kiso-task-ext": "0.22.0",
-		"@vincemakes/kiso-tools-node": "0.22.0",
-		"@vincemakes/kiso-tui": "0.22.0",
-		"@vincemakes/kiso-tui-cells": "0.22.0"
+		"@vincemakes/kiso-ask-ext": "0.23.0",
+		"@vincemakes/kiso-core": "0.23.0",
+		"@vincemakes/kiso-evals": "0.23.0",
+		"@vincemakes/kiso-mcp-ext": "0.23.0",
+		"@vincemakes/kiso-provider-anthropic": "0.23.0",
+		"@vincemakes/kiso-provider-openai": "0.23.0",
+		"@vincemakes/kiso-runtime": "0.23.0",
+		"@vincemakes/kiso-skills-ext": "0.23.0",
+		"@vincemakes/kiso-subagent-ext": "0.23.0",
+		"@vincemakes/kiso-task-ext": "0.23.0",
+		"@vincemakes/kiso-tools-node": "0.23.0",
+		"@vincemakes/kiso-tui": "0.23.0",
+		"@vincemakes/kiso-tui-cells": "0.23.0"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",