@vincemakes/kiso-core 0.39.2 → 0.40.0

package/dist/errors.d.ts

@@ -27,8 +27,8 @@ export declare function mapApiError(status: number | undefined, message: string,
  * run on a verdict nobody issued.
  *
  * Deliberately broader than what can be proven transient: a permanent
- * fault misclassified here costs `maxRetries` extra requests (2 by
- * default) and then ends in the same terminal it would have anyway,
+ * fault misclassified here costs the retry budget in extra requests and
+ * then ends in the same terminal it would have anyway,
  * while a transient one misclassified the other way costs the whole
  * session. The asymmetry is the argument.
  *
@@ -36,3 +36,14 @@ export declare function mapApiError(status: number | undefined, message: string,
  * mapping — `mapApiError` is untouched and stays the authority there.
  */
 export declare function streamFailure(message: string): StructuredError;
+/**
+ * A connection that failed BEFORE a response. Retryable — a refused or
+ * reset connection is what a restarting gateway looks like — with one
+ * exception: a host name that does not EXIST (ENOTFOUND, anywhere on the
+ * cause chain). That is a misconfigured baseUrl, not a provider's
+ * health, and the retry budget would spend minutes confirming a typo. It
+ * fails at once, saying so. The code stays `network`: the
+ * error codes are a persisted, closed set, and the difference is the
+ * retry decision, which is what `retryable` is.
+ */
+export declare function connectionFailure(err: unknown, message: string): StructuredError;

package/dist/errors.js

@@ -26,6 +26,11 @@ export function parseRetryAfter(value, now = Date.now()) {
     const ms = at - now;
     return ms >= 0 ? ms : undefined;
 }
+/** ADR-0055 §3: how the providers word a refused context — openai-compat's
+ *  "maximum context length" / `context_length_exceeded`, Anthropic's
+ *  "prompt is too long". That 400 is an overflow, not a malformed request:
+ *  the kernel compacts once and retries once. */
+const CONTEXT_TOO_LONG = /maximum context length|context_length_exceeded|prompt is too long|context window/i;
 export function mapApiError(status, message, retryAfterMs) {
     const withStatus = (e) => ({
         ...e,
@@ -43,7 +48,7 @@ export function mapApiError(status, message, retryAfterMs) {
         case 529:
             return withStatus({ code: "overloaded", retryable: true, message });
         case 400:
-            return withStatus({ code: "invalid_request", retryable: false, message });
+            return withStatus({ code: CONTEXT_TOO_LONG.test(message) ? "context_overflow" : "invalid_request", retryable: false, message });
         default:
             if (status !== undefined && status >= 500 && status < 600) {
                 // D4: every 500-599 is api_5xx and retryable.
@@ -66,8 +71,8 @@ export function mapApiError(status, message, retryAfterMs) {
  * run on a verdict nobody issued.
  *
  * Deliberately broader than what can be proven transient: a permanent
- * fault misclassified here costs `maxRetries` extra requests (2 by
- * default) and then ends in the same terminal it would have anyway,
+ * fault misclassified here costs the retry budget in extra requests and
+ * then ends in the same terminal it would have anyway,
  * while a transient one misclassified the other way costs the whole
  * session. The asymmetry is the argument.
  *
@@ -77,3 +82,23 @@ export function mapApiError(status, message, retryAfterMs) {
 export function streamFailure(message) {
     return { code: "network", retryable: true, message };
 }
+/**
+ * A connection that failed BEFORE a response. Retryable — a refused or
+ * reset connection is what a restarting gateway looks like — with one
+ * exception: a host name that does not EXIST (ENOTFOUND, anywhere on the
+ * cause chain). That is a misconfigured baseUrl, not a provider's
+ * health, and the retry budget would spend minutes confirming a typo. It
+ * fails at once, saying so. The code stays `network`: the
+ * error codes are a persisted, closed set, and the difference is the
+ * retry decision, which is what `retryable` is.
+ */
+export function connectionFailure(err, message) {
+    for (let e = err, depth = 0; e !== null && typeof e === "object" && depth < 5; e = e.cause, depth += 1) {
+        const code = e.code;
+        // EAI_AGAIN is not here: "temporary failure in name resolution" is a
+        // DNS server's blip by definition, and keeps the budget.
+        if (code === "ENOTFOUND")
+            return { code: "network", retryable: false, message: `${message} (the host name did not resolve — check the baseUrl)` };
+    }
+    return { code: "network", retryable: true, message };
+}

package/dist/kernel/compaction.js

@@ -35,13 +35,32 @@ const NON_TEXT_BLOCK_TOKENS = 8;
  */
 function contentTokens(content) {
     if (typeof content === "string")
-        return Math.ceil(content.length / 4);
+        return textTokens(content);
     let tokens = 0;
     for (const block of content) {
-        tokens += block.type === "text" ? Math.ceil(block.text.length / 4) : NON_TEXT_BLOCK_TOKENS;
+        tokens += block.type === "text" ? textTokens(block.text) : NON_TEXT_BLOCK_TOKENS;
     }
     return tokens;
 }
+/**
+ * 0.40.0 (the owner's session): chars/4, except that a CJK character counts
+ * as one token — which is about what a tokenizer spends on one. Plain
+ * chars/4 read a Chinese-heavy 730k context as ~470k, so the thresholds
+ * never fired and the ctx row lied. Text without CJK scores exactly what
+ * it scored before. A counting loop, not a regex match: the text can be
+ * megabytes, and a match array would hold one entry per character.
+ */
+function textTokens(text) {
+    let cjk = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        // kana, CJK ext A, unified ideographs, Hangul syllables,
+        // compatibility ideographs, full-width forms
+        if ((c >= 0x3040 && c <= 0x30ff) || (c >= 0x3400 && c <= 0x4dbf) || (c >= 0x4e00 && c <= 0x9fff) || (c >= 0xac00 && c <= 0xd7af) || (c >= 0xf900 && c <= 0xfaff) || (c >= 0xff00 && c <= 0xffef))
+            cjk++;
+    }
+    return cjk + Math.ceil((text.length - cjk) / 4);
+}
 /**
  * Rough token estimate (chars/4 + structural overhead). Calibration-free on
  * purpose: context economy only needs a stable MONOTONE proxy, not an exact
@@ -59,8 +78,8 @@ export function estimateTokens(messages) {
             for (const block of msg.blocks) {
                 total +=
                     block.type === "text"
-                        ? Math.ceil(block.text.length / 4)
-                        : Math.ceil(JSON.stringify(block.input).length / 4) + 20;
+                        ? textTokens(block.text)
+                        : textTokens(JSON.stringify(block.input)) + 20;
             }
         }
         else {

package/dist/kernel/hooks.d.ts

@@ -43,6 +43,21 @@ export interface HookHost {
     onPause?(reason: string, ctx: HookContext): Promise<void>;
     /** Lifecycle: the loop is about to stop. */
     onStop?(reason: string, ctx: HookContext): Promise<void>;
+    /** Lifecycle: the loop is about to WAIT and retry the model request
+     *  (ADR-0005 Amendment 2). Observation only — it cannot change the
+     *  decision, it writes nothing, and a throw is swallowed. */
+    onRetry?(info: RetryInfo, ctx: HookContext): Promise<void>;
+}
+/** What a retry is, as the loop announces it: the attempt about to be
+ *  made, the budget it is counted against, the classified error code,
+ *  the wait before it, and whether a draft had already streamed (a
+ *  mid-stream retry voids that draft first — ADR-0005 Amendment 1). */
+export interface RetryInfo {
+    readonly attempt: number;
+    readonly maxRetries: number;
+    readonly code: string;
+    readonly delayMs: number;
+    readonly midStream: boolean;
 }
 /** Every hook optional; unset = pass-through. The kernel runs with this. */
 export declare const NoOpHooks: HookHost;

package/dist/kernel/loop.d.ts

@@ -70,17 +70,14 @@ export interface LoopConfig {
     /** The run's event log. Pass the session's log to make this run durable. */
     readonly log?: EventLog;
     /**
-     * C area: MICROCOMPACT — when the projected context exceeds the threshold,
-     * append ONE durable `microcompacted` boundary (clearing compactable tool
-     * results older than the recent turns). The decision is a persisted fact:
-     * the projection derives the same cleared view from the same events,
-     * byte for byte, across crash/resume. Never a per-turn progressive
-     * clearing.
+     * ADR-0055 (A1b): the COMPACTION POINT — called before every request with
+     * the log and the messages about to be sent. It returns the durable facts
+     * to append (a `summarized` boundary, a `microcompacted` prune), or none.
+     * The kernel appends and yields them and re-derives; it keeps no policy.
+     * `why` is "overflow" once, after the provider refused the context: a
+     * run that gets nothing back then ends on that refusal.
      */
-    readonly microcompact?: {
-        readonly thresholdTokens: number;
-        readonly keepResults?: number;
-    };
+    readonly compact?: (events: readonly Event[], messages: readonly Message[], why: "request" | "overflow") => Promise<readonly EventInput[]>;
     readonly signal?: AbortSignalLike;
     readonly temperature?: number;
     readonly maxTokens?: number;
@@ -134,10 +131,24 @@ export interface LoopConfig {
  * as they were, and one line says what changed.
  */
 export declare const DEFAULT_MAX_TURNS: number;
-export declare const DEFAULT_MAX_RETRIES = 2;
+/** ADR-0005 Amendment 2: ten, about 2.7 minutes of backoff before a turn
+ *  gives up. It was 2 — three attempts inside 750 ms, which is no budget
+ *  at all against a gateway that drops a stream and comes back. */
+export declare const DEFAULT_MAX_RETRIES = 10;
 /** CX-1 F8: the longest Retry-After the kernel will honor; beyond it the
  *  run stops with an explicit error rather than waiting or retrying early. */
 export declare const RETRY_AFTER_MAX_MS = 60000;
+/**
+ * ADR-0005 Amendment 2 — the n-th retry's delay: exponential from 500 ms,
+ * capped at 32 s, plus up to 25% of that as jitter, and never shorter than
+ * the provider's Retry-After. 0.5 / 1 / 2 / 4 / 8 / 16 / 32 … seconds.
+ *
+ * It replaced `max(n × 250 ms, Retry-After)` (CX-1 F8), under which the
+ * whole default budget was spent in 750 ms. The jitter keeps many sessions
+ * behind one gateway from retrying in lockstep. `random` is a parameter so
+ * the curve can be asserted; the loop uses the real one.
+ */
+export declare function retryDelayMs(n: number, retryAfterMs?: number, random?: () => number): number;
 export declare function loop(config: LoopConfig): AsyncGenerator<Event>;
 /**
  * Adapter exceptions → StructuredError. Anything already shaped like one

package/dist/kernel/loop.js

@@ -33,7 +33,6 @@
  * re-stream that duplicates output or tool calls.
  */
 import { isAdapterEvent } from "../protocol/adapter.js";
-import { estimateTokens } from "./compaction.js";
 import { EventLog } from "./event-log.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { validateArgs } from "../tools/validate.js";
@@ -61,10 +60,27 @@ import { messagesToEvents, MICROCOMPACTABLE, DO_NOT_COMPACT, projectMessages } f
  * as they were, and one line says what changed.
  */
 export const DEFAULT_MAX_TURNS = Number.POSITIVE_INFINITY;
-export const DEFAULT_MAX_RETRIES = 2;
+/** ADR-0005 Amendment 2: ten, about 2.7 minutes of backoff before a turn
+ *  gives up. It was 2 — three attempts inside 750 ms, which is no budget
+ *  at all against a gateway that drops a stream and comes back. */
+export const DEFAULT_MAX_RETRIES = 10;
 /** CX-1 F8: the longest Retry-After the kernel will honor; beyond it the
  *  run stops with an explicit error rather than waiting or retrying early. */
 export const RETRY_AFTER_MAX_MS = 60_000;
+/**
+ * ADR-0005 Amendment 2 — the n-th retry's delay: exponential from 500 ms,
+ * capped at 32 s, plus up to 25% of that as jitter, and never shorter than
+ * the provider's Retry-After. 0.5 / 1 / 2 / 4 / 8 / 16 / 32 … seconds.
+ *
+ * It replaced `max(n × 250 ms, Retry-After)` (CX-1 F8), under which the
+ * whole default budget was spent in 750 ms. The jitter keeps many sessions
+ * behind one gateway from retrying in lockstep. `random` is a parameter so
+ * the curve can be asserted; the loop uses the real one.
+ */
+export function retryDelayMs(n, retryAfterMs, random = Math.random) {
+    const base = Math.min(500 * 2 ** (n - 1), 32_000);
+    return Math.max(retryAfterMs ?? 0, Math.round(base + random() * 0.25 * base));
+}
 export async function* loop(config) {
     const log = config.log ?? new EventLog();
     const hooks = config.hooks ?? NoOpHooks;
@@ -456,7 +472,11 @@ export async function* loop(config) {
         })());
     };
     let turns = 0;
-    while (true) {
+    // ADR-0055 §3: the provider's refusal of the context, held for ONE
+    // compaction and ONE retry; a second refusal ends the run as before.
+    let overflow = null;
+    let overflowRetried = false;
+    turn: while (true) {
         if (aborted()) {
             yield await terminal({ kind: "aborted", by: "user" });
             return;
@@ -466,16 +486,22 @@ export async function* loop(config) {
             return;
         }
         turns += 1;
-        // ── C area: one-shot microcompact boundary when over the threshold ──
-        if (config.microcompact !== undefined && estimateTokens(messages) > config.microcompact.thresholdTokens) {
-            const beforeSeq = microcompactBoundarySeq(log.all, config.microcompact.keepResults ?? KEEP_COMPACTABLE_RESULTS);
-            if (beforeSeq !== undefined) {
-                const full = log.append({ type: "microcompacted", beforeSeq });
+        // ── ADR-0055 (A1b): the compaction point, before every request ──
+        if (config.compact !== undefined) {
+            const added = await config.compact(log.all, messages, overflow === null ? "request" : "overflow");
+            for (const e of added) {
+                const full = log.append(e);
                 if (hooks.onEvent)
                     await hooks.onEvent(full, {}).catch(() => { });
                 yield full;
-                messages = derive();
             }
+            if (overflow !== null && added.length === 0) {
+                yield await terminal({ kind: "error", error: overflow });
+                return;
+            }
+            overflow = null;
+            if (added.length > 0)
+                messages = derive();
         }
         if (hooks.onPreLlm)
             await hooks.onPreLlm({ model: config.model, turns }, {});
@@ -636,13 +662,23 @@ export async function* loop(config) {
                     return;
                 }
                 let structured = toStructuredError(err);
-                // CX-1 F8 (ruled: the kernel owns retries): the n-th retry waits
-                // max(n × 250 ms, the provider's Retry-After), abortable — computed
-                // BEFORE `attempts` advances (the 2026-09-07 review's P3: computed
-                // after it, the first wait was 500 ms). A wait above the cap is
-                // never shortened — the run stops with an explicit error instead.
-                const retryWait = () => Math.max((attempts + 1) * 250, structured.retryAfterMs ?? 0);
-                if (structured.retryable && attempts < maxRetries && retryWait() > RETRY_AFTER_MAX_MS) {
+                // CX-1 F8 (ruled: the kernel owns retries), ADR-0005 Amendment 2:
+                // the delay for THIS failure, computed once — BEFORE `attempts`
+                // advances (the 2026-09-07 review's P3), and ONCE, because it is
+                // jittered: the cap check and the sleep must read the same number,
+                // or they could disagree about whether the wait was allowed. A wait
+                // above the cap is never shortened — the run stops with an explicit
+                // error instead.
+                const delay = retryDelayMs(attempts + 1, structured.retryAfterMs);
+                // Observation only (Amendment 2): the retry is announced before the
+                // wait so a surface can show it — a long retry with nothing on
+                // screen is indistinguishable from a hung session. It cannot change
+                // the decision, and a throw is swallowed exactly as onEvent's is.
+                const announce = async (midStream) => {
+                    if (hooks.onRetry)
+                        await hooks.onRetry({ attempt: attempts + 1, maxRetries, code: structured.code, delayMs: delay, midStream }, {}).catch(() => { });
+                };
+                if (structured.retryable && attempts < maxRetries && delay > RETRY_AFTER_MAX_MS) {
                     structured = {
                         ...structured,
                         retryable: false,
@@ -653,7 +689,8 @@ export async function* loop(config) {
                 // content — duplicates are worse than failures. Nothing streamed
                 // yet: the cheap in-place retry (no draft exists to void).
                 if (structured.retryable && !streamed && attempts < maxRetries) {
-                    await sleep(retryWait(), signal); // abortable backoff, Retry-After honored
+                    await announce(false);
+                    await sleep(delay, signal); // abortable backoff, Retry-After honored
                     attempts += 1;
                     continue;
                 }
@@ -668,7 +705,8 @@ export async function* loop(config) {
                 // F4 — the mid-stream retry: same classification, same per-turn
                 // budget (ADR-0005 Amendment 1: frame state, per-process).
                 if (structured.retryable && attempts < maxRetries && !unsafeStartedInDraft()) {
-                    await sleep(retryWait(), signal); // the same abortable backoff, Retry-After honored
+                    await announce(true);
+                    await sleep(delay, signal); // the same abortable backoff, Retry-After honored
                     attempts += 1;
                     // Fresh per-attempt state — the marker is the boundary now.
                     pending.length = 0;
@@ -688,6 +726,11 @@ export async function* loop(config) {
                     turnStart = log.lastSeq;
                     continue;
                 }
+                if (structured.code === "context_overflow" && config.compact !== undefined && !overflowRetried) {
+                    overflowRetried = true;
+                    overflow = structured;
+                    continue turn;
+                }
                 yield await terminal({ kind: "error", error: structured });
                 return;
             }
@@ -821,7 +864,13 @@ export async function* loop(config) {
         // A turn with no tool calls ends on its OWN stop reason (Phase B,
         // Area 6) — never a blanket `completed`. Reached only once committed.
         if (voided === null && pending.length === 0) {
-            yield await terminal(terminalForStop(lastStop));
+            const t = terminalForStop(lastStop);
+            if (t.kind === "error" && t.error.code === "context_overflow" && config.compact !== undefined && !overflowRetried) {
+                overflowRetried = true;
+                overflow = t.error;
+                continue;
+            }
+            yield await terminal(t);
             return;
         }
         // ── The turn settles: a void fires the violated signal — the
@@ -1326,50 +1375,6 @@ function sleep(ms, signal) {
         }, { once: true });
     });
 }
-/**
- * C area (bootstrap #3): the DEFAULT for how many of the NEWEST compactable tool
- * results survive a microcompact boundary (overridable per config via
- * microcompact.keepResults) — the model must keep reasoning over the
- * recent results, whatever turn they belong to.
- */
-const KEEP_COMPACTABLE_RESULTS = 4;
-/**
- * C area: the boundary seq for a microcompact — drawn by COMPACTABLE-RESULT
- * recentness, never user turns: a SINGLE user turn that reads several big
- * files (the coding agent's main overflow shape) crosses the threshold and
- * must trigger. The newest `keepResults` still-visible compactable tool
- * results stay intact; the boundary points AT the (K+1)th-newest of them,
- * so it and everything older is cleared. Results already cleared by an
- * earlier boundary do not count toward the kept window — each new boundary
- * makes progress. Undefined when fewer than keepResults+1 compactable
- * results remain (the kept window is the whole context).
- */
-function microcompactBoundarySeq(events, keepResults) {
-    const callName = new Map();
-    let lastCleared = -1;
-    for (const ev of events) {
-        if (ev.type === "tool_call_end")
-            callName.set(ev.callId, ev.name);
-        if (ev.type === "microcompacted" && ev.beforeSeq > lastCleared)
-            lastCleared = ev.beforeSeq;
-    }
-    const visible = [];
-    for (const ev of events) {
-        if (ev.type !== "tool_result" || ev.seq <= lastCleared)
-            continue;
-        const name = callName.get(ev.callId);
-        // the ergonomics batch C6 (P4): the do-not-compact tag makes a result UN-CLEARABLE
-        // (the projection keeps it) — the count must EXCLUDE it, exactly like
-        // the clearing side. A tagged result counted here would steal a keep
-        // window slot forever and could anchor the boundary at a result the
-        // projection refuses to clear (the count and the clearing share one rule).
-        if (name !== undefined && MICROCOMPACTABLE.has(name) && !(ev.tags ?? []).includes(DO_NOT_COMPACT))
-            visible.push(ev.seq);
-    }
-    if (visible.length <= keepResults)
-        return undefined;
-    return visible[visible.length - keepResults - 1];
-}
 /** A signal that never aborts — for executions outside any abort scope. */
 const NEVER_ABORT = {
     aborted: false,

package/dist/protocol/events.d.ts

@@ -158,6 +158,16 @@ export interface UserInputEvent {
     readonly content: string | readonly import("./messages.js").ContentBlock[];
     /** Provenance of the prompt (Area 6) — preserved losslessly. */
     readonly source?: import("./messages.js").MessageSource;
+    /** 0.40.0 (ADR-0051 §5 rule 1): how a PERSON's turn was composed — a
+     *  skill they invoked, and the line they typed. Display provenance only:
+     *  `content` is what the model receives and the projection never reads
+     *  this, so no byte of it reaches a request. */
+    readonly via?: UserInputVia;
+}
+export interface UserInputVia {
+    readonly kind: "skill";
+    readonly name: string;
+    readonly line: string;
 }
 /**
  * Compaction happened at this point in the trajectory. The EXACT

package/dist/protocol/events.js

@@ -93,6 +93,12 @@ function isContent(v) {
 function isSource(v) {
     return v.source === undefined || MESSAGE_SOURCES.has(v.source);
 }
+function isVia(v) {
+    if (v.via === undefined)
+        return true;
+    const via = v.via;
+    return isPlainObject(via) && via.kind === "skill" && typeof via.name === "string" && via.name !== "" && typeof via.line === "string" && via.line !== "";
+}
 function isTags(v) {
     return v.tags === undefined || (Array.isArray(v.tags) && v.tags.every((t) => typeof t === "string"));
 }
@@ -216,7 +222,7 @@ const EVENT_VALIDATORS = {
     thinking: (v) => typeof v.text === "string",
     usage: isUsage,
     stop: (v) => STOP_REASONS.has(v.reason) && isContinuation(v.continuation),
-    user_input: (v) => isContent(v.content) && isSource(v),
+    user_input: (v) => isContent(v.content) && isSource(v) && isVia(v),
     compacted: (v) => Array.isArray(v.cleared) &&
         v.cleared.every((c) => isPlainObject(c) &&
             // round 4: eventSeq is optional — v1 (round three) entries are

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-core",
-	"version": "0.39.2",
+	"version": "0.40.0",
 	"description": "kiso core \u2014 protocol, event log, loop, hooks, modes, permissions, compaction, delivery truth. The 2,000-line kernel at the bottom of the kiso framework.",
 	"type": "module",
 	"license": "MIT",
@@ -33,7 +33,7 @@
 		"openai"
 	],
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.39.2",
+		"@vincemakes/kiso-evals": "0.40.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"