@vincemakes/kiso-core 0.15.12 → 0.16.0

package/dist/kernel/loop.d.ts

@@ -33,7 +33,7 @@
  * re-stream that duplicates output or tool calls.
  */
 import { type Adapter, type AbortSignalLike } from "../protocol/adapter.js";
-import type { Event, StructuredError } from "../protocol/events.js";
+import type { ContinuationScope, Event, StructuredError } from "../protocol/events.js";
 import type { ApprovalChain } from "../protocol/extension.js";
 import { EventLog } from "./event-log.js";
 import type { EventInput } from "./event-log.js";
@@ -53,6 +53,19 @@ export interface LoopConfig {
     readonly mode?: string;
     readonly maxTurns?: number;
     readonly maxRetries?: number;
+    /**
+     * MG-1 (ADR-0051 Amendment 5): the run's continuation scope — the
+     * kernel stamps it onto a committed stop's envelope (adapters cannot
+     * forge scope). Absent = an unscoped run (SDK-injected or faux
+     * adapters): adapter-emitted continuation is STRIPPED at the commit.
+     */
+    readonly continuationScope?: ContinuationScope;
+    /** XP-1: the RESOLVED reasoning wire values — passed to the adapter
+     *  verbatim; absent = provider defaults (the byte anchor). */
+    readonly reasoning?: {
+        readonly thinking?: "adaptive" | "enabled" | "disabled";
+        readonly effort?: string;
+    };
     /**
      * Seed history. When a `log` is provided, the log IS the truth and this
      * is only used if the log is empty. See ADR-0002 / kernel/project.ts.

package/dist/kernel/loop.js

@@ -527,6 +527,7 @@ export async function* loop(config) {
                 const stream = config.adapter.stream({
                     model: config.model,
                     messages,
+                    ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
                     ...(config.systemPrompt !== undefined ? { systemPrompt: config.systemPrompt } : {}),
                     tools: registry.toSpecs(),
                     ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
@@ -727,6 +728,22 @@ export async function* loop(config) {
                     break;
             }
         }
+        // ── MG-1 (A5): the trust boundary's half of the envelope ─────────
+        // Stamp, strip, cap — BEFORE the commit decision, so a hard-cap
+        // violation voids the turn (no durable stop persists that is known
+        // unable to continue correctly; the F4b abandon voids its draft).
+        if (voided === null && heldStop !== null && heldStop.continuation !== undefined) {
+            const prepared = prepareContinuation(heldStop, config.continuationScope);
+            if (prepared === "hard-cap") {
+                voided = {
+                    kind: "error",
+                    error: { code: "invalid_request", retryable: false, message: "the turn's required continuation metadata exceeds the hard cap" },
+                };
+            }
+            else {
+                heldStop = prepared;
+            }
+        }
         // ── EC-1 ① — TURN COMMIT ──────────────────────────────────────────
         // The held stop is persisted HERE and only here: iterator done (the
         // stream loop broke cleanly) AND structurally compatible (above). The
@@ -1273,3 +1290,39 @@ const NEVER_ABORT = {
     addEventListener: () => { },
     removeEventListener: () => { },
 };
+// ── MG-1 (ADR-0051 Amendment 5): the envelope preparation ────────────────
+//
+// Pure: stamp the run's scope over whatever the adapter claimed (adapters
+// are not trusted), strip on an unscoped run, and enforce the two caps —
+// optional entries drop WHOLE at the soft cap (earliest first, emission
+// order) with a durable `truncated: true`; a required set over the hard
+// cap is a provider-contract violation the caller turns into a voided
+// turn. Sizes are UTF-8 bytes of the serialized entry.
+const CONTINUATION_SOFT_CAP = 256 * 1024;
+const CONTINUATION_HARD_CAP = 2 * 1024 * 1024;
+function prepareContinuation(stop, scope) {
+    const c = stop.continuation;
+    if (c === undefined)
+        return stop;
+    if (scope === undefined) {
+        const { continuation: _stripped, ...rest } = stop;
+        return rest;
+    }
+    const size = (e) => new TextEncoder().encode(e.data).length + new TextEncoder().encode(e.kind).length + 32;
+    const requiredBytes = c.entries.filter((e) => e.required).reduce((n, e) => n + size(e), 0);
+    if (requiredBytes > CONTINUATION_HARD_CAP)
+        return "hard-cap";
+    const kept = [...c.entries];
+    let total = kept.reduce((n, e) => n + size(e), 0);
+    let truncated = false;
+    for (let i = 0; total > CONTINUATION_SOFT_CAP && i < kept.length;) {
+        if (kept[i].required) {
+            i += 1;
+            continue;
+        }
+        total -= size(kept[i]);
+        kept.splice(i, 1);
+        truncated = true;
+    }
+    return { ...stop, continuation: { scope, entries: kept, ...(truncated ? { truncated: true } : {}) } };
+}

package/dist/kernel/project.js

@@ -87,20 +87,28 @@ export function projectMessages(events) {
     // `thinking` events and attached to the assistant message at flush —
     // deterministic (same events → same messages → same request body, D area).
     let pendingReasoning = null;
+    // MG-1 (A5): the committed stop's continuation envelope, attached to the
+    // SAME flush its stop triggers — only a durable stop carries one, so a
+    // voided draft can never leak stale continuation (invariant ③).
+    let pendingContinuation = null;
     const flushAssistant = () => {
         pushText();
         if (blocks.length === 0) {
             assistantSource = undefined;
+            pendingContinuation = null;
             return;
         }
         const callIds = blocks.filter((b) => b.type === "tool_use").map((b) => b.callId);
         const reasoning = pendingReasoning;
         pendingReasoning = null;
+        const continuation = pendingContinuation;
+        pendingContinuation = null;
         out.push({
             role: "assistant",
             blocks: [...blocks],
             ...(assistantSource !== undefined ? { source: assistantSource } : {}),
             ...(reasoning !== null ? { reasoning } : {}),
+            ...(continuation !== null ? { continuation } : {}),
         });
         blocks = [];
         assistantSource = undefined;
@@ -506,6 +514,9 @@ export function projectMessages(events) {
                 // projects [assistant, results…] in reading order, and the
                 // stream-open guards below only ever flush a CLOSED turn's
                 // late (post-stop) results.
+                // MG-1 (A5): the committed stop hands its envelope to the
+                // flush it triggers; every other flush site carries none.
+                pendingContinuation = ev.continuation ?? null;
                 flushAssistant();
                 flushResults();
                 break;

package/dist/protocol/adapter.d.ts

@@ -46,6 +46,13 @@ export interface StreamOptions {
     readonly tools?: readonly ToolSpec[];
     readonly maxTokens?: number;
     readonly temperature?: number;
+    /** XP-1: the RESOLVED reasoning setting — native wire values only (the
+     *  runtime's matrix resolves and refuses; adapters serialize per
+     *  dialect). Absent = provider defaults, byte-identical to pre-XP-1. */
+    readonly reasoning?: {
+        readonly thinking?: "adaptive" | "enabled" | "disabled";
+        readonly effort?: string;
+    };
     readonly signal?: AbortSignalLike;
 }
 /**

package/dist/protocol/events.d.ts

@@ -417,10 +417,43 @@ export interface Usage {
     readonly cacheWrite: number | null;
     readonly known: boolean;
 }
+/** MG-1 (ADR-0051 Amendment 5): the continuation envelope's scope — WHO
+ *  may replay it. Kernel-stamped at the Turn Commit append from the run's
+ *  configured binding; an adapter-supplied scope is always overwritten
+ *  (adapters are not trusted), and a run with no configured scope has
+ *  adapter-emitted continuation stripped at the same boundary. */
+export interface ContinuationScope {
+    readonly providerId: string;
+    readonly apiId: string;
+    readonly modelId: string;
+    /** Origin only; REQUIRED when providerId === "custom". */
+    readonly endpoint?: string;
+}
+/** One opaque provider block. `data` is bytes to the kernel — serialized
+ *  verbatim by the emitting adapter, replayed verbatim by the scope-matched
+ *  one, never reconstructed from projected text. */
+export interface ContinuationEntry {
+    readonly kind: string;
+    /** true = the next request is INVALID without it (never dropped; a
+     *  required set over the hard cap voids the turn before commit).
+     *  false = quality-degradable (droppable under the soft cap). */
+    readonly required: boolean;
+    readonly data: string;
+}
+export interface Continuation {
+    readonly scope: ContinuationScope;
+    /** EMISSION ORDER, preserved end to end. */
+    readonly entries: readonly ContinuationEntry[];
+    /** Present only when OPTIONAL entries were dropped at the soft cap. */
+    readonly truncated?: true;
+}
 export interface Stop {
     readonly seq: number;
     readonly type: "stop";
     readonly reason: StopReason;
+    /** MG-1 (Amendment 5): absent on every pre-A5 log — rule 1's truly
+     *  optional field; old logs project byte-identically. */
+    readonly continuation?: Continuation;
 }
 /**
  * Structured failure classification for MODEL / TRANSPORT errors.

package/dist/protocol/events.js

@@ -143,6 +143,33 @@ function isTerminal(v) {
  * safe integer; the others are null when the provider did not report
  * them.
  */
+/** A5: shape-checked ONLY when present — rule 1's truly-optional clause.
+ *  The key set stays open, so older bins load newer logs unchanged. */
+function isContinuation(v) {
+    if (v === undefined)
+        return true;
+    if (typeof v !== "object" || v === null)
+        return false;
+    const c = v;
+    const s = c.scope;
+    if (typeof s !== "object" || s === null)
+        return false;
+    const sc = s;
+    if (typeof sc.providerId !== "string" || typeof sc.apiId !== "string" || typeof sc.modelId !== "string")
+        return false;
+    if (sc.endpoint !== undefined && typeof sc.endpoint !== "string")
+        return false;
+    if (!Array.isArray(c.entries))
+        return false;
+    for (const e of c.entries) {
+        if (typeof e !== "object" || e === null)
+            return false;
+        const r = e;
+        if (typeof r.kind !== "string" || typeof r.required !== "boolean" || typeof r.data !== "string")
+            return false;
+    }
+    return c.truncated === undefined || c.truncated === true;
+}
 function isUsage(v) {
     if (typeof v.known !== "boolean")
         return false;
@@ -176,7 +203,7 @@ const EVENT_VALIDATORS = {
         isTags(v) && isInvocationSeq(v),
     thinking: (v) => typeof v.text === "string",
     usage: isUsage,
-    stop: (v) => STOP_REASONS.has(v.reason),
+    stop: (v) => STOP_REASONS.has(v.reason) && isContinuation(v.continuation),
     user_input: (v) => isContent(v.content) && isSource(v),
     compacted: (v) => Array.isArray(v.cleared) &&
         v.cleared.every((c) => isPlainObject(c) &&

package/dist/protocol/messages.d.ts

@@ -82,6 +82,13 @@ export interface AssistantMessage {
      * follow-up requests). Present only when the turn actually reasoned.
      */
     readonly reasoning?: string;
+    /**
+     * MG-1 (ADR-0051 Amendment 5): the turn's committed continuation
+     * envelope, derived from its stop. Opaque to everything but the
+     * scope-matched adapter; messages are the versioned model-request
+     * side (Amendment 3(a)), never the frozen plane.
+     */
+    readonly continuation?: import("./events.js").Continuation;
 }
 /**
  * Sent back to the model after a tool ran.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-core",
-	"version": "0.15.12",
+	"version": "0.16.0",
 	"description": "kiso (foundation) 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.15.12",
+		"@vincemakes/kiso-evals": "0.16.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"