@vincemakes/kiso-runtime 0.39.0 → 0.39.2

package/dist/session.d.ts

@@ -30,7 +30,7 @@
 import { EventLog, type AbortSignalLike, type Adapter, type Event, type KisoExtension, type Message, type PermissionDecision, type Tool } from "@vincemakes/kiso-core";
 import { type TaskAssessment } from "./task-assessment.js";
 import { type ContinuationScope } from "@vincemakes/kiso-core";
-import type { ReasoningSetting } from "./provider/metadata.js";
+import { type ReasoningSetting } from "./provider/metadata.js";
 import { type SessionStore } from "./store.js";
 import { Run } from "./run.js";
 /** TUI2-R3v2 ③ — one off-trajectory model request (session.sideQuery).
@@ -89,7 +89,6 @@ export interface CompactInfo {
     /** The covered content's estimated tokens (the chars/4 proxy). */
     readonly tokens: number;
 }
-/** @deprecated the canonical name is `Session` (root export, 1.1.0); this alias is removed in the next major. */
 export declare class AgentSession {
     #private;
     readonly id: string;
@@ -265,6 +264,7 @@ export declare class AgentSession {
         onStart?: (info: CompactInfo) => void;
         drop?: boolean;
         focus?: string;
+        manualBudget?: boolean;
     }): Promise<SummarizeResult | null>;
     /**
      * E6 — the run-start context policy (candidate A + the crux drop arm).

package/dist/session.js

@@ -36,7 +36,8 @@ import { assessTasks } from "./task-assessment.js";
 const DEFAULT_EVIDENCE_TOOLS = new Set(["shell"]);
 import { denialResult } from "@vincemakes/kiso-core";
 import { buildProfile, readProfile, writeProfile } from "./profile.js";
-import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, SUMMARY_MAX_OUTPUT, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
+import { resolveReasoning } from "./provider/metadata.js";
+import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, MANUAL_SUMMARY_BUDGET, SUMMARY_MAX_OUTPUT, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
 import { canonicalizeUsageForModel } from "./usage/canonical.js";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -69,6 +70,24 @@ export class ResumeBlockedError extends Error {
     }
 }
 /** @deprecated the canonical name is `Session` (root export, 1.1.0); this alias is removed in the next major. */
+/**
+ * 0.39.2 — thinking OFF for a manual summary, where it can be turned off.
+ *
+ * The summary call sent no reasoning at all, so it ran at the provider's
+ * default, and for a model whose thinking defaults ON the reasoning tokens
+ * came out of the same output budget as the checkpoint. Resolved through
+ * `resolveReasoning` — the one authority the `/model` path uses — so it
+ * only ever sends a NATIVE value for a model the registry knows. For a
+ * model it does not know (66 of the 73 profiles on the machine this was
+ * found on, the failing one among them) it sends nothing, exactly as
+ * before: a raw field to an unknown model can be a 400. That is why this
+ * is an optimisation and the scaled budget is the fix — the budget
+ * reaches every model, this reaches the ones we can vouch for.
+ */
+function summaryReasoning(model, baseUrl) {
+    const r = resolveReasoning(model, { thinking: "disabled", effort: "default" }, baseUrl);
+    return r.ok && r.wire.thinking !== undefined ? { reasoning: r.wire } : {};
+}
 export class AgentSession {
     id;
     log;
@@ -428,6 +447,11 @@ export class AgentSession {
     // R3a: `focus` — an optional steer for the summary call ("keep the
     // auth details"). Rides the serialized input as ONE instruction
     // line; absent = byte-identical to the pre-round call.
+    // 0.39.2: `manualBudget` — the MANUAL `/compact` gesture's summary
+    // call: the measured output budget, and thinking off where the
+    // registry says the model can turn it off. Absent — the auto
+    // policy — the call is byte-identical to before; see
+    // `MANUAL_SUMMARY_BUDGET` for the measurement and for why.
     options = {}) {
         this.ensureHealthy();
         const keepRounds = options.keepRounds ?? KEEP_RECENT_ROUNDS;
@@ -456,10 +480,11 @@ export class AgentSession {
         // call with no fraction (kiso never invents a percentage here).
         if (options.signal !== undefined && options.signal.aborted)
             throw cancelled();
+        const coveredTokens = estimateTokens(covered);
         options.onStart?.({
             coversToSeq: boundary,
             rounds: events.filter((e) => e.type === "user_input" && e.seq > prevPoint && e.seq <= boundary).length,
-            tokens: estimateTokens(covered),
+            tokens: coveredTokens,
         });
         let summary;
         let usage = null;
@@ -483,11 +508,13 @@ export class AgentSession {
                 // E6 (a): ONE serialized user message — the DSML bug's
                 // raw-message array is structurally dead on this path.
                 messages: [{ role: "user", content: serializedInput }],
-                // E6 (g): the summary call ALWAYS carries the explicit
-                // output budget — 4,000 adapter maxTokens (a wire-level
-                // truncation is caught by the (b) required-section
-                // validation, never silently passed).
-                maxOutputTokens: SUMMARY_MAX_OUTPUT,
+                // E6 (g): the summary call ALWAYS carries an explicit output
+                // budget (a wire-level truncation is caught by the (b)
+                // required-section validation, never silently passed).
+                // 0.39.2: measured for the manual gesture, fixed for the policy.
+                ...(options.manualBudget === true
+                    ? { maxOutputTokens: MANUAL_SUMMARY_BUDGET, ...summaryReasoning(binding.model, binding.baseUrl) }
+                    : { maxOutputTokens: SUMMARY_MAX_OUTPUT }),
                 ...(options.signal !== undefined ? { signal: options.signal } : {}),
             });
             summary = call.text;

package/dist/summarize.d.ts

@@ -44,7 +44,48 @@ export declare const SUMMARY_RESULT_MAX_CHARS = 2000;
 export declare const SUMMARY_MAX_OUTPUT = 4000;
 export declare const KEEP_TOKENS_DEFAULT = 20000;
 export declare const IN_FLIGHT_HEADROOM = 8000;
+/** ONE NUMBER, TWO CONSUMERS. `SUMMARY_MAX_OUTPUT` is both the summary
+ *  call's output budget AND a term of this reserve — the reserve buys
+ *  back room for exactly that much summary. Change one and you have
+ *  changed the other; see `MANUAL_SUMMARY_BUDGET` for why the manual
+ *  gesture's larger budget does NOT reach the auto policy that reads this. */
 export declare const POLICY_RESERVE: number;
+/**
+ * 0.39.2 — the output budget of a MANUAL `/compact`, and it is MEASURED.
+ *
+ * The fixed 4,000 failed live sessions: `the summary turn ended with
+ * max_tokens`. On the failing profile (an unregistered DeepSeek model
+ * behind a gateway), a covered range the size of the reported one —
+ * ~100k tokens of real source — was run three ways:
+ *
+ *   budget  4,000  → max_tokens   reasoning 3,093   checkpoint    828   3 of 7 sections
+ *   budget  8,391  → max_tokens   reasoning 1,613   checkpoint  6,544   4 of 7
+ *   budget 32,000  → end_turn     reasoning 3,557   checkpoint 15,261   7 of 7
+ *
+ * A complete checkpoint took 18,837 output tokens. At 4,000 the reasoning
+ * LOOKED like the cause (77% of the budget) only because the budget was
+ * too small for the checkpoint to get going; with room, reasoning is a
+ * fifth and the checkpoint itself is the size. A rule scaled from the
+ * covered estimate (a twelfth: 8,391, doubling to 16,782 on retry) was
+ * built first and failed BOTH attempts on this data — it was a guess, and
+ * the measurement is what falsified it.
+ *
+ * So the budget is not scaled; it is a generous flat CAP, because a cap
+ * is not a charge — the model is billed for what it writes, and a higher
+ * limit costs nothing unless the output would have run away anyway. The
+ * one thing a lower first budget buys is a failed call before the one
+ * that works. 32,000 holds the measured 18,837 with room, and bounds what
+ * a genuinely runaway summary can cost: a checkpoint larger than this has
+ * stopped being a summary.
+ *
+ * MANUAL ONLY, and that is the patch boundary. The auto policy's
+ * `POLICY_RESERVE` assumes `SUMMARY_MAX_OUTPUT`; giving the policy a larger
+ * budget without moving its reserve would let a fire leave less room than
+ * the reserve promised, and moving the reserve moves every session's
+ * compaction trigger — BM-1 §3's compaction tier, where the paired bench
+ * blocks. That belongs to A1b, and the measurement above is its input.
+ */
+export declare const MANUAL_SUMMARY_BUDGET = 32000;
 /** The reference context-window scale (the flash-family window); the
  *  env overrides. The default arming point is 120,000 − 32,000 =
  *  88,000 — a post-fire projection (≥ 24k) can never re-cross it, so
@@ -114,6 +155,13 @@ export interface SummarizeConversationOptions {
     readonly signal?: AbortSignalLike;
     /** E6 (g): the summary call's explicit output budget (adapter maxTokens). */
     readonly maxOutputTokens?: number;
+    /** 0.39.2: the RESOLVED reasoning for the summary call — native wire
+     *  values from `resolveReasoning`, never a raw field. Absent sends
+     *  nothing, and the provider's default applies. */
+    readonly reasoning?: {
+        readonly thinking?: "adaptive" | "enabled" | "disabled";
+        readonly effort?: string;
+    };
 }
 /** The summary call's result — the text PLUS the provider-reported usage
  *  (E6: the honest accounting — the summary call's cost rides the trace
@@ -124,9 +172,21 @@ export interface SummarizeConversationResult {
     readonly usage: RawUsage | null;
 }
 /**
- * The one-shot summary call. Collects the adapter's text deltas into the
- * summary; usage/stop pass through untouched. Throws when the model
- * produced no text — the caller reports it and nothing is persisted.
+ * The summary call, with ONE retry.
+ *
+ * 0.39.1: `/compact` had no retry at all. The kernel owns retries
+ * (ADR-0005) and this path does not go through the kernel — it calls the
+ * adapter directly — so a gateway that drops a 95k-token summary stream
+ * failed `/compact` every single time, with an honest message and no way
+ * forward. The adapter classifies that as a retryable `network` failure
+ * (the transport-failure-after-headers class); here is the only place
+ * that can act on it.
+ *
+ * ONE retry, not a loop, and not the kernel's budget: a summary re-pays
+ * its whole input, which on the sessions that need compacting is the
+ * most expensive request the session makes. A permanent error still
+ * throws on the first attempt — the retry is keyed on the classification
+ * the adapter already made, never on the fact that something failed.
  */
 export declare function summarizeConversation(options: SummarizeConversationOptions): Promise<SummarizeConversationResult>;
 /** E6 — the crux-experiment drop arm: the covered turns are replaced by

package/dist/summarize.js

@@ -41,7 +41,61 @@ export const SUMMARY_RESULT_MAX_CHARS = 2000;
 export const SUMMARY_MAX_OUTPUT = 4000;
 export const KEEP_TOKENS_DEFAULT = 20000;
 export const IN_FLIGHT_HEADROOM = 8000;
+/** ONE NUMBER, TWO CONSUMERS. `SUMMARY_MAX_OUTPUT` is both the summary
+ *  call's output budget AND a term of this reserve — the reserve buys
+ *  back room for exactly that much summary. Change one and you have
+ *  changed the other; see `MANUAL_SUMMARY_BUDGET` for why the manual
+ *  gesture's larger budget does NOT reach the auto policy that reads this. */
 export const POLICY_RESERVE = SUMMARY_MAX_OUTPUT + KEEP_TOKENS_DEFAULT + IN_FLIGHT_HEADROOM;
+/**
+ * 0.39.2 — the output budget of a MANUAL `/compact`, and it is MEASURED.
+ *
+ * The fixed 4,000 failed live sessions: `the summary turn ended with
+ * max_tokens`. On the failing profile (an unregistered DeepSeek model
+ * behind a gateway), a covered range the size of the reported one —
+ * ~100k tokens of real source — was run three ways:
+ *
+ *   budget  4,000  → max_tokens   reasoning 3,093   checkpoint    828   3 of 7 sections
+ *   budget  8,391  → max_tokens   reasoning 1,613   checkpoint  6,544   4 of 7
+ *   budget 32,000  → end_turn     reasoning 3,557   checkpoint 15,261   7 of 7
+ *
+ * A complete checkpoint took 18,837 output tokens. At 4,000 the reasoning
+ * LOOKED like the cause (77% of the budget) only because the budget was
+ * too small for the checkpoint to get going; with room, reasoning is a
+ * fifth and the checkpoint itself is the size. A rule scaled from the
+ * covered estimate (a twelfth: 8,391, doubling to 16,782 on retry) was
+ * built first and failed BOTH attempts on this data — it was a guess, and
+ * the measurement is what falsified it.
+ *
+ * So the budget is not scaled; it is a generous flat CAP, because a cap
+ * is not a charge — the model is billed for what it writes, and a higher
+ * limit costs nothing unless the output would have run away anyway. The
+ * one thing a lower first budget buys is a failed call before the one
+ * that works. 32,000 holds the measured 18,837 with room, and bounds what
+ * a genuinely runaway summary can cost: a checkpoint larger than this has
+ * stopped being a summary.
+ *
+ * MANUAL ONLY, and that is the patch boundary. The auto policy's
+ * `POLICY_RESERVE` assumes `SUMMARY_MAX_OUTPUT`; giving the policy a larger
+ * budget without moving its reserve would let a fire leave less room than
+ * the reserve promised, and moving the reserve moves every session's
+ * compaction trigger — BM-1 §3's compaction tier, where the paired bench
+ * blocks. That belongs to A1b, and the measurement above is its input.
+ */
+export const MANUAL_SUMMARY_BUDGET = 32_000;
+/** Thrown by an attempt that stopped on `max_tokens`, and it NAMES the
+ *  budget: "not a complete turn" alone told the person nothing about what
+ *  ran out. Still an `Error`, and still carries the `max_tokens … not a
+ *  complete turn` wording the CX-1 F3 gate matches. */
+class SummaryBudgetExhausted extends Error {
+    budget;
+    constructor(budget) {
+        super(budget === undefined
+            ? "the summary turn ended with max_tokens — not a complete turn"
+            : `the summary turn ended with max_tokens — it needed more than its ${budget}-token output budget, not a complete turn`);
+        this.budget = budget;
+    }
+}
 /** The reference context-window scale (the flash-family window); the
  *  env overrides. The default arming point is 120,000 − 32,000 =
  *  88,000 — a post-fire projection (≥ 24k) can never re-cross it, so
@@ -188,12 +242,74 @@ export function validateSummary(text) {
     }
     return null;
 }
+/** A thrown value the adapter CLASSIFIED — `{ code, retryable, message }`
+ *  (ADR-0005 rule 1). The core's own guard is private, and this asks a
+ *  narrower question than that one: is this a failure someone already
+ *  decided is worth trying again. A validation rejection below is a plain
+ *  `Error` and can never match, which is the separation E6 (b) wants —
+ *  "the model wrote a bad summary" is not retried, ever. */
+function retryableStructured(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const e = err;
+    return typeof e.code === "string" && typeof e.message === "string" && e.retryable === true;
+}
+/** How long to wait before the one retry. The provider's own ask when it
+ *  made one and it is short enough to be worth honouring; otherwise a
+ *  token pause — the failure this exists for is a dropped stream, not a
+ *  rate limit, and an immediate second attempt is the right response to
+ *  a socket that died. */
+function retryWaitMs(err) {
+    const asked = err.retryAfterMs;
+    return typeof asked === "number" && Number.isFinite(asked) && asked >= 0 && asked <= 60_000 ? asked : 250;
+}
 /**
- * The one-shot summary call. Collects the adapter's text deltas into the
- * summary; usage/stop pass through untouched. Throws when the model
- * produced no text — the caller reports it and nothing is persisted.
+ * The summary call, with ONE retry.
+ *
+ * 0.39.1: `/compact` had no retry at all. The kernel owns retries
+ * (ADR-0005) and this path does not go through the kernel — it calls the
+ * adapter directly — so a gateway that drops a 95k-token summary stream
+ * failed `/compact` every single time, with an honest message and no way
+ * forward. The adapter classifies that as a retryable `network` failure
+ * (the transport-failure-after-headers class); here is the only place
+ * that can act on it.
+ *
+ * ONE retry, not a loop, and not the kernel's budget: a summary re-pays
+ * its whole input, which on the sessions that need compacting is the
+ * most expensive request the session makes. A permanent error still
+ * throws on the first attempt — the retry is keyed on the classification
+ * the adapter already made, never on the fact that something failed.
  */
 export async function summarizeConversation(options) {
+    // Asked as a CALL, twice, because `aborted` is a readonly property and
+    // the narrowing from the first read would otherwise be carried across
+    // the await — where the whole point is that it can have changed.
+    const aborted = () => options.signal?.aborted === true;
+    // A `max_tokens` stop is NOT retried here. A retry at the same budget
+    // buys the same truncation, and a retry at a larger one is only worth
+    // having if the first budget was chosen small — which is why the manual
+    // gesture now asks for the whole measured budget up front instead
+    // (see `MANUAL_SUMMARY_BUDGET`).
+    try {
+        return await summaryAttempt(options);
+    }
+    catch (err) {
+        // The caller's cancel is the caller's: an aborted `/compact` must
+        // not spend a second call on its way out.
+        if (!retryableStructured(err) || aborted())
+            throw err;
+        await new Promise((r) => setTimeout(r, retryWaitMs(err)));
+        if (aborted())
+            throw err;
+        return await summaryAttempt(options);
+    }
+}
+/**
+ * ONE attempt. Collects the adapter's text deltas into the summary;
+ * usage/stop pass through untouched. Throws when the model produced no
+ * text — the caller reports it and nothing is persisted.
+ */
+async function summaryAttempt(options) {
     const { adapter, model, messages } = options;
     let text = "";
     let usage = null;
@@ -213,6 +329,7 @@ export async function summarizeConversation(options) {
         systemPrompt: SUMMARY_PROMPT,
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.maxOutputTokens !== undefined ? { maxTokens: options.maxOutputTokens } : {}),
+        ...(options.reasoning !== undefined ? { reasoning: options.reasoning } : {}),
     })) {
         if (stops > 0 && ev.type !== "usage" && ev.type !== "stop" && afterStop === undefined)
             afterStop = ev.type;
@@ -247,6 +364,9 @@ export async function summarizeConversation(options) {
         throw new Error(`the summary turn stopped ${stops} times — not a complete turn`);
     if (toolCalls > 0)
         throw new Error("the summary turn called a tool — a summary is text, never a tool call");
+    // The one stop a larger budget can cure, told apart from the rest.
+    if (stopReason === "max_tokens")
+        throw new SummaryBudgetExhausted(options.maxOutputTokens);
     if (stopReason !== "end_turn")
         throw new Error(`the summary turn ended with ${String(stopReason)} — not a complete turn`);
     if (afterStop !== undefined)

package/package.json

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