@vincemakes/kiso-runtime 0.28.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/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.28.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.28.0"
+		"@vincemakes/kiso-core": "0.29.0"
 	},
 	"peerDependencies": {
-		"@vincemakes/kiso-provider-anthropic": "0.28.0",
-		"@vincemakes/kiso-provider-openai": "0.28.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.28.0",
+		"@vincemakes/kiso-evals": "0.29.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"