@vincemakes/kiso-runtime 0.1.26 → 0.1.28

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./session.js";
 export * from "./run.js";
 export * from "./recovery.js";
 export * from "./compose.js";
+export * from "./summarize.js";
 export * from "./store.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./session.js";
 export * from "./run.js";
 export * from "./recovery.js";
 export * from "./compose.js";
+export * from "./summarize.js";
 export * from "./store.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/session.js

@@ -29,7 +29,7 @@
  */
 import { EventLog, executionLedger, projectMessages, } from "@vincemakes/kiso-core";
 import { denialResult } from "@vincemakes/kiso-core";
-import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "@vincemakes/kiso-core";
+import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
 import { StaleWriterError } from "./store.js";
 import { composeHooks } from "./compose.js";
 import { Run } from "./run.js";

package/dist/summarize.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The /compact summary layer (ADR-0044) — the MODEL-GENERATED half of
+ * context economy. 归位式抽取 (0.1.26 gate 裁决): this OFF-LOOP
+ * ORCHESTRATION lived in the kernel by a context-round expedience; it
+ * calls the ADAPTER to generate the summary, which is the RUNTIME's
+ * business — the kernel's duty is the `summarized` EVENT TYPE and the
+ * projection semantics (kernel/project.ts), not who calls the model.
+ * The mechanical half (microcompact) stays in the kernel (compaction.ts).
+ *
+ * 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 "@vincemakes/kiso-core";
+import type { Event } from "@vincemakes/kiso-core";
+import type { Message } from "@vincemakes/kiso-core";
+/** 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/summarize.js

@@ -0,0 +1,108 @@
+/**
+ * The /compact summary layer (ADR-0044) — the MODEL-GENERATED half of
+ * context economy. 归位式抽取 (0.1.26 gate 裁决): this OFF-LOOP
+ * ORCHESTRATION lived in the kernel by a context-round expedience; it
+ * calls the ADAPTER to generate the summary, which is the RUNTIME's
+ * business — the kernel's duty is the `summarized` EVENT TYPE and the
+ * projection semantics (kernel/project.ts), not who calls the model.
+ * The mechanical half (microcompact) stays in the kernel (compaction.ts).
+ *
+ * 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 "@vincemakes/kiso-core";
+/** 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/package.json

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