@vincemakes/kiso-core 0.44.0 → 0.45.0

package/dist/index.d.ts

@@ -7,5 +7,4 @@ export * from "./kernel/event-log.js";
 export * from "./kernel/hooks.js";
 export * from "./kernel/permission.js";
 export * from "./kernel/loop.js";
-export * from "./kernel/compaction.js";
 export * from "./kernel/project.js";

package/dist/index.js

@@ -7,5 +7,4 @@ export * from "./kernel/event-log.js";
 export * from "./kernel/hooks.js";
 export * from "./kernel/permission.js";
 export * from "./kernel/loop.js";
-export * from "./kernel/compaction.js";
 export * from "./kernel/project.js";

package/dist/kernel/loop.d.ts

@@ -33,14 +33,25 @@
  * re-stream that duplicates output or tool calls.
  */
 import { type Adapter, type AbortSignalLike } from "../protocol/adapter.js";
-import type { ContinuationScope, Event, StructuredError } from "../protocol/events.js";
+import type { ContinuationScope, Event, StructuredError, UserInputVia } from "../protocol/events.js";
 import type { ApprovalChain } from "../protocol/extension.js";
 import { EventLog } from "./event-log.js";
 import type { EventInput } from "./event-log.js";
-import type { AssistantBlock, AssistantMessage, Message, ToolResultMessage } from "../protocol/messages.js";
+import type { AssistantBlock, AssistantMessage, ContentBlock, Message, MessageSource, ToolResultMessage } from "../protocol/messages.js";
 import { ToolRegistry } from "../tools/registry.js";
 import type { HookHost } from "./hooks.js";
 import { type PermissionDecision } from "./permission.js";
+/**
+ * ADR-0057 (Safe Admission): input handed to a running run at a quiescent
+ * boundary. A "human" input passes onUserMessage once; a "runtime" input —
+ * a fact the runtime owes the model — never does.
+ */
+export interface AdmissionInput {
+    readonly kind: "human" | "runtime";
+    readonly content: string | readonly ContentBlock[];
+    readonly source?: MessageSource;
+    readonly via?: UserInputVia;
+}
 export interface LoopConfig {
     readonly adapter: Adapter;
     readonly model: string;
@@ -78,6 +89,14 @@ export interface LoopConfig {
      * run that gets nothing back then ends on that refusal.
      */
     readonly compact?: (events: readonly Event[], messages: readonly Message[], why: "request" | "overflow") => Promise<readonly EventInput[]>;
+    /**
+     * ADR-0057 (Safe Admission): the run's ingress. The kernel asks at the
+     * three sites — "take", or "takeOrSeal" where the run would otherwise
+     * end — and every terminal asks "seal" first. What it returns is
+     * appended as `user_input`. Absent: nothing is admitted, and no request
+     * byte changes.
+     */
+    readonly admit?: (mode: "take" | "takeOrSeal" | "seal") => Promise<readonly AdmissionInput[]>;
     readonly signal?: AbortSignalLike;
     readonly temperature?: number;
     readonly maxTokens?: number;

package/dist/kernel/loop.js

@@ -105,6 +105,7 @@ export async function* loop(config) {
     const derive = () => projectMessages(log.all);
     /** Yield a terminal: onStop (lifecycle) → event → onEvent (observer). */
     const terminal = async (outcome) => {
+        await config.admit?.("seal"); // ADR-0057: the ingress closes before onStop can be awaited
         if (hooks.onStop)
             await hooks.onStop(outcome.kind, {}).catch(() => { });
         const full = log.append({ type: "terminal", outcome });
@@ -129,6 +130,35 @@ export async function* loop(config) {
     // every later turn of the run sees.
     let messages = derive();
     let vetoed = false;
+    // ADR-0057 §4 — the hook speaks ONCE per human input, the run's own or
+    // one admitted mid-run; its outcome is persisted at the input's
+    // position. Returns true for a veto.
+    async function* hook(seq, msg) {
+        const rewritten = await hooks.onUserMessage(msg, {});
+        yield log.append({ type: "user_input_replaced", replaces: seq, content: rewritten?.content ?? null, ...(rewritten !== null && rewritten.source !== undefined ? { source: rewritten.source } : {}) });
+        messages = derive();
+        return rewritten === null;
+    }
+    // An input admitted mid-run follows a committed model turn of the same run
+    // (a stop after the last terminal); the run's own input — or a seeded
+    // history, which carries no stop — never does. A veto of the run's own
+    // input ends the run; a veto of an admitted one drops only that input.
+    const midRun = (seq) => {
+        const after = [...log.all].reverse().find((e) => e.type === "terminal")?.seq ?? -1;
+        return log.all.some((e) => e.type === "stop" && e.seq > after && e.seq < seq);
+    };
+    /** ADR-0057 — admit what has arrived; returns how many inputs landed (a veto does not). */
+    async function* admit(mode) {
+        let landed = 0;
+        for (const input of (await config.admit?.(mode)) ?? []) {
+            const src = input.source !== undefined ? { source: input.source } : {};
+            yield* emit({ type: "user_input", content: input.content, ...src, ...(input.via !== undefined ? { via: input.via } : {}) });
+            messages = derive();
+            if (!(input.kind === "human" && hooks.onUserMessage && (yield* hook(log.lastSeq, { role: "user", content: input.content, ...src }))))
+                landed += 1;
+        }
+        return landed;
+    }
     if (hooks.onUserMessage && messages.length > 0) {
         const last = messages.at(-1);
         if (last?.role === "user") {
@@ -147,21 +177,12 @@ export async function* loop(config) {
                 if (replacement.content === null)
                     vetoed = true;
             }
-            if (replacement === undefined && inputEvent) {
-                const rewritten = await hooks.onUserMessage(last, {});
-                // round 1: the rewrite/veto is a NORMAL stream event — persisted by
-                // the harness and visible to consumers, never a hidden append.
-                const replaced = log.append({
-                    type: "user_input_replaced",
-                    replaces: inputEvent.seq,
-                    content: rewritten?.content ?? null,
-                    ...(rewritten !== null && rewritten.source !== undefined ? { source: rewritten.source } : {}),
-                });
-                messages = derive();
-                yield replaced;
-                if (rewritten === null)
-                    vetoed = true; // round 3: a true veto ends the run
-            }
+            // round 1: the rewrite/veto is a NORMAL stream event — persisted by
+            // the harness and visible to consumers, never a hidden append.
+            // round 3: a true veto ends the run — unless the input was admitted
+            // mid-run (ADR-0057: a resume decides as the live path did).
+            if (replacement === undefined && inputEvent && (yield* hook(inputEvent.seq, last)) && !midRun(inputEvent.seq))
+                vetoed = true;
         }
     }
     // round 3: a true veto ends the run — the provider is NEVER called, even
@@ -491,6 +512,12 @@ export async function* loop(config) {
             yield await terminal({ kind: "aborted", by: "user" });
             return;
         }
+        // ADR-0057 site A: the turn head — quiescent, eligible (maxTurns wins),
+        // and BEFORE the END_TURN scan, which stops at an admitted input. The
+        // overflow retry is left alone (request mode only).
+        const requestMode = overflow === null;
+        if (requestMode && turns < maxTurns)
+            yield* admit("take");
         // 0.42.0: a settled result tagged END_TURN in the OPEN turn — after
         // the most recent stop, user_input or terminal — completes the run
         // instead of asking again. Read from the log at the HEAD of every
@@ -522,6 +549,9 @@ export async function* loop(config) {
             if (added.length > 0)
                 messages = derive();
         }
+        // ADR-0057 site C: what arrived during a request-mode compaction.
+        if (requestMode)
+            yield* admit("take");
         if (hooks.onPreLlm)
             await hooks.onPreLlm({ model: config.model, turns }, {});
         if (aborted()) {
@@ -891,6 +921,9 @@ export async function* loop(config) {
                 overflow = t.error;
                 continue;
             }
+            // ADR-0057 site B: the run would end — take what arrived, or seal.
+            if (t.kind === "completed" && turns < maxTurns && (yield* admit("takeOrSeal")) > 0)
+                continue;
             yield await terminal(t);
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-core",
-	"version": "0.44.0",
+	"version": "0.45.0",
 	"description": "kiso 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.44.0",
+		"@vincemakes/kiso-evals": "0.45.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"

package/dist/kernel/compaction.d.ts

@@ -1,28 +0,0 @@
-/**
- * L2 — context-economy primitives, the MECHANICAL half.
- *
- * The kernel's compaction policy is identity preservation, not summary
- * (the predecessor's 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.
- *
- * 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 { Message } from "../protocol/messages.js";
-/**
- * Rough token estimate (chars/4 + structural overhead). Calibration-free on
- * purpose: context economy only needs a stable MONOTONE proxy, not an exact
- * count — the threshold absorbs the error (the predecessor's ADR-0007). The proxy's
- * three-word contract, and the pins that hold it, are
- * packages/core/tests/sc1b-estimator.test.ts.
- */
-export declare function estimateTokens(messages: readonly Message[]): number;

package/dist/kernel/compaction.js

@@ -1,90 +0,0 @@
-/**
- * L2 — context-economy primitives, the MECHANICAL half.
- *
- * The kernel's compaction policy is identity preservation, not summary
- * (the predecessor's 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.
- *
- * 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.
- */
-/**
- * What a non-text block (an image) contributes. There is no character count
- * to proxy, and this module refuses to guess a provider's image
- * tokenization; the figure exists so a block is never worth ZERO, which is
- * what MONOTONE requires. Deliberately small: under-stating an image is a
- * threshold that fires slightly late, over-stating it is one that fires on
- * a conversation that was never large.
- */
-const NON_TEXT_BLOCK_TOKENS = 8;
-/**
- * chars/4 over a `string | ContentBlock[]` content field.
- *
- * SC-1b ①: the array arm must be summed BLOCK BY BLOCK. Reading `.length`
- * off it yields the block COUNT — a five-block 50 KB message scored ~2
- * tokens, and the live microcompact threshold believed it.
- */
-function contentTokens(content) {
-    if (typeof content === "string")
-        return textTokens(content);
-    let tokens = 0;
-    for (const block of content) {
-        tokens += block.type === "text" ? textTokens(block.text) : NON_TEXT_BLOCK_TOKENS;
-    }
-    return tokens;
-}
-/**
- * 0.40.0 (the owner's session): chars/4, except that a CJK character counts
- * as one token — which is about what a tokenizer spends on one. Plain
- * chars/4 read a Chinese-heavy 730k context as ~470k, so the thresholds
- * never fired and the ctx row lied. Text without CJK scores exactly what
- * it scored before. A counting loop, not a regex match: the text can be
- * megabytes, and a match array would hold one entry per character.
- */
-function textTokens(text) {
-    let cjk = 0;
-    for (let i = 0; i < text.length; i++) {
-        const c = text.charCodeAt(i);
-        // kana, CJK ext A, unified ideographs, Hangul syllables,
-        // compatibility ideographs, full-width forms
-        if ((c >= 0x3040 && c <= 0x30ff) || (c >= 0x3400 && c <= 0x4dbf) || (c >= 0x4e00 && c <= 0x9fff) || (c >= 0xac00 && c <= 0xd7af) || (c >= 0xf900 && c <= 0xfaff) || (c >= 0xff00 && c <= 0xffef))
-            cjk++;
-    }
-    return cjk + Math.ceil((text.length - cjk) / 4);
-}
-/**
- * Rough token estimate (chars/4 + structural overhead). Calibration-free on
- * purpose: context economy only needs a stable MONOTONE proxy, not an exact
- * count — the threshold absorbs the error (the predecessor's ADR-0007). The proxy's
- * three-word contract, and the pins that hold it, are
- * packages/core/tests/sc1b-estimator.test.ts.
- */
-export function estimateTokens(messages) {
-    let total = 0;
-    for (const msg of messages) {
-        if (msg.role === "user") {
-            total += contentTokens(msg.content);
-        }
-        else if (msg.role === "assistant") {
-            for (const block of msg.blocks) {
-                total +=
-                    block.type === "text"
-                        ? textTokens(block.text)
-                        : textTokens(JSON.stringify(block.input)) + 20;
-            }
-        }
-        else {
-            total += contentTokens(msg.content) + 10;
-        }
-    }
-    return total;
-}