@vincemakes/kiso-core 0.1.0 → 0.1.1

package/dist/kernel/loop.d.ts

@@ -58,6 +58,17 @@ export interface LoopConfig {
     readonly compaction?: {
         readonly thresholdTokens: number;
     };
+    /**
+     * C 区: MICROCOMPACT — when the projected context exceeds the threshold,
+     * append ONE durable `microcompacted` boundary (clearing compactable tool
+     * results older than the recent turns). The decision is a persisted fact:
+     * the projection derives the same cleared view from the same events,
+     * byte for byte, across crash/resume. Never a per-turn progressive
+     * clearing.
+     */
+    readonly microcompact?: {
+        readonly thresholdTokens: number;
+    };
     readonly signal?: AbortSignalLike;
     readonly temperature?: number;
     readonly maxTokens?: number;

package/dist/kernel/loop.js

@@ -27,7 +27,7 @@
  * re-stream that duplicates output or tool calls.
  */
 import { isAdapterEvent } from "../protocol/adapter.js";
-import { estimateTokens, microcompact } from "./compaction.js";
+import { estimateTokens, KEEP_RECENT_TURNS, microcompact } from "./compaction.js";
 import { EventLog } from "./event-log.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { validateArgs } from "../tools/validate.js";
@@ -149,6 +149,17 @@ export async function* loop(config) {
                     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);
+            if (beforeSeq !== undefined) {
+                const full = log.append({ type: "microcompacted", beforeSeq });
+                if (hooks.onEvent)
+                    await hooks.onEvent(full, {}).catch(() => { });
+                yield full;
+                messages = derive();
+            }
+        }
         if (hooks.onPreLlm)
             await hooks.onPreLlm({ model: config.model, turns }, {});
         if (aborted()) {
@@ -785,6 +796,21 @@ function sleep(ms, signal) {
         }, { once: true });
     });
 }
+/**
+ * C 区: the boundary seq for a microcompact — the seq of the user input
+ * KEEP_RECENT_TURNS+1 places from the end (everything BEFORE that user
+ * input is old enough to clear; the recent turns stay intact). Undefined
+ * when the history is too short to clear anything.
+ */
+function microcompactBoundarySeq(events) {
+    const userSeqs = [];
+    for (const ev of events) {
+        if (ev.type === "user_input")
+            userSeqs.push(ev.seq);
+    }
+    const boundary = userSeqs[userSeqs.length - KEEP_RECENT_TURNS - 1];
+    return boundary !== undefined ? boundary - 1 : undefined;
+}
 /** A signal that never aborts — for executions outside any abort scope. */
 const NEVER_ABORT = {
     aborted: false,

package/dist/kernel/project.d.ts

@@ -22,9 +22,15 @@
 import type { Event } from "../protocol/events.js";
 import type { EventInput } from "./event-log.js";
 import type { AssistantBlock, Message, MessageSource } from "../protocol/messages.js";
+/** The tag that makes a tool result un-clearable (C 区). */
+export declare const DO_NOT_COMPACT = "do-not-compact";
 /**
  * Rebuild the message array from events. Deterministic and order-sensitive:
- * replaying the same log always produces the same messages.
+ * 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).
  *
  * 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

@@ -19,9 +19,41 @@
  * microcompact is deterministic and idempotent, so the replay equals the
  * live run. See ADR-0002.
  */
+/**
+ * C 区: tools whose output is eligible for microcompact clearing — reads,
+ * listings, searches, and shell output. write/edit outputs are short and
+ * never cleared.
+ */
+const MICROCOMPACTABLE = new Set(["read_file", "list_dir", "search_text", "shell"]);
+/** The tag that makes a tool result un-clearable (C 区). */
+export const DO_NOT_COMPACT = "do-not-compact";
+/**
+ * C 区: the fixed placeholder for a cleared tool output, derived ONLY from
+ * the event stream (deterministic across replay): the tool's name and its
+ * primary argument (the first string-valued field of its input).
+ */
+function microPlaceholder(name, arg) {
+    return arg === undefined
+        ? `[old tool output cleared: ${name}]`
+        : `[old tool output cleared: ${name} ${arg}]`;
+}
+/** The first string-valued argument of a tool input, if any. */
+function primaryArg(input) {
+    if (input === null || input === undefined)
+        return undefined;
+    for (const value of Object.values(input)) {
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    return undefined;
+}
 /**
  * Rebuild the message array from events. Deterministic and order-sensitive:
- * replaying the same log always produces the same messages.
+ * 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).
  *
  * Text block boundaries are preserved: `text_end` closes the current text
  * block (an explicit boundary); `text_start` after a block opens a new one.
@@ -68,6 +100,12 @@ export function projectMessages(events) {
             });
         }
     }
+    // C 区: callId → {name, input} for the microcompact placeholder.
+    const callMeta = new Map();
+    for (const ev of events) {
+        if (ev.type === "tool_call_end")
+            callMeta.set(ev.callId, { name: ev.name, input: ev.input });
+    }
     let explicitAssistant = false;
     for (const ev of events) {
         switch (ev.type) {
@@ -171,6 +209,27 @@ export function projectMessages(events) {
                 out.push(message);
                 break;
             }
+            case "microcompacted": {
+                flushAssistant();
+                // C 区: replace every eligible OLD tool result with the fixed
+                // placeholder. Eligibility: the result's own event seq <= the
+                // boundary, its tool in the whitelist, and no do-not-compact
+                // tag. Deterministic — the boundary event IS the decision.
+                const replaced = out.map((m) => {
+                    if (m.role !== "tool")
+                        return m;
+                    if (m.eventSeq === undefined || m.eventSeq > ev.beforeSeq)
+                        return m;
+                    const meta = callMeta.get(m.callId);
+                    if (meta === undefined || !MICROCOMPACTABLE.has(meta.name))
+                        return m;
+                    if ((m.tags ?? []).includes(DO_NOT_COMPACT))
+                        return m;
+                    return { ...m, content: microPlaceholder(meta.name, primaryArg(meta.input)) };
+                });
+                out.splice(0, out.length, ...replaced);
+                break;
+            }
             case "compacted": {
                 flushAssistant();
                 // Apply the EXACT persisted replacements — never re-run the
@@ -200,6 +259,7 @@ export function projectMessages(events) {
             case "usage":
             case "stop":
             case "terminal":
+            case "microcompacted":
             case "tool_execution_started":
             case "tool_execution_succeeded":
             case "tool_execution_failed":

package/dist/protocol/events.d.ts

@@ -310,6 +310,20 @@ export interface UserInputReplaced {
     /** Provenance of the replacement — preserved from the hook (三). */
     readonly source?: import("./messages.js").MessageSource;
 }
+/**
+ * C 区: a MICROCOMPACT boundary — the durable record of a context-clearing
+ * decision. `beforeSeq` is the event seq up to which eligible tool results
+ * are cleared: the projection replaces every tool_result with seq <=
+ * beforeSeq (whose tool is in the compactable whitelist and carries no
+ * do-not-compact tag) with a fixed placeholder derived from the stream
+ * itself. The decision is a PERSISTED FACT — replaying the same events
+ * derives the same messages, byte for byte, after a crash or resume.
+ */
+export interface MicroCompactEvent {
+    readonly seq: number;
+    readonly type: "microcompacted";
+    readonly beforeSeq: number;
+}
 /** Extended-thinking content. Providers without it emit nothing here. */
 export interface Thinking {
     readonly seq: number;
@@ -400,7 +414,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 | 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 | 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

@@ -212,6 +212,7 @@ const EVENT_VALIDATORS = {
         (v.reason === undefined || typeof v.reason === "string"),
     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),
     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.0",
+  "version": "0.1.1",
   "description": "kiso(\u57fa\u790e) core \u2014 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.0",
+    "@vincemakes/kiso-evals": "0.1.1",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"