oakode 0.0.0-stage → 0.5.0

package/dist/compact.js

@@ -0,0 +1,231 @@
+import { OickiError } from "./oicki.js";
+import { INTERRUPTED, estimateTokens, repair } from "./session.js";
+export const RESERVE_TOKENS = 16_384;
+/** OICKI rejects requests over 2000 messages or 4,000,000 bytes, which 1M-token models reach before their window fills. */
+export const MAX_MESSAGES = 1900;
+export const MAX_BODY_BYTES = 3_000_000;
+const HARD_MESSAGES = 2000;
+const HARD_BYTES = 4_000_000;
+/** Text size of a request. Images are left out: compaction keeps the newest message, so it cannot shrink them (the client leaves out old images to fit instead). */
+export const bodyBytes = (ctx) => Buffer.byteLength(JSON.stringify(ctx, (k, v) => (k === "images" ? undefined : v)));
+/** Headroom kept free for the reply. Scaled down for small windows: models with 4k-16k windows exist, and a fixed 16k reserve would mean compacting on every request. */
+export const reserveFor = (window) => Math.min(RESERVE_TOKENS, Math.floor(window * 0.25));
+export function shouldCompact(used, window, ctx = []) {
+    if (ctx.length > MAX_MESSAGES || bodyBytes(ctx) > MAX_BODY_BYTES)
+        return true;
+    return !!window && used > window - reserveFor(window);
+}
+/** The request cannot be sent at all as it is (as opposed to merely being large). */
+export function overHardLimits(used, window, ctx) {
+    return ctx.length >= HARD_MESSAGES || bodyBytes(ctx) >= HARD_BYTES || (!!window && used > window - 2_000);
+}
+// ---------------------------------------------------------------- deterministic file tracking
+/** Files read / modified by tool calls that succeeded, accumulated over `prev`. Modified wins over read. */
+export function trackFiles(messages, prev = { read: [], modified: [] }) {
+    const read = new Set(prev.read);
+    const modified = new Set(prev.modified);
+    const ok = new Map();
+    for (const m of messages)
+        if (m.role === "tool")
+            ok.set(m.tool_call_id, !m.content.startsWith("Error:") && m.content !== INTERRUPTED && !m.content.includes("[interrupted by user]"));
+    for (const m of messages) {
+        if (m.role !== "assistant")
+            continue;
+        for (const c of m.tool_calls ?? []) {
+            if (ok.get(c.id) === false)
+                continue;
+            let path;
+            try {
+                path = JSON.parse(c.function.arguments).path;
+            }
+            catch {
+                continue;
+            }
+            if (typeof path !== "string" || !path)
+                continue;
+            const p = path.replace(/^\.\//, "");
+            if (c.function.name === "read")
+                read.add(p);
+            else if (c.function.name === "write" || c.function.name === "edit")
+                modified.add(p);
+        }
+    }
+    for (const p of modified)
+        read.delete(p);
+    return { read: [...read].sort(), modified: [...modified].sort() };
+}
+const msgBytes = (m) => Buffer.byteLength(JSON.stringify(m));
+/** Index in `raw` where the verbatim tail starts, or undefined if there is nothing worth compacting. */
+export function findCut(session, window, aggressive = false) {
+    const raw = session.raw;
+    const keep = aggressive ? Math.floor(window * 0.08) : Math.min(20_000, Math.floor(window * 0.25));
+    const lo = session.keepFrom + 1;
+    const tailStats = (from) => {
+        let tokens = 0, bytes = 0;
+        for (let i = from; i < raw.length; i++) {
+            tokens += estimateTokens(raw[i]);
+            bytes += msgBytes(raw[i]);
+        }
+        return { tokens, bytes, count: raw.length - from };
+    };
+    // 1. walk back until the token / count / byte budget of the tail is used up
+    let cut = raw.length;
+    let tokens = 0, bytes = 0;
+    for (let i = raw.length - 1; i >= lo; i--) {
+        tokens += estimateTokens(raw[i]);
+        bytes += msgBytes(raw[i]);
+        cut = i;
+        if (tokens >= keep || raw.length - i >= 400 || bytes >= 1_500_000)
+            break;
+    }
+    // never separate a tool call from its results. If the budget ran out inside an exchange: summarize the exchange when
+    // something follows it (it is stale), keep it whole only when it is the latest thing the agent still needs.
+    if (raw[cut].role === "tool") {
+        let fwd = cut, back = cut;
+        while (fwd < raw.length && raw[fwd].role === "tool")
+            fwd++;
+        while (back > lo && raw[back].role === "tool")
+            back--;
+        cut = fwd < raw.length ? fwd : back;
+    }
+    if (!(cut >= lo && cut < raw.length))
+        return undefined;
+    // 2. prefer a turn boundary: move back to the user message that started this turn if keeping it whole stays within 2x budget
+    let turnStart = -1;
+    for (let i = cut; i >= lo; i--)
+        if (raw[i].role === "user") {
+            turnStart = i;
+            break;
+        }
+    if (raw[cut].role === "user")
+        return { index: cut, split: false };
+    if (turnStart >= lo) {
+        const t = tailStats(turnStart);
+        if (t.tokens <= keep * 2 && t.count <= 800 && t.bytes <= 2_500_000)
+            return { index: turnStart, split: false };
+    }
+    // 2b. otherwise the next user message, if the tail from there fits the budget (no turn is split; that message stays verbatim)
+    let nextUser = -1;
+    for (let i = cut + 1; i < raw.length; i++)
+        if (raw[i].role === "user") {
+            nextUser = i;
+            break;
+        }
+    if (nextUser > 0) {
+        const t = tailStats(nextUser);
+        if (t.tokens <= keep && t.count <= 400 && t.bytes <= 1_500_000)
+            return { index: nextUser, split: false };
+    }
+    // 3. one huge turn: cut inside it and keep the request that started it
+    let request;
+    for (let i = cut - 1; i >= session.keepFrom; i--) {
+        const m = raw[i];
+        if (m.role === "user" && !String(m.content).startsWith("[OAKODE notice]")) {
+            request = m.content;
+            break;
+        }
+    }
+    request ??= session.request; // the turn began before an earlier compaction
+    return { index: cut, split: true, request: request ? clipMiddle(request, 6000) : undefined };
+}
+const clipMiddle = (s, n) => (s.length <= n ? s : s.slice(0, n / 2) + "\n…[middle omitted]…\n" + s.slice(-n / 2));
+// ---------------------------------------------------------------- summarizing
+const SECTIONS = `Use these sections:
+## Goal
+## Constraints & preferences
+## Progress (done / in progress)
+## Key decisions
+## Important tool results (errors, test output, facts that matter)
+## Next steps
+Be concrete and preserve exact paths, names, commands and error messages, but stay concise (under 600 words in total). Do not list files read/modified (tracked separately). Output only the summary.`;
+const INITIAL = `Summarize the conversation above so a coding agent can continue the work without it.\n${SECTIONS}`;
+const UPDATE = `Update the previous summary using the new conversation above. Keep everything in the previous summary that still matters, add new progress, decisions and results, and remove what is now obsolete or finished. Do not drop open tasks or constraints.\n${SECTIONS}`;
+function serialize(messages, maxChars) {
+    const parts = messages.map((m) => {
+        if (m.role === "tool")
+            return `[tool result]\n${m.content.length > 3000 ? m.content.slice(0, 1500) + "\n…[trimmed]…\n" + m.content.slice(-1500) : m.content}`;
+        if (m.role === "assistant") {
+            const calls = (m.tool_calls ?? []).map((c) => `[call ${c.function.name}(${c.function.arguments.slice(0, 600)})]`).join("\n");
+            return `[assistant]\n${m.content ?? ""}\n${calls}`.trim();
+        }
+        return `[${m.role}]\n${m.content}`;
+    });
+    return clipMiddle(parts.join("\n\n"), maxChars);
+}
+/**
+ * The instruction appended to the agent's own request for a cached compaction: the model sees the conversation as it
+ * is (not a clipped copy), and the boundary is named by how many recent messages stay.
+ */
+export function cachedInstruction(update, firstKept, split) {
+    const quote = firstKept?.replace(/\s+/g, " ").trim().slice(0, 120);
+    const boundary = quote
+        ? `Everything above before the ${split ? "message" : "user message"} that begins «${quote}» is about to be replaced by your summary; that message and everything after it stay verbatim (if unsure where it is, include it in the summary).${split ? " The user's request that started this turn is kept verbatim too." : ""}`
+        : "Everything above is about to be replaced by your summary.";
+    return (`Context compaction (from OAKODE, not the user). ${boundary} ` +
+        `That includes every tool result in it: what you learned from files and commands is lost unless you write it down. ` +
+        (update ? "The summary at the start of the conversation is the earlier one: carry over everything in it that still matters, then add what happened since. " : "") +
+        `Write a handoff summary for yourself to continue the user's work: the overall goal from the user's first request on (not only the latest question), ` +
+        `every request that is still open (a request is done only if its answer was actually given to the user), constraints and preferences, what was done and decided, ` +
+        `what each file you read or command you ran showed that you will still need (exact paths, names, signatures, values, commands, errors), and the next steps. ` +
+        `Be thorough rather than brief: use the word budget when there is much to keep. Do not call any tools and do not continue the task: reply with the summary only.\n` +
+        SECTIONS);
+}
+/** The text of a message, for naming it. */
+const textOf = (m) => (!m ? undefined : typeof m.content === "string" && m.content.trim() ? m.content : m.role === "assistant" && m.tool_calls?.length ? `[call ${m.tool_calls[0].function.name}(${m.tool_calls[0].function.arguments.slice(0, 80)})]` : undefined);
+async function summarize(client, model, previous, old, maxChars, maxTokens, signal) {
+    const prompt = previous
+        ? `<previous-summary>\n${previous}\n</previous-summary>\n\n<new-conversation>\n${serialize(old, maxChars)}\n</new-conversation>\n\n${UPDATE}`
+        : `<conversation>\n${serialize(old, maxChars)}\n</conversation>\n\n${INITIAL}`;
+    return client.chat({
+        model,
+        maxTokens: maxTokens ? Math.min(4096, maxTokens) : undefined,
+        signal,
+        messages: [
+            { role: "system", content: "You write precise summaries of coding sessions." },
+            { role: "user", content: prompt },
+        ],
+    });
+}
+export async function compact(client, session, model, window, signal, aggressive = false, maxTokens, 
+/** Sends the agent's next request plus this instruction (a cache hit); undefined when that request would not fit. */
+viaCache, onUsage) {
+    const cut = findCut(session, window, aggressive);
+    if (!cut)
+        return undefined;
+    const before = session.estimateTokens();
+    const old = repair(session.raw.slice(session.keepFrom, cut.index));
+    const counted = (r) => (r.usage && onUsage?.(r.usage, r.model ?? model), r);
+    let cached;
+    let refused = false;
+    if (viaCache) {
+        cached = await viaCache(cachedInstruction(!!session.summary, textOf(session.raw[cut.index]), cut.split)).then(counted, (e) => {
+            if (signal?.aborted)
+                throw e;
+            return undefined; // the separate request below still works
+        });
+        if (cached?.aborted)
+            return undefined;
+        // a reply that is not a whole summary (a tool call, nothing, cut off) is not used
+        if (cached && (cached.tool_calls.length || !cached.content.trim() || cached.finish_reason === "length"))
+            (cached = undefined), (refused = true);
+    }
+    if (cached) {
+        session.compact(cached.content.trim(), cut.index, trackFiles(old, session.files), cut.split ? cut.request : undefined);
+        return { before, after: session.estimateTokens(), split: cut.split, cached: true };
+    }
+    let maxChars = Math.min(1_500_000, Math.max(20_000, (window - 20_000) * 3));
+    let res = await summarize(client, model, session.summary, old, maxChars, maxTokens, signal).then(counted).catch(async (e) => {
+        // Refused as too long: documented as unbilled, so shrinking the input and asking once more is safe.
+        if (e instanceof OickiError && e.code === "context_length_exceeded") {
+            maxChars = Math.floor(maxChars / 3);
+            return summarize(client, model, session.summary, old, maxChars, maxTokens, signal).then(counted);
+        }
+        throw e;
+    });
+    if (res.aborted)
+        return undefined;
+    if (!res.content.trim() || res.finish_reason === "length")
+        throw new Error(res.finish_reason === "length" ? "Summarization hit its output limit before finishing; history left untouched." : "Summarization produced no usable summary; history left untouched.");
+    session.compact(res.content.trim(), cut.index, trackFiles(old, session.files), cut.split ? cut.request : undefined);
+    return { before, after: session.estimateTokens(), split: cut.split, cached: false, refused };
+}

package/dist/config.js

@@ -0,0 +1,82 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const VERSION = "0.5.0";
+export const DEFAULT_BASE_URL = "https://oicki.vercel.app";
+/**
+ * The OAKODE service's id in OICKI ("Sign in with OICKI" client id; public, not a secret). Its redirect URIs must be
+ * http://localhost:8976/callback, :8977/callback and :8978/callback (OICKI rewrites 127.0.0.1 to localhost; the
+ * 127.0.0.1 forms are registered too). Registered 2026-10-29; with it,
+ * `oakode login` needs no flags. OAKODE_CLIENT_ID or `clientId` in the config override it.
+ */
+export const DEFAULT_CLIENT_ID = "74fa0e931cea469f";
+/** First loopback port for the sign-in callback (OICKI matches redirect URIs exactly; the next two are fallbacks). */
+export const DEFAULT_REDIRECT_PORT = 8976;
+export const home = () => process.env.OAKODE_HOME || join(homedir(), ".oakode");
+export function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Atomic write; `secret` files are 0600. */
+export function writeJson(file, data, secret = false) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: secret ? 0o600 : 0o644 });
+        if (secret)
+            chmodSync(tmp, 0o600);
+        renameRetry(tmp, file);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true }); // never leave a copy (of credentials, say) behind
+        throw e;
+    }
+}
+/**
+ * rename(), retried for about a second on Windows, where a virus scanner or indexer briefly holding the new file makes
+ * it fail with EPERM/EACCES/EBUSY.
+ */
+export function renameRetry(from, to) {
+    for (let i = 0;; i++) {
+        try {
+            return renameSync(from, to);
+        }
+        catch (e) {
+            const code = e.code;
+            if (process.platform !== "win32" || i >= 20 || !["EPERM", "EACCES", "EBUSY"].includes(code ?? ""))
+                throw e;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
+    }
+}
+export const configFile = () => join(home(), "config.json");
+export const loadConfig = () => readJson(configFile()) ?? {};
+/** Why config.json is being ignored (it exists but is not a JSON object), or undefined. It is edited by hand. */
+export function configProblem() {
+    let text;
+    try {
+        text = readFileSync(configFile(), "utf8");
+    }
+    catch {
+        return undefined; // no file: defaults
+    }
+    try {
+        const v = JSON.parse(text);
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return undefined;
+    }
+    catch { }
+    return `${configFile()} is not a valid JSON object, so it is ignored and default settings are used. Fix it (e.g. a trailing comma) or delete it.`;
+}
+/** Saving never replaces a hand-edited file that does not parse: that would silently drop the person's settings. */
+export const saveConfig = (patch) => {
+    const problem = configProblem();
+    if (problem)
+        throw new Error(`Not saved: ${problem}`);
+    writeJson(configFile(), { ...loadConfig(), ...patch }, true);
+};
+export const baseUrl = () => (process.env.OAKODE_BASE_URL || loadConfig().baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");

package/dist/diff.js

@@ -0,0 +1,98 @@
+/** Real unified diffs of proposed file changes (computed from the actual before/after text, never from the model's description). */
+import { structuredPatch } from "diff";
+import { bold, dim, green, red, reveal, truncate, width, wrap } from "./ui.js";
+const CONTEXT = 3;
+/** `oldText` is null for a file that does not exist yet. Both texts use \n line endings. */
+export function makeDiff(path, oldText, newText) {
+    const oldStr = oldText ?? "";
+    let hunks;
+    let coarse = false;
+    if (oldStr.length + newText.length < 2_000_000) {
+        try {
+            const p = structuredPatch(path, path, oldStr, newText, "", "", { context: CONTEXT, timeout: 3000 });
+            if (p)
+                hunks = p.hunks.map(toHunk);
+        }
+        catch { }
+    }
+    if (!hunks) {
+        coarse = true;
+        hunks = [coarseHunk(oldStr, newText)];
+    }
+    let added = 0, removed = 0;
+    for (const h of hunks)
+        for (const l of h.lines)
+            l.t === "+" ? added++ : l.t === "-" ? removed++ : 0;
+    return { path, isNew: oldText === null, added, removed, hunks, ...(coarse ? { coarse } : {}) };
+}
+function toHunk(h) {
+    let o = h.oldStart, n = h.newStart;
+    const lines = [];
+    for (const raw of h.lines) {
+        const c = raw[0];
+        if (c === "\\")
+            continue; // ""
+        const text = raw.slice(1);
+        if (c === "+")
+            lines.push({ t: "+", text, newNo: n++ });
+        else if (c === "-")
+            lines.push({ t: "-", text, oldNo: o++ });
+        else
+            lines.push({ t: " ", text, oldNo: o++, newNo: n++ });
+    }
+    // unified-diff convention: an empty side starts at the line BEFORE the change (jsdiff reports 1 for an empty file)
+    return { oldStart: h.oldLines === 0 ? h.oldStart - 1 : h.oldStart, oldLines: h.oldLines, newStart: h.newLines === 0 ? h.newStart - 1 : h.newStart, newLines: h.newLines, lines };
+}
+function coarseHunk(a, b) {
+    const x = a.split("\n"), y = b.split("\n");
+    let s = 0;
+    while (s < x.length && s < y.length && x[s] === y[s])
+        s++;
+    let e = 0;
+    while (e < x.length - s && e < y.length - s && x[x.length - 1 - e] === y[y.length - 1 - e])
+        e++;
+    const lines = [];
+    x.slice(s, x.length - e).forEach((t, i) => lines.push({ t: "-", text: t, oldNo: s + i + 1 }));
+    y.slice(s, y.length - e).forEach((t, i) => lines.push({ t: "+", text: t, newNo: s + i + 1 }));
+    return { oldStart: s + 1, oldLines: x.length - s - e, newStart: s + 1, newLines: y.length - s - e, lines };
+}
+/** Colored unified diff for `cols` columns. At most `maxLines` lines are returned; `hidden` counts what was cut. */
+export function renderDiff(d, cols, maxLines = Infinity) {
+    const maxNo = Math.max(1, ...d.hunks.flatMap((h) => h.lines.map((l) => l.newNo ?? l.oldNo ?? 0)));
+    const gw = String(maxNo).length;
+    const out = [];
+    out.push(`${bold(reveal(d.path))}  ${green("+" + d.added)} ${red("−" + d.removed)}${d.isNew ? dim("  (new file)") : ""}${d.coarse ? dim("  (large file: approximate diff)") : ""}`);
+    for (const h of d.hunks) {
+        out.push(dim(`@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@`));
+        for (const l of h.lines) {
+            const no = String(l.t === "-" ? l.oldNo : l.newNo).padStart(gw);
+            const sign = l.t === "+" ? "+" : l.t === "-" ? "−" : " ";
+            const style = l.t === "+" ? green : l.t === "-" ? red : dim;
+            const bodyW = Math.max(10, cols - gw - 4);
+            const pieces = wrap(reveal(l.text), bodyW); // invisible and bidi characters shown, so a diff cannot hide code
+            pieces.forEach((p, i) => out.push(style(`${i === 0 ? no : " ".repeat(gw)} ${i === 0 ? sign : " "} `) + (l.t === " " ? dim(p) : style(p))));
+        }
+    }
+    if (d.dropped)
+        out.push(dim(`… ${d.dropped} more changed lines not stored`));
+    if (out.length > maxLines)
+        return { lines: out.slice(0, maxLines).map((l) => truncate(l, cols)), hidden: out.length - maxLines };
+    return { lines: out.map((l) => (width(l) > cols ? truncate(l, cols) : l)), hidden: 0 };
+}
+/** Bound what is stored in the session file: at most `max` diff lines per change. */
+export function capDiff(d, max = 2000) {
+    let left = max;
+    let dropped = 0;
+    const hunks = [];
+    for (const h of d.hunks) {
+        if (left <= 0) {
+            dropped += h.lines.length;
+            continue;
+        }
+        const keep = h.lines.slice(0, left);
+        dropped += h.lines.length - keep.length;
+        left -= keep.length;
+        hunks.push({ ...h, lines: keep });
+    }
+    return dropped ? { ...d, hunks, dropped } : d;
+}

package/dist/doctor.js

@@ -0,0 +1,106 @@
+/** `oakode doctor`: checks the installation, credentials and connection. Every request it makes is free. */
+import { allowedModel, experimentalModels } from "./models.js";
+import { configProblem } from "./config.js";
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { billingLines } from "./account.js";
+import { clientIdSetting, isRemoteSession } from "./auth.js";
+import { VERSION, baseUrl, home, loadConfig } from "./config.js";
+import { trustedExecutable } from "./fileio.js";
+import { shell } from "./shell.js";
+import { bold, dim, green, red, yellow } from "./ui.js";
+import { updateCheckEnabled, updateNotice } from "./update.js";
+const mark = { ok: green("✓"), warn: yellow("!"), fail: red("✗") };
+export async function doctor(auth, client, cwd) {
+    let failed = false;
+    const line = (r, what, detail = "") => {
+        if (r === "fail")
+            failed = true;
+        console.log(`${mark[r]} ${what}${detail ? dim(`  ${detail}`) : ""}`);
+    };
+    console.log(bold(`OAKODE ${VERSION} doctor`));
+    const major = Number(process.versions.node.split(".")[0]);
+    line(major >= 22 ? "ok" : "fail", `Node.js ${process.versions.node}`, major >= 22 ? "" : "OAKODE needs Node.js 22 or newer");
+    line("ok", `Platform ${process.platform} ${process.arch}`, process.stdout.isTTY ? `terminal ${process.stdout.columns}x${process.stdout.rows}, TERM=${process.env.TERM ?? "?"}` : "not a terminal");
+    // data directory and credentials file
+    const dir = home();
+    try {
+        const st = statSync(dir);
+        const loose = process.platform !== "win32" && (st.mode & 0o077) !== 0;
+        line(loose ? "warn" : "ok", `Data directory ${dir}`, loose ? `readable by other users (mode ${(st.mode & 0o777).toString(8)}); run: chmod 700 "${dir}"` : "");
+    }
+    catch {
+        line("ok", `Data directory ${dir}`, "not created yet");
+    }
+    const cp = configProblem();
+    if (cp)
+        line("fail", "config.json cannot be read", cp);
+    try {
+        const st = statSync(join(dir, "auth.json"));
+        if (process.platform !== "win32" && (st.mode & 0o077))
+            line("fail", "Credentials file is readable by other users", `run: chmod 600 "${join(dir, "auth.json")}"`);
+    }
+    catch { }
+    // credentials
+    const src = auth.source();
+    if (src === "none")
+        line("fail", "Not signed in", "run `oakode login` (or `oakode login --api-key`)");
+    else if (src === "oauth") {
+        const exp = auth.expiresAt() ?? 0;
+        line("ok", `Signed in with OICKI`, `scopes: ${auth.scopes().join(" ")}; access token ${exp > Date.now() ? "valid" : "expired (refreshed on next use)"}`);
+        if (!auth.scopes().includes("billing:read"))
+            line("warn", "Credits are not visible", "the sign-in did not include billing:read; run `oakode login` again to grant it");
+    }
+    else
+        line("ok", `API key ${src === "env" ? "from OICKI_API_KEY" : "stored"}`, "credits are not visible with an API key");
+    const server = auth.storedServer();
+    if (src !== "env" && server && server.replace(/\/+$/, "") !== baseUrl())
+        line("fail", `Saved sign-in is for ${server}`, `but OAKODE is using ${baseUrl()}`);
+    // connection: health is unauthenticated, models proves the credentials
+    const t0 = Date.now();
+    try {
+        const r = await fetch(`${baseUrl()}/api/health`, { signal: AbortSignal.timeout(10_000) });
+        line(r.ok ? "ok" : "fail", `OICKI reachable at ${baseUrl()}`, `HTTP ${r.status}, ${Date.now() - t0} ms`);
+    }
+    catch (e) {
+        line("fail", `Cannot reach ${baseUrl()}`, e.message);
+    }
+    if (src !== "none") {
+        try {
+            const models = await client.listModels(AbortSignal.timeout(20_000));
+            const want = loadConfig().model ?? "auto";
+            line("ok", `Credentials accepted; ${models.length} models available`);
+            if (!models.some((m) => m.id === want))
+                line("warn", `Default model "${want}" is not in the list`, "choose another with /model");
+            else if (!allowedModel(want))
+                line("warn", `Default model "${want}" is not a supported model; new sessions use auto`, "choose one with /model, or allow it with \"experimentalModels\": true in config.json");
+            if (experimentalModels())
+                line("warn", "Experimental models are on", "models outside the supported list can be chosen; they are unsupported");
+        }
+        catch (e) {
+            line("fail", "Credentials not accepted or model list unavailable", e.message);
+        }
+        if (auth.kind() === "oauth") {
+            try {
+                const b = await client.billing(AbortSignal.timeout(10_000));
+                for (const l of billingLines(b, "oauth"))
+                    console.log(`  ${l}`);
+                if (b && (b.state === "exhausted" || b.state === "no_plan" || b.state === "past_due"))
+                    line("fail", "The account cannot pay for requests", b.headline);
+            }
+            catch (e) {
+                line("warn", "Could not read credits", e.message);
+            }
+        }
+    }
+    // sign-in and tools
+    if (src !== "env")
+        line(clientIdSetting() ? "ok" : "warn", "Browser sign-in", clientIdSetting() ? (isRemoteSession() ? "remote session: `oakode login` prints the link and an ssh -L hint" : "available") : "no OICKI client id in this build; use `oakode login --api-key`");
+    line(trustedExecutable("git", cwd) ? "ok" : "warn", "git", trustedExecutable("git", cwd) ? "" : "not found: search cannot apply .gitignore");
+    line(trustedExecutable("python3", cwd) ? "ok" : "warn", "python3", trustedExecutable("python3", cwd) ? "" : "not found: Python files are not syntax-checked after edits");
+    const sh = shell();
+    line(sh.posix ? "ok" : "warn", `Commands run with ${sh.name}`, sh.posix ? "" : "models write POSIX shell commands; install Git for Windows for bash");
+    const n = updateCheckEnabled() ? updateNotice() : undefined;
+    line(n ? "warn" : "ok", n ?? "No newer version known", updateCheckEnabled() ? "" : "update check off (CI, not a terminal, or OAKODE_NO_UPDATE_CHECK)");
+    return !failed;
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+import { OickiError } from "./oicki.js";
+import { dim, red, yellow } from "./ui.js";
+/** One user-facing description of any error: what happened, what to do, and the request id for support. */
+export function explain(e) {
+    if (e instanceof OickiError) {
+        return [red(`Error (${e.code}${e.status ? `, HTTP ${e.status}` : ""}): ${e.message}`), e.hint && yellow(e.hint), e.requestId && dim(`request id: ${e.requestId}`)]
+            .filter(Boolean)
+            .join("\n");
+    }
+    // fetch() only says "fetch failed"; the reason (DNS, refused, TLS, proxy) is in `cause`
+    const cause = e?.cause;
+    if (e?.message === "fetch failed")
+        return [red(`Error: could not reach the server${cause ? ` (${cause.code ?? cause.message})` : ""}.`), yellow("Check your connection or proxy; `oakode doctor` tests it.")].join("\n");
+    return red(`Error: ${e.message}`);
+}