@vincemakes/kiso-runtime 0.34.0 → 0.37.0

package/dist/compose.js

@@ -16,7 +16,7 @@ const TOOL_RULES = [
     { tool: "read_file", line: "read files with read_file, never shell cat/head/tail" },
     { tool: "search_text", line: "search with search_text, never shell grep/rg" },
     { tool: "list_dir", line: "list with list_dir, never ls" },
-    { tool: "shell", line: "reserve shell for real system commands" },
+    { tool: "shell", line: "shell for what the file tools cannot do: commands, git, the network, the system" },
 ];
 /** The table, or "" when the registry is empty (no vocabulary, no tools). */
 export function composeToolTable(registry) {

package/dist/provider/metadata.js

@@ -189,7 +189,28 @@ const ENTRIES = [
         capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: {
                 emitsThinkingStream: true,
                 thinking: { modes: ["enabled", "disabled"], default: "enabled" },
-                effort: { levels: ["low", "high", "max"], default: "high", wire: "reasoning_effort" },
+                // `none` added 2026-09-14 from a live probe. The three natives were
+                // RIGHT and stay: the endpoint's enum accepts seven values, but
+                // the vendor maps minimal->low, medium->high and xhigh->high, so
+                // those three are the provider's own aliases and this row's rule
+                // is that an alias is never shown as native. Offering `medium`
+                // would promise a level the model does not have.
+                //
+                // `none` is not an alias. It turns thinking OFF: the response
+                // carries no reasoning_content and completion_tokens_details is
+                // null outright. A distinct behaviour the row simply lacked, and
+                // the only reachable way to buy no reasoning at all.
+                //
+                // Measured, 12 runs per level on one task (median reasoning
+                // tokens): minimal 191, low 186 | medium 212, high 199, xhigh 195
+                // | max 229. The grouping and the ordering match the vendor's
+                // mapping. The unset default sits at 219, which this sample
+                // cannot separate from high or from max, so `default` stays what
+                // the vendor documents rather than what one task suggests.
+                //
+                // bench/probe-effort-levels.mjs reads the accepted set from the
+                // endpoint's own refusal and costs nothing.
+                effort: { levels: ["none", "low", "high", "max"], default: "high", wire: "reasoning_effort" },
                 asOf: "2026-08-26",
                 source: "https://api-docs.deepseek.com/guides/thinking_mode",
             }, inputModalities: null },
@@ -197,6 +218,61 @@ const ENTRIES = [
         capabilitiesSource: "https://api-docs.deepseek.com/guides/thinking_mode",
         pricing: null,
     },
+    {
+        // Astra F5: THE VENDOR'S CURRENT RECOMMENDED NAME, registered so that
+        // copying it out of the vendor's own docs does not silently cost the
+        // effort controls. `deepseek-flash` had no row, and an unregistered
+        // model resolves default/default to an empty wire setting while
+        // REFUSING any explicit level by name — correct behaviour (unknown
+        // stays unknown) reached for the wrong reason: the model is known,
+        // the registry just had not been told its current name.
+        //
+        // The legacy alias is RETAINED above, not replaced: the vendor still
+        // accepts it and routes both to the same weights, so removing it
+        // would break configs that work today.
+        //
+        // SAME capabilities as the legacy row, deliberately. The vendor's
+        // page lists a 1M context window, and a window read off a page is not
+        // a measurement — it would make the meter claim precision the product
+        // has not earned, on the row that decides when context relief fires.
+        // contextWindow stays null, the CLI's conservative fallback applies,
+        // and the override is documented. Pricing likewise stays null: no
+        // price is invented for a name.
+        model: "deepseek-flash",
+        providerId: "deepseek",
+        endpoint: "https://api.deepseek.com",
+        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: {
+                emitsThinkingStream: true,
+                thinking: { modes: ["enabled", "disabled"], default: "enabled" },
+                // `none` added 2026-09-14 from a live probe. The three natives were
+                // RIGHT and stay: the endpoint's enum accepts seven values, but
+                // the vendor maps minimal->low, medium->high and xhigh->high, so
+                // those three are the provider's own aliases and this row's rule
+                // is that an alias is never shown as native. Offering `medium`
+                // would promise a level the model does not have.
+                //
+                // `none` is not an alias. It turns thinking OFF: the response
+                // carries no reasoning_content and completion_tokens_details is
+                // null outright. A distinct behaviour the row simply lacked, and
+                // the only reachable way to buy no reasoning at all.
+                //
+                // Measured, 12 runs per level on one task (median reasoning
+                // tokens): minimal 191, low 186 | medium 212, high 199, xhigh 195
+                // | max 229. The grouping and the ordering match the vendor's
+                // mapping. The unset default sits at 219, which this sample
+                // cannot separate from high or from max, so `default` stays what
+                // the vendor documents rather than what one task suggests.
+                //
+                // bench/probe-effort-levels.mjs reads the accepted set from the
+                // endpoint's own refusal and costs nothing.
+                effort: { levels: ["none", "low", "high", "max"], default: "high", wire: "reasoning_effort" },
+                asOf: "2026-09-12",
+                source: "https://api-docs.deepseek.com/quick_start/pricing/",
+            }, inputModalities: null },
+        capabilitiesAsOf: "2026-09-12",
+        capabilitiesSource: "https://api-docs.deepseek.com/quick_start/pricing/",
+        pricing: null,
+    },
     {
         model: "deepseek-v4-pro",
         providerId: "deepseek",
@@ -204,7 +280,28 @@ const ENTRIES = [
         capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: {
                 emitsThinkingStream: true,
                 thinking: { modes: ["enabled", "disabled"], default: "enabled" },
-                effort: { levels: ["low", "high", "max"], default: "high", wire: "reasoning_effort" },
+                // `none` added 2026-09-14 from a live probe. The three natives were
+                // RIGHT and stay: the endpoint's enum accepts seven values, but
+                // the vendor maps minimal->low, medium->high and xhigh->high, so
+                // those three are the provider's own aliases and this row's rule
+                // is that an alias is never shown as native. Offering `medium`
+                // would promise a level the model does not have.
+                //
+                // `none` is not an alias. It turns thinking OFF: the response
+                // carries no reasoning_content and completion_tokens_details is
+                // null outright. A distinct behaviour the row simply lacked, and
+                // the only reachable way to buy no reasoning at all.
+                //
+                // Measured, 12 runs per level on one task (median reasoning
+                // tokens): minimal 191, low 186 | medium 212, high 199, xhigh 195
+                // | max 229. The grouping and the ordering match the vendor's
+                // mapping. The unset default sits at 219, which this sample
+                // cannot separate from high or from max, so `default` stays what
+                // the vendor documents rather than what one task suggests.
+                //
+                // bench/probe-effort-levels.mjs reads the accepted set from the
+                // endpoint's own refusal and costs nothing.
+                effort: { levels: ["none", "low", "high", "max"], default: "high", wire: "reasoning_effort" },
                 asOf: "2026-08-26",
                 source: "https://api-docs.deepseek.com/guides/thinking_mode",
             }, inputModalities: null },

package/dist/session.d.ts

@@ -141,7 +141,30 @@ export declare class AgentSession {
         /** XP-1: the reasoning axes travel with the binding too; absent =
          *  fresh defaults (a new binding never inherits stale effort). */
         readonly reasoning?: ReasoningSetting;
+        /** CTX-1: the compaction threshold follows the live model's window.
+         *  Absent KEEPS the current one — a caller that does not know the new
+         *  model's window must not silently reset the policy to nothing. */
+        readonly microcompact?: {
+            readonly thresholdTokens: number;
+        };
     }): void;
+    /**
+     * CTX-1: the compaction threshold alone, with NO profile revision.
+     *
+     * `setModelBinding` is the atomic switch — the adapter and everything
+     * that must travel with it, recorded durably. This is the other door:
+     * a session OPENED onto a model the process was not configured for.
+     * `/resume` restores the recorded model, which can be any model the
+     * session ever used, while the threshold came from whatever model this
+     * process started on. Resuming a 1M session from a 200k start left it
+     * clearing tool results at 100,000.
+     *
+     * It writes no revision because nothing was selected: the caller is
+     * bringing the policy into line with a model already in force, not
+     * choosing one. Recording a revision here would write a new profile on
+     * every open.
+     */
+    setMicrocompactThreshold(thresholdTokens: number): void;
     /** E2: the adapter identity (anthropic / openai-compat / openai-responses) — the route
      *  key the canonical consumer (CLI usage, the trace block) keys on. The
      *  per-run tracer reads the SAME live binding; one source, one

package/dist/session.js

@@ -92,6 +92,12 @@ export class AgentSession {
     #continuationScope;
     // XP-1: the selected axes; resolved per request (next-turn semantics).
     #reasoning;
+    // CTX-1: the compaction threshold is derived from the LIVE model's window,
+    // so it is a passenger on the binding like the four above. PH-F8 fixed
+    // exactly this class — a frozen startup value still in use after a switch
+    // — for the model id, the provider, the endpoint and the scope. The
+    // threshold was one field over and was never asked.
+    #microcompact;
     // XP-1: a legacy session records revision 1 at the next explicit
     // selection or first request — never eagerly at open.
     #profilePending;
@@ -146,6 +152,8 @@ export class AgentSession {
         this.#baseUrl = config.baseUrl;
         this.#continuationScope = config.continuationScope;
         this.#reasoning = config.reasoning ?? { thinking: "default", effort: "default" };
+        // CTX-1: starts as the startup policy, then follows the binding.
+        this.#microcompact = config.microcompact;
         this.#profilePending = config.profilePending === true;
     }
     /** The config a NEW run/resume/summary sees: the frozen startup config
@@ -153,9 +161,10 @@ export class AgentSession {
      *  fresh per call so an in-flight run keeps the config it started with
      *  — the same boundary setAdapter has always drawn. */
     #effectiveConfig() {
-        const { provider: _startup, baseUrl: _startupUrl, continuationScope: _startupScope, ...rest } = this.#config;
+        const { provider: _startup, baseUrl: _startupUrl, continuationScope: _startupScope, microcompact: _startupMicro, ...rest } = this.#config;
         return {
             ...rest,
+            ...(this.#microcompact !== undefined ? { microcompact: this.#microcompact } : {}),
             model: this.#model,
             ...(this.#provider !== undefined ? { provider: this.#provider } : {}),
             ...(this.#baseUrl !== undefined ? { baseUrl: this.#baseUrl } : {}),
@@ -224,10 +233,31 @@ export class AgentSession {
         this.#baseUrl = binding.baseUrl;
         this.#continuationScope = binding.scope;
         this.#reasoning = binding.reasoning ?? { thinking: "default", effort: "default" };
+        if (binding.microcompact !== undefined)
+            this.#microcompact = binding.microcompact;
         // XP-1: an explicit selection is DURABLE — the setting survives
         // /resume because a revision records it now, not at some later flush.
         this.#recordProfile();
     }
+    /**
+     * CTX-1: the compaction threshold alone, with NO profile revision.
+     *
+     * `setModelBinding` is the atomic switch — the adapter and everything
+     * that must travel with it, recorded durably. This is the other door:
+     * a session OPENED onto a model the process was not configured for.
+     * `/resume` restores the recorded model, which can be any model the
+     * session ever used, while the threshold came from whatever model this
+     * process started on. Resuming a 1M session from a 200k start left it
+     * clearing tool results at 100,000.
+     *
+     * It writes no revision because nothing was selected: the caller is
+     * bringing the policy into line with a model already in force, not
+     * choosing one. Recording a revision here would write a new profile on
+     * every open.
+     */
+    setMicrocompactThreshold(thresholdTokens) {
+        this.#microcompact = { thresholdTokens };
+    }
     /** E2: the adapter identity (anthropic / openai-compat / openai-responses) — the route
      *  key the canonical consumer (CLI usage, the trace block) keys on. The
      *  per-run tracer reads the SAME live binding; one source, one

package/dist/summarize.js

@@ -226,7 +226,19 @@ export async function summarizeConversation(options) {
         }
         // The LAST usage event is the call's (a turn reports usage once).
         if (ev.type === "usage" && ev.known) {
-            usage = { inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, cacheRead: ev.cacheRead, cacheWrite: ev.cacheWrite };
+            // RSN-1, and the summary path was missed on the first wiring:
+            // the quartet was copied field by field, so a fifth field added
+            // later is silently dropped. The summary IS a billed call whose
+            // cost the ledger records; leaving its split behind made that
+            // one call's thinking unknown while every other call's was
+            // measured. The output total was never wrong — the split was.
+            usage = {
+                inputTokens: ev.inputTokens,
+                outputTokens: ev.outputTokens,
+                cacheRead: ev.cacheRead,
+                cacheWrite: ev.cacheWrite,
+                ...(ev.reasoningTokens !== undefined ? { reasoningTokens: ev.reasoningTokens } : {}),
+            };
         }
     }
     if (stops === 0)

package/dist/trace/guard.js

@@ -71,6 +71,14 @@ export class RequestTracer {
         let cacheWrite = null;
         let outputTokens = null;
         let usageKnown = false;
+        // TRACE-F1: the server's own statement of what it ran. Null until a
+        // usage event carries one; it stays null when the provider says
+        // nothing, which is a different fact from "it matched".
+        let servedModel = null;
+        // RSN-1: the reported thinking split. Undefined until a usage event
+        // carries one; it stays undefined when the provider reports none,
+        // which is a different fact from a measured zero.
+        let reasoningTokens;
         const toolCalls = [];
         let outcome = "ok";
         try {
@@ -91,6 +99,10 @@ export class RequestTracer {
                         cacheWrite = ev.cacheWrite;
                     if (ev.outputTokens !== null)
                         outputTokens = ev.outputTokens;
+                    if (ev.servedModel !== undefined)
+                        servedModel = ev.servedModel;
+                    if (ev.reasoningTokens !== undefined)
+                        reasoningTokens = ev.reasoningTokens;
                 }
                 yield ev;
             }
@@ -111,6 +123,8 @@ export class RequestTracer {
                     cacheWrite,
                     outputTokens,
                     usageKnown,
+                    servedModel,
+                    reasoningTokens,
                 });
             }
         }
@@ -163,6 +177,10 @@ export class RequestTracer {
             // turn (freshness fresh) is never part of it (slice 4)
             segmentHashes: hashes,
             stablePrefixFingerprint: stablePrefixFingerprint(cacheableHashes(manifest, hashes)),
+            // F33-1: the convention below writes unknown as zero, so the
+            // record says out loud which of the two it is. False until a
+            // usage event settles it.
+            usageKnown: false,
             freshInput: 0, // unknown until the usage event — "0 = unknown"
             cacheRead: 0,
             cacheWrite: null,
@@ -192,6 +210,35 @@ export class RequestTracer {
         record.latencyMs = performance.now() - p.t0;
         record.ttftMs = p.ttftMs ?? 0; // null = no event ever — the "0 = unknown" marker
         record.toolCalls = p.toolCalls;
+        // F33-1: the settle path has always been TOLD whether the provider
+        // reported usage; it just never wrote it down, and every consumer
+        // downstream then had to guess from four zeros.
+        //
+        // F33-R3: but `known` is NOT completeness. Core states the contract
+        // exactly — `known: true` means AT LEAST ONE field was reported and
+        // the others may still be null (protocol/events.ts, Area 6 round 9)
+        // — and canonicalization then fills the unreported ones with zero.
+        // Copying the boolean therefore re-lost the distinction one level
+        // down: a provider that reported input and cache but no output wrote
+        // `usageKnown: true, canonical.output: 0`, and every consumer read a
+        // measured zero.
+        //
+        // What a consumer needs is whether THE FIELDS THE COST IS MADE OF
+        // were each reported. That is a property of the raw quartet, so it
+        // is computed from the raw quartet rather than inherited from a flag
+        // that answers a weaker question. A genuine reported zero stays
+        // known: null is unreported, 0 is measured, and only null makes this
+        // false.
+        record.usageKnown =
+            p.usageKnown &&
+                p.inputTokens !== null &&
+                p.cacheRead !== null &&
+                p.outputTokens !== null;
+        // TRACE-F1: written ONLY when the server stated one. The field is
+        // absent otherwise — writing the requested id here would manufacture
+        // the agreement the reconciliation exists to test.
+        if (p.servedModel !== null)
+            record.servedModel = p.servedModel;
         if (p.usageKnown) {
             record.freshInput =
                 this.#provider === "anthropic"
@@ -218,6 +265,7 @@ export class RequestTracer {
             outputTokens: p.outputTokens,
             cacheRead: p.cacheRead,
             cacheWrite: p.cacheWrite,
+            ...(p.reasoningTokens !== undefined ? { reasoningTokens: p.reasoningTokens } : {}),
         });
         this.#writer.enqueue(record);
     }

package/dist/trace/record.d.ts

@@ -35,15 +35,64 @@
  * 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.
+ *
+ * Astra F33-1 (0.36.x) — schemaVersion 5: the record gains `usageKnown`.
+ * The writer has always initialised the quartet to zero under an explicit
+ * "0 = unknown" convention, and settled it only when the provider actually
+ * reported usage — so a request nobody measured was written as a request
+ * that cost nothing, indistinguishable from a genuine zero. Every consumer
+ * reading the sidecar inherited that: the bench extractors' "unknown is not
+ * zero" fix ran only on the plain-log branch, and adding a conforming
+ * sidecar to a session with one unmeasured request flipped
+ * usage_incomplete from true to false.
+ *
+ * The settle path already receives `usageKnown`; it simply never wrote it
+ * down. Recording it makes the ledger self-describing, which is the only
+ * form in which a later reader can tell the two zeros apart. It is listed
+ * as OPTIONAL so that v1-v4 sidecars stay readable — their absence means
+ * "this generation could not say", which a consumer must treat as unknown
+ * rather than as complete.
+ *
+ * TRACE-F1 (0.36.x) — schemaVersion 6: the record gains `servedModel`, the
+ * id the SERVER says it served. Every generation before this one recorded
+ * only `model`, the id we asked for, and the two were assumed identical
+ * because nothing ever checked. A vendor is free to disagree: a retired
+ * name becomes an alias, a migration id resolves elsewhere, a tier is
+ * silently upgraded. The bench asked for `deepseek-v4-flash` on every leg
+ * for four days while the server answered as `deepseek-flash`, and the
+ * specified-vs-observed reconciliation built to catch precisely that
+ * reported nothing — it had no observed half to compare, so it compared
+ * the specification against itself.
+ *
+ * OPTIONAL, and absent means "the server stated nothing" — NEVER "the same
+ * as requested". That default is the whole defect: a field filled in with
+ * the request manufactures the agreement the reconciliation exists to
+ * test.
  */
-/** schemaVersion: 4 for 0.12.0 (the optional `purpose` marker). Version
+/** schemaVersion: 6 for the `servedModel` statement (TRACE-F1);
+ *  5 was the `usageKnown` marker (F33-1). 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;
+export declare const TRACE_SCHEMA_VERSION = 6;
 /** 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). */
+/**
+ * EVERY generation ever written, named explicitly.
+ *
+ * F33-R1: this was `[1, 2, 3, TRACE_SCHEMA_VERSION]`, and a set spelled
+ * with a MOVING member drops the generation it was standing on every time
+ * the version rises. Raising 4 to 5 silently removed 4 — the version every
+ * trace the deployed 0.36.0 has ever written carries — so the reader
+ * stopped accepting the product's own live output while a v5 record went
+ * through. The whole generation-compat discipline exists to prevent that,
+ * and its own constant undid it.
+ *
+ * A new version is added here BY HAND, next to its field set and its hash
+ * spec. Three lists to extend is the point: a bump that forgets one is a
+ * bump that fails loudly rather than a reader that quietly narrows.
+ */
 export declare const TRACE_SCHEMA_VERSIONS: Readonly<Set<number>>;
 import type { CanonicalUsage } from "../usage/canonical.js";
 import { type RentLine } from "./rent.js";
@@ -62,7 +111,7 @@ export interface TraceSegment {
 }
 /** That is the complete set for 1.2.0. */
 export interface TraceRecord {
-    schemaVersion: 4;
+    schemaVersion: 6;
     kind: "request";
     requestId: string;
     runId: string;
@@ -86,6 +135,12 @@ export interface TraceRecord {
      *  Canonical/billing usage lives in the `canonical` block (E2); these
      *  fields are observation only (a provider may count a token a dozen
      *  ways; billing must not). */
+    /** F33-1 (v5): did the provider actually REPORT usage for this request?
+     *  The quartet below is written under a "0 = unknown" convention, so
+     *  without this a request nobody measured and a request that genuinely
+     *  cost nothing are the same four zeros. Optional only for reading v1-v4
+     *  sidecars; every v5 writer records it. */
+    usageKnown?: boolean;
     freshInput: number;
     cacheRead: number;
     cacheWrite: number | null;
@@ -117,25 +172,31 @@ export interface TraceRecord {
      *  its purpose: "safer-options". A consumer separating on-demand rent
      *  from run rent reads this field and needs no heuristic. */
     purpose?: string;
+    /** TRACE-F1 (v6) — the model id the SERVER said it served, when it said
+     *  one. ABSENT means the server stated nothing, NEVER "the same as
+     *  requested": that default is what let a retired id read as live for
+     *  four days. The requested id stays in `model`; these are two facts,
+     *  never merged. */
+    servedModel?: string;
     ts: number;
 }
 /** That is the complete set for 1.2.0. */
 export interface HeaderLine {
-    schemaVersion: 4;
+    schemaVersion: 6;
     kind: "header";
     sessionId: string;
     kisoVersion: string;
     createdAt: number;
 }
 export interface RunEndLine {
-    schemaVersion: 4;
+    schemaVersion: 6;
     kind: "run_end";
     runId: string;
     ts: number;
     lastRequestIndex: number;
 }
 export interface CrashLine {
-    schemaVersion: 4;
+    schemaVersion: 6;
     kind: "crash";
     ts: number;
     note: string;
@@ -159,9 +220,18 @@ export declare const TRACE_RECORD_FIELDS_V3: readonly ["schemaVersion", "kind",
  *  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"];
+export declare const TRACE_RECORD_FIELDS_V4: 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 field set (schemaVersion 5) = the v4 set + `usageKnown` (F33-1).
+ *  Optional for the same reason `purpose` is: requiring it would invalidate
+ *  every v4 record ever written, and reading old generations is the whole
+ *  point of the discipline. Absent means the generation could not say. */
+export declare const TRACE_RECORD_FIELDS_V5: 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", "usageKnown"];
+/** TRACE-F1 (v6): the model the SERVER said it served. A v5 ledger has none
+ *  on any record, which reads as "nobody asked the server" — the true
+ *  statement about a ledger written before the adapters read the field. */
+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", "usageKnown", "servedModel"];
 /** The fields the closed-set check does not require to be present. */
-export declare const TRACE_RECORD_OPTIONAL: readonly ["purpose"];
+export declare const TRACE_RECORD_OPTIONAL: readonly ["purpose", "usageKnown", "servedModel"];
 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

@@ -35,16 +35,65 @@
  * 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.
+ *
+ * Astra F33-1 (0.36.x) — schemaVersion 5: the record gains `usageKnown`.
+ * The writer has always initialised the quartet to zero under an explicit
+ * "0 = unknown" convention, and settled it only when the provider actually
+ * reported usage — so a request nobody measured was written as a request
+ * that cost nothing, indistinguishable from a genuine zero. Every consumer
+ * reading the sidecar inherited that: the bench extractors' "unknown is not
+ * zero" fix ran only on the plain-log branch, and adding a conforming
+ * sidecar to a session with one unmeasured request flipped
+ * usage_incomplete from true to false.
+ *
+ * The settle path already receives `usageKnown`; it simply never wrote it
+ * down. Recording it makes the ledger self-describing, which is the only
+ * form in which a later reader can tell the two zeros apart. It is listed
+ * as OPTIONAL so that v1-v4 sidecars stay readable — their absence means
+ * "this generation could not say", which a consumer must treat as unknown
+ * rather than as complete.
+ *
+ * TRACE-F1 (0.36.x) — schemaVersion 6: the record gains `servedModel`, the
+ * id the SERVER says it served. Every generation before this one recorded
+ * only `model`, the id we asked for, and the two were assumed identical
+ * because nothing ever checked. A vendor is free to disagree: a retired
+ * name becomes an alias, a migration id resolves elsewhere, a tier is
+ * silently upgraded. The bench asked for `deepseek-v4-flash` on every leg
+ * for four days while the server answered as `deepseek-flash`, and the
+ * specified-vs-observed reconciliation built to catch precisely that
+ * reported nothing — it had no observed half to compare, so it compared
+ * the specification against itself.
+ *
+ * OPTIONAL, and absent means "the server stated nothing" — NEVER "the same
+ * as requested". That default is the whole defect: a field filled in with
+ * the request manufactures the agreement the reconciliation exists to
+ * test.
  */
-/** schemaVersion: 4 for 0.12.0 (the optional `purpose` marker). Version
+/** schemaVersion: 6 for the `servedModel` statement (TRACE-F1);
+ *  5 was the `usageKnown` marker (F33-1). 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;
+export const TRACE_SCHEMA_VERSION = 6;
 /** 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, 3, TRACE_SCHEMA_VERSION]);
+/**
+ * EVERY generation ever written, named explicitly.
+ *
+ * F33-R1: this was `[1, 2, 3, TRACE_SCHEMA_VERSION]`, and a set spelled
+ * with a MOVING member drops the generation it was standing on every time
+ * the version rises. Raising 4 to 5 silently removed 4 — the version every
+ * trace the deployed 0.36.0 has ever written carries — so the reader
+ * stopped accepting the product's own live output while a v5 record went
+ * through. The whole generation-compat discipline exists to prevent that,
+ * and its own constant undid it.
+ *
+ * A new version is added here BY HAND, next to its field set and its hash
+ * spec. Three lists to extend is the point: a bump that forgets one is a
+ * bump that fails loudly rather than a reader that quietly narrows.
+ */
+export const TRACE_SCHEMA_VERSIONS = new Set([1, 2, 3, 4, 5, 6]);
 import { PRICING_TABLE_V1, priceFor, pricingTableFor, validateCanonicalUsage } from "../usage/canonical.js";
 import { validateRentLine } from "./rent.js";
 export const HASH_SPEC_BY_VERSION = {
@@ -52,6 +101,8 @@ export const HASH_SPEC_BY_VERSION = {
     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
+    5: { algorithm: "sha-256", output: "full-hex" }, // F33-1 — `usageKnown` is a marker, not an input to any hash; re-pinned by the same ritual
+    6: { algorithm: "sha-256", output: "full-hex" }, // TRACE-F1 — `servedModel` is the server's statement, not an input to any hash; re-pinned by the same ritual
 };
 export function hashSpecFor(version) {
     const spec = HASH_SPEC_BY_VERSION[version];
@@ -100,9 +151,18 @@ export const TRACE_RECORD_FIELDS_V3 = [...TRACE_RECORD_FIELDS_V2, "rent"];
  *  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"];
+export const TRACE_RECORD_FIELDS_V4 = [...TRACE_RECORD_FIELDS_V3, "purpose"];
+/** The field set (schemaVersion 5) = the v4 set + `usageKnown` (F33-1).
+ *  Optional for the same reason `purpose` is: requiring it would invalidate
+ *  every v4 record ever written, and reading old generations is the whole
+ *  point of the discipline. Absent means the generation could not say. */
+export const TRACE_RECORD_FIELDS_V5 = [...TRACE_RECORD_FIELDS_V4, "usageKnown"];
+/** TRACE-F1 (v6): the model the SERVER said it served. A v5 ledger has none
+ *  on any record, which reads as "nobody asked the server" — the true
+ *  statement about a ledger written before the adapters read the field. */
+export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V5, "servedModel"];
 /** The fields the closed-set check does not require to be present. */
-export const TRACE_RECORD_OPTIONAL = ["purpose"];
+export const TRACE_RECORD_OPTIONAL = ["purpose", "usageKnown", "servedModel"];
 export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
 // ── Validators ────────────────────────────────────────────────────────────
 // Strict by design: extra keys are rejected (the closed set), so a
@@ -157,13 +217,37 @@ export function validateTraceRecord(v) {
     // 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)
+    // F33-R1: the same moving-member defect lived here too. Every generation
+    // dispatches to ITS OWN field set; v4 is not "whatever the current one
+    // is minus a field", it is the set a v4 writer actually emitted.
+    if (typeof version !== "number" || !TRACE_SCHEMA_VERSIONS.has(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;
+    const fields = version === 1
+        ? TRACE_RECORD_FIELDS_V1
+        : version === 2
+            ? TRACE_RECORD_FIELDS_V2
+            : version === 3
+                ? TRACE_RECORD_FIELDS_V3
+                : version === 4
+                    ? TRACE_RECORD_FIELDS_V4
+                    : version === 5
+                        ? TRACE_RECORD_FIELDS_V5
+                        : TRACE_RECORD_FIELDS;
     if (!hasClosedKeys(v, fields, ["lineageLink", ...TRACE_RECORD_OPTIONAL]))
         return false;
     if (v.purpose !== undefined && (typeof v.purpose !== "string" || v.purpose === ""))
         return false;
+    // F33-R8: the completeness marker is a BOOLEAN. It was accepted as
+    // anything at all, so a record carrying `usageKnown: "yes"` validated and
+    // every consumer that branches on it read truthy — a marker a reader acts
+    // on has to be the type it claims to be.
+    if (v.usageKnown !== undefined && typeof v.usageKnown !== "boolean")
+        return false;
+    // TRACE-F1: the served id is a NON-EMPTY string when stated. Empty would
+    // reconcile as a contradiction against every requested id; absent is the
+    // honest "the server said nothing".
+    if (v.servedModel !== undefined && (typeof v.servedModel !== "string" || v.servedModel === ""))
+        return false;
     if (v.kind !== "request")
         return false;
     if (typeof v.requestId !== "string" || typeof v.runId !== "string")

package/dist/usage/canonical.d.ts

@@ -33,6 +33,10 @@ export interface RawUsage {
     readonly outputTokens: number | null;
     readonly cacheRead: number | null;
     readonly cacheWrite: number | null;
+    /** RSN-1: absent when the provider reported no split. Optional rather
+     *  than `number | null` so every existing caller stays valid and an
+     *  omission cannot be mistaken for a measured zero. */
+    readonly reasoningTokens?: number;
 }
 /** The ONE canonical usage record. Every field has exactly one meaning
  *  (proposal §1.2). wall/ttft live in the trace record (latencyMs/ttftMs)
@@ -45,7 +49,17 @@ export interface CanonicalUsage {
     readonly cacheRead: number;
     /** null = the provider reports none (openai-compat honestly does). */
     readonly cacheWrite: number | null;
-    /** null = no reasoning split reported (reserved — every provider today). */
+    /** RSN-1: how much of `output` was THINKING, when the provider says.
+     *  A SPLIT of the output, never a fifth quantity — completion tokens
+     *  have always included reasoning ones, so the bill was never short;
+     *  what was missing is which half the money went to, and that is the
+     *  half the effort knob moves.
+     *
+     *  null = not reported. The comment here used to say "reserved — every
+     *  provider today", which was true when it was written and had stopped
+     *  being true: the field sat hardcoded null while the vendor's own
+     *  response carried `completion_tokens_details.reasoning_tokens`, read
+     *  from the SAME object we already read the cache figure out of. */
     readonly reasoning: number | null;
     /** USD from the pricing table below — null is the R5b-④c ABSENT stamp:
      *  the table has no rate for this route (an injected table's hole is

package/dist/usage/canonical.js

@@ -101,7 +101,11 @@ export function canonicalizeUsage(route, raw, table = PRICING_TABLE_V1) {
         output,
         cacheRead,
         cacheWrite,
-        reasoning: null, // reserved — no provider reports a split today
+        // RSN-1: the reported split, or null when none was reported. NEVER 0
+        // for an absent one — a provider that measured no thinking and a
+        // provider that measured nothing are different facts, and this file
+        // spent a release conflating them under a comment that had aged out.
+        reasoning: raw.reasoningTokens ?? null,
         costUsd: priceFor(route, { input, output, cacheRead, cacheWrite }, table),
         pricingTableId: table.id,
         pricingTableVersion: table.version,

package/package.json

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