@vincemakes/kiso-core 0.15.11 → 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

@@ -493,6 +493,29 @@ export async function* loop(config) {
         turnSettled = new Promise((res) => {
             settleTurn = res;
         });
+        // F4b: the ONE abandon sequence, for EVERY uncommitted exit — the
+        // mid-stream error (retryable or not), the user abort, and the
+        // voided turn. Settle (parked launches bail on the un-committed
+        // gate), drain (started executions land their receipts), then
+        // durably void the draft. The defensive check stands: a started
+        // commit-required execution in the draft (impossible under
+        // invariant 3) suppresses the marker — no void over a started
+        // fact, the pre-F4 abandon exactly.
+        const unsafeStartedInDraft = () => log.all.some((e) => e.type === "tool_execution_started" && e.seq > turnStart && registry.get(e.name)?.effects?.precommitSafe !== true);
+        const abandonDraft = async function* (reason) {
+            settleTurn();
+            violated = true;
+            violatedReject();
+            yield* drainSettled();
+            if (launchError !== null)
+                throw launchError;
+            if (log.lastSeq > turnStart && !unsafeStartedInDraft()) {
+                const marker = log.append({ type: "model_output_abandoned", voidFromSeq: turnStart, reason });
+                if (hooks.onEvent)
+                    await hooks.onEvent(marker, {}).catch(() => { });
+                yield marker;
+            }
+        };
         while (true) {
             // Area 4: the backoff is abortable — a cancel landing during a
             // retry wait ends the run now, not after the backoff.
@@ -504,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 } : {}),
@@ -577,8 +601,12 @@ export async function* loop(config) {
             catch (err) {
                 // Area 4: a user cancel surfaced by the SDK (APIUserAbortError
                 // or any error while the signal is set) is an honest `aborted`
-                // terminal, never a generic error.
+                // terminal, never a generic error. F4b: the aborted draft is
+                // voided LIVE — pre-F4b only a resume voided it, so the same
+                // durable prefix projected differently depending on whether
+                // the process crashed first.
                 if (aborted()) {
+                    yield* abandonDraft("the run was aborted before this turn committed");
                     yield await terminal({ kind: "aborted", by: "user" });
                     return;
                 }
@@ -591,42 +619,17 @@ export async function* loop(config) {
                     await sleep(attempts * 250, signal); // abortable backoff
                     continue;
                 }
-                // F4 — ABANDON HYGIENE, every streamed exit: the attempt settles
-                // (parked launches bail on the un-committed gate, started ones
-                // land their receipts), the draft is durably voided, and only
-                // THEN a retry or the terminal. Pre-F4 this path returned with
-                // the draft un-voided under the terminal — the next request
-                // projected it as committed history (ADR-0047 Gap B, live), and
-                // a dangling tool_call_end fed the provider-400 class (EC1-F1).
-                settleTurn();
-                violated = true;
-                violatedReject();
-                yield* drainSettled();
-                if (launchError !== null)
-                    throw launchError;
-                // Invariant 3 makes a started commit-required execution in the
-                // draft structurally impossible (the turn never committed) —
-                // CHECKED, not assumed: if one ever exists, fall back to the
-                // pre-F4 abandon (no marker over a started fact, no retry).
-                const unsafeStarted = log.all.some((e) => e.type === "tool_execution_started" && e.seq > turnStart && registry.get(e.name)?.effects?.precommitSafe !== true);
-                if (log.lastSeq > turnStart && !unsafeStarted) {
-                    // The loop's THIRD producer of `model_output_abandoned` (an
-                    // existing variant — no new protocol surface): broader than
-                    // the live void's dangling-call condition, because the SAME
-                    // process re-requests immediately and an un-voided text
-                    // draft would glue onto the retried stream's projection.
-                    const marker = log.append({
-                        type: "model_output_abandoned",
-                        voidFromSeq: turnStart,
-                        reason: "the provider stream failed before this turn committed",
-                    });
-                    if (hooks.onEvent)
-                        await hooks.onEvent(marker, {}).catch(() => { });
-                    yield marker;
-                }
+                // F4 — ABANDON HYGIENE, every streamed exit: settle, drain,
+                // durably void (the loop's third `model_output_abandoned`
+                // producer; text-only drafts included), and only THEN a retry
+                // or the terminal. Pre-F4 this path returned with the draft
+                // un-voided under the terminal — the next request projected it
+                // as committed history (ADR-0047 Gap B, live), and a dangling
+                // tool_call_end fed the provider-400 class (EC1-F1).
+                yield* abandonDraft("the provider stream failed before this turn committed");
                 // F4 — the mid-stream retry: same classification, same per-turn
                 // budget (ADR-0005 Amendment 1: frame state, per-process).
-                if (structured.retryable && attempts < maxRetries && !unsafeStarted) {
+                if (structured.retryable && attempts < maxRetries && !unsafeStartedInDraft()) {
                     attempts += 1;
                     await sleep(attempts * 250, signal); // the same abortable backoff
                     // Fresh per-attempt state — the marker is the boundary now.
@@ -725,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
@@ -745,7 +764,11 @@ export async function* loop(config) {
         // NO calls has nothing to abandon and still ends on its own stop
         // reason, the pre-EC-1 order.
         if (voided === null && pending.length > 0 && aborted()) {
-            settleTurn();
+            // F4b: the abandoned calls are voided LIVE — the resume derives
+            // the same void from the same prefix, so live and post-crash
+            // projections agree, and no dangling tool_use reaches the next
+            // request in either world.
+            yield* abandonDraft("the run was aborted before this turn committed");
             yield await terminal({ kind: "aborted", by: "user" });
             return;
         }
@@ -773,43 +796,28 @@ export async function* loop(config) {
         //    the in-between gaps (mid-handler launches, the ask pause:
         //    never a busy spin, never a deadlock on a pending ack).
         if (voided !== null) {
-            violated = true;
-            violatedReject();
+            // EC-1 ⑤ — THE LIVE VOID, F4b: the shared abandon sequence. ①
+            // means a voided turn's commit-required call never ran, so nothing
+            // answers the `tool_use` its tool_call_end already persisted; the
+            // run ends on its terminal and the recovery driver never sees it
+            // (its first rule is "the open run reached its terminal") — the
+            // provider-400 class, live rather than after a crash. The marker
+            // is the instrument the resume already uses, produced here (an
+            // existing variant — no new protocol surface). F4b broadened the
+            // condition from dangling-calls-only to ANY draft: a text-only
+            // voided draft glued onto the next request exactly the way the
+            // mid-stream cut's did. A started commit-required call (a FACT)
+            // still suppresses the marker — abandonDraft's standing check,
+            // the same rule as recovery-plan.ts's `unexecuted`. Idempotent by
+            // construction: the marker becomes the last boundary, so no later
+            // resume derives a second draft over the same range.
+            yield* abandonDraft("the turn was voided before it committed");
+            yield await terminal(voided);
+            return;
         }
         yield* drainSettled();
         if (launchError !== null)
             throw launchError;
-        if (voided !== null) {
-            // EC-1 ⑤ — THE LIVE VOID. ① means a voided turn's commit-required
-            // call never ran, so nothing answers the `tool_use` its
-            // tool_call_end already persisted. The run ends here on its error
-            // terminal, and the recovery driver will never see it: its first
-            // rule is "the open run reached its terminal". So the NEXT turn of
-            // the same session would send the model an assistant tool_use with
-            // no result — the provider-400 class, live rather than after a
-            // crash. Pre-EC-1 the streaming launch had already answered the
-            // pair; closing the destructive hole opened this one.
-            //
-            // The fix is the instrument the resume already uses, produced here
-            // instead: the loop is a SECOND PRODUCER of `model_output_abandoned`
-            // (an existing variant — no new protocol surface, the frozen event
-            // contract holds). It voids the whole draft range, exactly as
-            // ABANDON_DRAFT does, and only when a call is still pure intent —
-            // a call with a durable started is a FACT, and the same rule as
-            // recovery-plan.ts's `unexecuted`. Idempotent by construction: the
-            // marker becomes the last boundary, so no later resume derives a
-            // second draft over the same range.
-            if (log.all.some((e) => e.type === "tool_call_end" &&
-                e.seq > turnStart &&
-                !log.all.some((x) => x.type === "tool_execution_started" && x.callId === e.callId))) {
-                const marker = log.append({ type: "model_output_abandoned", voidFromSeq: turnStart, reason: "the turn was voided before it committed" });
-                if (hooks.onEvent)
-                    await hooks.onEvent(marker, {}).catch(() => { });
-                yield marker;
-            }
-            yield await terminal(voided);
-            return;
-        }
         // ── Advance history: the log grew; re-derive for the next turn ─────
         messages = derive();
     }
@@ -1282,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;
@@ -159,12 +167,17 @@ export function projectMessages(events) {
     // disjoint and in seq order; the skip below treats them exactly like the
     // summary ranges (the marker itself renders nothing and skips itself).
     // R-E 0.1.44 (the void scope sentence): the void range voids MODEL
-    // OUTPUT only — text_delta / thinking / tool_call_* — never the
-    // framework's facts (permission*, tool_execution, tool_result,
-    // user_input, terminal). The summary ranges keep their blanket reach
-    // (the summary replaces everything it covers).
+    // OUTPUT only — never the framework's facts (permission*,
+    // tool_execution, tool_result, user_input, terminal). The summary
+    // ranges keep their blanket reach (the summary replaces everything it
+    // covers). F4b: the block boundaries text_start/text_end ARE model
+    // output and join the family — a voided text_start carries the
+    // draft's provenance (`source`), and leaving it alive relabeled the
+    // RETRIED answer with the abandoned attempt's source.
     const MODEL_OUTPUT_TYPES = new Set([
+        "text_start",
         "text_delta",
+        "text_end",
         "thinking",
         "tool_call_start",
         "tool_call_input_delta",
@@ -501,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.11",
+	"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.11",
+		"@vincemakes/kiso-evals": "0.16.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"