@vincemakes/kiso-runtime 0.12.0 → 0.13.0

package/dist/recovery-plan.js

@@ -86,17 +86,38 @@ export function deriveRecoveryPlan(events, scope) {
     const uncertain = [...executionLedger(events).values()].filter((r) => r.status === "uncertain");
     if (uncertain.length > 0)
         return { kind: "RESOLVE_UNCERTAIN", executionId: uncertain[0].executionId };
-    // 4. Gap B: a text-bearing no-stop suffix is an abandoned draft — void it.
-    //    Text-only detection (the 0.1.44 verification): a bare tool-call
-    //    suffix is the legal approval-panel pause, never a draft. The
-    //    boundary/draft scans run over the OPEN RUN's events INCLUDING the
-    //    driver's own appends — the driver re-derives after every append,
-    //    and the marker IT appended must already be the last boundary (the
-    //    old one-pass Gap B never needed this: it ran before any append).
+    // 4. Gap B: a no-stop suffix of MODEL OUTPUT is an abandoned draft — void
+    //    it. The boundary/draft scans run over the OPEN RUN's events
+    //    INCLUDING the driver's own appends — the driver re-derives after
+    //    every append, and the marker IT appended must already be the last
+    //    boundary (the old one-pass Gap B never needed this: it ran before
+    //    any append).
+    //
+    //    EC-1, finding EC1-F1: the scan counts `tool_call_end` too. It used
+    //    to be text-only, on the 0.1.44 reasoning that "a bare tool-call
+    //    suffix is the legal approval-panel pause, never a draft" — but that
+    //    reasoning only ever held for a suffix carrying a REQUEST (the
+    //    liveAsk clause below, which still decides that case). A bare call
+    //    with no request is not a pause; it is an uncommitted draft, and
+    //    leaving it un-voided projects an assistant `tool_use` block with no
+    //    result — a provider 400. Pre-EC-1 the window was microseconds wide
+    //    (the stop was persisted the moment it arrived); ① holds the stop
+    //    until the stream is exhausted, so crash-pair A lands in this shape
+    //    by construction.
     const openEvents = openRunEvents(events, scope);
     const boundary = [...openEvents].reverse().find(isBoundary);
     if (boundary !== undefined) {
-        const afterBoundary = openEvents.some((e) => (e.type === "text_delta" || e.type === "thinking") && e.seq > boundary.seq);
+        //    A call only makes a DRAFT while it is still pure intent. Once it
+        //    has a durable `tool_execution_started` the world may have moved,
+        //    and the existing repair passes own it: voiding such a call would
+        //    strand a real receipt behind a voided declaration (pair atomicity
+        //    would then drop its result and the model would never learn the
+        //    outcome of work that actually happened). Pre-EC-1 logs contain
+        //    exactly that shape — a call that launched mid-stream and finished
+        //    before its stop was persisted — and they must keep recovering the
+        //    way they always did.
+        const unexecuted = (e) => e.type === "tool_call_end" && !openEvents.some((x) => x.type === "tool_execution_started" && x.callId === e.callId);
+        const afterBoundary = openEvents.some((e) => (e.type === "text_delta" || e.type === "thinking" || unexecuted(e)) && e.seq > boundary.seq);
         // The approval-panel pause: a suffix that carries a pending ask of the
         // LIVE turn — the last boundary is the user_input, no stop since — is
         // the human's pause, never a draft: the call was extracted and asked,
@@ -105,6 +126,16 @@ export function deriveRecoveryPlan(events, scope) {
         // crash mid-pause leaves exactly this shape.) A request AFTER a STOP
         // is different: it is the draft's own ask (0143's shape) — the marker
         // voids it and the request expires with the draft.
+        //
+        // EC-1 ERA NOTE — this clause is now GENERATION COMPAT, and is kept
+        // for that reason alone. A kiso at 0.13.0 or later cannot produce the
+        // shape: asks moved AFTER Turn Commit (③), so a durable
+        // `permission_requested` always has a durable stop before it. Logs
+        // written by EARLIER bins do carry it, they are on disk, and they
+        // must keep re-presenting their ask instead of being voided as
+        // drafts. Deleting this clause would silently change how pre-EC-1
+        // sessions recover; it stays until the generation corpus no longer
+        // contains a pre-EC-1 era.
         const liveAsk = afterBoundary &&
             boundary.type === "user_input" &&
             openEvents.some((e) => e.type === "permission_requested" && e.seq > boundary.seq);

package/dist/truncation-guard.d.ts

@@ -26,25 +26,52 @@
  *   4. NO STOP AT ALL drops the held calls entirely — the kernel already
  *      voids that malformed turn (invalid_request).
  *
- * THE CONSERVATISM SPLIT — core and runtime differ here BY DESIGN:
- *
- *   - the RAW KERNEL STREAMS. `loop()` over a bare adapter launches each
- *     validated, policy-allowed call the moment its `tool_call_end` lands
- *     (ADR-0024 Amendment 1, streaming execution): maximum overlap with
- *     the model stream, trusting calls as they arrive.
- *   - the FLAGSHIP RUNTIME STOP-GATES. `run.ts` composes this wrapper into
- *     EVERY run unconditionally, so the product pays a real latency cost —
- *     the 0.1.26 mid-stream launch timing is gone (the parallel window is
- *     NOT: the released batch still runs concurrently) — to buy the
- *     guarantee.
- *
- * So the kernel's default is speed and the flagship's default is safety;
- * an embedder choosing the kernel alone chooses the streaming launch, and
- * applying this wrapper is how they opt into the guarantee. The kernel
- * machinery (the launch, the window, the voided settle) is untouched
- * either way — the gate lives at the adapter boundary.
- *
- * Pinned by `packages/runtime/tests/truncation-guard.test.ts`.
+ * EC-1 ④ — THE CONTRACT AMENDMENT. The kernel closed the destructive half
+ * of this by itself: `max_tokens` cannot carry a tool call, so a truncated
+ * turn never reaches Turn Commit, and a commit-required handler never starts
+ * before that commit. What max_tokens means now, in full — the four clauses
+ * that replace the old "zero tools executed on truncation" line:
+ *
+ *   1. COMMIT-REQUIRED CALLS NEVER EXECUTE. On either path, guarded or bare.
+ *      This is the kernel's guarantee, not the wrapper's, and it holds for
+ *      every tool that declares nothing — which is every write, edit and
+ *      shell tool kiso ships.
+ *   2. PRECOMMIT-SAFE CALLS MAY ALREADY HAVE EXECUTED, and that execution is
+ *      DECLARED HARMLESS. A tool carrying `effects.precommitSafe` says
+ *      running it before the turn commits is harmless for EVERY invocation —
+ *      read-only, free, local. Bare, such a call launches during the stream
+ *      and a truncated turn may find its receipt already durable. That is
+ *      the certificate being spent, not a leak.
+ *   3. THE TURN IS NOT COMMITTED. No durable stop is written. The calls are
+ *      an uncommitted draft, which is what the resume sees.
+ *   4. PRECOMMIT RESULTS NEVER LEGITIMIZE IT (invariant 7). A durable
+ *      receipt from clause 2 is an execution fact and nothing more: it does
+ *      not commit the invocation, and it does not make the model turn valid.
+ *
+ * WHAT THE WRAPPER STILL BUYS, given all that:
+ *
+ *   - REPORTING. It releases the held batch with `input: null`, so every
+ *     call is ANSWERED with an honest invalid_input result. Bare, the same
+ *     turn leaves its calls with no results at all — an uncommitted draft
+ *     the resume must void.
+ *   - THE PRECOMMIT CASE. The hold sits UPSTREAM of the kernel: a held call
+ *     never reaches the loop until the stop is known, so clause 2's "may
+ *     already have executed" is exactly what the guard removes. Guarded,
+ *     nothing runs at all — not even a declared read.
+ *
+ * So the conservatism split did not disappear, it MOVED. It used to be the
+ * difference between a destructive edit running and not running; it is now
+ * the difference between a harmless read running and not running, plus the
+ * reporting. The kernel's default is speed for CERTIFIED calls and safety
+ * for everything else; the flagship runtime composes this wrapper into every
+ * run and pays the latency to have neither.
+ *
+ * Pinned by `packages/runtime/tests/truncation-guard.test.ts` (clauses 1-3
+ * of the wrapper contract, byte-unchanged across EC-1 — the amendment did
+ * not weaken the guard) and by
+ * `packages/runtime/tests/sc1-truncation-contract-pins.test.ts` (clause 4 of
+ * the wrapper contract, and the four amended max_tokens clauses above — the
+ * declared TRUNCATION CLASS).
  */
 import type { Adapter } from "@vincemakes/kiso-core";
 /** Wrap the adapter so a truncated turn's tool batch can never execute. */

package/dist/truncation-guard.js

@@ -26,25 +26,52 @@
  *   4. NO STOP AT ALL drops the held calls entirely — the kernel already
  *      voids that malformed turn (invalid_request).
  *
- * THE CONSERVATISM SPLIT — core and runtime differ here BY DESIGN:
+ * EC-1 ④ — THE CONTRACT AMENDMENT. The kernel closed the destructive half
+ * of this by itself: `max_tokens` cannot carry a tool call, so a truncated
+ * turn never reaches Turn Commit, and a commit-required handler never starts
+ * before that commit. What max_tokens means now, in full — the four clauses
+ * that replace the old "zero tools executed on truncation" line:
  *
- *   - the RAW KERNEL STREAMS. `loop()` over a bare adapter launches each
- *     validated, policy-allowed call the moment its `tool_call_end` lands
- *     (ADR-0024 Amendment 1, streaming execution): maximum overlap with
- *     the model stream, trusting calls as they arrive.
- *   - the FLAGSHIP RUNTIME STOP-GATES. `run.ts` composes this wrapper into
- *     EVERY run unconditionally, so the product pays a real latency cost —
- *     the 0.1.26 mid-stream launch timing is gone (the parallel window is
- *     NOT: the released batch still runs concurrently) — to buy the
- *     guarantee.
+ *   1. COMMIT-REQUIRED CALLS NEVER EXECUTE. On either path, guarded or bare.
+ *      This is the kernel's guarantee, not the wrapper's, and it holds for
+ *      every tool that declares nothing — which is every write, edit and
+ *      shell tool kiso ships.
+ *   2. PRECOMMIT-SAFE CALLS MAY ALREADY HAVE EXECUTED, and that execution is
+ *      DECLARED HARMLESS. A tool carrying `effects.precommitSafe` says
+ *      running it before the turn commits is harmless for EVERY invocation —
+ *      read-only, free, local. Bare, such a call launches during the stream
+ *      and a truncated turn may find its receipt already durable. That is
+ *      the certificate being spent, not a leak.
+ *   3. THE TURN IS NOT COMMITTED. No durable stop is written. The calls are
+ *      an uncommitted draft, which is what the resume sees.
+ *   4. PRECOMMIT RESULTS NEVER LEGITIMIZE IT (invariant 7). A durable
+ *      receipt from clause 2 is an execution fact and nothing more: it does
+ *      not commit the invocation, and it does not make the model turn valid.
  *
- * So the kernel's default is speed and the flagship's default is safety;
- * an embedder choosing the kernel alone chooses the streaming launch, and
- * applying this wrapper is how they opt into the guarantee. The kernel
- * machinery (the launch, the window, the voided settle) is untouched
- * either way — the gate lives at the adapter boundary.
+ * WHAT THE WRAPPER STILL BUYS, given all that:
  *
- * Pinned by `packages/runtime/tests/truncation-guard.test.ts`.
+ *   - REPORTING. It releases the held batch with `input: null`, so every
+ *     call is ANSWERED with an honest invalid_input result. Bare, the same
+ *     turn leaves its calls with no results at all — an uncommitted draft
+ *     the resume must void.
+ *   - THE PRECOMMIT CASE. The hold sits UPSTREAM of the kernel: a held call
+ *     never reaches the loop until the stop is known, so clause 2's "may
+ *     already have executed" is exactly what the guard removes. Guarded,
+ *     nothing runs at all — not even a declared read.
+ *
+ * So the conservatism split did not disappear, it MOVED. It used to be the
+ * difference between a destructive edit running and not running; it is now
+ * the difference between a harmless read running and not running, plus the
+ * reporting. The kernel's default is speed for CERTIFIED calls and safety
+ * for everything else; the flagship runtime composes this wrapper into every
+ * run and pays the latency to have neither.
+ *
+ * Pinned by `packages/runtime/tests/truncation-guard.test.ts` (clauses 1-3
+ * of the wrapper contract, byte-unchanged across EC-1 — the amendment did
+ * not weaken the guard) and by
+ * `packages/runtime/tests/sc1-truncation-contract-pins.test.ts` (clause 4 of
+ * the wrapper contract, and the four amended max_tokens clauses above — the
+ * declared TRUNCATION CLASS).
  */
 /** Wrap the adapter so a truncated turn's tool batch can never execute. */
 export function truncationGuard(adapter) {

package/package.json

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