@vincemakes/kiso-runtime 1.1.0 → 1.2.0

package/dist/agent.js

@@ -55,6 +55,7 @@ export class AgentRuntime {
         const adapter = await this.#adapterPromise;
         const config = {
             model: this.#definition.model,
+            ...(this.#definition.provider !== undefined ? { provider: this.#definition.provider } : {}),
             ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
             registry: this.#registry,
             ...(this.#definition.permissionPolicy !== undefined || this.#definition.hooks !== undefined

package/dist/run.js

@@ -8,6 +8,8 @@ import { ABORTED, MergedSignal, abortable, openRunId } from "./recovery.js";
 import { deriveRecoveryPlan, invocationSeqOf } from "./recovery-plan.js";
 import { composeApprovalChain, composeSystemPrompt, composeToolTable, microcompactFor } from "./compose.js";
 import { truncationGuard } from "./truncation-guard.js";
+import { RequestTracer, traceGuard } from "./trace/guard.js";
+import { runtimeVersion } from "./trace/writer.js";
 import { ResumeBlockedError } from "./session.js";
 /**
  * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
@@ -47,6 +49,7 @@ export class Run {
         // The WHOLE body is one try/finally: a consumer that abandons the
         // run at ANY yield (even the user_input one) must release the
         // session's single-run slot and its approval resolvers.
+        let tracer = null;
         try {
             // round 4: health is re-checked when the iterator ACTUALLY starts —
             // a run constructed before the session was poisoned must fail
@@ -54,6 +57,20 @@ export class Run {
             this.#session.ensureHealthy();
             this.#session.beginRun(this);
             const log = this.#session.log;
+            // E1 (1.2.0): the request tracer — the observation ledger. It
+            // sits at the adapter boundary; the model-visible byte stream is
+            // untouched (I6, trace-bytes.test.ts). Soft-fail: a degraded
+            // writer costs one stderr line and the run goes on.
+            tracer = new RequestTracer({
+                root: this.#store.root,
+                sessionId: this.#session.id,
+                runId: this.runId,
+                provider: this.#config.provider ?? "adapter",
+                model: this.#config.model,
+                adapterVersion: runtimeVersion(),
+                log: log.all,
+            });
+            tracer.init();
             const signal = this.#externalSignal ? new MergedSignal(this.#abort.signal, this.#externalSignal) : this.#abort.signal;
             // E2: the session's own microcompact wins; otherwise the FIRST
             // extension providing a compaction config supplies it.
@@ -75,7 +92,7 @@ export class Run {
             const loopConfig = () => ({
                 // 0.1.40 (R-C item 3): the truncation guard gates the model
                 // stream — a truncated turn's tool batch never executes.
-                adapter: truncationGuard(this.#adapter),
+                adapter: traceGuard(tracer, truncationGuard(this.#adapter)), // tracer assigned above, before loopConfig
                 model: this.#config.model,
                 sessionId: this.#session.id, // P3: tools see their session (ToolContext.sessionId)
                 ...(systemPrompt !== undefined ? { systemPrompt } : {}),
@@ -230,6 +247,9 @@ export class Run {
             for (const executionId of this.#uncertaintyIds) {
                 this.#session.dropUncertaintyResolver(executionId);
             }
+            // E1: the run's ledger story — the run_end lands synchronously
+            // (a killed run leaves no run_end, and the next init marks it).
+            tracer?.finishRun();
             this.#session.endRun(this);
         }
     }

package/dist/session.d.ts

@@ -179,6 +179,9 @@ export declare class AgentSession {
 }
 export interface SessionConfig {
     readonly model: string;
+    /** E1: the adapter identity ("anthropic" | "openai-compat") — trace
+     *  provenance, additive (S1 surface untouched: type-only, optional). */
+    readonly provider?: "anthropic" | "openai-compat";
     readonly systemPrompt?: string;
     readonly tools?: readonly Tool<any>[];
     readonly registry: import("@vincemakes/kiso-core").ToolRegistry;

package/dist/trace/analyze.d.ts

@@ -0,0 +1,35 @@
+/**
+ * E1 (1.2.0) — slice 4, the cache-break derivation (proposal §4, ruling
+ * R4b: per-segment hashes + prefix fingerprint; the BREAK COUNT is an
+ * analysis-side derivation, never a recorded field).
+ *
+ * The cacheable prefix is every segment that is NOT the current turn —
+ * freshness "fresh" is the boundary (manifest.ts). `cacheableHashes`
+ * pairs the manifest segments 1:1 with the per-segment hashes and
+ * drops the fresh tail, so the fingerprint and the break derivation
+ * share one boundary by construction: a current-turn change alone
+ * never moves the fingerprint and never counts a break.
+ *
+ * `prefixBreak` compares two adjacent requests' cacheable prefixes:
+ * the first differing segment is the break, at its (0-based) depth;
+ * a prefix that merely GREW (a new turn joined) breaks at the old
+ * length. Unchanged prefixes → null (0 breaks). This is what
+ * bench/trace-report.mjs and the bench render per-request (slice 5).
+ */
+import type { TraceSegment } from "./record.js";
+/** The cacheable-prefix hashes: segments[i] ↔ hashes[i], dropping every
+ *  freshness "fresh" segment (the current turn). */
+export declare function cacheableHashes(segments: readonly TraceSegment[], hashes: readonly string[]): string[];
+export interface PrefixBreak {
+    /** 0-based segment index within the cacheable prefix where the
+     *  prefix first diverges (depth 0 = the system prompt). */
+    readonly depth: number;
+}
+/** R4b: compare two adjacent requests' cacheable prefixes. null = the
+ *  prefix is unchanged (0 breaks). A prefix that grew breaks at the old
+ *  length — the new segment is where caching can no longer attach. */
+export declare function prefixBreak(prev: readonly string[], next: readonly string[]): PrefixBreak | null;
+/** Per-request breaks across a run's request sequence: request k's
+ *  break is relative to request k−1; the first request has no
+ *  predecessor (null). */
+export declare function deriveBreaks(requests: readonly (readonly string[])[]): (PrefixBreak | null)[];

package/dist/trace/analyze.js

@@ -0,0 +1,51 @@
+/**
+ * E1 (1.2.0) — slice 4, the cache-break derivation (proposal §4, ruling
+ * R4b: per-segment hashes + prefix fingerprint; the BREAK COUNT is an
+ * analysis-side derivation, never a recorded field).
+ *
+ * The cacheable prefix is every segment that is NOT the current turn —
+ * freshness "fresh" is the boundary (manifest.ts). `cacheableHashes`
+ * pairs the manifest segments 1:1 with the per-segment hashes and
+ * drops the fresh tail, so the fingerprint and the break derivation
+ * share one boundary by construction: a current-turn change alone
+ * never moves the fingerprint and never counts a break.
+ *
+ * `prefixBreak` compares two adjacent requests' cacheable prefixes:
+ * the first differing segment is the break, at its (0-based) depth;
+ * a prefix that merely GREW (a new turn joined) breaks at the old
+ * length. Unchanged prefixes → null (0 breaks). This is what
+ * bench/trace-report.mjs and the bench render per-request (slice 5).
+ */
+/** The cacheable-prefix hashes: segments[i] ↔ hashes[i], dropping every
+ *  freshness "fresh" segment (the current turn). */
+export function cacheableHashes(segments, hashes) {
+    const out = [];
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i].freshness !== "fresh")
+            out.push(hashes[i]);
+    }
+    return out;
+}
+/** R4b: compare two adjacent requests' cacheable prefixes. null = the
+ *  prefix is unchanged (0 breaks). A prefix that grew breaks at the old
+ *  length — the new segment is where caching can no longer attach. */
+export function prefixBreak(prev, next) {
+    const shared = Math.min(prev.length, next.length);
+    for (let i = 0; i < shared; i++) {
+        if (prev[i] !== next[i])
+            return { depth: i };
+    }
+    if (prev.length !== next.length)
+        return { depth: shared };
+    return null;
+}
+/** Per-request breaks across a run's request sequence: request k's
+ *  break is relative to request k−1; the first request has no
+ *  predecessor (null). */
+export function deriveBreaks(requests) {
+    const out = [];
+    for (let k = 0; k < requests.length; k++) {
+        out.push(k === 0 ? null : prefixBreak(requests[k - 1], requests[k]));
+    }
+    return out;
+}

package/dist/trace/guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * E1 (1.2.0) — slice 3, the request tracer (the guard).
+ *
+ * One TraceRecord per adapter call, settled when the stream ends. The
+ * guard lives AT the adapter boundary (run.ts wires
+ * truncationGuard(traceGuard(tracer, adapter))): the kernel, the log,
+ * and the model-visible byte stream are untouched (I6 — pinned by
+ * trace-bytes.test.ts). retryAttempt counts prior calls in this run
+ * with an identical contextHash — the loop re-streams the SAME messages
+ * array on retry (loop.ts), so an identical hash is exactly "same
+ * request, retried" (§1.4).
+ *
+ * Soft-fail: any failure in trace assembly (never expected — hashes and
+ * the manifest cannot throw today) marks the request ABSENT rather than
+ * breaking the stream; the writer's own degradation covers I/O.
+ *
+ * Usage is provider-raw, never normalized (E2's job): openai-compat
+ * reports input TOTAL (fresh = input − cacheRead); anthropic's
+ * input_tokens is ALREADY fresh-only (the trace records it as-is).
+ * A request that settles with NO usage data records the quartet as
+ * zeros with cacheWrite null — "0 = unknown", documented at record.ts;
+ * the honest nullable quartet is a schema bump, deferred.
+ */
+import type { Adapter, AdapterEvent, Event, StreamOptions } from "@vincemakes/kiso-core";
+export interface RequestTracerDeps {
+    root: string;
+    sessionId: string;
+    runId: string;
+    provider: string;
+    model: string;
+    /** The adapter contract's implementation version (the runtime's own),
+     *  resolved once at tracer init; null on failure (soft-fail). */
+    adapterVersion?: string | null;
+    /** The session log — the manifest's seqRange pointers derive from it. */
+    log: readonly Event[];
+}
+export declare class RequestTracer {
+    #private;
+    constructor(deps: RequestTracerDeps);
+    init(): void;
+    wrap(options: StreamOptions, upstream: AsyncIterable<AdapterEvent>): AsyncIterable<AdapterEvent>;
+    /** Clean-settle marking for the whole run. */
+    finishRun(): void;
+}
+/** Wrap the adapter so every stream() call settles a trace record. */
+export declare function traceGuard(tracer: RequestTracer, adapter: Adapter): Adapter;

package/dist/trace/guard.js

@@ -0,0 +1,185 @@
+/**
+ * E1 (1.2.0) — slice 3, the request tracer (the guard).
+ *
+ * One TraceRecord per adapter call, settled when the stream ends. The
+ * guard lives AT the adapter boundary (run.ts wires
+ * truncationGuard(traceGuard(tracer, adapter))): the kernel, the log,
+ * and the model-visible byte stream are untouched (I6 — pinned by
+ * trace-bytes.test.ts). retryAttempt counts prior calls in this run
+ * with an identical contextHash — the loop re-streams the SAME messages
+ * array on retry (loop.ts), so an identical hash is exactly "same
+ * request, retried" (§1.4).
+ *
+ * Soft-fail: any failure in trace assembly (never expected — hashes and
+ * the manifest cannot throw today) marks the request ABSENT rather than
+ * breaking the stream; the writer's own degradation covers I/O.
+ *
+ * Usage is provider-raw, never normalized (E2's job): openai-compat
+ * reports input TOTAL (fresh = input − cacheRead); anthropic's
+ * input_tokens is ALREADY fresh-only (the trace records it as-is).
+ * A request that settles with NO usage data records the quartet as
+ * zeros with cacheWrite null — "0 = unknown", documented at record.ts;
+ * the honest nullable quartet is a schema bump, deferred.
+ */
+import { randomUUID } from "node:crypto";
+import { buildContextManifest, segmentHashes } from "./manifest.js";
+import { cacheableHashes } from "./analyze.js";
+import { hashContext, hashSystemPrompt, hashToolSpecs, stablePrefixFingerprint } from "./hash.js";
+import { TRACE_SCHEMA_VERSION } from "./record.js";
+import { TraceWriter } from "./writer.js";
+export class RequestTracer {
+    #writer;
+    #log;
+    #provider;
+    #runId;
+    #adapterVersion;
+    #requestIndex = 0;
+    #contextHashCounts = new Map();
+    constructor(deps) {
+        this.#writer = new TraceWriter({ root: deps.root, sessionId: deps.sessionId });
+        this.#log = deps.log;
+        this.#provider = deps.provider;
+        this.#runId = deps.runId;
+        this.#adapterVersion = deps.adapterVersion ?? null;
+    }
+    init() {
+        this.#writer.init();
+    }
+    async *wrap(options, upstream) {
+        const t0 = performance.now();
+        let record = null;
+        try {
+            record = this.#startRecord(options);
+        }
+        catch {
+            record = null; // trace absent; the stream is never affected
+        }
+        // null until the first event; settled to 0 (unknown) only when no
+        // event ever came — a stream whose first event lands in the same
+        // tick records 0, the resolution limit of the "0 = unknown" marker
+        let ttftMs = null;
+        let inputTokens = null;
+        let cacheRead = null;
+        let cacheWrite = null;
+        let outputTokens = null;
+        let usageKnown = false;
+        const toolCalls = [];
+        let outcome = "ok";
+        try {
+            for await (const ev of upstream) {
+                // the null check must be the ONLY guard — a 0-initialized
+                // number never moves (the slice-3 dead-field finding)
+                if (ttftMs === null)
+                    ttftMs = performance.now() - t0;
+                if (ev.type === "tool_call_start")
+                    toolCalls.push(ev.name);
+                if (ev.type === "usage") {
+                    usageKnown = usageKnown || ev.known;
+                    if (ev.inputTokens !== null)
+                        inputTokens = ev.inputTokens;
+                    if (ev.cacheRead !== null)
+                        cacheRead = ev.cacheRead;
+                    if (ev.cacheWrite !== null)
+                        cacheWrite = ev.cacheWrite;
+                    if (ev.outputTokens !== null)
+                        outputTokens = ev.outputTokens;
+                }
+                yield ev;
+            }
+        }
+        catch (err) {
+            outcome = this.#classifyOutcome(err, options);
+            throw err;
+        }
+        finally {
+            if (record !== null) {
+                this.#settle(record, {
+                    outcome,
+                    t0,
+                    ttftMs,
+                    toolCalls,
+                    inputTokens,
+                    cacheRead,
+                    cacheWrite,
+                    outputTokens,
+                    usageKnown,
+                });
+            }
+        }
+    }
+    /** Clean-settle marking for the whole run. */
+    finishRun() {
+        this.#writer.finishRun(this.#runId, this.#requestIndex - 1);
+    }
+    #startRecord(options) {
+        const { systemPrompt, tools, messages } = options;
+        const contextHash = hashContext(systemPrompt, tools, messages);
+        const retryAttempt = this.#contextHashCounts.get(contextHash) ?? 0;
+        this.#contextHashCounts.set(contextHash, retryAttempt + 1);
+        const manifest = buildContextManifest({ log: this.#log, systemPrompt, tools, messages });
+        const hashes = segmentHashes(systemPrompt, tools, messages);
+        return {
+            schemaVersion: TRACE_SCHEMA_VERSION,
+            kind: "request",
+            requestId: randomUUID(),
+            runId: this.#runId,
+            requestIndex: this.#requestIndex++,
+            retryAttempt,
+            provider: this.#provider,
+            model: options.model,
+            adapterVersion: this.#adapterVersion,
+            systemPromptHash: hashSystemPrompt(systemPrompt),
+            toolSchemaHash: hashToolSpecs(tools),
+            contextHash,
+            contextManifest: manifest,
+            // R4b: the per-segment hash LIST rides the record (the break
+            // derivation is analysis-side but needs the list, not the
+            // aggregated fingerprint — slice 5's data source); the
+            // fingerprint covers the CACHEABLE prefix only — the current
+            // turn (freshness fresh) is never part of it (slice 4)
+            segmentHashes: hashes,
+            stablePrefixFingerprint: stablePrefixFingerprint(cacheableHashes(manifest, hashes)),
+            freshInput: 0, // unknown until the usage event — "0 = unknown"
+            cacheRead: 0,
+            cacheWrite: null,
+            output: 0,
+            latencyMs: 0,
+            ttftMs: 0,
+            toolCalls: [],
+            outcome: "ok",
+            ts: Date.now(),
+        };
+    }
+    #settle(record, p) {
+        record.outcome = p.outcome;
+        record.latencyMs = performance.now() - p.t0;
+        record.ttftMs = p.ttftMs ?? 0; // null = no event ever — the "0 = unknown" marker
+        record.toolCalls = p.toolCalls;
+        if (p.usageKnown) {
+            record.freshInput =
+                this.#provider === "anthropic"
+                    ? p.inputTokens ?? 0
+                    : p.inputTokens !== null
+                        ? Math.max(0, p.inputTokens - (p.cacheRead ?? 0))
+                        : 0;
+            record.cacheRead = p.cacheRead ?? 0;
+            record.cacheWrite = p.cacheWrite ?? null;
+            record.output = p.outputTokens ?? 0;
+        }
+        this.#writer.enqueue(record);
+    }
+    #classifyOutcome(err, options) {
+        if (options.signal?.aborted === true)
+            return "aborted";
+        const name = err instanceof Error ? err.name : "";
+        if (name === "AbortError" || name === "APIUserAbortError")
+            return "aborted";
+        return "provider_error";
+    }
+}
+/** Wrap the adapter so every stream() call settles a trace record. */
+export function traceGuard(tracer, adapter) {
+    return {
+        stream: (options) => tracer.wrap(options, adapter.stream(options)),
+    };
+}

package/dist/trace/hash.d.ts

@@ -0,0 +1,22 @@
+/**
+ * E1 (1.2.0) — the request hashes (proposal §4, ruling R4b + R1a).
+ *
+ * Every hash is pinned to the schemaVersion's HashSpec (sha-256,
+ * full hex) — `hashSpecFor(TRACE_SCHEMA_VERSION)` is checked at every
+ * call, so a version bump without a re-pin fails loudly instead of
+ * silently changing the algorithm. The canonical serialization is
+ * JSON.stringify of the request-shaped values; the byte discipline is
+ * that the same construction path (the kernel's projection) produces
+ * the same serialization, which the trace-bytes gate pins end-to-end.
+ */
+import type { Message, ToolSpec } from "@vincemakes/kiso-core";
+export declare function sha256Hex(input: string): string;
+export declare const canonicalJson: (v: unknown) => string;
+export declare function hashSystemPrompt(systemPrompt: string | undefined): string;
+export declare function hashToolSpecs(tools: readonly ToolSpec[] | undefined): string;
+/** The full request projection — the same messages array the loop hands
+ *  the adapter, so a retry re-serializes to an IDENTICAL hash (§1.4). */
+export declare function hashContext(systemPrompt: string | undefined, tools: readonly ToolSpec[] | undefined, messages: readonly Message[]): string;
+/** sha-256 over the per-segment hashes of the cacheable prefix — the
+ *  segments up to but NOT including the current turn (R4b). */
+export declare function stablePrefixFingerprint(segmentHashes: readonly string[]): string;

package/dist/trace/hash.js

@@ -0,0 +1,34 @@
+/**
+ * E1 (1.2.0) — the request hashes (proposal §4, ruling R4b + R1a).
+ *
+ * Every hash is pinned to the schemaVersion's HashSpec (sha-256,
+ * full hex) — `hashSpecFor(TRACE_SCHEMA_VERSION)` is checked at every
+ * call, so a version bump without a re-pin fails loudly instead of
+ * silently changing the algorithm. The canonical serialization is
+ * JSON.stringify of the request-shaped values; the byte discipline is
+ * that the same construction path (the kernel's projection) produces
+ * the same serialization, which the trace-bytes gate pins end-to-end.
+ */
+import { createHash } from "node:crypto";
+import { TRACE_SCHEMA_VERSION, hashSpecFor } from "./record.js";
+export function sha256Hex(input) {
+    hashSpecFor(TRACE_SCHEMA_VERSION); // the pinned algorithm, or fail loudly
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+export const canonicalJson = (v) => JSON.stringify(v);
+export function hashSystemPrompt(systemPrompt) {
+    return sha256Hex(systemPrompt ?? "");
+}
+export function hashToolSpecs(tools) {
+    return sha256Hex(canonicalJson(tools ?? []));
+}
+/** The full request projection — the same messages array the loop hands
+ *  the adapter, so a retry re-serializes to an IDENTICAL hash (§1.4). */
+export function hashContext(systemPrompt, tools, messages) {
+    return sha256Hex(canonicalJson({ systemPrompt, tools, messages }));
+}
+/** sha-256 over the per-segment hashes of the cacheable prefix — the
+ *  segments up to but NOT including the current turn (R4b). */
+export function stablePrefixFingerprint(segmentHashes) {
+    return sha256Hex(segmentHashes.join(""));
+}

package/dist/trace/manifest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * E1 (1.2.0) — slice 3, the context manifest (proposal §1.3).
+ *
+ * buildContextManifest derives the per-request segment list from the
+ * session log and the request projection. Segments are the system
+ * prompt, the tool schema, then one per user turn. Each turn carries a
+ * THIN seqRange pointer into the event log ([firstSeq, lastSeq] of the
+ * events that produced it) plus an estTokens estimate — the record
+ * never copies payloads (proposal §1.1).
+ *
+ * Turn boundaries are the log's visible user_input events: a VETOED
+ * input (user_input_replaced with null content) is not a boundary — the
+ * model never saw it; a REWRITE keeps the original boundary position
+ * (the projection renders the replacement in place, events.ts:339).
+ * The last turn is current_turn/fresh, earlier turns cache_read; the
+ * system/tools head is cache_read (a stable prefix, R4b).
+ *
+ * When the projection's user-message count and the log's visible
+ * boundary count diverge (a summary replaced whole turns, an alignment
+ * surprise), every turn range degrades to null — honest thin pointers
+ * rather than wrong ones.
+ */
+import type { Event, Message, ToolSpec } from "@vincemakes/kiso-core";
+import type { TraceSegment } from "./record.js";
+export interface ManifestInput {
+    log: readonly Event[];
+    systemPrompt: string | undefined;
+    tools: readonly ToolSpec[] | undefined;
+    messages: readonly Message[];
+}
+export declare function buildContextManifest(input: ManifestInput): TraceSegment[];
+/** Per-segment content hashes for the fingerprint (R4b): the system
+ *  prompt, the tool schema, and each turn's messages, in manifest
+ *  order. The CURRENT turn's hash is the last element — the cacheable
+ *  prefix is everything before it. */
+export declare function segmentHashes(systemPrompt: string | undefined, tools: readonly ToolSpec[] | undefined, messages: readonly Message[]): string[];

package/dist/trace/manifest.js

@@ -0,0 +1,100 @@
+/**
+ * E1 (1.2.0) — slice 3, the context manifest (proposal §1.3).
+ *
+ * buildContextManifest derives the per-request segment list from the
+ * session log and the request projection. Segments are the system
+ * prompt, the tool schema, then one per user turn. Each turn carries a
+ * THIN seqRange pointer into the event log ([firstSeq, lastSeq] of the
+ * events that produced it) plus an estTokens estimate — the record
+ * never copies payloads (proposal §1.1).
+ *
+ * Turn boundaries are the log's visible user_input events: a VETOED
+ * input (user_input_replaced with null content) is not a boundary — the
+ * model never saw it; a REWRITE keeps the original boundary position
+ * (the projection renders the replacement in place, events.ts:339).
+ * The last turn is current_turn/fresh, earlier turns cache_read; the
+ * system/tools head is cache_read (a stable prefix, R4b).
+ *
+ * When the projection's user-message count and the log's visible
+ * boundary count diverge (a summary replaced whole turns, an alignment
+ * surprise), every turn range degrades to null — honest thin pointers
+ * rather than wrong ones.
+ */
+import { estimateTokens } from "@vincemakes/kiso-core";
+import { canonicalJson, hashSystemPrompt, hashToolSpecs, sha256Hex } from "./hash.js";
+/** The log's visible user boundaries, in log order: every user_input
+ *  whose replacement (if any) is not a veto. */
+function visibleBoundaries(log) {
+    const vetoed = new Set();
+    for (const ev of log) {
+        if (ev.type === "user_input_replaced" && ev.content === null)
+            vetoed.add(ev.replaces);
+    }
+    const result = [];
+    for (const ev of log) {
+        if (ev.type === "user_input" && !vetoed.has(ev.seq))
+            result.push(ev.seq);
+    }
+    return result;
+}
+const systemSegment = (systemPrompt) => ({
+    role: "system",
+    seqRange: null,
+    estTokens: estimateTokens([{ role: "user", content: systemPrompt ?? "" }]),
+    freshness: "cache_read",
+});
+const toolsSegment = (tools) => ({
+    role: "tools",
+    seqRange: null,
+    estTokens: estimateTokens([{ role: "tool", callId: "", content: JSON.stringify(tools ?? []), isError: false }]),
+    freshness: "cache_read",
+});
+export function buildContextManifest(input) {
+    const { log, systemPrompt, tools, messages } = input;
+    const boundaries = visibleBoundaries(log);
+    const userCount = messages.filter((m) => m.role === "user").length;
+    const aligned = userCount === boundaries.length;
+    const lastSeq = log.length > 0 ? log[log.length - 1].seq : -1;
+    const segments = [systemSegment(systemPrompt), toolsSegment(tools)];
+    // Partition the projection at user boundaries: partition k runs from
+    // user_k (inclusive) to user_{k+1} (exclusive); messages before the
+    // first user (not produced by the projection today) join partition 0.
+    const userPositions = [];
+    messages.forEach((m, i) => {
+        if (m.role === "user")
+            userPositions.push(i);
+    });
+    for (let k = 0; k < userPositions.length; k++) {
+        const start = k === 0 ? 0 : userPositions[k];
+        const end = k + 1 < userPositions.length ? userPositions[k + 1] : messages.length;
+        const isCurrent = k === userPositions.length - 1;
+        const range = aligned && boundaries[k] !== undefined
+            ? [boundaries[k], k + 1 < boundaries.length ? boundaries[k + 1] - 1 : lastSeq]
+            : null;
+        segments.push({
+            role: isCurrent ? "current_turn" : "turn",
+            seqRange: range,
+            estTokens: estimateTokens(messages.slice(start, end)),
+            freshness: isCurrent ? "fresh" : "cache_read",
+        });
+    }
+    return segments;
+}
+/** Per-segment content hashes for the fingerprint (R4b): the system
+ *  prompt, the tool schema, and each turn's messages, in manifest
+ *  order. The CURRENT turn's hash is the last element — the cacheable
+ *  prefix is everything before it. */
+export function segmentHashes(systemPrompt, tools, messages) {
+    const hashes = [hashSystemPrompt(systemPrompt), hashToolSpecs(tools)];
+    const userPositions = [];
+    messages.forEach((m, i) => {
+        if (m.role === "user")
+            userPositions.push(i);
+    });
+    for (let k = 0; k < userPositions.length; k++) {
+        const start = k === 0 ? 0 : userPositions[k];
+        const end = k + 1 < userPositions.length ? userPositions[k + 1] : messages.length;
+        hashes.push(sha256Hex(canonicalJson(messages.slice(start, end))));
+    }
+    return hashes;
+}

package/dist/trace/record.d.ts

@@ -0,0 +1,107 @@
+/**
+ * E1 (1.2.0) — the Request Trace record schema (proposal §1.1 as adopted
+ * by the R1 ruling: "adopt as-is, keep ts, per-round additive"). This is
+ * the 1.2.0 field-set lock: every field below is spec'd, and the
+ * closed-field-set gate (ruling R1a) pins the shape bidirectionally —
+ * `TRACE_RECORD_FIELDS`/`TRACE_SEGMENT_FIELDS` must stay in exact
+ * agreement with the interfaces, or trace-schema.test.ts goes red.
+ *
+ * R1a: `schemaVersion` pins BOTH the record shape AND the hash /
+ * fingerprint algorithms (`HASH_SPEC_BY_VERSION`). A version bump must
+ * pin a spec for the new version before any writer can use it
+ * (`hashSpecFor` throws otherwise).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): versionable, never part of the
+ * correctness ABI. These types are runtime-internal (Case B of R2 — the
+ * export surface stays untouched pending the product-line countersign).
+ */
+/** schemaVersion: 1 for 1.2.0. Algorithm and shape changes bump it
+ *  (ADR-0051 §6 OUT-side versioning). */
+export declare const TRACE_SCHEMA_VERSION = 1;
+export type Freshness = "fresh" | "cache_read" | "cache_write";
+/** That is the complete set for 1.2.0. */
+export type Outcome = "ok" | "provider_error" | "aborted";
+/** That is the complete set for 1.2.0. (Truncation surfaces as "aborted"
+ *  when the stream ends before settle; refined in E5 if needed.) */
+export interface TraceSegment {
+    role: "system" | "tools" | "turn" | "current_turn";
+    /** Thin pointer into the event log: [firstSeq, lastSeq] inclusive of the
+     *  events that produced this segment. null for system/tools (not events). */
+    seqRange: [number, number] | null;
+    estTokens: number;
+    freshness: Freshness;
+}
+/** That is the complete set for 1.2.0. */
+export interface TraceRecord {
+    schemaVersion: 1;
+    kind: "request";
+    requestId: string;
+    runId: string;
+    requestIndex: number;
+    retryAttempt: number;
+    provider: string;
+    model: string;
+    adapterVersion: string | null;
+    systemPromptHash: string;
+    toolSchemaHash: string;
+    contextHash: string;
+    contextManifest: TraceSegment[];
+    /** Per-segment content hashes, indexed 1:1 with contextManifest
+     *  (segment i's canonical serialization — R4b's analysis-side data
+     *  source: the cache-break derivation needs the LIST, not the
+     *  aggregated fingerprint). Sizing note: 64 hex chars × segments
+     *  per request. */
+    segmentHashes: string[];
+    stablePrefixFingerprint: string;
+    /** The usage quartet is PROVIDER-RAW — never a billing surface.
+     *  Canonical/billing usage lives in E2; these fields are observation
+     *  only (a provider may count a token a dozen ways; billing must not). */
+    freshInput: number;
+    cacheRead: number;
+    cacheWrite: number | null;
+    output: number;
+    latencyMs: number;
+    ttftMs: number;
+    toolCalls: string[];
+    outcome: Outcome;
+    lineageLink?: {
+        parentSessionId: string;
+        parentRunId: string;
+        parentInvocationSeq: number;
+        role: string;
+    };
+    ts: number;
+}
+/** That is the complete set for 1.2.0. */
+export interface HeaderLine {
+    schemaVersion: 1;
+    kind: "header";
+    sessionId: string;
+    kisoVersion: string;
+    createdAt: number;
+}
+export interface RunEndLine {
+    schemaVersion: 1;
+    kind: "run_end";
+    runId: string;
+    ts: number;
+    lastRequestIndex: number;
+}
+export interface CrashLine {
+    schemaVersion: 1;
+    kind: "crash";
+    ts: number;
+    note: string;
+}
+export type TraceLine = HeaderLine | TraceRecord | RunEndLine | CrashLine;
+export interface HashSpec {
+    readonly algorithm: "sha-256";
+    readonly output: "full-hex";
+}
+export declare const HASH_SPEC_BY_VERSION: Readonly<Record<number, HashSpec>>;
+export declare function hashSpecFor(version: number): HashSpec;
+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"];
+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;
+export declare function validateTraceLine(v: unknown): v is TraceLine;

package/dist/trace/record.js

@@ -0,0 +1,185 @@
+/**
+ * E1 (1.2.0) — the Request Trace record schema (proposal §1.1 as adopted
+ * by the R1 ruling: "adopt as-is, keep ts, per-round additive"). This is
+ * the 1.2.0 field-set lock: every field below is spec'd, and the
+ * closed-field-set gate (ruling R1a) pins the shape bidirectionally —
+ * `TRACE_RECORD_FIELDS`/`TRACE_SEGMENT_FIELDS` must stay in exact
+ * agreement with the interfaces, or trace-schema.test.ts goes red.
+ *
+ * R1a: `schemaVersion` pins BOTH the record shape AND the hash /
+ * fingerprint algorithms (`HASH_SPEC_BY_VERSION`). A version bump must
+ * pin a spec for the new version before any writer can use it
+ * (`hashSpecFor` throws otherwise).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): versionable, never part of the
+ * correctness ABI. These types are runtime-internal (Case B of R2 — the
+ * export surface stays untouched pending the product-line countersign).
+ */
+/** schemaVersion: 1 for 1.2.0. Algorithm and shape changes bump it
+ *  (ADR-0051 §6 OUT-side versioning). */
+export const TRACE_SCHEMA_VERSION = 1;
+export const HASH_SPEC_BY_VERSION = {
+    1: { algorithm: "sha-256", output: "full-hex" },
+};
+export function hashSpecFor(version) {
+    const spec = HASH_SPEC_BY_VERSION[version];
+    if (spec === undefined)
+        throw new Error(`no hash spec pinned for trace schemaVersion ${version}`);
+    return spec;
+}
+// ── The closed-field-set gate (R1a) ───────────────────────────────────────
+// Trace-schema.test.ts asserts Object.keys of a fully populated record is
+// EXACTLY this set (both directions).
+export const TRACE_RECORD_FIELDS = [
+    "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",
+];
+export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
+// ── Validators ────────────────────────────────────────────────────────────
+// Strict by design: extra keys are rejected (the closed set), so a
+// misspelled field can never silently enter the ledger.
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keysOf = (v) => (isRecord(v) ? Object.keys(v) : []);
+const isNonNegInt = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isHex64 = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+/** The closed set, both directions: no key outside the spec, and every
+ *  spec'd key present except the explicit optional ones. */
+const hasClosedKeys = (v, spec, optional = []) => {
+    const keys = keysOf(v);
+    if (keys.some((k) => !spec.includes(k)))
+        return false;
+    const optionalSet = new Set(optional);
+    return spec.every((k) => optionalSet.has(k) || keys.includes(k));
+};
+const VALID_SEGMENT_ROLES = new Set(["system", "tools", "turn", "current_turn"]);
+const VALID_FRESHNESS = new Set(["fresh", "cache_read", "cache_write"]);
+const VALID_OUTCOMES = new Set(["ok", "provider_error", "aborted"]);
+function isValidSeqRange(v) {
+    if (v === null)
+        return true;
+    if (!Array.isArray(v) || v.length !== 2)
+        return false;
+    const [a, b] = v;
+    return isNonNegInt(a) && isNonNegInt(b) && a <= b;
+}
+export function validateTraceSegment(v) {
+    if (!isRecord(v) || !hasClosedKeys(v, TRACE_SEGMENT_FIELDS))
+        return false;
+    if (typeof v.role !== "string" || !VALID_SEGMENT_ROLES.has(v.role))
+        return false;
+    if (!isValidSeqRange(v.seqRange))
+        return false;
+    if (!isNonNegInt(v.estTokens))
+        return false;
+    if (!VALID_FRESHNESS.has(v.freshness))
+        return false;
+    return true;
+}
+export function validateTraceRecord(v) {
+    if (!isRecord(v) || !hasClosedKeys(v, TRACE_RECORD_FIELDS, ["lineageLink"]))
+        return false;
+    if (v.schemaVersion !== TRACE_SCHEMA_VERSION)
+        return false;
+    if (v.kind !== "request")
+        return false;
+    if (typeof v.requestId !== "string" || typeof v.runId !== "string")
+        return false;
+    if (!isNonNegInt(v.requestIndex) || !isNonNegInt(v.retryAttempt))
+        return false;
+    if (typeof v.provider !== "string" || typeof v.model !== "string")
+        return false;
+    if (v.adapterVersion !== null && typeof v.adapterVersion !== "string")
+        return false;
+    if (!isHex64(v.systemPromptHash) || !isHex64(v.toolSchemaHash) || !isHex64(v.contextHash))
+        return false;
+    if (!isHex64(v.stablePrefixFingerprint))
+        return false;
+    if (!Array.isArray(v.contextManifest) || !v.contextManifest.every(validateTraceSegment))
+        return false;
+    // segmentHashes must mirror the manifest 1:1 — a misaligned list
+    // would silently corrupt the break derivation (R4b)
+    if (!Array.isArray(v.segmentHashes) ||
+        v.segmentHashes.length !== v.contextManifest.length ||
+        !v.segmentHashes.every(isHex64))
+        return false;
+    if (!isNumber(v.freshInput) || !isNumber(v.cacheRead))
+        return false;
+    if (v.cacheWrite !== null && !isNumber(v.cacheWrite))
+        return false;
+    if (!isNumber(v.output) || !isNumber(v.latencyMs))
+        return false;
+    if (!isNumber(v.ttftMs))
+        return false; // 0 = unknown, never null (locked set)
+    if (!Array.isArray(v.toolCalls) || !v.toolCalls.every((t) => typeof t === "string"))
+        return false;
+    if (typeof v.outcome !== "string" || !VALID_OUTCOMES.has(v.outcome))
+        return false;
+    if (v.lineageLink !== undefined) {
+        const l = v.lineageLink;
+        if (!isRecord(l))
+            return false;
+        if (typeof l.parentSessionId !== "string" || typeof l.parentRunId !== "string")
+            return false;
+        if (!isNonNegInt(l.parentInvocationSeq))
+            return false;
+        if (typeof l.role !== "string")
+            return false;
+    }
+    if (!isNumber(v.ts))
+        return false;
+    return true;
+}
+export function validateTraceLine(v) {
+    if (!isRecord(v))
+        return false;
+    if (v.schemaVersion !== TRACE_SCHEMA_VERSION)
+        return false;
+    switch (v.kind) {
+        case "header":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "sessionId", "kisoVersion", "createdAt"]) &&
+                typeof v.sessionId === "string" &&
+                typeof v.kisoVersion === "string" &&
+                isNumber(v.createdAt));
+        case "request":
+            return validateTraceRecord(v);
+        case "run_end":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "runId", "ts", "lastRequestIndex"]) &&
+                typeof v.runId === "string" &&
+                isNumber(v.ts) &&
+                // -1 = the run made no adapter calls (an empty run still
+                // settles cleanly); anything below that is not a request index
+                typeof v.lastRequestIndex === "number" &&
+                Number.isInteger(v.lastRequestIndex) &&
+                v.lastRequestIndex >= -1);
+        case "crash":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "ts", "note"]) &&
+                isNumber(v.ts) &&
+                typeof v.note === "string");
+        default:
+            return false;
+    }
+}

package/dist/trace/writer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { type TraceLine } from "./record.js";
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export declare function runtimeVersion(): string | null;
+export interface TraceWriterDeps {
+    /** The sessions dir (store.root). The ledger lives in <root>/traces/ —
+     *  NOT flat in root: a flat `<sid>.trace.jsonl` would be enumerated as
+     *  a phantom session by SessionStore.list() and corrupt the bench
+     *  sessions glob (proposal §3.2; the R3a gate pins it). */
+    root: string;
+    sessionId: string;
+}
+export declare class TraceWriter {
+    #private;
+    constructor(deps: TraceWriterDeps);
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init(): void;
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line: TraceLine): void;
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId: string, lastRequestIndex: number): void;
+}

package/dist/trace/writer.js

@@ -0,0 +1,154 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TRACE_SCHEMA_VERSION } from "./record.js";
+let cachedRuntimeVersion;
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export function runtimeVersion() {
+    if (cachedRuntimeVersion === undefined) {
+        cachedRuntimeVersion = (() => {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"));
+                return pkg.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return cachedRuntimeVersion;
+}
+export class TraceWriter {
+    #root;
+    #sessionId;
+    #path;
+    #pending = [];
+    #flushScheduled = false;
+    #degraded = false;
+    constructor(deps) {
+        this.#root = deps.root;
+        this.#sessionId = deps.sessionId;
+        this.#path = join(deps.root, "traces", `${deps.sessionId}.jsonl`);
+    }
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init() {
+        if (this.#degraded)
+            return;
+        try {
+            mkdirSync(join(this.#root, "traces"), { recursive: true });
+            const fresh = !existsSync(this.#path);
+            if (this.#crashDetect()) {
+                this.#writeSync([
+                    { schemaVersion: TRACE_SCHEMA_VERSION, kind: "crash", ts: Date.now(), note: "previous run left no run_end" },
+                ]);
+            }
+            if (fresh) {
+                this.#writeSync([
+                    {
+                        schemaVersion: TRACE_SCHEMA_VERSION,
+                        kind: "header",
+                        sessionId: this.#sessionId,
+                        kisoVersion: runtimeVersion() ?? "?",
+                        createdAt: Date.now(),
+                    },
+                ]);
+            }
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line) {
+        if (this.#degraded)
+            return;
+        this.#pending.push(line);
+        if (!this.#flushScheduled) {
+            this.#flushScheduled = true;
+            setImmediate(() => {
+                this.#flushScheduled = false;
+                this.#flushSync();
+            });
+        }
+    }
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId, lastRequestIndex) {
+        this.enqueue({
+            schemaVersion: TRACE_SCHEMA_VERSION,
+            kind: "run_end",
+            runId,
+            ts: Date.now(),
+            lastRequestIndex,
+        });
+        this.#flushSync();
+    }
+    /** True when the ledger already exists and its LAST line is neither
+     *  run_end nor crash — an un-terminated run (killed mid-run), to be
+     *  marked. A crash-marked ledger is not re-marked. */
+    #crashDetect() {
+        if (!existsSync(this.#path))
+            return false;
+        let last;
+        try {
+            for (const line of readFileSync(this.#path, "utf8").split("\n")) {
+                if (line.trim() === "")
+                    continue;
+                last = JSON.parse(line);
+            }
+        }
+        catch {
+            return false; // unreadable ledger — do not compound the failure
+        }
+        if (last === undefined)
+            return false;
+        return last.kind !== "run_end" && last.kind !== "crash";
+    }
+    #writeSync(lines) {
+        if (lines.length === 0)
+            return;
+        try {
+            appendFileSync(this.#path, `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`);
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    #flushSync() {
+        if (this.#pending.length === 0)
+            return;
+        const lines = this.#pending;
+        this.#pending = [];
+        this.#writeSync(lines);
+    }
+    /** The soft-fail law: one stderr line, then the ledger is dropped and
+     *  the session runs on. Idempotent. */
+    #degrade(err) {
+        if (this.#degraded)
+            return;
+        this.#degraded = true;
+        this.#pending = [];
+        console.error(`[kiso] trace writer degraded (${err instanceof Error ? err.message : String(err)}); request traces dropped`);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "1.1.0",
-  "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
+  "version": "1.2.0",
+  "description": "kiso runtime \u2014 durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",
   "exports": {