@vincemakes/kiso-core 0.1.19 → 0.1.20

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./kernel/mode.js";
 export * from "./kernel/permission.js";
 export * from "./kernel/loop.js";
 export * from "./kernel/compaction.js";
+export * from "./kernel/summarize.js";
 export * from "./kernel/project.js";
 export * from "./kernel/ledger.js";
 export * from "./governance/delivery.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./kernel/mode.js";
 export * from "./kernel/permission.js";
 export * from "./kernel/loop.js";
 export * from "./kernel/compaction.js";
+export * from "./kernel/summarize.js";
 export * from "./kernel/project.js";
 export * from "./kernel/ledger.js";
 export * from "./governance/delivery.js";

package/dist/kernel/compaction.d.ts

@@ -1,60 +1,26 @@
 /**
- * L2 — compaction primitives.
+ * L2 — context-economy primitives, the MECHANICAL half.
  *
  * The kernel's compaction policy is identity preservation, not summary
- * (mauri ADR-0007): keep the message SHELL (id, role, position), replace the
- * content with a marker, zero LLM calls. A summary is a NEW message; it never
- * rewrites an old one. Messages are immutable (ADR-0002) — "clearing" is
- * append, not mutation.
+ * (mauri ADR-0007): keep the message SHELL (id, role, position), replace
+ * the content with a marker, zero LLM calls. A summary is a NEW message; it
+ * never rewrites an old one. Messages are immutable (ADR-0002) — "clearing"
+ * is append, not mutation.
  *
- * The idempotence predicate is the first thing here because it is the FIRST
- * kernel function demanded by a fixture: the compaction-regrowth incident
- * (uooki 2026, video pipeline) was an O(N²) growth where repeated compaction
- * re-archived messages already marked cleared, overwriting their original
- * content. One line fixed it: a marked message is never archived again.
+ * ADR-0044 merged the classic auto-compaction (`config.compaction` +
+ * `compacted` events) INTO the microcompact boundary: the loop no longer
+ * produces `compacted` events (the boundary's projection derives the same
+ * cleared view deterministically), and this module now holds only what the
+ * live path shares. Old sessions' `compacted` events still replay verbatim
+ * — see kernel/project.ts.
+ *
+ * The model-generated half of context economy (the /compact summary layer)
+ * lives in kernel/summarize.ts.
  */
-import type { AssistantBlock, Message } from "../protocol/messages.js";
-/** Marker prefix for cleared tool results. Must be unambiguous and stable. */
-export declare const CLEARED_MARKER_PREFIX = "[content cleared \u2014 reference by revision]";
-export declare function isClearedMarker(content: string): boolean;
-/** Idempotence gate: a message whose content is already the clear marker is
- *  never compacted again, never re-archived, never overwritten. */
-export declare function shouldClearContent(content: string): boolean;
+import type { Message } from "../protocol/messages.js";
 /**
  * Rough token estimate (chars/4 + structural overhead). Calibration-free on
- * purpose: compaction only needs a stable MONOTONE proxy, not an exact
+ * purpose: context economy only needs a stable MONOTONE proxy, not an exact
  * count — the threshold absorbs the error (mauri ADR-0007).
  */
 export declare function estimateTokens(messages: readonly Message[]): number;
-/**
- * Microcompact — zero-LLM context relief (ported shape from oohki runner,
- * adapted to kiso's Message union; identity preservation, ADR-0007):
- *
- * 1. Find the boundary: the KEEP_RECENT_TURNS-th user message from the end.
- *    Recent turns stay fully intact — the model must reason about them.
- * 2. Tool results BEFORE the boundary have their content replaced by a stub
- *    that keeps the name + char count (an information anchor, not a hole).
- * 3. Idempotent: already-cleared content is never touched again (the
- *    compaction-regrowth incident's one-line fix, as a first-class rule).
- * 4. Returns a NEW array; messages are immutable (ADR-0002).
- */
-export declare const KEEP_RECENT_TURNS = 5;
-export interface MicrocompactResult {
-    readonly messages: readonly Message[];
-    /** How much content (chars) was cleared this pass. */
-    readonly clearedChars: number;
-    /**
-     * ONLY the tool results cleared THIS pass — the delta, never the
-     * cumulative marker set (五: a replayable trajectory must not record the
-     * same replacement on every turn). `eventSeq` is the cleared result's
-     * stable identity (the tool_result event's seq, attached by the
-     * projection); it is undefined for hand-built messages outside the loop.
-     */
-    readonly cleared: readonly {
-        readonly eventSeq?: number;
-        readonly callId: string;
-        readonly content: string;
-    }[];
-}
-export declare function microcompact(messages: readonly Message[]): MicrocompactResult;
-export type { AssistantBlock };

package/dist/kernel/compaction.js

@@ -1,31 +1,25 @@
 /**
- * L2 — compaction primitives.
+ * L2 — context-economy primitives, the MECHANICAL half.
  *
  * The kernel's compaction policy is identity preservation, not summary
- * (mauri ADR-0007): keep the message SHELL (id, role, position), replace the
- * content with a marker, zero LLM calls. A summary is a NEW message; it never
- * rewrites an old one. Messages are immutable (ADR-0002) — "clearing" is
- * append, not mutation.
+ * (mauri ADR-0007): keep the message SHELL (id, role, position), replace
+ * the content with a marker, zero LLM calls. A summary is a NEW message; it
+ * never rewrites an old one. Messages are immutable (ADR-0002) — "clearing"
+ * is append, not mutation.
  *
- * The idempotence predicate is the first thing here because it is the FIRST
- * kernel function demanded by a fixture: the compaction-regrowth incident
- * (uooki 2026, video pipeline) was an O(N²) growth where repeated compaction
- * re-archived messages already marked cleared, overwriting their original
- * content. One line fixed it: a marked message is never archived again.
+ * ADR-0044 merged the classic auto-compaction (`config.compaction` +
+ * `compacted` events) INTO the microcompact boundary: the loop no longer
+ * produces `compacted` events (the boundary's projection derives the same
+ * cleared view deterministically), and this module now holds only what the
+ * live path shares. Old sessions' `compacted` events still replay verbatim
+ * — see kernel/project.ts.
+ *
+ * The model-generated half of context economy (the /compact summary layer)
+ * lives in kernel/summarize.ts.
  */
-/** Marker prefix for cleared tool results. Must be unambiguous and stable. */
-export const CLEARED_MARKER_PREFIX = "[content cleared — reference by revision]";
-export function isClearedMarker(content) {
-    return content.startsWith(CLEARED_MARKER_PREFIX);
-}
-/** Idempotence gate: a message whose content is already the clear marker is
- *  never compacted again, never re-archived, never overwritten. */
-export function shouldClearContent(content) {
-    return !isClearedMarker(content);
-}
 /**
  * Rough token estimate (chars/4 + structural overhead). Calibration-free on
- * purpose: compaction only needs a stable MONOTONE proxy, not an exact
+ * purpose: context economy only needs a stable MONOTONE proxy, not an exact
  * count — the threshold absorbs the error (mauri ADR-0007).
  */
 export function estimateTokens(messages) {
@@ -48,70 +42,3 @@ export function estimateTokens(messages) {
     }
     return total;
 }
-/**
- * Microcompact — zero-LLM context relief (ported shape from oohki runner,
- * adapted to kiso's Message union; identity preservation, ADR-0007):
- *
- * 1. Find the boundary: the KEEP_RECENT_TURNS-th user message from the end.
- *    Recent turns stay fully intact — the model must reason about them.
- * 2. Tool results BEFORE the boundary have their content replaced by a stub
- *    that keeps the name + char count (an information anchor, not a hole).
- * 3. Idempotent: already-cleared content is never touched again (the
- *    compaction-regrowth incident's one-line fix, as a first-class rule).
- * 4. Returns a NEW array; messages are immutable (ADR-0002).
- */
-export const KEEP_RECENT_TURNS = 5;
-export function microcompact(messages) {
-    const userIndices = [];
-    for (let i = 0; i < messages.length; i++) {
-        if (messages[i]?.role === "user")
-            userIndices.push(i);
-    }
-    if (userIndices.length <= KEEP_RECENT_TURNS) {
-        return { messages, clearedChars: 0, cleared: [] };
-    }
-    const recentBoundary = userIndices[userIndices.length - KEEP_RECENT_TURNS];
-    const nameByCallId = buildToolNameMap(messages);
-    let clearedChars = 0;
-    const cleared = [];
-    let changed = false;
-    const result = messages.map((msg, i) => {
-        if (i >= recentBoundary || msg.role !== "tool")
-            return msg;
-        if (typeof msg.content !== "string")
-            return msg; // binary content is untouched
-        if (!shouldClearContent(msg.content))
-            return msg; // idempotence gate
-        const toolName = nameByCallId.get(msg.callId) ?? "unknown";
-        const eventSeq = msg.eventSeq;
-        clearedChars += msg.content.length;
-        cleared.push({
-            ...(eventSeq !== undefined ? { eventSeq } : {}),
-            callId: msg.callId,
-            content: `${CLEARED_MARKER_PREFIX} ${toolName} returned ${msg.content.length.toLocaleString()} chars — compacted`,
-        });
-        changed = true;
-        return {
-            ...msg,
-            content: `${CLEARED_MARKER_PREFIX} ${toolName} returned ${msg.content.length.toLocaleString()} chars — compacted`,
-        };
-    });
-    return {
-        messages: changed ? result : messages,
-        clearedChars,
-        cleared,
-    };
-}
-/** callId → tool name, from assistant tool_use blocks (for the stub). */
-function buildToolNameMap(messages) {
-    const map = new Map();
-    for (const msg of messages) {
-        if (msg.role !== "assistant")
-            continue;
-        for (const block of msg.blocks) {
-            if (block.type === "tool_use")
-                map.set(block.callId, block.name);
-        }
-    }
-    return map;
-}

package/dist/kernel/hooks.d.ts

@@ -39,9 +39,13 @@ export interface HookHost {
     onPreTool?(call: ToolCallPayload, ctx: HookContext): Promise<PermissionDecision>;
     /** Execute: rewrite the result a tool returns. */
     onPostTool?(call: ToolCallPayload, result: ToolResult, ctx: HookContext): Promise<ToolResult>;
-    /** Lifecycle: compaction is about to replace history. */
+    /**
+     * DEPRECATED (ADR-0044): the classic auto-compaction path is retired —
+     * the loop never fires these (the microcompact boundary replaced it).
+     * Kept so the extension contract type-checks; inert. Removed at 1.0.
+     */
     onPreCompact?(messages: readonly Message[], ctx: HookContext): Promise<void>;
-    /** Lifecycle: compaction finished. */
+    /** DEPRECATED (ADR-0044): see onPreCompact — never invoked. */
     onPostCompact?(messages: readonly Message[], ctx: HookContext): Promise<void>;
     /** Lifecycle: the loop paused (human decision pending). */
     onPause?(reason: string, ctx: HookContext): Promise<void>;

package/dist/kernel/loop.d.ts

@@ -9,8 +9,9 @@
  * stored alongside it — every adapter call derives them via
  * `projectMessages(log.all)` (kernel/project.ts). A fresh log encodes the
  * seed `messages` into events first, so even a one-shot call replays
- * exactly. Compaction is recorded as a `compacted` event and re-applied by
- * the projection, keeping the replay identical to the live run.
+ * exactly. Compaction is recorded as a `microcompacted` boundary (old
+ * sessions: a `compacted` event) and re-applied by the projection, keeping
+ * the replay identical to the live run.
  *
  * Per iteration:
  *   assemble (onUserMessage / onPreLlm)
@@ -54,8 +55,13 @@ export interface LoopConfig {
     readonly messages?: readonly Message[];
     /** The run's event log. Pass the session's log to make this run durable. */
     readonly log?: EventLog;
-    /** Auto-compaction: when the estimated context exceeds the threshold,
-     *  microcompact old tool results before the next model call. */
+    /**
+     * DEPRECATED (ADR-0044): the classic auto-compaction path is retired —
+     * the loop no longer produces `compacted` events; the microcompact
+     * boundary (below) absorbed the responsibility. Kept so old configs
+     * type-check; IGNORED. Old sessions' `compacted` events still replay
+     * verbatim (the projection). Removed at 1.0.
+     */
     readonly compaction?: {
         readonly thresholdTokens: number;
     };

package/dist/kernel/loop.js

@@ -9,8 +9,9 @@
  * stored alongside it — every adapter call derives them via
  * `projectMessages(log.all)` (kernel/project.ts). A fresh log encodes the
  * seed `messages` into events first, so even a one-shot call replays
- * exactly. Compaction is recorded as a `compacted` event and re-applied by
- * the projection, keeping the replay identical to the live run.
+ * exactly. Compaction is recorded as a `microcompacted` boundary (old
+ * sessions: a `compacted` event) and re-applied by the projection, keeping
+ * the replay identical to the live run.
  *
  * Per iteration:
  *   assemble (onUserMessage / onPreLlm)
@@ -27,7 +28,7 @@
  * re-stream that duplicates output or tool calls.
  */
 import { isAdapterEvent } from "../protocol/adapter.js";
-import { estimateTokens, microcompact } from "./compaction.js";
+import { estimateTokens } from "./compaction.js";
 import { EventLog } from "./event-log.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { validateArgs } from "../tools/validate.js";
@@ -124,31 +125,6 @@ export async function* loop(config) {
             return;
         }
         turns += 1;
-        // ── Auto-compaction: ONLY this turn's NEWLY cleared results are
-        //    persisted, keyed by the replaced tool-result event's seq; the
-        //    projection applies them verbatim (A 组/D 组/五).
-        if (config.compaction && estimateTokens(messages) > config.compaction.thresholdTokens) {
-            if (hooks.onPreCompact)
-                await hooks.onPreCompact(messages, {}).catch(() => { });
-            const result = microcompact(messages);
-            // 五: the delta only — messages already carrying the clear marker
-            // are never re-cleared (microcompact's idempotence gate), so the
-            // same replacement is never recorded twice across turns.
-            const cleared = result.cleared.map((c) => ({
-                eventSeq: c.eventSeq,
-                callId: c.callId,
-                content: c.content,
-            }));
-            if (cleared.length > 0) {
-                const full = log.append({ type: "compacted", cleared });
-                if (hooks.onEvent)
-                    await hooks.onEvent(full, {}).catch(() => { });
-                yield full;
-                messages = derive();
-                if (hooks.onPostCompact)
-                    await hooks.onPostCompact(messages, {}).catch(() => { });
-            }
-        }
         // ── C 区: one-shot microcompact boundary when over the threshold ──
         if (config.microcompact !== undefined && estimateTokens(messages) > config.microcompact.thresholdTokens) {
             const beforeSeq = microcompactBoundarySeq(log.all, config.microcompact.keepResults ?? KEEP_COMPACTABLE_RESULTS);

package/dist/kernel/project.d.ts

@@ -13,11 +13,14 @@
  * derives from the log, so there is one store and the replay of `seq` 0..N
  * reproduces the run exactly.
  *
- * Events with no message shape (usage, stop, thinking, terminal, compacted's
- * own record) are skipped by the projection; `compacted` REPLAYS the
- * compaction by re-running microcompact at that point in the sequence —
- * microcompact is deterministic and idempotent, so the replay equals the
- * live run. See ADR-0002.
+ * Events with no message shape (usage, stop, thinking, terminal, the
+ * compaction events' own records) are skipped by the projection;
+ * `compacted` applies the EXACT persisted replacements verbatim — it never
+ * re-runs the compaction algorithm (a future version could differ, A 组/D
+ * 组); `microcompacted` boundaries re-derive the cleared view from the
+ * stream itself (deterministic and idempotent); `summarized` (ADR-0044)
+ * replaces its covered range with one assistant summary message. All
+ * three are persisted facts — the replay equals the live run. See ADR-0002.
  */
 import type { Event } from "../protocol/events.js";
 import type { EventInput } from "./event-log.js";
@@ -36,8 +39,8 @@ export declare const DO_NOT_COMPACT = "do-not-compact";
  * replaying the same log always produces the same messages — BYTE FOR BYTE
  * (D 区): the same event prefix derives the same message prefix; the only
  * events that change already-derived messages are `microcompacted`
- * boundaries, which are themselves persisted facts (their replay derives
- * the same projection every time).
+ * boundaries and `summarized` facts, which are themselves persisted facts
+ * (their replay derives the same projection every time).
  *
  * Text block boundaries are preserved: `text_end` closes the current text
  * block (an explicit boundary); `text_start` after a block opens a new one.

package/dist/kernel/project.js

@@ -13,11 +13,14 @@
  * derives from the log, so there is one store and the replay of `seq` 0..N
  * reproduces the run exactly.
  *
- * Events with no message shape (usage, stop, thinking, terminal, compacted's
- * own record) are skipped by the projection; `compacted` REPLAYS the
- * compaction by re-running microcompact at that point in the sequence —
- * microcompact is deterministic and idempotent, so the replay equals the
- * live run. See ADR-0002.
+ * Events with no message shape (usage, stop, thinking, terminal, the
+ * compaction events' own records) are skipped by the projection;
+ * `compacted` applies the EXACT persisted replacements verbatim — it never
+ * re-runs the compaction algorithm (a future version could differ, A 组/D
+ * 组); `microcompacted` boundaries re-derive the cleared view from the
+ * stream itself (deterministic and idempotent); `summarized` (ADR-0044)
+ * replaces its covered range with one assistant summary message. All
+ * three are persisted facts — the replay equals the live run. See ADR-0002.
  */
 /**
  * C 区: tools whose output is eligible for microcompact clearing — reads,
@@ -53,8 +56,8 @@ function primaryArg(input) {
  * replaying the same log always produces the same messages — BYTE FOR BYTE
  * (D 区): the same event prefix derives the same message prefix; the only
  * events that change already-derived messages are `microcompacted`
- * boundaries, which are themselves persisted facts (their replay derives
- * the same projection every time).
+ * boundaries and `summarized` facts, which are themselves persisted facts
+ * (their replay derives the same projection every time).
  *
  * Text block boundaries are preserved: `text_end` closes the current text
  * block (an explicit boundary); `text_start` after a block opens a new one.
@@ -114,8 +117,49 @@ export function projectMessages(events) {
         if (ev.type === "tool_call_end")
             callMeta.set(ev.callId, { name: ev.name, input: ev.input });
     }
+    // ADR-0044: summarized coverage — each `summarized` event covers the
+    // range (previous coversToSeq, coversToSeq] of ORDINARY events. The
+    // ranges are disjoint and in seq order; boundaries are turn boundaries
+    // by construction (summaryBoundarySeq cuts before a user_input), so a
+    // skipped event never splits a message. Each summary message renders
+    // AT ITS BOUNDARY — the first event after the covered range — NOT at
+    // the summarized event itself: the event sits at the log's END (the
+    // kept rounds live between the boundary and it), and the summary must
+    // precede the kept conversation in reading order.
+    const summaryRanges = [];
+    {
+        let prev = -1;
+        for (const ev of events) {
+            if (ev.type === "summarized") {
+                summaryRanges.push({ from: prev, to: ev.coversToSeq, summary: ev.summary });
+                prev = ev.coversToSeq;
+            }
+        }
+    }
+    const isCovered = (seq) => summaryRanges.some((r) => seq > r.from && seq <= r.to);
+    // Summaries render in range order as the pass crosses their boundaries.
+    let renderedSummaries = 0;
     let explicitAssistant = false;
     for (const ev of events) {
+        // ADR-0044: covered events are replaced by their summary — seed
+        // events (EventInput, no seq) precede any summarized fact and are
+        // never covered. The summarized events themselves are exempt (their
+        // own event sits inside the NEXT range's coverage; the boundary
+        // render below is where their message lands).
+        if (ev.type !== "summarized" && isCovered(ev.seq ?? -1))
+            continue;
+        // The boundary render: every range whose end this event crosses
+        // yields its assistant summary message, before this event renders.
+        while (renderedSummaries < summaryRanges.length &&
+            ev.seq !== undefined &&
+            ev.seq > summaryRanges[renderedSummaries].to) {
+            flushAssistant();
+            out.push({
+                role: "assistant",
+                blocks: [{ type: "text", text: summaryRanges[renderedSummaries].summary }],
+            });
+            renderedSummaries += 1;
+        }
         switch (ev.type) {
             case "user_input": {
                 // 六: the final replacement renders HERE, at the input's own
@@ -270,6 +314,11 @@ export function projectMessages(events) {
                 flushAssistant();
                 pendingReasoning = (pendingReasoning ?? "") + ev.text;
                 break;
+            case "summarized":
+                // ADR-0044: this event produced nothing itself — its summary
+                // message was rendered at the boundary render above, in the
+                // covered range's position.
+                break;
             case "usage":
             case "stop":
             case "terminal":

package/dist/kernel/summarize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * L2 — the /compact summary layer (ADR-0044): the MODEL-GENERATED half of
+ * context economy. The mechanical half (microcompact, compaction.ts)
+ * clears TOOL RESULTS only; this layer compresses the CONVERSATION itself
+ * into one durable `summarized` event per call, replacing the covered
+ * range with a single assistant summary message in the projection.
+ *
+ * The summary call is OFF-LOOP: it goes through the session's OWN adapter
+ * (no new dependency), writes no events, and never touches the log — a
+ * failure throws, the caller reports it honestly, and the session is
+ * unchanged ("nothing happened"). Only the generated `summarized` event
+ * lands on disk; the original events stay there forever.
+ */
+import type { AbortSignalLike, Adapter } from "../protocol/adapter.js";
+import type { Event } from "../protocol/events.js";
+import type { Message } from "../protocol/messages.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;
+/**
+ * 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 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;
+}
+/**
+ * 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>;
+/**
+ * The last summary point: the previous `summarized` event's coversToSeq,
+ * or -1 (the trajectory's start) when none exists. The covered range of
+ * the next summary runs from here.
+ */
+export declare function lastSummaryPoint(events: readonly 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 —
+ * a turn boundary by construction, so the projection's skip never splits
+ * a message. Returns undefined when fewer than keepRounds+1 uncovered
+ * rounds exist (nothing worth covering yet).
+ */
+export declare function summaryBoundarySeq(events: readonly Event[], keepRounds?: 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
+ * MONOTONE savings figure, not a bill).
+ */
+export declare function estimateSummarySavings(covered: readonly Message[], summary: string): number;

package/dist/kernel/summarize.js

@@ -0,0 +1,106 @@
+/**
+ * L2 — the /compact summary layer (ADR-0044): the MODEL-GENERATED half of
+ * context economy. The mechanical half (microcompact, compaction.ts)
+ * clears TOOL RESULTS only; this layer compresses the CONVERSATION itself
+ * into one durable `summarized` event per call, replacing the covered
+ * range with a single assistant summary message in the projection.
+ *
+ * The summary call is OFF-LOOP: it goes through the session's OWN adapter
+ * (no new dependency), writes no events, and never touches the log — a
+ * failure throws, the caller reports it honestly, and the session is
+ * unchanged ("nothing happened"). Only the generated `summarized` event
+ * lands on disk; the original events stay there forever.
+ */
+import { estimateTokens } from "./compaction.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 const KEEP_RECENT_ROUNDS = 4;
+/**
+ * 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.
+
+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.
+
+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.
+
+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;
+- do not mention this prompt or the summarization task;
+- keep it under 200 words unless the conversation is exceptional.`;
+/**
+ * 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 async function summarizeConversation(options) {
+    const { adapter, model, messages } = options;
+    let text = "";
+    for await (const ev of adapter.stream({
+        model,
+        messages,
+        systemPrompt: SUMMARY_PROMPT,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    })) {
+        if (ev.type === "text_delta")
+            text += ev.text;
+    }
+    const trimmed = text.trim();
+    if (trimmed === "") {
+        throw new Error("the summary call produced no text");
+    }
+    return trimmed;
+}
+/**
+ * The last summary point: the previous `summarized` event's coversToSeq,
+ * or -1 (the trajectory's start) when none exists. The covered range of
+ * the next summary runs from here.
+ */
+export function lastSummaryPoint(events) {
+    let prev = -1;
+    for (const ev of events) {
+        if (ev.type === "summarized" && ev.coversToSeq > prev)
+            prev = ev.coversToSeq;
+    }
+    return prev;
+}
+/**
+ * The covered range's end: the seq of the event just before the
+ * keepRounds-th most recent user_input AFTER the last summary point —
+ * a turn boundary by construction, so the projection's skip never splits
+ * a message. Returns undefined when fewer than keepRounds+1 uncovered
+ * rounds exist (nothing worth covering yet).
+ */
+export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
+    const prevPoint = lastSummaryPoint(events);
+    const uncoveredInputs = [];
+    for (const ev of events) {
+        if (ev.type === "user_input" && ev.seq > prevPoint)
+            uncoveredInputs.push(ev.seq);
+    }
+    if (uncoveredInputs.length <= keepRounds)
+        return undefined;
+    // The input at m - keepRounds opens the FIRST KEPT round; everything
+    // before it (m - keepRounds ≥ 1 covered rounds) is summarizable.
+    return uncoveredInputs[uncoveredInputs.length - keepRounds] - 1;
+}
+/**
+ * The NoticeCell's number: estimated tokens of the covered content minus
+ * the summary's own — the same chars/4 proxy as estimateTokens (a stable
+ * MONOTONE savings figure, not a bill).
+ */
+export function estimateSummarySavings(covered, summary) {
+    return Math.max(0, estimateTokens(covered) - Math.ceil(summary.length / 4));
+}

package/dist/protocol/adapter.d.ts

@@ -51,11 +51,11 @@ export interface StreamOptions {
 /**
  * The NARROW event set an adapter may produce (五). Everything else in the
  * union is kernel-owned — `terminal`, `tool_execution_*`, `permission_*`,
- * `user_input`, `compacted`, `uncertain_pending`, `user_input_replaced`,
- * `assistant_start`/`assistant_end` — and a provider that yields any of
- * those is FORGING kernel state. The type narrows the adapter contract;
- * the loop ALSO enforces it at runtime (JS and third-party adapters are
- * not trusted — see kernel/loop.ts).
+ * `user_input`, `compacted`, `summarized`, `uncertain_pending`,
+ * `user_input_replaced`, `assistant_start`/`assistant_end` — and a
+ * provider that yields any of those is FORGING kernel state. The type
+ * narrows the adapter contract; the loop ALSO enforces it at runtime (JS
+ * and third-party adapters are not trusted — see kernel/loop.ts).
  */
 export type AdapterEvent = Extract<Event, {
     type: "text_start" | "text_delta" | "text_end" | "tool_call_start" | "tool_call_input_delta" | "tool_call_end" | "thinking" | "usage" | "stop";

package/dist/protocol/events.d.ts

@@ -327,6 +327,29 @@ export interface MicroCompactEvent {
     readonly type: "microcompacted";
     readonly beforeSeq: number;
 }
+/**
+ * ADR-0044 — a model-generated summary replaced the covered conversation
+ * range. `coversToSeq` is the seq of the LAST covered event; the covered
+ * range runs from just past the previous `summarized` event's coversToSeq
+ * (or the trajectory's start for the first) up to coversToSeq. The
+ * projection replaces exactly those events with ONE assistant summary
+ * message (`summary`); every `summarized` event always renders its own
+ * message. Byte-stable: a summarized event is a persisted fact, so the
+ * same events derive the same messages on every replay.
+ *
+ * The summary is generated OFF-LOOP through the session's own adapter —
+ * the summary request itself never enters the log, and a failed summary
+ * never leaves a record ("nothing happened"). The ORIGINAL events stay on
+ * disk forever: /last, /think, and the raw log still reach them.
+ */
+export interface SummarizedEvent {
+    readonly seq: number;
+    readonly type: "summarized";
+    /** The last covered event's seq; the range is (previous coversToSeq, coversToSeq]. */
+    readonly coversToSeq: number;
+    /** The model's compression — replaces the covered range in the projection. */
+    readonly summary: string;
+}
 /** Extended-thinking content. Providers without it emit nothing here. */
 export interface Thinking {
     readonly seq: number;
@@ -417,7 +440,7 @@ export interface TerminalEvent {
  * The union. Consume it with a `switch (event.type)`; with
  * `strictNullChecks` on, an unhandled variant is a compile error.
  */
-export type Event = AssistantStart | AssistantEnd | TextStart | TextDelta | TextEnd | ToolCallStart | ToolCallInputDelta | ToolCallEnd | ToolResultEvent | Thinking | Usage | Stop | UserInputEvent | CompactedEvent | ToolExecutionStarted | ToolExecutionSucceeded | ToolExecutionFailed | ToolExecutionResolved | PermissionRequested | PermissionDecided | PermissionExpired | UncertainPending | UserInputReplaced | MicroCompactEvent | TerminalEvent;
+export type Event = AssistantStart | AssistantEnd | TextStart | TextDelta | TextEnd | ToolCallStart | ToolCallInputDelta | ToolCallEnd | ToolResultEvent | Thinking | Usage | Stop | UserInputEvent | CompactedEvent | ToolExecutionStarted | ToolExecutionSucceeded | ToolExecutionFailed | ToolExecutionResolved | PermissionRequested | PermissionDecided | PermissionExpired | UncertainPending | UserInputReplaced | MicroCompactEvent | SummarizedEvent | TerminalEvent;
 /**
  * Runtime type guard for the union. The store validates every JSONL record
  * with it: valid JSON that is not a kiso event is corruption, not history.

package/dist/protocol/events.js

@@ -214,6 +214,12 @@ const EVENT_VALIDATORS = {
     permission_expired: (v) => typeof v.decisionId === "string" && typeof v.reason === "string",
     uncertain_pending: (v) => typeof v.executionId === "string" && typeof v.callId === "string" && typeof v.name === "string" && typeof v.error === "string",
     microcompacted: (v) => isNonNegativeInt(v.beforeSeq),
+    // ADR-0044: coversToSeq is a seq boundary BEFORE this event (a summary
+    // covers only what preceded it), and the summary is non-empty text.
+    summarized: (v) => isNonNegativeInt(v.coversToSeq) &&
+        typeof v.summary === "string" &&
+        v.summary.length > 0 &&
+        v.coversToSeq < v.seq,
     user_input_replaced: (v) => isNonNegativeInt(v.replaces) && (v.content === null || isContent(v.content)) && isSource(v),
     terminal: (v) => isTerminal(v.outcome),
 };

package/package.json

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