@vincemakes/kiso-runtime 0.2.1 → 0.5.0

package/dist/agent.d.ts

@@ -55,6 +55,8 @@ export interface AgentDefinition {
     readonly microcompact?: {
         readonly thresholdTokens: number;
     };
+    /** E6: the session context policy (run-start actions, injection-side only). */
+    readonly contextPolicy?: import("./session.js").ContextPolicy;
     readonly maxRetries?: number;
     /** E1: loaded extensions — their tools merge into the registry (a name
      *  collision with a built-in is a loud startup error), their hooks

package/dist/agent.js

@@ -71,6 +71,7 @@ export class AgentRuntime {
             ...(this.#definition.temperature !== undefined ? { temperature: this.#definition.temperature } : {}),
             ...(this.#definition.compaction !== undefined ? { compaction: this.#definition.compaction } : {}),
             ...(this.#definition.microcompact !== undefined ? { microcompact: this.#definition.microcompact } : {}),
+            ...(this.#definition.contextPolicy !== undefined ? { contextPolicy: this.#definition.contextPolicy } : {}),
             ...(this.#definition.maxRetries !== undefined ? { maxRetries: this.#definition.maxRetries } : {}),
             ...(this.#definition.extensions !== undefined ? { extensions: this.#definition.extensions } : {}),
         };

package/dist/compose.d.ts

@@ -3,7 +3,7 @@
  * from session.ts: the extension system-prompt appends, the extension
  * hook composition (the existing come first), and the loop's microcompact config lookup.
  */
-import type { ApprovalChain, HookHost, KisoExtension, ToolRegistry } from "@vincemakes/kiso-core";
+import type { ApprovalChain, Event, HookHost, KisoExtension, ToolRegistry } from "@vincemakes/kiso-core";
 import type { SessionConfig } from "./session.js";
 /** The table, or "" when the registry is empty (no vocabulary, no tools). */
 export declare function composeToolTable(registry: ToolRegistry): string;
@@ -23,12 +23,17 @@ export declare function composeSystemPrompt(base: string | undefined, extensions
  */
 export declare function composeHooks(existing: HookHost | undefined, extensions: readonly KisoExtension[]): HookHost | undefined;
 /**
- * E2: the loop's microcompact config — the session's own microcompact wins;
- * otherwise the FIRST extension providing a compaction config supplies it.
- * An extension config without a threshold contributes nothing (a boundary
- * needs a threshold to ever fire).
+ * E2/E6: the loop's microcompact config — the session's own microcompact
+ * wins; otherwise the FIRST extension providing a compaction config
+ * supplies it. An extension config without a threshold contributes nothing
+ * (a boundary needs a threshold to ever fire).
+ * E6 (candidate B): the session's contextPolicy.microcompact override beats
+ * the session's own config (a tuned policy wins over the CLI default), and
+ * its minTurns no-fire guard — below that many completed user inputs the
+ * boundary config is OMITTED: a short task never pays a break it cannot
+ * amortize (the E5-F1 accounting).
  */
-export declare function microcompactFor(config: SessionConfig): {
+export declare function microcompactFor(config: SessionConfig, log?: readonly Event[]): {
     readonly thresholdTokens: number;
     readonly keepResults?: number;
 } | undefined;

package/dist/compose.js

@@ -135,14 +135,28 @@ export function composeHooks(existing, extensions) {
     return out;
 }
 /**
- * E2: the loop's microcompact config — the session's own microcompact wins;
- * otherwise the FIRST extension providing a compaction config supplies it.
- * An extension config without a threshold contributes nothing (a boundary
- * needs a threshold to ever fire).
+ * E2/E6: the loop's microcompact config — the session's own microcompact
+ * wins; otherwise the FIRST extension providing a compaction config
+ * supplies it. An extension config without a threshold contributes nothing
+ * (a boundary needs a threshold to ever fire).
+ * E6 (candidate B): the session's contextPolicy.microcompact override beats
+ * the session's own config (a tuned policy wins over the CLI default), and
+ * its minTurns no-fire guard — below that many completed user inputs the
+ * boundary config is OMITTED: a short task never pays a break it cannot
+ * amortize (the E5-F1 accounting).
  */
-export function microcompactFor(config) {
-    if (config.microcompact !== undefined)
-        return config.microcompact;
+export function microcompactFor(config, log) {
+    const policy = config.contextPolicy?.microcompact;
+    const effective = policy !== undefined
+        ? { thresholdTokens: policy.thresholdTokens, ...(policy.keepResults !== undefined ? { keepResults: policy.keepResults } : {}) }
+        : config.microcompact;
+    if (policy?.minTurns !== undefined && log !== undefined) {
+        const userInputs = log.filter((e) => e.type === "user_input").length;
+        if (userInputs < policy.minTurns)
+            return undefined;
+    }
+    if (effective !== undefined)
+        return effective;
     for (const ext of config.extensions ?? []) {
         const c = ext.compaction;
         if (c !== undefined && c.thresholdTokens !== undefined) {

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
 export type { AgentDefinition, PermissionPolicy, PermissionRule } from "./agent.js";
 export { AgentSession, AgentSession as Session } from "./session.js";
 export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
-export type { ApprovalRequest, CompactInfo, SessionConfig, SummarizeResult } from "./session.js";
+export type { ApprovalRequest, CompactInfo, ContextPolicy, SessionConfig, SummarizeResult } from "./session.js";
 export { Run } from "./run.js";
 export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
 export type { Event, SessionMeta, StoreRecord } from "./store.js";

package/dist/run.js

@@ -96,9 +96,11 @@ export class Run {
             });
             tracer.init();
             const signal = this.#externalSignal ? new MergedSignal(this.#abort.signal, this.#externalSignal) : this.#abort.signal;
-            // E2: the session's own microcompact wins; otherwise the FIRST
-            // extension providing a compaction config supplies it.
-            const microcompact = microcompactFor(this.#config);
+            // E2/E6: the session's own microcompact wins; otherwise the FIRST
+            // extension providing a compaction config supplies it. E6: the
+            // contextPolicy override beats the session's own, and its minTurns
+            // no-fire guard may omit the config below the floor.
+            const microcompact = microcompactFor(this.#config, log.all);
             // E2: the session's own systemPrompt first, then every extension
             // append in LOAD order — deterministic (same extensions → same
             // prompt); no appends → byte-identical to the extension-less run.
@@ -228,6 +230,15 @@ export class Run {
             if (openRun !== undefined) {
                 throw new Error(`session ${this.#session.id} still has an open run (${openRun}) — resume() it instead of starting a new run`);
             }
+            // E6 — the run-start context policy: BEFORE this run's
+            // user_input lands, the policy may persist one `summarized`
+            // fact through the existing summarize() path (the manual
+            // /compact affordance point). The boundary then rides the LAST
+            // recorded run, and this run's first request projects the
+            // compressed view. Fresh runs only — the recovery path's
+            // projection must never shift mid-recovery. A summary failure
+            // is swallowed inside (the turn proceeds uncompressed).
+            await this.#session.maybeApplyContextPolicy(signal);
             // 1. Durable first: the prompt enters the log and the store
             //    before any model call — a crash here leaves a restorable
             //    session. The prompt is also the first event the consumer

package/dist/session.d.ts

@@ -127,9 +127,25 @@ export declare class AgentSession {
      */
     summarize(options?: {
         keepRounds?: number;
+        keepTokens?: number;
         signal?: AbortSignalLike;
         onStart?: (info: CompactInfo) => void;
+        drop?: boolean;
     }): Promise<SummarizeResult | null>;
+    /**
+     * E6 — the run-start context policy (candidate A + the crux drop arm).
+     * Called at the start of every FRESH run, BEFORE its user_input lands:
+     * when the policy is armed and the projected context crosses the
+     * trigger (and enough uncovered rounds exist — the keepRounds gate
+     * inside summarize), one `summarized` fact is persisted through the
+     * existing summarize() path. The boundary then rides the LAST recorded
+     * run and the run's first request projects the compressed view.
+     * Restraint: a short session never crosses the trigger — firing is a
+     * net loss by the E5-F1 accounting (a break that cannot amortize).
+     * Failure is swallowed: the compaction is an optimization — "nothing
+     * happened" must never break the user's turn.
+     */
+    maybeApplyContextPolicy(signal?: AbortSignalLike): Promise<void>;
     /**
      * Pauses that still await a human decision (durable, survives restart).
      * B group: a request whose RUN has terminated is DEAD — it is neither
@@ -182,6 +198,69 @@ export declare class AgentSession {
     flushPendingVerdicts(runId: string, log: EventLog): Promise<void>;
     dropResolver(decisionId: string): void;
 }
+/**
+ * E6 — the session context policy (all optional; absent = the pre-E6
+ * behavior, zero change). The policy is INJECTION-side only: every action
+ * persists a durable fact (`summarized`, `microcompacted`) whose projection
+ * shrinks the SENT view — the durable log's bytes never change (the E5
+ * discipline). Actions land at RUN START, never mid-run (D5); the manual
+ * /compact affordance point.
+ */
+export interface ContextPolicy {
+    /**
+     * A — the auto-summary: at run start, when the projected context
+     * crosses the trigger AND enough uncovered rounds exist, the
+     * existing summarize() path persists ONE `summarized` fact. The
+     * keepRounds gate is the amortization structure — a fire needs
+     * keepRounds+1 uncovered rounds, so each boundary is preceded by
+     * that much content and followed by the kept rounds' requests to
+     * amortize the break (the E5-F1 accounting).
+     *
+     * E6 (g): the trigger is EXACTLY ONE of triggerTokens (an absolute,
+     * the legacy override) or windowTokens (the product arming — the
+     * runtime computes window − POLICY_RESERVE; never a fixed low
+     * absolute). keepTokens floors the kept suffix (the (f) budget;
+     * the default KEEP_TOKENS_DEFAULT applies when absent). maxFailures
+     * sets the (h) circuit breaker (the default MAX_SUMMARY_FAILURES
+     * applies when absent).
+     */
+    readonly summary?: {
+        readonly triggerTokens?: number;
+        readonly windowTokens?: number;
+        readonly keepRounds?: number;
+        readonly keepTokens?: number;
+        readonly maxFailures?: number;
+    };
+    /**
+     * C — the crux-experiment drop arm (EXPERIMENT-ONLY, never a default):
+     * the same trigger persists the same-shaped fact with a fixed
+     * placeholder and NO model call — the covered turns leave the sent
+     * context at zero generation cost. When present, it REPLACES the
+     * summary mode (one conversation-layer compactor at a time). The
+     * adopted shape — if the crux evidence earns it — is a distinct
+     * `dropped` event family, not this placeholder text. Same trigger
+     * shapes, keep budget, and breaker as the summary arm.
+     */
+    readonly drop?: {
+        readonly triggerTokens?: number;
+        readonly windowTokens?: number;
+        readonly keepRounds?: number;
+        readonly keepTokens?: number;
+        readonly maxFailures?: number;
+    };
+    /**
+     * B — the session-aware microcompact: the threshold/keep-window
+     * override the session's own microcompact (a tuned policy wins over
+     * the CLI default). minTurns is the no-fire guard: below that many
+     * completed user inputs the boundary config is OMITTED from the loop
+     * — a short task never pays a break it cannot amortize.
+     */
+    readonly microcompact?: {
+        readonly thresholdTokens: number;
+        readonly keepResults?: number;
+        readonly minTurns?: number;
+    };
+}
 export interface SessionConfig {
     readonly model: string;
     /** E1: the adapter identity ("anthropic" | "openai-compat") — trace
@@ -205,6 +284,8 @@ export interface SessionConfig {
     readonly microcompact?: {
         readonly thresholdTokens: number;
     };
+    /** E6: the session context policy (run-start actions, injection-side only). */
+    readonly contextPolicy?: ContextPolicy;
     readonly maxRetries?: number;
     /**
      * E1: loaded extensions — their tools join the registry (idempotently;

package/dist/session.js

@@ -30,7 +30,10 @@
 import { EventLog, projectMessages, } from "@vincemakes/kiso-core";
 import { executionLedger } from "./ledger.js";
 import { denialResult } from "@vincemakes/kiso-core";
-import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "./summarize.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 { canonicalizeUsage } from "./usage/canonical.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { estimateTokens } from "@vincemakes/kiso-core";
 import { StaleWriterError } from "./store.js";
 import { composeHooks } from "./compose.js";
@@ -85,6 +88,9 @@ export class AgentSession {
     #pendingDurableApprovals = new Map();
     #pendingDurableUncertainties = new Map();
     #poisoned = null;
+    /** E6 (h): the circuit-breaker counter — consecutive auto-policy
+     *  summary failures this session (a success resets it). */
+    #summaryFailures = 0;
     /** Permanently invalidate the session after a rejected disk write (round 1). */
     poison(reason) {
         if (this.#poisoned === null)
@@ -199,11 +205,17 @@ export class AgentSession {
         if (options.signal !== undefined && options.signal.aborted)
             throw cancelled();
         const events = this.log.all;
-        const boundary = summaryBoundarySeq(events, keepRounds);
+        const boundary = summaryBoundarySeq(events, keepRounds, options.keepTokens);
         if (boundary === undefined)
             return null;
         const prevPoint = lastSummaryPoint(events);
+        // E6 (a): the summarizer's input is the covered range SERIALIZED to
+        // flat text — one guarded <conversation> user message — never the raw
+        // provider message array (the auto-T5-1 DSML garbage). The projected
+        // messages still feed the pre-call token estimate and the savings
+        // figure (estimate-only, never the model input).
         const covered = projectMessages(events.filter((e) => e.seq > prevPoint && e.seq <= boundary && e.type !== "summarized"));
+        const serializedInput = serializeCovered({ events, prevPoint, boundary });
         // W18: the indicator's pre-call data — rounds + the token estimate
         // are knowable BEFORE the adapter call; the summary itself is ONE
         // call with no fraction (kiso never invents a percentage here).
@@ -214,12 +226,30 @@ export class AgentSession {
             rounds: events.filter((e) => e.type === "user_input" && e.seq > prevPoint && e.seq <= boundary).length,
             tokens: estimateTokens(covered),
         });
-        const summary = await summarizeConversation({
-            adapter: this.#adapter,
-            model: this.#config.model,
-            messages: covered,
-            ...(options.signal !== undefined ? { signal: options.signal } : {}),
-        });
+        let summary;
+        let usage = null;
+        if (options.drop === true) {
+            // E6 — the crux drop arm: mechanical, no model call, the fixed
+            // placeholder replaces the covered range (experiment-only).
+            summary = DROP_PLACEHOLDER;
+        }
+        else {
+            const call = await summarizeConversation({
+                adapter: this.#adapter,
+                model: this.#config.model,
+                // 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,
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+            summary = call.text;
+            usage = call.usage;
+        }
         // The post-call boundary check: an abort that landed while the
         // adapter returned must NOT persist — "nothing happened".
         if (options.signal !== undefined && options.signal.aborted)
@@ -232,8 +262,86 @@ export class AgentSession {
         const records = this.#store.load(this.id);
         const runId = records.length > 0 ? records[records.length - 1].runId : "compact";
         await this.persist(runId, full);
+        // E6 — the honest accounting: the summary call's usage rides the
+        // trace ledger as a `kind: "summary"` line (the fifth ledger kind,
+        // observation-only — the request/run_end/crash vocabulary stands).
+        // The E5-era extraction could not see the call at all; both the
+        // manual /compact path and the auto policy land here. Soft-fail:
+        // a degraded ledger costs one stderr line, never the summary.
+        if (usage !== null) {
+            try {
+                const canonical = canonicalizeUsage(this.#config.provider ?? "adapter", usage);
+                const line = JSON.stringify({ kind: "summary", canonical }) + "\n";
+                mkdirSync(join(this.#store.root, "traces"), { recursive: true });
+                appendFileSync(join(this.#store.root, "traces", `${this.id}.jsonl`), line);
+            }
+            catch (err) {
+                console.error(`[kiso] summary usage ledger degraded (${err instanceof Error ? err.message : String(err)}); the summary call's cost is not recorded`);
+            }
+        }
         return { coversToSeq: boundary, summary, savedTokens: estimateSummarySavings(covered, summary) };
     }
+    /**
+     * E6 — the run-start context policy (candidate A + the crux drop arm).
+     * Called at the start of every FRESH run, BEFORE its user_input lands:
+     * when the policy is armed and the projected context crosses the
+     * trigger (and enough uncovered rounds exist — the keepRounds gate
+     * inside summarize), one `summarized` fact is persisted through the
+     * existing summarize() path. The boundary then rides the LAST recorded
+     * run and the run's first request projects the compressed view.
+     * Restraint: a short session never crosses the trigger — firing is a
+     * net loss by the E5-F1 accounting (a break that cannot amortize).
+     * Failure is swallowed: the compaction is an optimization — "nothing
+     * happened" must never break the user's turn.
+     */
+    async maybeApplyContextPolicy(signal) {
+        const policy = this.#config.contextPolicy;
+        if (policy === undefined)
+            return;
+        const mode = policy.drop ?? policy.summary;
+        if (mode === undefined)
+            return;
+        // E6 (g): the trigger is exactly one of triggerTokens (absolute)
+        // or windowTokens (window − POLICY_RESERVE, the product arming).
+        // The undefined guard is the belt: `projected <= undefined` is
+        // ALWAYS false, so a naive gate would fall THROUGH and fire
+        // unconditionally — an unresolved trigger must never fire.
+        const triggerTokens = mode.windowTokens !== undefined ? policyTriggerFromWindow(mode.windowTokens) : mode.triggerTokens;
+        if (triggerTokens === undefined)
+            return;
+        // E6 (h): the circuit breaker — after maxFailures consecutive
+        // summary failures the auto policy stands down for the rest of
+        // the session (a persistent failure — a broken provider, a
+        // hostile model — must never wedge the session into paying the
+        // summary call every run).
+        const maxFailures = mode.maxFailures ?? MAX_SUMMARY_FAILURES;
+        if (this.#summaryFailures >= maxFailures)
+            return;
+        if (estimateTokens(this.projected()) <= triggerTokens)
+            return;
+        try {
+            await this.summarize({
+                keepRounds: mode.keepRounds ?? KEEP_RECENT_ROUNDS,
+                // E6 (f): the keep budget is rounds AND tokens — the policy
+                // layer applies the 20k floor by default (small sessions are
+                // inert: the E5-F1 restraint, token-shaped).
+                keepTokens: mode.keepTokens ?? KEEP_TOKENS_DEFAULT,
+                ...(signal !== undefined ? { signal } : {}),
+                ...(policy.drop !== undefined ? { drop: true } : {}),
+            });
+            // A persisted fire resets the breaker — the failures were a
+            // transient blip, the budget starts fresh.
+            this.#summaryFailures = 0;
+        }
+        catch {
+            // the compaction failed — the session is unchanged and the run
+            // proceeds with the full context (the ADR-0044 "nothing
+            // happened" crash semantics, policy-shaped). The failure counts
+            // toward the breaker (both adapter failures and (b) rejections
+            // land here).
+            this.#summaryFailures += 1;
+        }
+    }
     // ── Phase D: approvals ───────────────────────────────────────────────
     /**
      * Pauses that still await a human decision (durable, survives restart).

package/dist/summarize.d.ts

@@ -16,28 +16,124 @@
 import type { AbortSignalLike, Adapter } from "@vincemakes/kiso-core";
 import type { Event } from "@vincemakes/kiso-core";
 import type { Message } from "@vincemakes/kiso-core";
+import type { RawUsage } from "./usage/canonical.js";
 /** K (ADR-0044): the recent ROUNDS kept intact by /compact — a constant,
  *  not a knob. The covered range ends just before the K-th most recent
  *  round, so the model still reasons over the recent conversation. */
 export declare const KEEP_RECENT_ROUNDS = 4;
+/** E6 (a) — the input-side DSML guard (the finding E6-F4/F5 follow-up):
+ *  the guard sentence sits at the TOP of the system prompt (the BEFORE
+ *  copy of the sandwich) AND again after the </conversation> block in the
+ *  serialized input (the AFTER copy). The summarizer is a side-channel
+ *  task — it must never continue the work, never touch tools, and only
+ *  emit the summary text. */
+export declare const SUMMARY_GUARD = "Only output the summary. Do not continue the conversation. Do not use any tools.";
+/** The tool-result truncation ceiling in the serialized input: a huge
+ *  result must not dominate the summary input, and the truncation is
+ *  MARKED with the discarded character count — never silent. */
+export declare const SUMMARY_RESULT_MAX_CHARS = 2000;
+/**
+ * E6 (g) — the reserve arithmetic (the pre-registered numbers): the
+ * armed trigger is WINDOW − RESERVE, never a fixed low absolute (the
+ * e6probe's fixed 1300 fired 16-19× a session — the pathology the
+ * window math kills). The reserve is what ONE fire must buy back:
+ * the summary's own output budget (4,000), the kept-suffix token
+ * floor (20,000, item (f)), and the current run's in-flight context
+ * while the post-fire projection settles (8,000).
+ */
+export declare const SUMMARY_MAX_OUTPUT = 4000;
+export declare const KEEP_TOKENS_DEFAULT = 20000;
+export declare const IN_FLIGHT_HEADROOM = 8000;
+export declare const POLICY_RESERVE: number;
+/** 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
+ *  the session settles after one fire. */
+export declare const DEFAULT_CONTEXT_WINDOW = 120000;
+/** The armed trigger for a context window: window − POLICY_RESERVE. A
+ *  window below the reserve arms a NEGATIVE trigger — the session
+ *  never fires (the honest inert refusal: the window cannot hold even
+ *  the post-fire projection, so the policy stays off, never clamped
+ *  into pretending). */
+export declare function policyTriggerFromWindow(windowTokens?: number): number;
+/**
+ * E6 (h) — the circuit breaker: MAX_SUMMARY_FAILURES consecutive
+ * summary failures per session stand the auto policy down (no further
+ * auto-fire attempts; a success resets). Both adapter failures and the
+ * (b) validation rejections count — they throw through the policy's
+ * safe catch. A persistent summary failure (a broken provider, a
+ * hostile model) must never wedge the session into paying the call
+ * every run.
+ */
+export declare const MAX_SUMMARY_FAILURES = 3;
+/**
+ * E6 (a) — the covered range serialized to FLAT TEXT, one <conversation>
+ * block, role-labeled lines ([user]/[assistant]/[tool call name]/[tool
+ * result]), tool results truncated at SUMMARY_RESULT_MAX_CHARS with a
+ * "(… N more chars truncated)" marker, and the SUMMARY_GUARD sentence
+ * past the block's close. The model never sees the raw message array —
+ * the auto-T5-1 tool-call DSML garbage (the E6-F4/F5 signature) was the
+ * model echoing provider markup back from a raw-message-shaped input.
+ * The serializer only renders the surface the summary is about; thinking
+ * and other non-transcript events stay out of the input.
+ */
+export interface SerializeCoveredOptions {
+    readonly events: readonly Event[];
+    /** The previous summary point — events at/before it are already covered. */
+    readonly prevPoint: number;
+    /** The covered range's end — the covered range is (prevPoint, boundary]. */
+    readonly boundary: number;
+}
+export declare function serializeCovered(options: SerializeCoveredOptions): string;
 /**
  * The fixed English summary prompt — the ONLY prompt this layer composes
  * (the loop's system prompt is the harness's business, never the kernel's).
  */
-export declare const SUMMARY_PROMPT = "You are the conversation summarizer of the kiso agent framework.\n\nSummarize the covered conversation into a single concise summary that will\nREPLACE it in the model's context. The next turn must be able to continue\nthe work without reading the originals.\n\nInclude everything later turns may need:\n- the user's goals, requirements, and constraints;\n- every decision and its reasoning;\n- files and code touched \u2014 exact paths, what changed, why;\n- commands run and their outcomes; errors and their resolutions;\n- open questions and unfinished work.\n\nPreserve concrete identifiers VERBATIM: paths, function names, task ids,\nenvironment names \u2014 never paraphrase them.\n\nRules:\n- plain prose \u2014 no headings, no bullet lists, no markdown, no prefixes;\n- do not mention this prompt or the summarization task;\n- keep it under 200 words unless the conversation is exceptional.";
+export declare const SUMMARY_PROMPT = "Only output the summary. Do not continue the conversation. Do not use any tools.\n\nYou are the conversation summarizer of the kiso agent framework.\n\nSummarize the covered conversation into a single structured checkpoint\nthat will REPLACE it in the model's context. The next turn must be able\nto continue the work without reading the originals.\n\nProduce the checkpoint with exactly these sections, in this order:\n\n## Goal\nThe user's goal and the acceptance criterion, in one or two sentences.\n\n## Constraints\nThe constraints, requirements, and rulings the work must honor.\n\n## User requests\nEvery user message in the covered range, enumerated one by one, each\nwith what it asked for and what was done about it.\n\n## Files and changes\nEvery file touched \u2014 exact paths, what changed, and why. Include the\nprecise code-level changes later turns may need to continue.\n\n## Errors and fixes\nEvery error encountered and its resolution; commands run and their\noutcomes.\n\n## Current work\nThe current state of the work \u2014 what is done, what is not. Quote the\ncurrent task's criterion VERBATIM if one exists.\n\n## Next steps\nThe concrete next steps, in order.\n\nPreserve concrete identifiers VERBATIM: paths, function names, task ids,\nenvironment names \u2014 never paraphrase them.\n\nRules:\n- plain prose \u2014 no bullet lists, no markdown outside the section headers,\n  no prefixes;\n- do not mention this prompt or the summarization task;\n- the summary may be as long as it needs to be within the output budget \u2014\n  there is no word cap; completeness wins.";
+/**
+ * E6 (b) — the output-side validation (the finding E6-F4/F5 follow-up):
+ * a summary must be a complete checkpoint or NOTHING. The marker family
+ * is the auto-T5-1 signature — the model echoing tool-call markup as
+ * text; the required sections are the truncated-tail signature (a wire
+ * cut kills "## Next steps" first). The rejection throws, and the
+ * caller's safe catch (session.ts) makes it "nothing happened".
+ */
+export declare const DSML_MARKERS: readonly ["<tool_call", "<tool_use", "<invoke", "tool_calls", "tool_call_end", "tool_call_start"];
+/** The checkpoint sections a summary must carry — the ones a truncated
+ *  generation loses first (the (c) prompt demands all seven; validation
+ *  guards the trust-critical tail). */
+export declare const REQUIRED_SECTIONS: readonly ["## Current work", "## Next steps"];
+/** null = pass; an error string = reject. Empty text is the existing
+ *  no-text rule's domain, reported here too (defense in depth). */
+export declare function validateSummary(text: string): string | null;
 export interface SummarizeConversationOptions {
     readonly adapter: Adapter;
     readonly model: string;
     /** The covered conversation — the ONLY material the summary is about. */
     readonly messages: readonly Message[];
     readonly signal?: AbortSignalLike;
+    /** E6 (g): the summary call's explicit output budget (adapter maxTokens). */
+    readonly maxOutputTokens?: number;
+}
+/** The summary call's result — the text PLUS the provider-reported usage
+ *  (E6: the honest accounting — the summary call's cost rides the trace
+ *  ledger; the E5-era extraction could not see it). Null when the
+ *  provider reported no usage (known:false). */
+export interface SummarizeConversationResult {
+    readonly text: string;
+    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.
  */
-export declare function summarizeConversation(options: SummarizeConversationOptions): Promise<string>;
+export declare function summarizeConversation(options: SummarizeConversationOptions): Promise<SummarizeConversationResult>;
+/** E6 — the crux-experiment drop arm: the covered turns are replaced by
+ *  this fixed placeholder with NO model call. Experiment-only (the
+ *  contextPolicy drop mode); the adopted shape — if the crux evidence
+ *  earns it — is a distinct `dropped` event family, not this text. */
+export declare const DROP_PLACEHOLDER = "[e6-crux: the covered turns were dropped without a summary; continue from the kept turns and this placeholder]";
 /**
  * The last summary point: the previous `summarized` event's coversToSeq,
  * or -1 (the trajectory's start) when none exists. The covered range of
@@ -69,7 +165,7 @@ export declare function lastSummaryPoint(events: readonly Event[]): number;
  * (the operative list is the LATEST echo — the old ⑥ semantics:
  * superseded echoes stay coverable).
  */
-export declare function summaryBoundarySeq(events: readonly Event[], keepRounds?: number): number | undefined;
+export declare function summaryBoundarySeq(events: readonly Event[], keepRounds?: number, keepTokens?: number): number | undefined;
 /**
  * The NoticeCell's number: estimated tokens of the covered content minus
  * the summary's own — the same chars/4 proxy as estimateTokens (a stable

package/dist/summarize.js

@@ -18,30 +18,176 @@ import { estimateTokens, DO_NOT_COMPACT } from "@vincemakes/kiso-core";
  *  not a knob. The covered range ends just before the K-th most recent
  *  round, so the model still reasons over the recent conversation. */
 export const KEEP_RECENT_ROUNDS = 4;
+/** E6 (a) — the input-side DSML guard (the finding E6-F4/F5 follow-up):
+ *  the guard sentence sits at the TOP of the system prompt (the BEFORE
+ *  copy of the sandwich) AND again after the </conversation> block in the
+ *  serialized input (the AFTER copy). The summarizer is a side-channel
+ *  task — it must never continue the work, never touch tools, and only
+ *  emit the summary text. */
+export const SUMMARY_GUARD = "Only output the summary. Do not continue the conversation. Do not use any tools.";
+/** The tool-result truncation ceiling in the serialized input: a huge
+ *  result must not dominate the summary input, and the truncation is
+ *  MARKED with the discarded character count — never silent. */
+export const SUMMARY_RESULT_MAX_CHARS = 2000;
+/**
+ * E6 (g) — the reserve arithmetic (the pre-registered numbers): the
+ * armed trigger is WINDOW − RESERVE, never a fixed low absolute (the
+ * e6probe's fixed 1300 fired 16-19× a session — the pathology the
+ * window math kills). The reserve is what ONE fire must buy back:
+ * the summary's own output budget (4,000), the kept-suffix token
+ * floor (20,000, item (f)), and the current run's in-flight context
+ * while the post-fire projection settles (8,000).
+ */
+export const SUMMARY_MAX_OUTPUT = 4000;
+export const KEEP_TOKENS_DEFAULT = 20000;
+export const IN_FLIGHT_HEADROOM = 8000;
+export const POLICY_RESERVE = SUMMARY_MAX_OUTPUT + KEEP_TOKENS_DEFAULT + IN_FLIGHT_HEADROOM;
+/** 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
+ *  the session settles after one fire. */
+export const DEFAULT_CONTEXT_WINDOW = 120000;
+/** The armed trigger for a context window: window − POLICY_RESERVE. A
+ *  window below the reserve arms a NEGATIVE trigger — the session
+ *  never fires (the honest inert refusal: the window cannot hold even
+ *  the post-fire projection, so the policy stays off, never clamped
+ *  into pretending). */
+export function policyTriggerFromWindow(windowTokens = DEFAULT_CONTEXT_WINDOW) {
+    return windowTokens - POLICY_RESERVE;
+}
+/**
+ * E6 (h) — the circuit breaker: MAX_SUMMARY_FAILURES consecutive
+ * summary failures per session stand the auto policy down (no further
+ * auto-fire attempts; a success resets). Both adapter failures and the
+ * (b) validation rejections count — they throw through the policy's
+ * safe catch. A persistent summary failure (a broken provider, a
+ * hostile model) must never wedge the session into paying the call
+ * every run.
+ */
+export const MAX_SUMMARY_FAILURES = 3;
+export function serializeCovered(options) {
+    const { events, prevPoint, boundary } = options;
+    const lines = ["<conversation>"];
+    // E6 (d) (the order's R4): the old summary texts are RETAINED CONTEXT —
+    // the durable record of the earlier ranges. They render first, labeled
+    // do-not-re-summarize: the summarizer must know what the earlier
+    // summaries covered, but never fold them into the new checkpoint.
+    const retained = events.filter((e) => e.type === "summarized" && e.coversToSeq <= prevPoint);
+    if (retained.length > 0) {
+        lines.push("[retained context — do not re-summarize]");
+        for (const r of retained)
+            lines.push(`[summary covers to seq ${r.coversToSeq}] ${r.summary}`);
+        lines.push("[end retained context]");
+    }
+    for (const ev of events) {
+        if (ev.seq <= prevPoint || ev.seq > boundary || ev.type === "summarized")
+            continue;
+        switch (ev.type) {
+            case "user_input":
+                lines.push(`[user] ${ev.content}`);
+                break;
+            case "text_delta":
+                lines.push(`[assistant] ${ev.text}`);
+                break;
+            case "tool_call_end":
+                lines.push(`[tool call ${ev.name}] ${JSON.stringify(ev.input ?? null)}`);
+                break;
+            case "tool_result": {
+                const content = String(ev.content ?? "");
+                if (content.length > SUMMARY_RESULT_MAX_CHARS) {
+                    const rest = content.length - SUMMARY_RESULT_MAX_CHARS;
+                    lines.push(`[tool result] ${content.slice(0, SUMMARY_RESULT_MAX_CHARS)}… (${rest.toLocaleString("en-US")} more chars truncated)`);
+                }
+                else {
+                    lines.push(`[tool result] ${content}`);
+                }
+                break;
+            }
+            default:
+                break; // thinking and the rest never enter the transcript surface
+        }
+    }
+    lines.push("</conversation>", "", SUMMARY_GUARD);
+    return lines.join("\n");
+}
 /**
  * The fixed English summary prompt — the ONLY prompt this layer composes
  * (the loop's system prompt is the harness's business, never the kernel's).
  */
-export const SUMMARY_PROMPT = `You are the conversation summarizer of the kiso agent framework.
+export const SUMMARY_PROMPT = `${SUMMARY_GUARD}
+
+You are the conversation summarizer of the kiso agent framework.
+
+Summarize the covered conversation into a single structured checkpoint
+that will REPLACE it in the model's context. The next turn must be able
+to continue the work without reading the originals.
+
+Produce the checkpoint with exactly these sections, in this order:
+
+## Goal
+The user's goal and the acceptance criterion, in one or two sentences.
+
+## Constraints
+The constraints, requirements, and rulings the work must honor.
+
+## User requests
+Every user message in the covered range, enumerated one by one, each
+with what it asked for and what was done about it.
 
-Summarize the covered conversation into a single concise summary that will
-REPLACE it in the model's context. The next turn must be able to continue
-the work without reading the originals.
+## Files and changes
+Every file touched — exact paths, what changed, and why. Include the
+precise code-level changes later turns may need to continue.
 
-Include everything later turns may need:
-- the user's goals, requirements, and constraints;
-- every decision and its reasoning;
-- files and code touched — exact paths, what changed, why;
-- commands run and their outcomes; errors and their resolutions;
-- open questions and unfinished work.
+## Errors and fixes
+Every error encountered and its resolution; commands run and their
+outcomes.
+
+## Current work
+The current state of the work — what is done, what is not. Quote the
+current task's criterion VERBATIM if one exists.
+
+## Next steps
+The concrete next steps, in order.
 
 Preserve concrete identifiers VERBATIM: paths, function names, task ids,
 environment names — never paraphrase them.
 
 Rules:
-- plain prose — no headings, no bullet lists, no markdown, no prefixes;
+- plain prose — no bullet lists, no markdown outside the section headers,
+  no prefixes;
 - do not mention this prompt or the summarization task;
-- keep it under 200 words unless the conversation is exceptional.`;
+- the summary may be as long as it needs to be within the output budget —
+  there is no word cap; completeness wins.`;
+/**
+ * E6 (b) — the output-side validation (the finding E6-F4/F5 follow-up):
+ * a summary must be a complete checkpoint or NOTHING. The marker family
+ * is the auto-T5-1 signature — the model echoing tool-call markup as
+ * text; the required sections are the truncated-tail signature (a wire
+ * cut kills "## Next steps" first). The rejection throws, and the
+ * caller's safe catch (session.ts) makes it "nothing happened".
+ */
+export const DSML_MARKERS = ["<tool_call", "<tool_use", "<invoke", "tool_calls", "tool_call_end", "tool_call_start"];
+/** The checkpoint sections a summary must carry — the ones a truncated
+ *  generation loses first (the (c) prompt demands all seven; validation
+ *  guards the trust-critical tail). */
+export const REQUIRED_SECTIONS = ["## Current work", "## Next steps"];
+/** null = pass; an error string = reject. Empty text is the existing
+ *  no-text rule's domain, reported here too (defense in depth). */
+export function validateSummary(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return "the summary is empty";
+    const lower = trimmed.toLowerCase();
+    for (const marker of DSML_MARKERS) {
+        if (lower.includes(marker))
+            return `the summary carries a tool-call marker (${marker}) — reject`;
+    }
+    for (const section of REQUIRED_SECTIONS) {
+        if (!trimmed.includes(section))
+            return `the summary is missing the required section ${section} — a truncated or incomplete checkpoint`;
+    }
+    return null;
+}
 /**
  * The one-shot summary call. Collects the adapter's text deltas into the
  * summary; usage/stop pass through untouched. Throws when the model
@@ -50,21 +196,38 @@ Rules:
 export async function summarizeConversation(options) {
     const { adapter, model, messages } = options;
     let text = "";
+    let usage = null;
     for await (const ev of adapter.stream({
         model,
         messages,
         systemPrompt: SUMMARY_PROMPT,
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.maxOutputTokens !== undefined ? { maxTokens: options.maxOutputTokens } : {}),
     })) {
         if (ev.type === "text_delta")
             text += ev.text;
+        // The LAST usage event is the call's (a turn reports usage once).
+        if (ev.type === "usage" && ev.known) {
+            usage = { inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, cacheRead: ev.cacheRead, cacheWrite: ev.cacheWrite };
+        }
     }
     const trimmed = text.trim();
     if (trimmed === "") {
         throw new Error("the summary call produced no text");
     }
-    return trimmed;
+    // E6 (b): a non-checkpoint summary is an honest failure — throw, the
+    // caller reports it, nothing is persisted (the auto-T5-1 regression).
+    const invalid = validateSummary(trimmed);
+    if (invalid !== null) {
+        throw new Error(`the summary call produced an invalid summary: ${invalid}`);
+    }
+    return { text: trimmed, usage };
 }
+/** E6 — the crux-experiment drop arm: the covered turns are replaced by
+ *  this fixed placeholder with NO model call. Experiment-only (the
+ *  contextPolicy drop mode); the adopted shape — if the crux evidence
+ *  earns it — is a distinct `dropped` event family, not this text. */
+export const DROP_PLACEHOLDER = "[e6-crux: the covered turns were dropped without a summary; continue from the kept turns and this placeholder]";
 /**
  * The last summary point: the previous `summarized` event's coversToSeq,
  * or -1 (the trajectory's start) when none exists. The covered range of
@@ -78,6 +241,23 @@ export function lastSummaryPoint(events) {
     }
     return prev;
 }
+/** 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) {
+    switch (ev.type) {
+        case "user_input":
+            return Math.ceil(ev.content.length / 4);
+        case "text_delta":
+            return Math.ceil(ev.text.length / 4);
+        case "tool_call_end":
+            return Math.ceil(JSON.stringify(ev.input ?? null).length / 4) + 20;
+        case "tool_result":
+            return Math.ceil(String(ev.content ?? "").length / 4);
+        default:
+            return 0;
+    }
+}
 /**
  * The covered range's end: the seq of the event just before the
  * keepRounds-th most recent user_input AFTER the last summary point —
@@ -103,7 +283,7 @@ export function lastSummaryPoint(events) {
  * (the operative list is the LATEST echo — the old ⑥ semantics:
  * superseded echoes stay coverable).
  */
-export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
+export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS, keepTokens) {
     const prevPoint = lastSummaryPoint(events);
     const uncoveredInputs = [];
     for (const ev of events) {
@@ -114,6 +294,36 @@ export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
         return undefined;
     const firstUncovered = uncoveredInputs[0];
     let boundary = uncoveredInputs[uncoveredInputs.length - keepRounds] - 1;
+    // E6 (f): the keep budget is rounds AND tokens. A kept suffix smaller
+    // than keepTokens is a break the session cannot amortize (the E5-F1
+    // accounting) — walk the boundary back (keep more) until the kept
+    // events clear the floor. The walk picks the smallest kept suffix
+    // meeting it: per-event cumulative tokens, one pass. A floor the whole
+    // uncovered range cannot meet → nothing to compact (the policy is
+    // inert on small sessions — the token-shaped restraint).
+    if (keepTokens !== undefined && keepTokens > 0) {
+        const prefixTokens = [0];
+        let total = 0;
+        for (const ev of events) {
+            total += estimateEventTokens(ev);
+            prefixTokens.push(total);
+        }
+        const keptTokens = (b) => total - prefixTokens[b + 1];
+        let floorBoundary;
+        for (let i = uncoveredInputs.length - 1; i >= 0; i--) {
+            const b = uncoveredInputs[i] - 1;
+            if (keptTokens(b) >= keepTokens) {
+                floorBoundary = b;
+                break;
+            }
+        }
+        // b < firstUncovered covers no whole round (or the empty residue) —
+        // the honest nothing-to-compact.
+        if (floorBoundary === undefined || floorBoundary < firstUncovered)
+            return undefined;
+        if (floorBoundary < boundary)
+            boundary = floorBoundary;
+    }
     // The protected pullback applies ONCE on the base range (⑥); the
     // straddle pullback recomputes against the SHRINKING range below it.
     const protectedBoundary = latestProtectedBoundary(events, prevPoint, boundary);

package/package.json

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