@vincemakes/kiso-runtime 0.27.0 → 0.29.0

package/dist/checkpoint.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A1a (C) — the checkpoint boundary at a SETTLED model turn.
+ *
+ * `summaryBoundarySeq` can only cut just before a `user_input` round; one
+ * instruction followed by hundreds of model/tool turns therefore never
+ * yields a boundary (roadmap R3.1, the audit's A1). This is the DEFINITION
+ * of a cut that lives inside such a run — a pure projection over the log,
+ * with the invariants stated, and nothing in production calls it until
+ * A1b chooses when (the policy is not decided here).
+ *
+ * A candidate is a model turn whose `stop` is committed and whose every
+ * `tool_call_end` has its answer — a `tool_result` paired by
+ * `invocationSeq` (the CX-1 F1 lesson: a callId is correlation, never
+ * identity; callId pairs only legacy results that carry no invocationSeq,
+ * and only after the call) — or lies in a void range (a voided draft's
+ * calls never ran and are not unanswered). The cut is the settled turn's
+ * LAST event: its last result, or its stop when it made no calls. EC-1
+ * persists the stop BEFORE the results land, so a cut at `stop.seq` would
+ * cover the call and keep the result — the straddle the whole-round
+ * pullback exists to prevent; here it cannot happen by construction.
+ *
+ * Invariants: the cut lies after the last summary point; at least one
+ * settled turn stays after it (the model keeps its most recent turn);
+ * the turn holding the LATEST do-not-compact result is never covered
+ * (the cut stays before that turn — per model turn, not per user round);
+ * the kept suffix meets `keepTokens` (the same event-token estimate the
+ * whole-round walk uses). No candidate → undefined, the honest "nothing
+ * to checkpoint".
+ */
+import type { Event } from "@vincemakes/kiso-core";
+export interface CheckpointOptions {
+    /** the minimum estimated tokens that must remain AFTER the cut (default 0). */
+    readonly keepTokens?: number;
+}
+export declare function checkpointBoundarySeq(events: readonly Event[], opts?: CheckpointOptions): number | undefined;

package/dist/checkpoint.js

@@ -0,0 +1,98 @@
+/**
+ * A1a (C) — the checkpoint boundary at a SETTLED model turn.
+ *
+ * `summaryBoundarySeq` can only cut just before a `user_input` round; one
+ * instruction followed by hundreds of model/tool turns therefore never
+ * yields a boundary (roadmap R3.1, the audit's A1). This is the DEFINITION
+ * of a cut that lives inside such a run — a pure projection over the log,
+ * with the invariants stated, and nothing in production calls it until
+ * A1b chooses when (the policy is not decided here).
+ *
+ * A candidate is a model turn whose `stop` is committed and whose every
+ * `tool_call_end` has its answer — a `tool_result` paired by
+ * `invocationSeq` (the CX-1 F1 lesson: a callId is correlation, never
+ * identity; callId pairs only legacy results that carry no invocationSeq,
+ * and only after the call) — or lies in a void range (a voided draft's
+ * calls never ran and are not unanswered). The cut is the settled turn's
+ * LAST event: its last result, or its stop when it made no calls. EC-1
+ * persists the stop BEFORE the results land, so a cut at `stop.seq` would
+ * cover the call and keep the result — the straddle the whole-round
+ * pullback exists to prevent; here it cannot happen by construction.
+ *
+ * Invariants: the cut lies after the last summary point; at least one
+ * settled turn stays after it (the model keeps its most recent turn);
+ * the turn holding the LATEST do-not-compact result is never covered
+ * (the cut stays before that turn — per model turn, not per user round);
+ * the kept suffix meets `keepTokens` (the same event-token estimate the
+ * whole-round walk uses). No candidate → undefined, the honest "nothing
+ * to checkpoint".
+ */
+import { DO_NOT_COMPACT } from "@vincemakes/kiso-core";
+import { estimateEventTokens, lastSummaryPoint } from "./summarize.js";
+const MODEL_EVENT = new Set(["text_start", "text_delta", "text_end", "thinking", "tool_call_start", "tool_call_input_delta", "tool_call_end"]);
+export function checkpointBoundarySeq(events, opts = {}) {
+    const keepTokens = opts.keepTokens ?? 0;
+    const prevPoint = lastSummaryPoint(events);
+    const voids = [];
+    for (const e of events)
+        if (e.type === "model_output_abandoned")
+            voids.push({ from: e.voidFromSeq, to: e.seq });
+    const voided = (seq) => voids.some((r) => seq > r.from && seq <= r.to);
+    const live = events.filter((e) => e.seq > prevPoint && !voided(e.seq));
+    // the answers: by invocationSeq (round 5+), by callId only for legacy results
+    const byInvocation = new Map();
+    const legacyByCallId = new Map();
+    for (const e of live) {
+        if (e.type !== "tool_result")
+            continue;
+        if (e.invocationSeq !== undefined)
+            byInvocation.set(e.invocationSeq, e);
+        else
+            (legacyByCallId.get(e.callId) ?? legacyByCallId.set(e.callId, []).get(e.callId)).push(e);
+    }
+    const answerOf = (call) => byInvocation.get(call.seq) ?? legacyByCallId.get(call.callId)?.find((r) => r.seq > call.seq);
+    // the model turns: from the first model event after a user_input / stop to the committed stop
+    const turns = [];
+    let start = null;
+    let calls = [];
+    for (const e of live) {
+        if (e.type === "user_input") {
+            start = null;
+            calls = [];
+            continue;
+        }
+        if (start === null && MODEL_EVENT.has(e.type))
+            start = e.seq;
+        if (e.type === "tool_call_end")
+            calls.push(e);
+        if (e.type !== "stop")
+            continue;
+        const answers = calls.map(answerOf);
+        const settled = answers.every((a) => a !== undefined);
+        const cut = Math.max(e.seq, ...answers.map((a) => a?.seq ?? -1));
+        const protectedTurn = answers.some((a) => a !== undefined && (a.tags ?? []).includes(DO_NOT_COMPACT));
+        turns.push({ start: start ?? e.seq, cut, settled, protectedTurn });
+        start = null;
+        calls = [];
+    }
+    // the latest do-not-compact turn is never covered: every cut stays before it
+    const lastProtected = [...turns].reverse().find((t) => t.protectedTurn);
+    const ceiling = lastProtected === undefined ? Number.POSITIVE_INFINITY : lastProtected.start;
+    let total = 0;
+    const tokensAfter = new Map(); // cut -> tokens of live events after it
+    for (let i = live.length - 1; i >= 0; i -= 1) {
+        tokensAfter.set(live[i].seq, total);
+        total += estimateEventTokens(live[i]);
+    }
+    const settledIdx = turns.map((t, i) => (t.settled ? i : -1)).filter((i) => i >= 0);
+    // a candidate must leave at least one settled turn after it
+    for (let k = settledIdx.length - 2; k >= 0; k -= 1) {
+        const t = turns[settledIdx[k]];
+        if (t.cut >= ceiling)
+            continue;
+        if ((tokensAfter.get(t.cut) ?? 0) < keepTokens)
+            continue;
+        return t.cut;
+    }
+    return undefined;
+}

package/dist/internal.d.ts

@@ -26,3 +26,5 @@ export * from "./trust.js";
 export * from "./provider/metadata.js";
 export { canonicalizeUsageForModel } from "./usage/canonical.js";
 export { BUILTIN_MANIFESTS, resolveContinuationScope, type ModelRef, type ProviderManifest } from "./provider/manifest.js";
+export * from "./checkpoint.js";
+export * from "./request-budget.js";

package/dist/internal.js

@@ -32,3 +32,7 @@ export * from "./provider/metadata.js";
 export { canonicalizeUsageForModel } from "./usage/canonical.js";
 // MG-1 (A5): the identity layer — manifests and the scope resolver.
 export { BUILTIN_MANIFESTS, resolveContinuationScope } from "./provider/manifest.js";
+// A1a: the checkpoint boundary (a definition — nothing fires it until A1b)
+// and the request-budget accounting the CLI's status line reads.
+export * from "./checkpoint.js";
+export * from "./request-budget.js";

package/dist/provider/metadata.js

@@ -29,6 +29,74 @@ const DEEPSEEK_PRICING = {
     asOf: "2026-08-13",
     source: "https://api-docs.deepseek.com/quick_start/pricing",
 };
+/** PA-1a: the Anthropic rates as read on 2026-09-07 (base input, output,
+ *  cache read = "cache hits and refreshes", cache write = the 5-minute
+ *  write). The pricing page notes Sonnet 5's $2/$10 is the standard
+ *  price (the announced September increase did not occur). */
+const ANTHROPIC_PRICING_SOURCE = "https://platform.claude.com/docs/en/about-claude/pricing";
+const ANTHROPIC_MODELS_SOURCE = "https://platform.claude.com/docs/en/models/overview";
+const ANTHROPIC_EFFORT_SOURCE = "https://platform.claude.com/docs/en/build-with-claude/effort";
+const ANTHROPIC_ASOF = "2026-09-07";
+const anthropicPricing = (inputPerM, outputPerM, cacheReadPerM, cacheWritePerM) => ({
+    inputPerM,
+    outputPerM,
+    cacheReadPerM,
+    cacheWritePerM,
+    asOf: ANTHROPIC_ASOF,
+    source: ANTHROPIC_PRICING_SOURCE,
+});
+/** The 5-line's effort control: five native levels, default high, wire
+ *  output_config.effort (the effort page, read 2026-09-07). The thinking
+ *  table (https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting)
+ *  gives the modes per model. */
+const FIVE_LEVELS = { levels: ["low", "medium", "high", "xhigh", "max"], default: "high", wire: "output_config.effort" };
+function anthropicLine() {
+    const row = (model, capabilities, pricing) => ({
+        model,
+        providerId: "anthropic",
+        capabilities,
+        capabilitiesAsOf: ANTHROPIC_ASOF,
+        capabilitiesSource: ANTHROPIC_MODELS_SOURCE,
+        pricing,
+    });
+    const fiveLine = (thinkingModes, forbidden) => ({
+        contextWindow: 1_000_000,
+        maxOutputTokens: 128_000,
+        promptCaching: "explicit",
+        reasoning: {
+            emitsThinkingStream: true,
+            thinking: { modes: thinkingModes, default: "adaptive" },
+            effort: FIVE_LEVELS,
+            ...(forbidden !== undefined ? { forbidden } : {}),
+            asOf: ANTHROPIC_ASOF,
+            source: ANTHROPIC_EFFORT_SOURCE,
+        },
+        inputModalities: ["text", "image"],
+    });
+    const haiku = {
+        contextWindow: 200_000,
+        maxOutputTokens: 64_000,
+        promptCaching: "explicit",
+        // Extended thinking only (budget_tokens; adaptive rejected) — the
+        // XP-1 setting has no budget axis, so the toggle is not driven;
+        // effort: "Not supported" on the models overview. Unknown stays null.
+        reasoning: { emitsThinkingStream: true, thinking: null, effort: null, asOf: ANTHROPIC_ASOF, source: ANTHROPIC_EFFORT_SOURCE },
+        inputModalities: ["text", "image"],
+    };
+    const haikuPricing = anthropicPricing(1, 5, 0.1, 1.25);
+    return [
+        // Fable 5.1: adaptive only, ALWAYS on — "enabled" and "disabled" both 400.
+        row("claude-fable-5-1", fiveLine(["adaptive"]), anthropicPricing(10, 50, 0.25, 12.5)),
+        // Opus 5: adaptive, on by default; "disabled" accepted at effort high
+        // or below — with xhigh or max it is a 400 (the forbidden pair).
+        row("claude-opus-5", fiveLine(["adaptive", "disabled"], [{ thinking: "disabled", effort: "xhigh" }, { thinking: "disabled", effort: "max" }]), anthropicPricing(5, 25, 0.5, 6.25)),
+        // Sonnet 5: adaptive, on by default; "disabled" accepted.
+        row("claude-sonnet-5", fiveLine(["adaptive", "disabled"]), anthropicPricing(2, 10, 0.2, 2.5)),
+        // Haiku 4.5: the pinned id and its alias (the registry matches exact ids).
+        row("claude-haiku-4-5-20251001", haiku, haikuPricing),
+        row("claude-haiku-4-5", haiku, haikuPricing),
+    ];
+}
 /** The v1 table. Nulls outnumber numbers ON PURPOSE: only values with a
  *  named source enter; everything else waits for one. */
 const ENTRIES = [
@@ -54,22 +122,16 @@ const ENTRIES = [
         capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: { emitsThinkingStream: true, thinking: null, effort: null, asOf: null, source: null }, inputModalities: null },
         pricing: DEEPSEEK_PRICING,
     },
-    {
-        model: "claude-sonnet-5",
-        providerId: "anthropic",
-        capabilities: { contextWindow: 200_000, maxOutputTokens: null, promptCaching: "explicit",
-            reasoning: {
-                emitsThinkingStream: true,
-                thinking: null,
-                effort: { levels: ["low", "medium", "high", "xhigh", "max"], default: "high", wire: "output_config.effort" },
-                asOf: "2026-08-26",
-                source: "https://platform.claude.com/docs/en/build-with-claude/effort",
-            },
-            inputModalities: null },
-        // Priced only when the rates are read from the live billing page
-        // and dated — never copied from memory (the review's boundary ②).
-        pricing: null,
-    },
+    // PA-1a (2026-09-07): the Anthropic first-party line, read from the live
+    // docs that day — the models overview (ids, context, max output,
+    // modalities, thinking type, default effort), the thinking table
+    // (accepted / rejected thinking.type per model, the Opus 5 forbidden
+    // pair), the effort page (levels), the pricing page (rates). Each row
+    // carries the dates; nothing here is from memory. Extended thinking
+    // (`enabled` + budget_tokens) is registered for NO model: the 5-line
+    // rejects it, and Haiku 4.5's manual-budget mode has no axis in the
+    // XP-1 setting — recorded as `thinking: null` on that row, never guessed.
+    ...anthropicLine(),
     {
         // XP-1: the current DeepSeek line — the model every RD-1 benchmark
         // artifact was produced with, previously ABSENT (null pricing and

package/dist/request-budget.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A1a (A) — request-budget accounting: the parts of the request the
+ * kernel assembles (system prompt, tool table, projected messages with
+ * their continuation envelopes, the output reserve), each estimated the
+ * way the kernel estimates (chars / 4 — a proxy, marked approximate),
+ * summed ONCE. The CLI's `ctx left` had measured the projected messages
+ * alone, so a fresh session with a large tool table read "~100%" — the
+ * headroom was never that.
+ *
+ * Two definitional points (the 2026-09-07 review): the continuation
+ * envelopes ride INSIDE the projected assistant messages and are
+ * measured as a sub-part of `messages`, never added on top; the output
+ * reserve is the request's `max_tokens` when a profile or provider sets
+ * one and NULL when unknown (the openai-compat path sends none unless
+ * configured) — the total then excludes it and says so.
+ *
+ * This is a display and design entry. The auto-compact policy keeps its
+ * own number (`estimateCtxRatio` in the CLI) — moving it is A1b's.
+ */
+import type { Message, ToolSpec } from "@vincemakes/kiso-core";
+export interface RequestParts {
+    readonly systemPrompt?: string;
+    readonly toolSpecs: readonly ToolSpec[];
+    readonly messages: readonly Message[];
+    /** the request's max_tokens; undefined/null = the provider sends none */
+    readonly maxTokens?: number | null;
+}
+export interface RequestBudget {
+    readonly approximate: true;
+    readonly system: number;
+    readonly tools: number;
+    readonly user: number;
+    readonly assistant: number;
+    readonly toolResults: number;
+    /** the continuation envelopes inside the assistant messages (a sub-part of `messages`) */
+    readonly continuations: number;
+    /** user + assistant + toolResults + continuations */
+    readonly messages: number;
+    readonly outputReserve: number | null;
+    /** system + tools + messages + (outputReserve ?? 0) */
+    readonly total: number;
+    readonly window: number;
+    readonly headroom: number;
+    readonly ratio: number;
+}
+export declare function requestBudget(parts: RequestParts, window: number): RequestBudget;

package/dist/request-budget.js

@@ -0,0 +1,45 @@
+/**
+ * A1a (A) — request-budget accounting: the parts of the request the
+ * kernel assembles (system prompt, tool table, projected messages with
+ * their continuation envelopes, the output reserve), each estimated the
+ * way the kernel estimates (chars / 4 — a proxy, marked approximate),
+ * summed ONCE. The CLI's `ctx left` had measured the projected messages
+ * alone, so a fresh session with a large tool table read "~100%" — the
+ * headroom was never that.
+ *
+ * Two definitional points (the 2026-09-07 review): the continuation
+ * envelopes ride INSIDE the projected assistant messages and are
+ * measured as a sub-part of `messages`, never added on top; the output
+ * reserve is the request's `max_tokens` when a profile or provider sets
+ * one and NULL when unknown (the openai-compat path sends none unless
+ * configured) — the total then excludes it and says so.
+ *
+ * This is a display and design entry. The auto-compact policy keeps its
+ * own number (`estimateCtxRatio` in the CLI) — moving it is A1b's.
+ */
+import { estimateTokens } from "@vincemakes/kiso-core";
+const chars = (s) => Math.ceil(s.length / 4);
+export function requestBudget(parts, window) {
+    const system = parts.systemPrompt === undefined ? 0 : chars(parts.systemPrompt);
+    const tools = parts.toolSpecs.length === 0 ? 0 : chars(JSON.stringify(parts.toolSpecs));
+    let user = 0;
+    let assistant = 0;
+    let toolResults = 0;
+    let continuations = 0;
+    for (const m of parts.messages) {
+        const t = estimateTokens([m]);
+        if (m.role === "user")
+            user += t;
+        else if (m.role === "assistant") {
+            assistant += t;
+            if (m.continuation !== undefined)
+                continuations += chars(JSON.stringify(m.continuation));
+        }
+        else
+            toolResults += t;
+    }
+    const messages = user + assistant + toolResults + continuations;
+    const outputReserve = parts.maxTokens ?? null;
+    const total = system + tools + messages + (outputReserve ?? 0);
+    return { approximate: true, system, tools, user, assistant, toolResults, continuations, messages, outputReserve, total, window, headroom: window - total, ratio: total / window };
+}

package/dist/session.d.ts

@@ -147,6 +147,17 @@ export declare class AgentSession {
      *  binding, restored from the durable profile on open. The status row
      *  reads THIS, so the row and the request can never disagree. */
     get model(): string;
+    /** A1a: the parts of the NEXT request as the kernel would assemble them —
+     *  the system prompt, the tool table (the same snapshot the loop sends:
+     *  live extension tools included), the projected messages with their
+     *  continuation envelopes, and the request's max_tokens (absent when
+     *  the provider sends none). For `requestBudget` — accounting, no policy. */
+    requestParts(): {
+        readonly systemPrompt?: string;
+        readonly toolSpecs: readonly import("@vincemakes/kiso-core").ToolSpec[];
+        readonly messages: readonly Message[];
+        readonly maxTokens?: number;
+    };
     /** XP-1: the selected reasoning axes (resolution happens per request). */
     get reasoning(): ReasoningSetting;
     /**

package/dist/session.js

@@ -235,6 +235,19 @@ export class AgentSession {
     get model() {
         return this.#model;
     }
+    /** A1a: the parts of the NEXT request as the kernel would assemble them —
+     *  the system prompt, the tool table (the same snapshot the loop sends:
+     *  live extension tools included), the projected messages with their
+     *  continuation envelopes, and the request's max_tokens (absent when
+     *  the provider sends none). For `requestBudget` — accounting, no policy. */
+    requestParts() {
+        return {
+            ...(this.#config.systemPrompt !== undefined ? { systemPrompt: this.#config.systemPrompt } : {}),
+            toolSpecs: this.#config.registry.snapshot().specs,
+            messages: this.projected(),
+            ...(this.#config.maxTokens !== undefined ? { maxTokens: this.#config.maxTokens } : {}),
+        };
+    }
     /** XP-1: the selected reasoning axes (resolution happens per request). */
     get reasoning() {
         return this.#reasoning;

package/dist/summarize.d.ts

@@ -140,6 +140,10 @@ export declare const DROP_PLACEHOLDER = "[e6-crux: the covered turns were droppe
  * the next summary runs from here.
  */
 export declare function lastSummaryPoint(events: readonly Event[]): number;
+/** The chars/4 token proxy for a single EVENT (the same convention as
+ *  estimateTokens, event-shaped — the (f) keep-floor walk needs the kept
+ *  suffix's tokens without projecting it). */
+export declare function estimateEventTokens(ev: Event): number;
 /**
  * The covered range's end: the seq of the event just before the
  * keepRounds-th most recent user_input AFTER the last summary point —

package/dist/summarize.js

@@ -272,7 +272,7 @@ export function lastSummaryPoint(events) {
 /** The chars/4 token proxy for a single EVENT (the same convention as
  *  estimateTokens, event-shaped — the (f) keep-floor walk needs the kept
  *  suffix's tokens without projecting it). */
-function estimateEventTokens(ev) {
+export function estimateEventTokens(ev) {
     switch (ev.type) {
         case "user_input":
             return Math.ceil(ev.content.length / 4);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-runtime",
-	"version": "0.27.0",
+	"version": "0.29.0",
 	"description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
 	"type": "module",
 	"license": "MIT",
@@ -25,11 +25,11 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.27.0"
+		"@vincemakes/kiso-core": "0.29.0"
 	},
 	"peerDependencies": {
-		"@vincemakes/kiso-provider-anthropic": "0.27.0",
-		"@vincemakes/kiso-provider-openai": "0.27.0"
+		"@vincemakes/kiso-provider-anthropic": "0.29.0",
+		"@vincemakes/kiso-provider-openai": "0.29.0"
 	},
 	"peerDependenciesMeta": {
 		"@vincemakes/kiso-provider-anthropic": {
@@ -40,7 +40,7 @@
 		}
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.27.0",
+		"@vincemakes/kiso-evals": "0.29.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"