@vincemakes/kiso-runtime 0.44.0 → 0.45.1

package/dist/context-anchor.d.ts

@@ -15,7 +15,7 @@
  * differently), or one of the STALE_AFTER events after it, each of which
  * changes what the next request carries.
  */
-import { type Event, type Usage } from "@vincemakes/kiso-core";
+import type { Event, Usage } from "@vincemakes/kiso-core";
 /**
  * `usageTotal` turns one usage event into the tokens that request put in
  * the context: its canonical prompt (fresh + cache read + cache write — the

package/dist/context-anchor.js

@@ -1,21 +1,4 @@
-/**
- * 0.40.0 (the owner's session) — what the context holds, anchored on the
- * last BILLED request.
- *
- * The estimate alone read a Chinese-heavy context as ~470k while the
- * provider billed 732,448 input tokens on a 1M window: the ctx row said
- * "~53% left" and the microcompact trigger (window/2) never fired. The
- * provider's own count of the last request is the truth; only what the log
- * appended after it is estimated.
- *
- * The anchor is refused — the caller falls back to the estimate — when no
- * bill describes the context any more: no usage yet, a usage the provider
- * did not report (`known: false`), a usage at or before `floorSeq` (the
- * session switched models since, and a different tokenizer counts
- * differently), or one of the STALE_AFTER events after it, each of which
- * changes what the next request carries.
- */
-import { estimateTokens } from "@vincemakes/kiso-core";
+import { estimateTokens } from "./estimate-tokens.js";
 const STALE_AFTER = new Set([
     "compacted",
     "microcompacted",

package/dist/estimate-tokens.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The token estimator: runtime context-accounting policy.
+ *
+ * A stable, monotone chars/4 proxy for the size of a message list. The
+ * runtime's context policy, request budget, summary layer, context anchor
+ * and request trace read it; the kernel never did.
+ *
+ * ADR-0043 Amendment 13: moved here unchanged from the core package
+ * (`kernel/compaction.ts`). Since ADR-0044 moved compaction into the
+ * microcompact boundary, that file held only this estimator, and nothing
+ * in core called it — so it left the counted kernel instead of the cap
+ * moving.
+ */
+import type { Message } from "@vincemakes/kiso-core";
+/**
+ * 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 (it stays with the
+ * kernel-loop cases it also pins).
+ */
+export declare function estimateTokens(messages: readonly Message[]): number;

package/dist/estimate-tokens.js

@@ -0,0 +1,85 @@
+/**
+ * The token estimator: runtime context-accounting policy.
+ *
+ * A stable, monotone chars/4 proxy for the size of a message list. The
+ * runtime's context policy, request budget, summary layer, context anchor
+ * and request trace read it; the kernel never did.
+ *
+ * ADR-0043 Amendment 13: moved here unchanged from the core package
+ * (`kernel/compaction.ts`). Since ADR-0044 moved compaction into the
+ * microcompact boundary, that file held only this estimator, and nothing
+ * in core called it — so it left the counted kernel instead of the cap
+ * moving.
+ */
+/**
+ * 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 (it stays with the
+ * kernel-loop cases it also pins).
+ */
+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;
+}

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { AgentSession, AgentSession as Session } from "./session.js";
 export type { SideQueryOptions } from "./session.js";
 export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
 export type { ApprovalRequest, CompactInfo, ContextPolicy, SessionConfig, SummarizeResult } from "./session.js";
-export { Run } from "./run.js";
+export { Run, RunClosedError } from "./run.js";
 export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
 export type { Event, SessionMeta, StoreRecord } from "./store.js";
 export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
@@ -34,3 +34,4 @@ export type { ExecutionRecord, ExecutionStatus } from "./ledger.js";
 export { kisoHome, projectArtifacts, recordTrust, trustFor } from "./trust.js";
 export type { ProjectArtifact, ProjectArtifacts, TrustDecision, TrustRecord } from "./trust.js";
 export { canonicalizeUsage } from "./usage/canonical.js";
+export { estimateTokens } from "./estimate-tokens.js";

package/dist/index.js

@@ -24,7 +24,7 @@ export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
 export { AgentSession, AgentSession as Session } from "./session.js";
 export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
 // run
-export { Run } from "./run.js";
+export { Run, RunClosedError } from "./run.js";
 // store
 export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
 // extensions
@@ -42,3 +42,7 @@ export { kisoHome, projectArtifacts, recordTrust, trustFor } from "./trust.js";
 // provider observation; canonicalizeUsage derives at the accounting
 // boundary (R4 Case B — the frozen usage union does not move).
 export { canonicalizeUsage } from "./usage/canonical.js";
+// ADR-0043 Amendment 13: the token estimator is runtime context-accounting
+// policy, not a kernel primitive — it moved here unchanged from the core
+// package, which never called it.
+export { estimateTokens } from "./estimate-tokens.js";

package/dist/request-budget.js

@@ -17,7 +17,7 @@
  * This is a display and design entry. The auto-compact policy keeps its
  * own number (`estimateCtxRatio` in the CLI) — moving it is A1b's.
  */
-import { estimateTokens } from "@vincemakes/kiso-core";
+import { estimateTokens } from "./estimate-tokens.js";
 const chars = (s) => Math.ceil(s.length / 4);
 export function requestBudget(parts, window) {
     const system = parts.systemPrompt === undefined ? 0 : chars(parts.systemPrompt);

package/dist/run.d.ts

@@ -7,8 +7,19 @@ import { type AbortSignalLike, type Adapter, type ContentBlock, type Event } fro
 import type { SessionStore } from "./store.js";
 import { type AgentSession, type SessionConfig } from "./session.js";
 /**
- * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
- * is the natural shape; the handle also carries the runId and the abort.
+ * ADR-0057: `run.steer()` after the run decided to end — its ingress is
+ * sealed. The host starts a new run with the input instead.
+ */
+export declare class RunClosedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * A single foreground execution, from its input to one terminal (ADR-0057:
+ * it may admit further input at Safe Admission boundaries).
+ * Async-iterable, so `for await (const ev of session.run(x))` is the
+ * natural shape; the handle also carries the runId, the abort and the
+ * steer.
  */
 export declare class Run implements AsyncIterable<Event> {
     #private;
@@ -16,5 +27,16 @@ export declare class Run implements AsyncIterable<Event> {
     constructor(store: SessionStore, adapter: Adapter, config: SessionConfig, session: AgentSession, input: string | readonly ContentBlock[] | undefined, externalSignal: AbortSignalLike | undefined, resume: boolean, source?: import("@vincemakes/kiso-core").MessageSource, via?: import("@vincemakes/kiso-core").UserInputVia);
     /** Cancel the run: propagates to the adapter (SDK) and future executions. */
     abort(): void;
+    /**
+     * ADR-0057 — hand this run a person's input. It is admitted at the next
+     * Safe Admission boundary (every started effect settled, no approval
+     * open) as a user_input the model sees on its next request. Throws
+     * {@link RunClosedError} once the run has decided to end.
+     */
+    steer(content: string | readonly ContentBlock[]): void;
+    /** ADR-0057 — take back the input that has not been admitted yet. */
+    retract(): readonly (string | readonly ContentBlock[])[];
+    /** ADR-0057 — input that arrived but was not admitted when the run ended. */
+    unadmitted(): readonly (string | readonly ContentBlock[])[];
     [Symbol.asyncIterator](): AsyncIterator<Event>;
 }

package/dist/run.js

@@ -15,8 +15,23 @@ import { RequestTracer, traceGuard } from "./trace/guard.js";
 import { runtimeVersion } from "./trace/writer.js";
 import { ResumeBlockedError } from "./session.js";
 /**
- * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
- * is the natural shape; the handle also carries the runId and the abort.
+ * ADR-0057: `run.steer()` after the run decided to end — its ingress is
+ * sealed. The host starts a new run with the input instead.
+ */
+export class RunClosedError extends Error {
+    runId;
+    constructor(runId) {
+        super(`run ${runId} has ended — start a new run with this input`);
+        this.name = "RunClosedError";
+        this.runId = runId;
+    }
+}
+/**
+ * A single foreground execution, from its input to one terminal (ADR-0057:
+ * it may admit further input at Safe Admission boundaries).
+ * Async-iterable, so `for await (const ev of session.run(x))` is the
+ * natural shape; the handle also carries the runId, the abort and the
+ * steer.
  */
 export class Run {
     runId;
@@ -36,6 +51,12 @@ export class Run {
     #externalSignal;
     #decisionIds = [];
     #started = false;
+    // ADR-0057 — the ephemeral ingress: a person's input in arrival order,
+    // held in memory until an admission site takes it. The log owns what was
+    // admitted; nothing here is durable (a crash before admission loses it).
+    #pending = [];
+    #unadmitted = [];
+    #sealed = false;
     constructor(store, adapter, config, session, input, externalSignal, resume, 
     // TV-1B: durable PROVENANCE for the input (e.g. source:"system"
     // for a line the product wrote) — who produced the line, never a
@@ -59,6 +80,41 @@ export class Run {
     abort() {
         this.#abort.abort();
     }
+    /**
+     * ADR-0057 — hand this run a person's input. It is admitted at the next
+     * Safe Admission boundary (every started effect settled, no approval
+     * open) as a user_input the model sees on its next request. Throws
+     * {@link RunClosedError} once the run has decided to end.
+     */
+    steer(content) {
+        if (this.#sealed)
+            throw new RunClosedError(this.runId);
+        this.#pending.push(content);
+    }
+    /** ADR-0057 — take back the input that has not been admitted yet. */
+    retract() {
+        return this.#pending.splice(0);
+    }
+    /** ADR-0057 — input that arrived but was not admitted when the run ended. */
+    unadmitted() {
+        return [...this.#unadmitted];
+    }
+    /** The kernel's `admit`: what is pending becomes ONE human input — a
+     *  single line as itself, several as text blocks in arrival order. */
+    async #admit(mode) {
+        if (mode !== "seal" && this.#pending.length > 0) {
+            const lines = this.#pending.splice(0);
+            const content = lines.length === 1 ? lines[0] : lines.flatMap((l) => (typeof l === "string" ? [{ type: "text", text: l }] : l));
+            return [{ kind: "human", content, source: "user" }];
+        }
+        if (mode !== "take")
+            this.#seal();
+        return [];
+    }
+    #seal() {
+        this.#sealed = true;
+        this.#unadmitted.push(...this.#pending.splice(0));
+    }
     async *[Symbol.asyncIterator]() {
         if (this.#started)
             throw new Error("a run may only be consumed once");
@@ -204,6 +260,9 @@ export class Run {
                 // the human gave in the same instant as the abort is
                 // recorded, exactly once.
                 approvalVerdict: (decisionId) => this.#session.approvalVerdict(decisionId),
+                // ADR-0057: the ingress — the kernel admits at its three sites
+                // and seals at every terminal.
+                admit: (mode) => this.#admit(mode),
             });
             const self = this;
             const runLoop = async function* () {
@@ -328,6 +387,9 @@ export class Run {
                 yield ev;
         }
         finally {
+            // ADR-0057: however the run ended — terminal, throw or abandoned —
+            // its ingress is closed; pending input is handed back.
+            this.#seal();
             // round 5(P1-5): flush verdicts the consumer submitted before the
             // generator was abandoned — an approve()/resolveUncertain() whose
             // durable event the loop never got to persist must STILL land on

package/dist/session.js

@@ -40,7 +40,7 @@ import { canonicalizeUsageForModel } from "./usage/canonical.js";
 import { contextAnchor } from "./context-anchor.js";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { estimateTokens } from "@vincemakes/kiso-core";
+import { estimateTokens } from "./estimate-tokens.js";
 import { StaleWriterError } from "./store.js";
 import { composeHooks, composeSystemPrompt, microcompactFor, runBasePrompt } from "./compose.js";
 import { checkpointBoundarySeq } from "./checkpoint.js";

package/dist/summarize.js

@@ -13,7 +13,8 @@
  * unchanged ("nothing happened"). Only the generated `summarized` event
  * lands on disk; the original events stay there forever.
  */
-import { estimateTokens, DO_NOT_COMPACT, DEFAULT_MAX_RETRIES, RETRY_AFTER_MAX_MS, retryDelayMs } from "@vincemakes/kiso-core";
+import { DO_NOT_COMPACT, DEFAULT_MAX_RETRIES, RETRY_AFTER_MAX_MS, retryDelayMs } from "@vincemakes/kiso-core";
+import { estimateTokens } from "./estimate-tokens.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. */

package/dist/trace/manifest.js

@@ -20,7 +20,7 @@
  * surprise), every turn range degrades to null — honest thin pointers
  * rather than wrong ones.
  */
-import { estimateTokens } from "@vincemakes/kiso-core";
+import { estimateTokens } from "../estimate-tokens.js";
 import { canonicalJson, hashSystemPrompt, hashToolSpecs, sha256Hex } from "./hash.js";
 /** The log's visible user boundaries, in log order: every user_input
  *  whose replacement (if any) is not a veto. */

package/package.json

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