@vincemakes/kiso-runtime 0.40.6 → 0.40.7

package/dist/trace/guard.d.ts

@@ -23,6 +23,17 @@
  */
 import type { Adapter, AdapterEvent, Event, StreamOptions } from "@vincemakes/kiso-core";
 import { type RentParts } from "./rent.js";
+import { type ProviderErrorNote } from "./record.js";
+/** SMK0400-F1: what a provider error is allowed to leave in the ledger — a
+ *  message capped, and with anything credential-shaped removed first: an
+ *  `sk-`/`Bearer` token, an `api_key=`/`token:` value, and any unbroken run
+ *  of 32+ key characters (a provider that echoes a masked or whole key
+ *  back in its refusal must not get it written to disk). */
+export declare function redactProviderMessage(message: string): string;
+/** SMK0400-F1: the note a `provider_error` record carries. The adapters
+ *  throw the structured error (code, message, status when there was one);
+ *  anything else thrown is named by its error name. */
+export declare function providerErrorNote(err: unknown): ProviderErrorNote;
 export interface RequestTracerDeps {
     root: string;
     sessionId: string;

package/dist/trace/guard.js

@@ -27,7 +27,29 @@ import { cacheableHashes } from "./analyze.js";
 import { hashContext, hashSystemPrompt, hashToolSpecs, stablePrefixFingerprint } from "./hash.js";
 import { PRICING_TABLE_V1, canonicalizeUsageForModel } from "../usage/canonical.js";
 import { buildRentLedger } from "./rent.js";
-import { TRACE_SCHEMA_VERSION } from "./record.js";
+import { PROVIDER_ERROR_MESSAGE_MAX, TRACE_SCHEMA_VERSION } from "./record.js";
+/** SMK0400-F1: what a provider error is allowed to leave in the ledger — a
+ *  message capped, and with anything credential-shaped removed first: an
+ *  `sk-`/`Bearer` token, an `api_key=`/`token:` value, and any unbroken run
+ *  of 32+ key characters (a provider that echoes a masked or whole key
+ *  back in its refusal must not get it written to disk). */
+export function redactProviderMessage(message) {
+    return message
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 <redacted>")
+        .replace(/\b(api[_-]?key|access[_-]?token|token|secret|password|authorization)(["']?\s*[:=]\s*["']?)[^\s"',;]+/gi, "$1$2<redacted>")
+        .replace(/\bsk-[A-Za-z0-9_-]{6,}/g, "sk-<redacted>")
+        .replace(/[A-Za-z0-9_-]{32,}/g, "<redacted>")
+        .slice(0, PROVIDER_ERROR_MESSAGE_MAX);
+}
+/** SMK0400-F1: the note a `provider_error` record carries. The adapters
+ *  throw the structured error (code, message, status when there was one);
+ *  anything else thrown is named by its error name. */
+export function providerErrorNote(err) {
+    const e = (typeof err === "object" && err !== null ? err : {});
+    const code = typeof e.code === "string" && e.code !== "" ? e.code : typeof e.name === "string" && e.name !== "" ? e.name : "error";
+    const message = typeof e.message === "string" ? e.message : String(err);
+    return { code, ...(typeof e.status === "number" && Number.isInteger(e.status) ? { status: e.status } : {}), message: redactProviderMessage(message) };
+}
 import { TraceWriter } from "./writer.js";
 export class RequestTracer {
     #writer;
@@ -81,6 +103,8 @@ export class RequestTracer {
         let reasoningTokens;
         const toolCalls = [];
         let outcome = "ok";
+        // SMK0400-F1: what the provider said, when the outcome is its error
+        let providerError;
         try {
             for await (const ev of upstream) {
                 // the null check must be the ONLY guard — a 0-initialized
@@ -109,6 +133,8 @@ export class RequestTracer {
         }
         catch (err) {
             outcome = this.#classifyOutcome(err, options);
+            if (outcome === "provider_error")
+                providerError = providerErrorNote(err);
             throw err;
         }
         finally {
@@ -125,6 +151,7 @@ export class RequestTracer {
                     usageKnown,
                     servedModel,
                     reasoningTokens,
+                    providerError,
                 });
             }
         }
@@ -239,6 +266,9 @@ export class RequestTracer {
         // the agreement the reconciliation exists to test.
         if (p.servedModel !== null)
             record.servedModel = p.servedModel;
+        // SMK0400-F1: on a provider_error record only; absent otherwise
+        if (p.providerError !== undefined)
+            record.providerError = p.providerError;
         if (p.usageKnown) {
             record.freshInput =
                 this.#provider === "anthropic"

package/dist/trace/record.d.ts

@@ -68,13 +68,22 @@
  * as requested". That default is the whole defect: a field filled in with
  * the request manufactures the agreement the reconciliation exists to
  * test.
+ *
+ * SMK0400-F1 (0.40.7) — schemaVersion 7: a `provider_error` record gains
+ * `providerError` — the error's code, the HTTP status when there was one,
+ * and the provider's message (capped, and redacted of anything
+ * credential-shaped). Until now the record said only `provider_error`, so
+ * a failed request could not be named after the fact (the 0.40.0 smoke's
+ * two failures). OPTIONAL: absent on every other outcome, and on every
+ * record a v1–v6 writer produced.
  */
-/** schemaVersion: 6 for the `servedModel` statement (TRACE-F1);
+/** schemaVersion: 7 for the `providerError` statement (SMK0400-F1);
+ *  6 was 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 = 6;
+export declare const TRACE_SCHEMA_VERSION = 7;
 /** 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). */
@@ -111,7 +120,7 @@ export interface TraceSegment {
 }
 /** That is the complete set for 1.2.0. */
 export interface TraceRecord {
-    schemaVersion: 6;
+    schemaVersion: 7;
     kind: "request";
     requestId: string;
     runId: string;
@@ -178,25 +187,29 @@ export interface TraceRecord {
      *  four days. The requested id stays in `model`; these are two facts,
      *  never merged. */
     servedModel?: string;
+    /** SMK0400-F1 (v7) — on a `provider_error` record: what the provider
+     *  said. `message` is capped at PROVIDER_ERROR_MESSAGE_MAX characters and
+     *  redacted of credential-shaped strings before it is written. */
+    providerError?: ProviderErrorNote;
     ts: number;
 }
 /** That is the complete set for 1.2.0. */
 export interface HeaderLine {
-    schemaVersion: 6;
+    schemaVersion: 7;
     kind: "header";
     sessionId: string;
     kisoVersion: string;
     createdAt: number;
 }
 export interface RunEndLine {
-    schemaVersion: 6;
+    schemaVersion: 7;
     kind: "run_end";
     runId: string;
     ts: number;
     lastRequestIndex: number;
 }
 export interface CrashLine {
-    schemaVersion: 6;
+    schemaVersion: 7;
     kind: "crash";
     ts: number;
     note: string;
@@ -229,9 +242,21 @@ export declare const TRACE_RECORD_FIELDS_V5: readonly ["schemaVersion", "kind",
 /** 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"];
+export declare const TRACE_RECORD_FIELDS_V6: 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"];
+/** SMK0400-F1 (v7): what the provider said on a `provider_error` record. */
+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", "providerError"];
 /** The fields the closed-set check does not require to be present. */
-export declare const TRACE_RECORD_OPTIONAL: readonly ["purpose", "usageKnown", "servedModel"];
+export declare const TRACE_RECORD_OPTIONAL: readonly ["purpose", "usageKnown", "servedModel", "providerError"];
+/** SMK0400-F1: the shape of `providerError`. */
+export interface ProviderErrorNote {
+    /** the structured error's code (`rate_limit`, `network`, …), or the
+     *  thrown error's name when it carried none */
+    code: string;
+    /** the HTTP status, when the failure had one */
+    status?: number;
+    message: string;
+}
+export declare const PROVIDER_ERROR_MESSAGE_MAX = 300;
 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

@@ -68,13 +68,22 @@
  * as requested". That default is the whole defect: a field filled in with
  * the request manufactures the agreement the reconciliation exists to
  * test.
+ *
+ * SMK0400-F1 (0.40.7) — schemaVersion 7: a `provider_error` record gains
+ * `providerError` — the error's code, the HTTP status when there was one,
+ * and the provider's message (capped, and redacted of anything
+ * credential-shaped). Until now the record said only `provider_error`, so
+ * a failed request could not be named after the fact (the 0.40.0 smoke's
+ * two failures). OPTIONAL: absent on every other outcome, and on every
+ * record a v1–v6 writer produced.
  */
-/** schemaVersion: 6 for the `servedModel` statement (TRACE-F1);
+/** schemaVersion: 7 for the `providerError` statement (SMK0400-F1);
+ *  6 was 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 = 6;
+export const TRACE_SCHEMA_VERSION = 7;
 /** 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). */
@@ -93,7 +102,7 @@ export const TRACE_SCHEMA_VERSION = 6;
  * 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]);
+export const TRACE_SCHEMA_VERSIONS = new Set([1, 2, 3, 4, 5, 6, 7]);
 import { PRICING_TABLE_V1, priceFor, pricingTableFor, validateCanonicalUsage } from "../usage/canonical.js";
 import { validateRentLine } from "./rent.js";
 export const HASH_SPEC_BY_VERSION = {
@@ -103,6 +112,7 @@ export const HASH_SPEC_BY_VERSION = {
     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
+    7: { algorithm: "sha-256", output: "full-hex" }, // SMK0400-F1 — `providerError` is the provider'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];
@@ -160,9 +170,12 @@ 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"];
+export const TRACE_RECORD_FIELDS_V6 = [...TRACE_RECORD_FIELDS_V5, "servedModel"];
+/** SMK0400-F1 (v7): what the provider said on a `provider_error` record. */
+export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V6, "providerError"];
 /** The fields the closed-set check does not require to be present. */
-export const TRACE_RECORD_OPTIONAL = ["purpose", "usageKnown", "servedModel"];
+export const TRACE_RECORD_OPTIONAL = ["purpose", "usageKnown", "servedModel", "providerError"];
+export const PROVIDER_ERROR_MESSAGE_MAX = 300;
 export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
 // ── Validators ────────────────────────────────────────────────────────────
 // Strict by design: extra keys are rejected (the closed set), so a
@@ -232,7 +245,9 @@ export function validateTraceRecord(v) {
                     ? TRACE_RECORD_FIELDS_V4
                     : version === 5
                         ? TRACE_RECORD_FIELDS_V5
-                        : TRACE_RECORD_FIELDS;
+                        : version === 6
+                            ? TRACE_RECORD_FIELDS_V6
+                            : TRACE_RECORD_FIELDS;
     if (!hasClosedKeys(v, fields, ["lineageLink", ...TRACE_RECORD_OPTIONAL]))
         return false;
     if (v.purpose !== undefined && (typeof v.purpose !== "string" || v.purpose === ""))
@@ -248,6 +263,17 @@ export function validateTraceRecord(v) {
     // honest "the server said nothing".
     if (v.servedModel !== undefined && (typeof v.servedModel !== "string" || v.servedModel === ""))
         return false;
+    // SMK0400-F1: closed keys; a non-empty code; an integer status when
+    // stated; the message a string within the cap (the writer caps it)
+    if (v.providerError !== undefined) {
+        const e = v.providerError;
+        if (!isRecord(e) || !hasClosedKeys(e, ["code", "message", "status"], ["status"]))
+            return false;
+        if (typeof e.code !== "string" || e.code === "" || typeof e.message !== "string" || e.message.length > PROVIDER_ERROR_MESSAGE_MAX)
+            return false;
+        if (e.status !== undefined && !Number.isInteger(e.status))
+            return false;
+    }
     if (v.kind !== "request")
         return false;
     if (typeof v.requestId !== "string" || typeof v.runId !== "string")
@@ -318,7 +344,9 @@ export function validateTraceRecord(v) {
                 return false;
         }
     }
-    if (version === TRACE_SCHEMA_VERSION) {
+    // SMK0400-F1: `>= 6`, not `=== TRACE_SCHEMA_VERSION` — the bump to 7
+    // must not stop checking the rent lines of the v6 records already written
+    if (version >= 6) {
         // the rent block: every line validates (closed fields, non-empty
         // surface, non-negative integer chars, the estTokens == ceil(chars/4)
         // cross-check — R6). v1/v2 sidecars have no block (R2-1).

package/package.json

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