@vincemakes/kiso-runtime 0.11.0 → 0.13.0

package/dist/compose.js

@@ -89,8 +89,8 @@ export function composeHooks(existing, extensions) {
         // message as the PREVIOUS one left it (the existing come first), and a null (veto)
         // anywhere ends the chain immediately: never "no opinion" for the
         // next handler to outvote. Adding an extension can therefore never
-        // make the chain MORE permissive (the approval chain's deny>ask>allow
-        // monotonicity, on the message side).
+        // make the chain MORE permissive (the approval chain's
+        // deny > allow > ask monotonicity, on the message side).
         out.onUserMessage = async (msg, ctx) => {
             let current = msg;
             for (const h of messageHandlers) {

package/dist/index.d.ts

@@ -12,12 +12,16 @@
  * (unstable, first-party only — see internal.ts).
  *
  * Canonical names: Agent = AgentRuntime, Session = AgentSession. The old
- * names are deprecated aliases, removed in the next major (additive,
- * ADR-0051 Amendment 1 — release rounds move the cli minor).
+ * names are deprecated aliases, removed in the next major (additive). The
+ * cadence is ADR-0051 Amendment 4 — the LOCKSTEP line: all thirteen public
+ * packages share one version, a release round is a minor on the line and a
+ * fix-only round a patch. (Amendment 1's per-package counters, which moved
+ * the cli minor on its own, are superseded.)
  */
 export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
 export type { AgentDefinition, PermissionPolicy, PermissionRule } from "./agent.js";
 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";

package/dist/index.js

@@ -12,8 +12,11 @@
  * (unstable, first-party only — see internal.ts).
  *
  * Canonical names: Agent = AgentRuntime, Session = AgentSession. The old
- * names are deprecated aliases, removed in the next major (additive,
- * ADR-0051 Amendment 1 — release rounds move the cli minor).
+ * names are deprecated aliases, removed in the next major (additive). The
+ * cadence is ADR-0051 Amendment 4 — the LOCKSTEP line: all thirteen public
+ * packages share one version, a release round is a minor on the line and a
+ * fix-only round a patch. (Amendment 1's per-package counters, which moved
+ * the cli minor on its own, are superseded.)
  */
 // agent
 export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";

package/dist/ledger.d.ts

@@ -14,8 +14,17 @@
  * provider's `callId` is correlation only and may repeat; two logical calls
  * with identical (name, input) are two executions.
  *
+ * UNCERTAINTY BELONGS TO THE CRASH WINDOW ALONE (ADR-0038): the ONLY shape
+ * that derives "uncertain" here is a `tool_execution_started` with no
+ * receipt after it — the process died between the write-ahead and the
+ * outcome, so what the side effect did is genuinely unknown and a human
+ * must rule. A receipted execution is an outcome, success or failure alike;
+ * no tool property and no error kind can make a receipted execution
+ * uncertain. ADR-0038 superseded ADR-0025 decision #3, which had routed a
+ * failed non-idempotent execution into this bucket.
+ *
  * Status derivation:
- *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   started, no terminal event yet   → "uncertain"   (the crash window: human)
  *   succeeded                        → "succeeded"   (confirmed, never re-run)
  *   failed (any)                     → "failed"      (a complete receipt IS
  *                                       the outcome — ruling #12 / ADR-0038;

package/dist/ledger.js

@@ -14,8 +14,17 @@
  * provider's `callId` is correlation only and may repeat; two logical calls
  * with identical (name, input) are two executions.
  *
+ * UNCERTAINTY BELONGS TO THE CRASH WINDOW ALONE (ADR-0038): the ONLY shape
+ * that derives "uncertain" here is a `tool_execution_started` with no
+ * receipt after it — the process died between the write-ahead and the
+ * outcome, so what the side effect did is genuinely unknown and a human
+ * must rule. A receipted execution is an outcome, success or failure alike;
+ * no tool property and no error kind can make a receipted execution
+ * uncertain. ADR-0038 superseded ADR-0025 decision #3, which had routed a
+ * failed non-idempotent execution into this bucket.
+ *
  * Status derivation:
- *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   started, no terminal event yet   → "uncertain"   (the crash window: human)
  *   succeeded                        → "succeeded"   (confirmed, never re-run)
  *   failed (any)                     → "failed"      (a complete receipt IS
  *                                       the outcome — ruling #12 / ADR-0038;

package/dist/recovery-plan.js

@@ -79,20 +79,45 @@ export function deriveRecoveryPlan(events, scope) {
     //    order blocks; the driver throws with the full list. A receipted
     //    execution is an outcome (ruling #12 / the α ruling: the audit keeps
     //    it) — never uncertain.
+    //    ADR-0038: uncertainty belongs to the crash window ALONE. This filter
+    //    is the whole of it — `executionLedger` derives "uncertain" only for
+    //    started-without-receipt, so a FAILED execution never reaches this
+    //    branch and never blocks a resume, whatever its safeToRetry says.
     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,
@@ -101,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/session.d.ts

@@ -30,6 +30,21 @@
 import { EventLog, type AbortSignalLike, type Adapter, type Event, type KisoExtension, type Message, type PermissionDecision, type Tool } from "@vincemakes/kiso-core";
 import { type SessionStore } from "./store.js";
 import { Run } from "./run.js";
+/** TUI2-R3v2 ③ — one off-trajectory model request (session.sideQuery).
+ *  Deliberately tiny: a purpose to mark it in the trace, its own short
+ *  system prompt, one user message, and an abort. No tools — a side
+ *  query answers, it never acts. */
+export interface SideQueryOptions {
+    /** what this request is FOR — lands in the trace as `purpose`. */
+    readonly purpose: string;
+    /** the side query's OWN system prompt; the session's is not sent. */
+    readonly systemPrompt: string;
+    /** the single user message. */
+    readonly prompt: string;
+    readonly maxTokens?: number;
+    /** cancels the request — the CLI wires esc to it. */
+    readonly signal?: AbortSignalLike;
+}
 /** A session whose disk write was rejected (stale handle) is PERMANENTLY
  * poisoned: its in-memory log no longer matches the disk, so no further
  * run may proceed — reload the session (round 1). */
@@ -103,6 +118,43 @@ export declare class AgentSession {
      *  per-run tracer reads the SAME #config.provider; one source, one
      *  route — the CLI and the trace can never disagree. */
     get provider(): "anthropic" | "openai-compat" | undefined;
+    /**
+     * TUI2-R3v2 ③ — ONE model request that belongs to no run (the
+     * safer-options seam, adjudicated 2026-08-18).
+     *
+     * A side query exists for the case where the human, staring at a
+     * paused approval, presses a button and wants an answer NOW. It is
+     * not a turn, not a run, and not part of the trajectory.
+     *
+     * IT WRITES NOTHING DURABLE. No session-log lines, no receipts, no
+     * execution records — nothing. This is the design, not an omission,
+     * and it is what makes the method safe to call while a run sits
+     * paused: it cannot interleave with that run's own event sequence
+     * because it produces no events to interleave. The ONLY durable
+     * consequence a side query can have is what the human does with the
+     * answer, and that lands through an existing channel — for the
+     * safer-options flow, the amend channel, exactly as a typed denial
+     * would. Nothing here touches the durable approval contract.
+     *
+     * IT IS VISIBLE. It rides the same traceGuard every run request
+     * rides, so it lands one request line in the trace ledger, carrying
+     * a FRESH runId (it is not the paused run's work) and the `purpose`
+     * marker (schemaVersion 4) that lets a rent audit separate on-demand
+     * requests from a run's own without heuristics. A request the ledger
+     * cannot see is rent nobody can audit, and the entire argument for
+     * an on-demand feature is that its rent is countable.
+     *
+     * IT PAYS ITS OWN, SMALLER RENT. It sends its own short system
+     * prompt and ONE user message, and NO TOOLS AT ALL — it cannot call
+     * anything, it can only answer. Its declared prediction arm is
+     * predictSideQueryRentLedger (scripts/request-surface.mjs), gated
+     * against a real call in rent-ledger-gate.test.ts.
+     *
+     * The returned string is the model's text, concatenated. The caller
+     * parses it and must treat a failure to parse as a failure — see the
+     * CLI's honest degradation.
+     */
+    sideQuery(options: SideQueryOptions): Promise<string>;
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input: string, options?: {
         signal?: AbortSignalLike;

package/dist/session.js

@@ -38,6 +38,10 @@ import { estimateTokens } from "@vincemakes/kiso-core";
 import { StaleWriterError } from "./store.js";
 import { composeHooks } from "./compose.js";
 import { Run } from "./run.js";
+// TUI2-R3v2 ③ — the side query rides the SAME tracer the runs ride; that
+// sameness is the whole point (one ledger, one shape, no second path).
+import { RequestTracer, traceGuard } from "./trace/guard.js";
+import { runtimeVersion } from "./trace/writer.js";
 /** A session whose disk write was rejected (stale handle) is PERMANENTLY
  * poisoned: its in-memory log no longer matches the disk, so no further
  * run may proceed — reload the session (round 1). */
@@ -168,6 +172,83 @@ export class AgentSession {
     get provider() {
         return this.#config.provider;
     }
+    /**
+     * TUI2-R3v2 ③ — ONE model request that belongs to no run (the
+     * safer-options seam, adjudicated 2026-08-18).
+     *
+     * A side query exists for the case where the human, staring at a
+     * paused approval, presses a button and wants an answer NOW. It is
+     * not a turn, not a run, and not part of the trajectory.
+     *
+     * IT WRITES NOTHING DURABLE. No session-log lines, no receipts, no
+     * execution records — nothing. This is the design, not an omission,
+     * and it is what makes the method safe to call while a run sits
+     * paused: it cannot interleave with that run's own event sequence
+     * because it produces no events to interleave. The ONLY durable
+     * consequence a side query can have is what the human does with the
+     * answer, and that lands through an existing channel — for the
+     * safer-options flow, the amend channel, exactly as a typed denial
+     * would. Nothing here touches the durable approval contract.
+     *
+     * IT IS VISIBLE. It rides the same traceGuard every run request
+     * rides, so it lands one request line in the trace ledger, carrying
+     * a FRESH runId (it is not the paused run's work) and the `purpose`
+     * marker (schemaVersion 4) that lets a rent audit separate on-demand
+     * requests from a run's own without heuristics. A request the ledger
+     * cannot see is rent nobody can audit, and the entire argument for
+     * an on-demand feature is that its rent is countable.
+     *
+     * IT PAYS ITS OWN, SMALLER RENT. It sends its own short system
+     * prompt and ONE user message, and NO TOOLS AT ALL — it cannot call
+     * anything, it can only answer. Its declared prediction arm is
+     * predictSideQueryRentLedger (scripts/request-surface.mjs), gated
+     * against a real call in rent-ledger-gate.test.ts.
+     *
+     * The returned string is the model's text, concatenated. The caller
+     * parses it and must treat a failure to parse as a failure — see the
+     * CLI's honest degradation.
+     */
+    async sideQuery(options) {
+        this.ensureHealthy();
+        // a fresh id: this request is not the paused run's work, and giving
+        // it the run's id would put on-demand rent inside a run's total.
+        const runId = crypto.randomUUID();
+        const tracer = new RequestTracer({
+            root: this.#store.root,
+            sessionId: this.id,
+            runId,
+            provider: this.#config.provider ?? "adapter",
+            model: this.#config.model,
+            adapterVersion: runtimeVersion(),
+            purpose: options.purpose,
+            // the manifest's seqRange pointers derive from the log, and a side
+            // query's messages come from NO events — an empty log is the
+            // honest input, and it keeps the manifest from pointing at events
+            // this request never sent.
+            log: [],
+            // the declared rent arm: its own prompt, no appends, no tools
+            rentParts: { base: options.systemPrompt, appends: [] },
+        });
+        tracer.init();
+        const guarded = traceGuard(tracer, this.#adapter);
+        let text = "";
+        try {
+            for await (const ev of guarded.stream({
+                model: this.#config.model,
+                messages: [{ role: "user", content: options.prompt }],
+                systemPrompt: options.systemPrompt,
+                ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            })) {
+                if (ev.type === "text_delta")
+                    text += ev.text;
+            }
+        }
+        finally {
+            tracer.finishRun();
+        }
+        return text;
+    }
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input, options) {
         this.ensureHealthy();

package/dist/trace/guard.d.ts

@@ -34,6 +34,12 @@ export interface RequestTracerDeps {
     adapterVersion?: string | null;
     /** The session log — the manifest's seqRange pointers derive from it. */
     log: readonly Event[];
+    /** TUI2-R3v2 ③ — what these requests are FOR, when they are not a
+     *  run's own work. Omitted by every run (the tracer Run builds); set to
+     *  "safer-options" by session.sideQuery. It lands verbatim on each
+     *  record this tracer settles, which is what lets a rent audit tell an
+     *  on-demand request from an ambient one without guessing. */
+    purpose?: string;
     /** E3 — the rent ledger's inputs: the base prompt as configured and
      *  the per-extension appends in load order (the adapter's composed
      *  systemPrompt is their RESULT — the parts are what the ledger

package/dist/trace/guard.js

@@ -36,6 +36,7 @@ export class RequestTracer {
     #runId;
     #adapterVersion;
     #rentParts;
+    #purpose;
     #requestIndex = 0;
     #contextHashCounts = new Map();
     constructor(deps) {
@@ -45,6 +46,7 @@ export class RequestTracer {
         this.#runId = deps.runId;
         this.#adapterVersion = deps.adapterVersion ?? null;
         this.#rentParts = deps.rentParts;
+        this.#purpose = deps.purpose;
     }
     init() {
         this.#writer.init();
@@ -139,6 +141,10 @@ export class RequestTracer {
             kind: "request",
             requestId: randomUUID(),
             runId: this.#runId,
+            // exactOptionalPropertyTypes: the key is ABSENT on a run request,
+            // never `purpose: undefined` — a present-but-undefined key would
+            // fail the closed-set gate and would read as a claim in the JSON.
+            ...(this.#purpose !== undefined ? { purpose: this.#purpose } : {}),
             requestIndex: this.#requestIndex++,
             retryAttempt,
             provider: this.#provider,

package/dist/trace/record.d.ts

@@ -25,12 +25,22 @@
  * writers record it; v1/v2 sidecars keep reading as defaults (R1d-1,
  * R2-1): no rent block = no rent lines = the zero-rent reading, never a
  * crash.
+ *
+ * TUI2-R3v2 (0.12.0) — schemaVersion 4: the record gains the OPTIONAL
+ * `purpose` marker (the safer-options seam, adjudicated 2026-08-18). A
+ * session can now make a request that belongs to no run — a side query
+ * (session.sideQuery) — and a ledger that could not tell one from a run
+ * request would make every rent audit guesswork. `purpose` is absent on
+ * run requests and present on side queries, naming what the request was
+ * FOR ("safer-options"). Optional by construction: adding a required
+ * field would have invalidated every v3 record ever written, and the
+ * whole generation-compat discipline exists to prevent exactly that.
  */
-/** schemaVersion: 3 for 0.2.1 (the rent block). Version 1 = the 1.2.0
- *  shape, version 2 = the 1.3.0 shape; both kept for generation-compat
- *  reads (R1d-1, R2-1). Algorithm and shape changes bump it (ADR-0051 §6
- *  OUT-side versioning). */
-export declare const TRACE_SCHEMA_VERSION = 3;
+/** schemaVersion: 4 for 0.12.0 (the optional `purpose` marker). Version
+ *  1 = the 1.2.0 shape, 2 = the 1.3.0 shape, 3 = the 0.2.1 shape; all
+ *  kept for generation-compat reads (R1d-1, R2-1). Algorithm and shape
+ *  changes bump it (ADR-0051 §6 OUT-side versioning). */
+export declare const TRACE_SCHEMA_VERSION = 4;
 /** The versions a reader may meet in a ledger. v1 and v2 records are
  *  accepted (generation-compat) and read as defaults — no canonical
  *  block (v1), no rent block (v1, v2). */
@@ -52,7 +62,7 @@ export interface TraceSegment {
 }
 /** That is the complete set for 1.2.0. */
 export interface TraceRecord {
-    schemaVersion: 3;
+    schemaVersion: 4;
     kind: "request";
     requestId: string;
     runId: string;
@@ -101,25 +111,31 @@ export interface TraceRecord {
         parentInvocationSeq: number;
         role: string;
     };
+    /** TUI2-R3v2 ③ (v4) — what this request was FOR, when it was not a
+     *  run's own work. ABSENT on every run request (the overwhelming
+     *  majority) and present on a side query (session.sideQuery), naming
+     *  its purpose: "safer-options". A consumer separating on-demand rent
+     *  from run rent reads this field and needs no heuristic. */
+    purpose?: string;
     ts: number;
 }
 /** That is the complete set for 1.2.0. */
 export interface HeaderLine {
-    schemaVersion: 3;
+    schemaVersion: 4;
     kind: "header";
     sessionId: string;
     kisoVersion: string;
     createdAt: number;
 }
 export interface RunEndLine {
-    schemaVersion: 3;
+    schemaVersion: 4;
     kind: "run_end";
     runId: string;
     ts: number;
     lastRequestIndex: number;
 }
 export interface CrashLine {
-    schemaVersion: 3;
+    schemaVersion: 4;
     kind: "crash";
     ts: number;
     note: string;
@@ -138,7 +154,14 @@ export declare const TRACE_RECORD_FIELDS_V1: readonly ["schemaVersion", "kind",
 /** The 1.3.0 field set (schemaVersion 2) = the v1 set + `canonical`. */
 export declare const TRACE_RECORD_FIELDS_V2: readonly ["schemaVersion", "kind", "requestId", "runId", "requestIndex", "retryAttempt", "provider", "model", "adapterVersion", "systemPromptHash", "toolSchemaHash", "contextHash", "contextManifest", "segmentHashes", "stablePrefixFingerprint", "freshInput", "cacheRead", "cacheWrite", "output", "latencyMs", "ttftMs", "toolCalls", "outcome", "lineageLink", "ts", "canonical"];
 /** The 0.2.1 field set (schemaVersion 3) = the v2 set + `rent`. */
-export declare const TRACE_RECORD_FIELDS: readonly ["schemaVersion", "kind", "requestId", "runId", "requestIndex", "retryAttempt", "provider", "model", "adapterVersion", "systemPromptHash", "toolSchemaHash", "contextHash", "contextManifest", "segmentHashes", "stablePrefixFingerprint", "freshInput", "cacheRead", "cacheWrite", "output", "latencyMs", "ttftMs", "toolCalls", "outcome", "lineageLink", "ts", "canonical", "rent"];
+export declare const TRACE_RECORD_FIELDS_V3: readonly ["schemaVersion", "kind", "requestId", "runId", "requestIndex", "retryAttempt", "provider", "model", "adapterVersion", "systemPromptHash", "toolSchemaHash", "contextHash", "contextManifest", "segmentHashes", "stablePrefixFingerprint", "freshInput", "cacheRead", "cacheWrite", "output", "latencyMs", "ttftMs", "toolCalls", "outcome", "lineageLink", "ts", "canonical", "rent"];
+/** The 0.12.0 field set (schemaVersion 4) = the v3 set + `purpose`.
+ *  TUI2-R3v2 ③: `purpose` is OPTIONAL — a run request omits it entirely,
+ *  a side query names what it was for. It is listed in TRACE_RECORD_OPTIONAL
+ *  below so the closed-set gate accepts a record without it. */
+export declare const TRACE_RECORD_FIELDS: readonly ["schemaVersion", "kind", "requestId", "runId", "requestIndex", "retryAttempt", "provider", "model", "adapterVersion", "systemPromptHash", "toolSchemaHash", "contextHash", "contextManifest", "segmentHashes", "stablePrefixFingerprint", "freshInput", "cacheRead", "cacheWrite", "output", "latencyMs", "ttftMs", "toolCalls", "outcome", "lineageLink", "ts", "canonical", "rent", "purpose"];
+/** The fields the closed-set check does not require to be present. */
+export declare const TRACE_RECORD_OPTIONAL: readonly ["purpose"];
 export declare const TRACE_SEGMENT_FIELDS: readonly ["role", "seqRange", "estTokens", "freshness"];
 export declare function validateTraceSegment(v: unknown): v is TraceSegment;
 export declare function validateTraceRecord(v: unknown): v is TraceRecord;

package/dist/trace/record.js

@@ -25,22 +25,33 @@
  * writers record it; v1/v2 sidecars keep reading as defaults (R1d-1,
  * R2-1): no rent block = no rent lines = the zero-rent reading, never a
  * crash.
+ *
+ * TUI2-R3v2 (0.12.0) — schemaVersion 4: the record gains the OPTIONAL
+ * `purpose` marker (the safer-options seam, adjudicated 2026-08-18). A
+ * session can now make a request that belongs to no run — a side query
+ * (session.sideQuery) — and a ledger that could not tell one from a run
+ * request would make every rent audit guesswork. `purpose` is absent on
+ * run requests and present on side queries, naming what the request was
+ * FOR ("safer-options"). Optional by construction: adding a required
+ * field would have invalidated every v3 record ever written, and the
+ * whole generation-compat discipline exists to prevent exactly that.
  */
-/** schemaVersion: 3 for 0.2.1 (the rent block). Version 1 = the 1.2.0
- *  shape, version 2 = the 1.3.0 shape; both kept for generation-compat
- *  reads (R1d-1, R2-1). Algorithm and shape changes bump it (ADR-0051 §6
- *  OUT-side versioning). */
-export const TRACE_SCHEMA_VERSION = 3;
+/** schemaVersion: 4 for 0.12.0 (the optional `purpose` marker). Version
+ *  1 = the 1.2.0 shape, 2 = the 1.3.0 shape, 3 = the 0.2.1 shape; all
+ *  kept for generation-compat reads (R1d-1, R2-1). Algorithm and shape
+ *  changes bump it (ADR-0051 §6 OUT-side versioning). */
+export const TRACE_SCHEMA_VERSION = 4;
 /** The versions a reader may meet in a ledger. v1 and v2 records are
  *  accepted (generation-compat) and read as defaults — no canonical
  *  block (v1), no rent block (v1, v2). */
-export const TRACE_SCHEMA_VERSIONS = new Set([1, 2, TRACE_SCHEMA_VERSION]);
+export const TRACE_SCHEMA_VERSIONS = new Set([1, 2, 3, TRACE_SCHEMA_VERSION]);
 import { PRICING_TABLE_V1, priceFor, pricingTableFor, validateCanonicalUsage } from "../usage/canonical.js";
 import { validateRentLine } from "./rent.js";
 export const HASH_SPEC_BY_VERSION = {
     1: { algorithm: "sha-256", output: "full-hex" },
     2: { algorithm: "sha-256", output: "full-hex" }, // E2 — the algorithms do not change
     3: { algorithm: "sha-256", output: "full-hex" }, // E3 — same algorithms, re-pinned (the E2 ritual)
+    4: { algorithm: "sha-256", output: "full-hex" }, // TUI2-R3v2 — `purpose` is a marker, not an input to any hash; re-pinned by the same ritual
 };
 export function hashSpecFor(version) {
     const spec = HASH_SPEC_BY_VERSION[version];
@@ -84,7 +95,14 @@ export const TRACE_RECORD_FIELDS_V1 = [
 /** The 1.3.0 field set (schemaVersion 2) = the v1 set + `canonical`. */
 export const TRACE_RECORD_FIELDS_V2 = [...TRACE_RECORD_FIELDS_V1, "canonical"];
 /** The 0.2.1 field set (schemaVersion 3) = the v2 set + `rent`. */
-export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V2, "rent"];
+export const TRACE_RECORD_FIELDS_V3 = [...TRACE_RECORD_FIELDS_V2, "rent"];
+/** The 0.12.0 field set (schemaVersion 4) = the v3 set + `purpose`.
+ *  TUI2-R3v2 ③: `purpose` is OPTIONAL — a run request omits it entirely,
+ *  a side query names what it was for. It is listed in TRACE_RECORD_OPTIONAL
+ *  below so the closed-set gate accepts a record without it. */
+export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V3, "purpose"];
+/** The fields the closed-set check does not require to be present. */
+export const TRACE_RECORD_OPTIONAL = ["purpose"];
 export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
 // ── Validators ────────────────────────────────────────────────────────────
 // Strict by design: extra keys are rejected (the closed set), so a
@@ -135,10 +153,16 @@ export function validateTraceRecord(v) {
     // block, a v2 sidecar has no rent block — both read as defaults,
     // accepted, never a crash; the current version is fully checked
     // (shape + the canonical block + the rent ledger).
-    if (version !== 1 && version !== 2 && version !== TRACE_SCHEMA_VERSION)
+    // TUI2-R3v2 ③: v3 joins the generation-compat set — a v3 sidecar has
+    // no `purpose` on any record, which reads as "every request was a run
+    // request", the true statement about a ledger written before side
+    // queries existed.
+    if (version !== 1 && version !== 2 && version !== 3 && version !== TRACE_SCHEMA_VERSION)
+        return false;
+    const fields = version === 1 ? TRACE_RECORD_FIELDS_V1 : version === 2 ? TRACE_RECORD_FIELDS_V2 : version === 3 ? TRACE_RECORD_FIELDS_V3 : TRACE_RECORD_FIELDS;
+    if (!hasClosedKeys(v, fields, ["lineageLink", ...TRACE_RECORD_OPTIONAL]))
         return false;
-    const fields = version === 1 ? TRACE_RECORD_FIELDS_V1 : version === 2 ? TRACE_RECORD_FIELDS_V2 : TRACE_RECORD_FIELDS;
-    if (!hasClosedKeys(v, fields, ["lineageLink"]))
+    if (v.purpose !== undefined && (typeof v.purpose !== "string" || v.purpose === ""))
         return false;
     if (v.kind !== "request")
         return false;

package/dist/truncation-guard.d.ts

@@ -1,27 +1,77 @@
 /**
  * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
  *
- * The reference implementation's protection: a truncated stream (stopReason
- * max_tokens/length) can
- * yield tool args that parse and validate but are silently incomplete —
- * executing them is the destructive-bug class. The provider adapters already
- * see the stop reason; the RUNTIME vetoes execution of the whole batch:
- *
- *   - tool_call_end events are held per turn (the deltas pass through live —
- *     the UI still shows the calls building, only the COMPLETION is gated);
- *   - a compatible stop flushes the held calls in order, then the stop — the
- *     kernel launches them exactly as before (the parallel window survives;
- *     only the 0.1.26 mid-stream launch timing is gone — the cost of the
- *     guarantee: the turn's truncated intent is never half-executed);
- *   - a truncation stop flushes the held calls with input: null — the
- *     kernel's EXISTING invalid-input denial fails the whole batch without
- *     executing anything (the same honest null the adapters already emit
- *     for unparseable partials — zero new protocol surface), and the turn
- *     still ends with the max_tokens terminal (the loop's voided settle).
- *
- * The kernel machinery (the streaming launch, the window, the voided
- * settle) is untouched — the gate lives at the adapter boundary, where the
- * stop reason is already known.
+ * WHY: a truncated stream (stop reason max_tokens/length) can yield tool
+ * args that PARSE and VALIDATE while being silently incomplete — a delete
+ * whose `filter` never arrived, an edit missing its second hunk. Executing
+ * those is the destructive-bug class. The adapters already know the stop
+ * reason, so the veto belongs at that boundary.
+ *
+ * THE CONTRACT this wrapper establishes:
+ *
+ *   1. HOLD. A `tool_call_end` is withheld until the turn's stop reason is
+ *      known. No call completes — so none launches — before the provider
+ *      has said why it stopped. The deltas still pass through live: a
+ *      surface shows the calls building; only the COMPLETION is gated.
+ *   2. RELEASE ON A VALID STOP. A compatible stop flushes the held calls
+ *      unchanged and in CALL order, then the stop itself. Downstream sees
+ *      exactly what the provider sent.
+ *   3. max_tokens VOIDS THE WHOLE BATCH. Every held call is flushed with
+ *      `input: null`, and the kernel's EXISTING invalid-input denial fails
+ *      all of them without executing anything (the same honest null the
+ *      adapters already emit for unparseable partials — zero new protocol
+ *      surface). The turn still ends on the max_tokens terminal (the
+ *      loop's voided settle). All-or-nothing per turn: a truncated intent
+ *      is never HALF executed.
+ *   4. NO STOP AT ALL drops the held calls entirely — the kernel already
+ *      voids that malformed turn (invalid_request).
+ *
+ * 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

@@ -1,27 +1,77 @@
 /**
  * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
  *
- * The reference implementation's protection: a truncated stream (stopReason
- * max_tokens/length) can
- * yield tool args that parse and validate but are silently incomplete —
- * executing them is the destructive-bug class. The provider adapters already
- * see the stop reason; the RUNTIME vetoes execution of the whole batch:
- *
- *   - tool_call_end events are held per turn (the deltas pass through live —
- *     the UI still shows the calls building, only the COMPLETION is gated);
- *   - a compatible stop flushes the held calls in order, then the stop — the
- *     kernel launches them exactly as before (the parallel window survives;
- *     only the 0.1.26 mid-stream launch timing is gone — the cost of the
- *     guarantee: the turn's truncated intent is never half-executed);
- *   - a truncation stop flushes the held calls with input: null — the
- *     kernel's EXISTING invalid-input denial fails the whole batch without
- *     executing anything (the same honest null the adapters already emit
- *     for unparseable partials — zero new protocol surface), and the turn
- *     still ends with the max_tokens terminal (the loop's voided settle).
- *
- * The kernel machinery (the streaming launch, the window, the voided
- * settle) is untouched — the gate lives at the adapter boundary, where the
- * stop reason is already known.
+ * WHY: a truncated stream (stop reason max_tokens/length) can yield tool
+ * args that PARSE and VALIDATE while being silently incomplete — a delete
+ * whose `filter` never arrived, an edit missing its second hunk. Executing
+ * those is the destructive-bug class. The adapters already know the stop
+ * reason, so the veto belongs at that boundary.
+ *
+ * THE CONTRACT this wrapper establishes:
+ *
+ *   1. HOLD. A `tool_call_end` is withheld until the turn's stop reason is
+ *      known. No call completes — so none launches — before the provider
+ *      has said why it stopped. The deltas still pass through live: a
+ *      surface shows the calls building; only the COMPLETION is gated.
+ *   2. RELEASE ON A VALID STOP. A compatible stop flushes the held calls
+ *      unchanged and in CALL order, then the stop itself. Downstream sees
+ *      exactly what the provider sent.
+ *   3. max_tokens VOIDS THE WHOLE BATCH. Every held call is flushed with
+ *      `input: null`, and the kernel's EXISTING invalid-input denial fails
+ *      all of them without executing anything (the same honest null the
+ *      adapters already emit for unparseable partials — zero new protocol
+ *      surface). The turn still ends on the max_tokens terminal (the
+ *      loop's voided settle). All-or-nothing per turn: a truncated intent
+ *      is never HALF executed.
+ *   4. NO STOP AT ALL drops the held calls entirely — the kernel already
+ *      voids that malformed turn (invalid_request).
+ *
+ * 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).
  */
 /** 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.11.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.11.0"
+    "@vincemakes/kiso-core": "0.13.0"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.11.0",
-    "@vincemakes/kiso-provider-openai": "0.11.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.11.0",
+    "@vincemakes/kiso-evals": "0.13.0",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"