@vincemakes/kiso-runtime 0.11.0 → 0.12.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,6 +79,10 @@ 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 };

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,50 @@
 /**
  * 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:
+ * 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.
  *
- *   - 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 CONTRACT this wrapper establishes:
  *
- * 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.
+ *   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).
+ *
+ * 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`.
  */
 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,50 @@
 /**
  * 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:
+ * 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.
  *
- *   - 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 CONTRACT this wrapper establishes:
  *
- * 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.
+ *   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).
+ *
+ * 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`.
  */
 /** 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.12.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.12.0"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.11.0",
-    "@vincemakes/kiso-provider-openai": "0.11.0"
+    "@vincemakes/kiso-provider-anthropic": "0.12.0",
+    "@vincemakes/kiso-provider-openai": "0.12.0"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -40,7 +40,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.11.0",
+    "@vincemakes/kiso-evals": "0.12.0",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"