@vizuh/sabi 0.1.4 → 0.2.0

package/README.md

@@ -18,7 +18,9 @@ The two paths are independent:
 - The Command Code mod needs no Sabi provider key or proxy. It routes the subscription already
   available to Command Code.
 - The local proxy works with OpenCode, Hermes, Kilo, and other OpenAI-compatible clients. It uses
-  OpenRouter, Ollama, or another configured upstream.
+  OpenRouter, Ollama, or another configured upstream. In the shipped default the OpenRouter
+  upstream is **free-models-only** (`paidModelsAllowed: false`): a priced model id is refused
+  before the request leaves the process, so the proxy cannot spend on its own.
 
 For the proxy, Sabi loads only the credential names referenced by `sabi.config.json`. Existing
 environment variables win, followed by `SABI_SECRETS_FILE`, the nearest workspace `secrets/.env`,

package/mod/sabi.mjs

@@ -1,6 +1,260 @@
-// @vizuh/sabi 0.1.4 — generated by pack.mjs from packages/adapters/command-code/mod/sabi.ts.
+// @vizuh/sabi 0.2.0 — generated by pack.mjs from packages/adapters/command-code/mod/sabi.ts.
 // Source and docs: https://github.com/vizuh/sabi
 
+// packages/core/src/telemetry.ts
+var ALLOWLIST = /* @__PURE__ */ new Set([
+  "error-line",
+  "python-traceback",
+  "panic",
+  "exception",
+  "typescript-error",
+  "fail-marker",
+  "command-failed",
+  "nonzero-exit",
+  "failure-count",
+  "command-not-found",
+  "permission-denied",
+  "missing-file",
+  "soft-warning",
+  "soft-deprecated",
+  "soft-retrying",
+  "soft-timeout",
+  "tool-error",
+  "permission-denial",
+  "rate-limited",
+  "quota-exceeded",
+  "timeout",
+  "mutation",
+  "verification-receipt",
+  "summary-claim",
+  "scope-observed",
+  "constraint",
+  "prior-failure",
+  "context-boundary",
+  "observation"
+]);
+function allowlisted(value) {
+  const code = value.split(":")[0]?.trim();
+  return ALLOWLIST.has(code);
+}
+function telemetryPolicy(config) {
+  const captureSnippets = config?.captureSnippets === true;
+  const captureChars = config?.captureChars ?? 800;
+  return {
+    captureSnippets,
+    allowlisted: (value) => allowlisted(value),
+    snippet: (value) => captureSnippets ? String(value).slice(0, captureChars) : ""
+  };
+}
+function sanitizeReason(reason, policy) {
+  if (!policy.captureSnippets) {
+    if (!reason || allowlisted(reason)) return reason;
+    const segments = reason.split(":").map((segment) => segment.trim());
+    const last = segments[segments.length - 1] ?? "";
+    if (allowlisted(last)) return reason;
+    return "reason withheld (telemetry.allowlistOnly)";
+  }
+  return policy.snippet(reason);
+}
+var KEYWORD_REDACT = /\b(bearer|authorization|api[-_]?\s*key|token|secret|password|passwd)\b["']?\s*[:=\s]\s*["']?[^\s"'{},\]]+/gi;
+var BARE_TOKEN_REDACT = [
+  [/\bsk-[A-Za-z0-9_-]{8,}\b/g, "sk-[REDACTED]"],
+  [/\bAKIA[0-9A-Z]{16}\b/g, "AKIA[REDACTED]"],
+  [/\bAIza[0-9A-Za-z_-]{30,}\b/g, "AIza[REDACTED]"],
+  [/\bghp_[A-Za-z0-9]{8,}\b/g, "ghp_[REDACTED]"],
+  [/\bghu_[A-Za-z0-9]{8,}\b/g, "ghu_[REDACTED]"],
+  [/\bghs_[A-Za-z0-9]{8,}\b/g, "ghs_[REDACTED]"],
+  [/\bgithub_pat_[A-Za-z0-9_]{8,}\b/g, "github_pat_[REDACTED]"]
+];
+var CREDENTIAL_URL_REDACT = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^:@\s/]+:[^@\s/]+@/g;
+function sanitizeError(error) {
+  const first = String(error ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+  if (!first.trim()) return "unknown error";
+  let redacted = first.replace(KEYWORD_REDACT, "$1=REDACTED");
+  for (const [pattern, replacement] of BARE_TOKEN_REDACT) redacted = redacted.replace(pattern, replacement);
+  redacted = redacted.replace(CREDENTIAL_URL_REDACT, "$1REDACTED@");
+  if (looksLikeCanary(redacted)) return "upstream error redacted (possible secret)";
+  return redacted || "unknown error";
+}
+var CANARY_PATTERNS = [
+  /\b(BEGIN|END)\s+(RSA|OPENSSH|EC|DSA)\s+PRIVATE\s+KEY/i,
+  /\bsk-[A-Za-z0-9_-]{8,}\b/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bAIza[0-9A-Za-z_-]{30,}\b/,
+  /\bghp_[A-Za-z0-9]{8,}\b/,
+  /\bghu_[A-Za-z0-9]{8,}\b/,
+  /\bghs_[A-Za-z0-9]{8,}\b/,
+  /\bgithub_pat_[A-Za-z0-9_]{8,}\b/,
+  /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^:@\s/]+:[^@\s/]+@/,
+  /(?:password|passwd|pwd|secret)\s*[:=]\s*\S+/i
+];
+function looksLikeCanary(text) {
+  return CANARY_PATTERNS.some((re) => re.test(text));
+}
+
+// packages/core/src/evidence.ts
+var MAX_EVIDENCE_ITEMS = 16;
+var MAX_EVIDENCE_DETAIL_CHARS = 240;
+var MAX_SCOPE_ITEMS = 32;
+var MAX_SCOPE_LABEL_CHARS = 120;
+var MAX_RECEIPT_ID_CHARS = 128;
+var EVIDENCE_CODES = /* @__PURE__ */ new Set([
+  "error-line",
+  "python-traceback",
+  "panic",
+  "exception",
+  "typescript-error",
+  "fail-marker",
+  "command-failed",
+  "nonzero-exit",
+  "failure-count",
+  "command-not-found",
+  "permission-denied",
+  "missing-file",
+  "soft-warning",
+  "soft-deprecated",
+  "soft-retrying",
+  "soft-timeout",
+  "tool-error",
+  "permission-denial",
+  "rate-limited",
+  "quota-exceeded",
+  "timeout",
+  "mutation",
+  "verification-receipt",
+  "summary-claim",
+  "scope-observed",
+  "constraint",
+  "prior-failure",
+  "context-boundary",
+  "observation"
+]);
+var EVIDENCE_SOURCES = /* @__PURE__ */ new Set(["tool", "user", "harness", "judge", "summary"]);
+var EVIDENCE_STATUSES = /* @__PURE__ */ new Set(["observed", "verified", "unverified", "contradicted"]);
+function boundedText(value, maxChars) {
+  if (typeof value !== "string") return void 0;
+  const text = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+  if (!text || looksLikeCanary(text)) return void 0;
+  return text.slice(0, maxChars);
+}
+function generationOf(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function isEvidenceCode(value) {
+  return typeof value === "string" && EVIDENCE_CODES.has(value);
+}
+function isEvidenceSource(value) {
+  return typeof value === "string" && EVIDENCE_SOURCES.has(value);
+}
+function isEvidenceStatus(value) {
+  return typeof value === "string" && EVIDENCE_STATUSES.has(value);
+}
+function normalizeTrajectoryEvidence(value, fallbackGeneration = 0) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const item = value;
+  if (!isEvidenceCode(item.code) || !isEvidenceSource(item.source) || !isEvidenceStatus(item.status)) return void 0;
+  const detail = boundedText(item.detail, MAX_EVIDENCE_DETAIL_CHARS);
+  return {
+    code: item.code,
+    source: item.source,
+    status: item.status,
+    contextGeneration: generationOf(item.contextGeneration ?? fallbackGeneration),
+    ...detail ? { detail } : {}
+  };
+}
+function boundTrajectoryEvidence(values, maxItems = MAX_EVIDENCE_ITEMS) {
+  const result2 = [];
+  if (maxItems <= 0) return result2;
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values ?? []) {
+    const item = normalizeTrajectoryEvidence(value);
+    if (!item) continue;
+    const key = JSON.stringify(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result2.push(item);
+    if (result2.length >= Math.max(0, Math.min(maxItems, MAX_EVIDENCE_ITEMS))) break;
+  }
+  return result2;
+}
+function countScope(value) {
+  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0 ? { count: value } : {};
+  if (!Array.isArray(value)) return {};
+  const labels = [...new Set(value.map((item) => boundedText(item, MAX_SCOPE_LABEL_CHARS)).filter((item) => Boolean(item)))].slice(0, MAX_SCOPE_ITEMS);
+  return { count: labels.length, labels };
+}
+function buildScopeCoverage(input = {}) {
+  const expected = countScope(input.expected);
+  const observed = countScope(input.observed);
+  const explicit = input.source === "explicit" || input.expected !== void 0;
+  const source = input.source ?? (explicit ? "explicit" : input.observed !== void 0 ? "inferred" : "unknown");
+  const expectedCount = expected.count;
+  const observedCount = observed.count;
+  const ratio = expectedCount !== void 0 && expectedCount > 0 && observedCount !== void 0 ? Math.min(1, observedCount / expectedCount) : void 0;
+  const missing = input.missing ? [...new Set(input.missing.map((item) => boundedText(item, MAX_SCOPE_LABEL_CHARS)).filter((item) => Boolean(item)))].slice(0, MAX_SCOPE_ITEMS) : expected.labels && observed.labels ? expected.labels.filter((item) => !observed.labels.includes(item)).slice(0, MAX_SCOPE_ITEMS) : void 0;
+  return {
+    ...expectedCount !== void 0 ? { expected: expectedCount } : {},
+    ...observedCount !== void 0 ? { observed: observedCount } : {},
+    ...ratio !== void 0 ? { ratio } : {},
+    source,
+    ...missing && missing.length > 0 ? { missing } : {}
+  };
+}
+function validReceipt(value, generation) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const item = value;
+  const id = boundedText(item.id, MAX_RECEIPT_ID_CHARS);
+  const status = item.status === "passed" || item.status === "failed" ? item.status : void 0;
+  const source = item.source === "tool" || item.source === "user" || item.source === "harness" ? item.source : void 0;
+  const receiptGeneration = generationOf(item.generation);
+  if (!id || !status || !source || item.valid === false || receiptGeneration !== generation) return void 0;
+  return { id, status, source, generation: receiptGeneration, ...item.valid === true ? { valid: true } : {} };
+}
+function deriveVerificationState(input = {}) {
+  const generation = generationOf(input.generation);
+  const receiptCandidate = input.receipt;
+  if (receiptCandidate !== void 0) {
+    const receipt = validReceipt(receiptCandidate, generation);
+    if (receipt) return { status: receipt.status, receiptId: receipt.id, generation };
+    return { status: "unknown", reason: "invalid-receipt", generation };
+  }
+  if (input.summaryClaim) return { status: "unknown", reason: "summary-without-receipt", generation };
+  if (input.mutation) return { status: "needed", reason: "mutation-without-receipt", generation };
+  if (input.verificationAttempted) return { status: "attempted", reason: "missing-receipt", generation };
+  return { status: "not-required", generation };
+}
+function evidenceForTrajectory(state, options = {}) {
+  const generation = generationOf(state.contextGeneration);
+  const evidence = [];
+  if (state.roundKind === "implementation") evidence.push({ code: "mutation", source: "tool", status: "observed", contextGeneration: generation });
+  for (const code of state.failureEvidence) {
+    if (isEvidenceCode(code)) evidence.push({ code, source: "tool", status: "observed", contextGeneration: generation });
+  }
+  if (options.verificationReceipt) evidence.push({ code: "verification-receipt", source: "harness", status: "verified", contextGeneration: generation });
+  if (options.summaryClaim) evidence.push({ code: "summary-claim", source: "summary", status: "unverified", contextGeneration: generation });
+  if (generation > 0) evidence.push({ code: "context-boundary", source: "harness", status: "observed", contextGeneration: generation });
+  return boundTrajectoryEvidence(evidence);
+}
+function decorateTrajectoryState(state, metadata = {}) {
+  const generation = generationOf(metadata.generation ?? state.contextGeneration);
+  const receipt = metadata.verificationReceipt;
+  const verification = deriveVerificationState({
+    mutation: state.roundKind === "implementation",
+    verificationAttempted: state.roundKind === "verification",
+    summaryClaim: metadata.summaryClaim,
+    generation,
+    receipt
+  });
+  const scopeCoverage = metadata.scope ? buildScopeCoverage(metadata.scope) : void 0;
+  const evidence = evidenceForTrajectory(state, { summaryClaim: metadata.summaryClaim, verificationReceipt: receipt !== void 0 });
+  return {
+    ...state,
+    ...evidence.length > 0 ? { evidence } : {},
+    verification,
+    ...scopeCoverage ? { scopeCoverage } : {}
+  };
+}
+
 // packages/core/src/state.ts
 var EXPLORE_TOOLS = /* @__PURE__ */ new Set([
   "read",
@@ -337,6 +591,96 @@ function firstServingTier(tiers, required, declared) {
   return void 0;
 }
 
+// packages/core/src/cache-routing.ts
+var SWITCH_ACTIONS = /* @__PURE__ */ new Set([
+  "escalate-model",
+  "fresh-context",
+  "rollback-with-reflection",
+  "retry-with-feedback"
+]);
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function boundedTokens(value) {
+  return Number.isSafeInteger(value) && finiteNonNegative(value) ? value : void 0;
+}
+function cacheObservationFromUsage(usage) {
+  if (!usage || !Number.isSafeInteger(usage.promptTokens) || usage.promptTokens < 0 || !Number.isSafeInteger(usage.cachedTokens) || usage.cachedTokens < 0) {
+    return { status: "unknown" };
+  }
+  const cachedTokens = Math.min(usage.promptTokens, usage.cachedTokens);
+  return {
+    status: cachedTokens > 0 ? "hit" : "miss",
+    promptTokens: usage.promptTokens,
+    cachedTokens
+  };
+}
+function phaseOf(input, sameToolCycle) {
+  if (input.state.failure === "hard") return "failure";
+  if (input.recoveryAction && SWITCH_ACTIONS.has(input.recoveryAction)) return "escalation";
+  if (sameToolCycle) return "same-tool-cycle";
+  if (input.previousTier !== void 0) return "new-phase";
+  return "unknown";
+}
+function routeCost(rate, tokens) {
+  return finiteNonNegative(rate) && boundedTokens(tokens) !== void 0 ? rate * tokens / 1e6 : void 0;
+}
+function switchEconomics(input, cachedTokens, contextTokens) {
+  const expectedGain = input.previousCost && input.plannedCost && contextTokens !== void 0 ? routeCost(Math.max(0, input.previousCost.input - input.plannedCost.input), contextTokens) : void 0;
+  const cachePenalty = input.previousCost && input.plannedCost && cachedTokens !== void 0 ? routeCost(Math.max(0, input.plannedCost.input - (input.previousCost.cacheRead ?? input.previousCost.input)), cachedTokens) : void 0;
+  return {
+    ...expectedGain !== void 0 ? { expectedGain } : {},
+    ...cachePenalty !== void 0 ? { cachePenalty } : {}
+  };
+}
+function result(input, action, phase, selectedTier, reason, extra = {}) {
+  const cache = input.previousCache;
+  const contextTokens = boundedTokens(input.state.contextTokens) ?? boundedTokens(input.state.estimatedTokens);
+  const cachedTokens = boundedTokens(cache?.cachedTokens);
+  const reprocessTokens = cache?.status === "hit" && cachedTokens !== void 0 ? cachedTokens : void 0;
+  return {
+    action,
+    phase,
+    cacheStatus: cache?.status ?? "unknown",
+    plannedTier: input.plannedTier,
+    selectedTier,
+    ...input.previousTier !== void 0 ? { previousTier: input.previousTier } : {},
+    ...contextTokens !== void 0 ? { estimatedContextTokens: contextTokens } : {},
+    ...cachedTokens !== void 0 ? { cachedTokens } : {},
+    ...reprocessTokens !== void 0 ? { reprocessTokens } : {},
+    ...extra,
+    reason
+  };
+}
+function cacheAwareRoute(input) {
+  const sameToolCycle = input.state.lastRole === "tool" && input.previousTier !== void 0 && (input.state.contextGeneration ?? 0) === (input.previousGeneration ?? 0);
+  const phase = phaseOf(input, sameToolCycle);
+  const canKeep = input.previousTier !== void 0 && input.canKeepPrevious !== false;
+  const cache = input.previousCache;
+  const cachedTokens = boundedTokens(cache?.cachedTokens);
+  const contextTokens = boundedTokens(input.state.contextTokens) ?? boundedTokens(input.state.estimatedTokens);
+  const economics = switchEconomics(input, cachedTokens, contextTokens);
+  if (!input.previousTier || !canKeep) {
+    return result(input, "evaluate", phase, input.plannedTier, "no usable previous route affinity; policy decision evaluated", economics);
+  }
+  if (input.plannedTier === input.previousTier) {
+    return result(input, "evaluate", phase, input.previousTier, "policy selected the current model; route unchanged", economics);
+  }
+  if (phase === "same-tool-cycle") {
+    return result(input, "keep", phase, input.previousTier, "same tool cycle; keep the current model", economics);
+  }
+  if (phase === "failure" || phase === "escalation") {
+    return result(input, "switch", phase, input.plannedTier, "failure or escalation requires evaluating a different model", economics);
+  }
+  if (cache?.status === "hit" && cachedTokens !== void 0 && economics.expectedGain !== void 0 && economics.cachePenalty !== void 0 && economics.expectedGain > economics.cachePenalty) {
+    return result(input, "switch", phase, input.plannedTier, "expected cost gain exceeds the measured cache penalty", economics);
+  }
+  if (cache?.status === "hit" && cachedTokens !== void 0) {
+    return result(input, "keep", phase, input.previousTier, "cache hit retained; unpriced policy gain does not exceed cache loss", economics);
+  }
+  return result(input, "switch", phase, input.plannedTier, "policy changed phase without a measured cache hit to preserve", economics);
+}
+
 // packages/core/src/config.ts
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
@@ -516,6 +860,9 @@ function validateConfig(value, source = "<inline>") {
     if (upstream.enabled !== void 0 && typeof upstream.enabled !== "boolean") {
       throw new Error(`Sabi config ${source}: upstream '${name}'.enabled must be a boolean`);
     }
+    if (upstream.paidModelsAllowed !== void 0 && typeof upstream.paidModelsAllowed !== "boolean") {
+      throw new Error(`Sabi config ${source}: upstream '${name}'.paidModelsAllowed must be a boolean`);
+    }
   }
   if (!Object.keys(models).length) throw new Error(`Sabi config ${source}: no models declared`);
   for (const [name, model] of Object.entries(models)) {
@@ -678,6 +1025,24 @@ function validateConfig(value, source = "<inline>") {
   return { ...config, upstreams, models, aliases, policy };
 }
 
+// packages/core/src/recovery-actions.ts
+var RECOVERY_ACTIONS = [
+  "continue",
+  "retry-same",
+  "retry-with-feedback",
+  "gather-evidence",
+  "escalate-model",
+  "fresh-context",
+  "rollback-with-reflection",
+  "ask-user"
+];
+function isRecoveryAction(value) {
+  return typeof value === "string" && RECOVERY_ACTIONS.includes(value);
+}
+function normalizeRecoveryAction(value, fallback = "ask-user") {
+  return isRecoveryAction(value) ? value : fallback;
+}
+
 // packages/core/src/log.ts
 import { appendFileSync, chmodSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { createHmac, randomBytes, randomUUID } from "node:crypto";
@@ -774,12 +1139,102 @@ function recordLogWriteFailure(logFile, error) {
 }
 function appendDecision(record, logFile = defaultLogPath()) {
   try {
-    appendPrivateLine(logFile, `${JSON.stringify(record)}
+    appendPrivateLine(logFile, `${serializeDecisionRecord(record)}
 `);
   } catch (error) {
     recordLogWriteFailure(logFile, error);
   }
 }
+function boundedStringList(values, maxItems, maxChars) {
+  if (!Array.isArray(values)) return [];
+  return values.filter((value) => typeof value === "string" && value.trim().length > 0).map((value) => value.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, maxChars)).slice(0, maxItems);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeState(state, config) {
+  const policy = telemetryPolicy(config);
+  const failureEvidence = boundedStringList(state.failureEvidence, 8, 64).filter((value) => policy.allowlisted(value));
+  const evidence = boundTrajectoryEvidence(state.evidence);
+  const clean = {
+    messageCount: state.messageCount,
+    assistantTurns: state.assistantTurns,
+    toolMessages: state.toolMessages,
+    lastRole: String(state.lastRole ?? "").slice(0, 32),
+    contextChars: state.contextChars,
+    estimatedTokens: state.estimatedTokens,
+    hasTools: state.hasTools,
+    toolNames: boundedStringList(state.toolNames, 40, 120),
+    lastToolNames: boundedStringList(state.lastToolNames, 12, 120),
+    roundKind: state.roundKind,
+    failure: state.failure,
+    failureEvidence,
+    ...state.contextTokens !== void 0 ? { contextTokens: state.contextTokens } : {},
+    ...state.contextKnown !== void 0 ? { contextKnown: state.contextKnown } : {},
+    ...state.contextGeneration !== void 0 ? { contextGeneration: state.contextGeneration } : {},
+    ...state.repeatedFailure !== void 0 ? { repeatedFailure: state.repeatedFailure } : {},
+    ...state.failureStreak !== void 0 ? { failureStreak: state.failureStreak } : {},
+    ...state.contextWindow !== void 0 ? { contextWindow: state.contextWindow } : {},
+    ...state.inputModalities ? { inputModalities: state.inputModalities.slice(0, 5) } : {},
+    ...state.mediaCounts ? { mediaCounts: state.mediaCounts } : {},
+    ...evidence.length > 0 ? { evidence } : {},
+    ...state.verification ? { verification: { ...state.verification, receiptId: state.verification.receiptId?.slice(0, 128) } } : {},
+    ...state.scopeCoverage ? {
+      scopeCoverage: {
+        ...state.scopeCoverage,
+        ...state.scopeCoverage.missing ? { missing: boundedStringList(state.scopeCoverage.missing, 32, 120) } : {}
+      }
+    } : {}
+  };
+  return clean;
+}
+function sanitizeDecisionRecord(record, config) {
+  const policy = telemetryPolicy(config);
+  const state = isPlainObject(record.state) ? sanitizeState(record.state, config) : void 0;
+  const sanitized = {
+    ts: record.ts,
+    sessionId: record.sessionId,
+    sessionKnown: record.sessionKnown,
+    requestId: record.requestId,
+    client: record.client,
+    turnId: record.turnId,
+    servedModel: record.servedModel,
+    alias: record.alias,
+    mode: record.mode,
+    rule: record.rule,
+    tier: record.tier,
+    reason: sanitizeReason(String(record.reason ?? ""), policy),
+    upstream: record.upstream,
+    upstreamModel: record.upstreamModel,
+    stream: record.stream,
+    state,
+    cache: record.cache,
+    judge: record.judge,
+    usage: record.usage,
+    cost: record.cost,
+    latencyMs: record.latencyMs,
+    ttftMs: record.ttftMs,
+    outcome: record.outcome,
+    ...record.error ? { error: sanitizeError(record.error) } : {},
+    transport: record.transport,
+    fallback: record.fallback,
+    ...record.recovery ? {
+      recovery: {
+        ...record.recovery,
+        action: normalizeRecoveryAction(record.recovery.action),
+        evidenceGrade: record.recovery.evidenceGrade === "matched" || record.recovery.evidenceGrade === "replayed" ? record.recovery.evidenceGrade : "observed",
+        failureSignature: String(record.recovery.failureSignature).slice(0, 64),
+        stateFingerprint: String(record.recovery.stateFingerprint).slice(0, 64),
+        ...record.recovery.route ? { route: String(record.recovery.route).slice(0, 160) } : {},
+        ...record.recovery.receiptId ? { receiptId: String(record.recovery.receiptId).slice(0, 128) } : {}
+      }
+    } : {}
+  };
+  return sanitized;
+}
+function serializeDecisionRecord(record, config) {
+  return JSON.stringify(sanitizeDecisionRecord(record, config));
+}
 function hashIdentity(kind, ...parts) {
   return createHmac("sha256", getIdentitySalt()).update(JSON.stringify([kind, ...parts])).digest("hex");
 }
@@ -804,7 +1259,7 @@ function trajectoryFromRound(round, previous) {
   const sameFailure = previous?.failure === "hard" && failure === "hard";
   const repeatedFailure = sameFailure === true;
   const failureStreak = repeatedFailure ? 2 : failure === "hard" ? 1 : 0;
-  return {
+  const state = {
     messageCount: round.messageCount,
     assistantTurns: round.assistantTurns,
     toolMessages: round.calls.length,
@@ -825,6 +1280,12 @@ function trajectoryFromRound(round, previous) {
     ...round.inputModalities ? { inputModalities: round.inputModalities } : {},
     ...round.mediaCounts && Object.keys(round.mediaCounts).length ? { inputModalities: round.inputModalities ?? modalitiesOf(round.mediaCounts), mediaCounts: round.mediaCounts } : {}
   };
+  return decorateTrajectoryState(state, {
+    generation: round.contextGeneration,
+    verificationReceipt: round.verificationReceipt,
+    summaryClaim: round.summaryClaim,
+    scope: round.scope
+  });
 }
 function roundMedia(round) {
   return { counts: round.mediaCounts ?? {}, payloadChars: 0 };
@@ -844,6 +1305,20 @@ function planRound(state, policy, tiers, options = {}) {
     rule = "capability";
     tier = alternate;
   }
+  const cache = cacheAwareRoute({
+    state: withWindow,
+    plannedTier: tier,
+    previousTier: options.previous?.tier,
+    previousLastRole: options.previous?.lastRole,
+    previousGeneration: options.previous?.generation,
+    previousCache: options.previous?.cache,
+    canKeepPrevious: Boolean(options.previous?.tier && tiers[options.previous.tier] && servesInputModalities(tiers[options.previous.tier]?.inputModalities, required))
+  });
+  if (cache.selectedTier !== tier) {
+    tier = cache.selectedTier;
+    rule = "cache-affinity";
+    reason = cache.reason;
+  }
   const chosen = tiers[tier];
   if (!chosen || !chosen.model) return void 0;
   return {
@@ -852,61 +1327,31 @@ function planRound(state, policy, tiers, options = {}) {
     effort: chosen.effort,
     rule,
     reason,
-    state: withWindow
+    state: withWindow,
+    cache
   };
 }
 
-// packages/core/src/telemetry.ts
-var ALLOWLIST = /* @__PURE__ */ new Set([
-  "error-line",
-  "python-traceback",
-  "panic",
-  "exception",
-  "typescript-error",
-  "fail-marker",
-  "command-failed",
-  "nonzero-exit",
-  "failure-count",
-  "command-not-found",
-  "permission-denied",
-  "missing-file",
-  "soft-warning",
-  "soft-deprecated",
-  "soft-retrying",
-  "soft-timeout",
-  "tool-error",
-  "permission-denial",
-  "rate-limited",
-  "quota-exceeded",
-  "timeout"
-]);
-function allowlisted(value) {
-  const code = value.split(":")[0]?.trim();
-  return ALLOWLIST.has(code);
-}
-function telemetryPolicy(config) {
-  const captureSnippets = config?.captureSnippets === true;
-  const captureChars = config?.captureChars ?? 800;
-  return {
-    captureSnippets,
-    allowlisted: (value) => allowlisted(value),
-    snippet: (value) => captureSnippets ? String(value).slice(0, captureChars) : ""
-  };
-}
-function sanitizeReason(reason, policy) {
-  if (!policy.captureSnippets) {
-    if (!reason || allowlisted(reason)) return reason;
-    const segments = reason.split(":").map((segment) => segment.trim());
-    const last = segments[segments.length - 1] ?? "";
-    if (allowlisted(last)) return reason;
-    return "reason withheld (telemetry.allowlistOnly)";
-  }
-  return policy.snippet(reason);
-}
-
 // packages/core/src/prompt.ts
 import * as readline from "node:readline/promises";
 
+// packages/core/src/signals.ts
+var KNOWN_SIGNAL_KINDS = [
+  "failure.real",
+  "failure.transport",
+  "progress.stalled",
+  "verification.complete",
+  "coverage",
+  "context.pressure",
+  "context.staleness",
+  "task.ambiguity",
+  "mutation.risk",
+  "retry.value",
+  "evidence.nextValue",
+  "model.requiredStrength"
+];
+var KNOWN_KINDS = new Set(KNOWN_SIGNAL_KINDS);
+
 // packages/adapters/command-code/mod/sabi.ts
 import path3 from "node:path";
 var MOD_ID = "sabi";
@@ -924,6 +1369,9 @@ function readLedger(state) {
     hasTools: raw.hasTools === true,
     lastModel: raw.lastModel,
     lastUsage: raw.lastUsage,
+    lastTier: raw.lastTier,
+    lastLastRole: raw.lastLastRole,
+    lastCache: raw.lastCache,
     sessionId: typeof raw.sessionId === "string" ? raw.sessionId : void 0
   };
 }
@@ -992,12 +1440,12 @@ function sabi(cmd) {
       return writeLedger(state, { ...ledger, rounds: turnNumber });
     },
     // Sabi observes tool outcomes and never rewrites what the model sees.
-    afterToolCall: ({ toolName, input, isError, result }) => {
+    afterToolCall: ({ toolName, input, isError, result: result2 }) => {
       calls.push({
         name: toolName,
         args: JSON.stringify(input ?? {}),
         failed: isError === true,
-        output: typeof result === "string" ? result : void 0
+        output: typeof result2 === "string" ? result2 : void 0
       });
       return void 0;
     },
@@ -1008,6 +1456,9 @@ function sabi(cmd) {
         previousFailure = void 0;
         ledger.generation = (ledger.generation ?? 0) + 1;
         ledger.contextTokens = void 0;
+        ledger.lastTier = void 0;
+        ledger.lastLastRole = void 0;
+        ledger.lastCache = { status: "unknown" };
       }
       const round = {
         messageCount: stats.messageCount,
@@ -1022,7 +1473,15 @@ function sabi(cmd) {
         ...Object.keys(stats.media.counts).length ? { inputModalities: modalitiesOf(stats.media.counts), mediaCounts: stats.media.counts } : {}
       };
       const trajectory = trajectoryFromRound(round, previousFailure);
-      const plan = planRound(trajectory, policy, tiers, { contextWindow: config.harness?.contextWindow });
+      const plan = planRound(trajectory, policy, tiers, {
+        contextWindow: config.harness?.contextWindow,
+        previous: {
+          tier: ledger.lastTier,
+          lastRole: ledger.lastLastRole,
+          generation: ledger.generation,
+          cache: ledger.lastCache
+        }
+      });
       if (!plan) return void 0;
       nextPlan = plan;
       return plan.effort ? { model: plan.model, effort: plan.effort } : { model: plan.model };
@@ -1048,7 +1507,10 @@ function sabi(cmd) {
         // Only advance attribution when a fresh value actually arrived this turn. A missing
         // usage or model event stays unknown rather than re-serializing an old round's value.
         lastModel: servedBy,
-        lastUsage: usedThisTurn ? usage : void 0
+        lastUsage: usedThisTurn ? usage : void 0,
+        lastTier: adopted?.tier ?? (compacted ? void 0 : ledger.lastTier),
+        lastLastRole: adopted?.state.lastRole ?? (compacted ? void 0 : ledger.lastLastRole),
+        lastCache: usedThisTurn ? cacheObservationFromUsage(toUsageTotals(usage)) : { status: "unknown" }
       };
       previousFailure = adopted ? { failure: adopted.state.failure, failureEvidence: adopted.state.failureEvidence } : void 0;
       recordCustomEntry(ctx, {
@@ -1091,6 +1553,7 @@ function sabi(cmd) {
           // This is the host adapter, not a provider entitlement claim.
           upstream: CLIENT_ID,
           upstreamModel: servingPlan.model,
+          cache: servingPlan.cache,
           stream: false,
           state: {
             ...servingPlan.state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizuh/sabi",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Adaptive inference scheduling for Command Code: one bundled mod that routes each continuing round by model, effort and trajectory state.",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,9 @@
     "command-code",
     "mod",
     "llm",
-    "routing"
+    "routing",
+    "ai-agents",
+    "inference-scheduling"
   ],
   "publishConfig": {
     "access": "public"

package/sabi.config.json

@@ -1,11 +1,12 @@
 {
-  "provenance": "Model ids, context windows, output limits and prices verified live from https://openrouter.ai/api/v1/models on 2026-09-20; input modalities for the same ids verified from the same endpoint. Prices are USD per 1M tokens. Declared modalities are enforced: an undeclared capability is unknown, a declared one is binding.",
+  "provenance": "Operator rule (2026-09-22): OpenRouter may serve FREE models only. The openrouter upstream declares paidModelsAllowed:false, so any model whose price is unknown or non-zero is refused at dispatch (packages/core/src/compatibility.ts) — a config mistake cannot spend money. Every openrouter model id below carries the :free variant and cost 0. Ids, context windows, output ceilings, modalities and zero pricing verified live from https://openrouter.ai/api/v1/models and a real completion per id on 2026-09-22. Jev (TypeSafe judge) is a separate upstream and unaffected by this rule.",
   "server": { "host": "127.0.0.1", "port": 8787 },
   "upstreams": {
     "openrouter": {
       "baseURL": "https://openrouter.ai/api/v1",
       "apiKey": "$OPENROUTER_API_KEY",
       "streamUsage": true,
+      "paidModelsAllowed": false,
       "headers": {
         "HTTP-Referer": "https://github.com/vizuh/sabi",
         "X-Title": "Sabi"
@@ -20,27 +21,27 @@
   "models": {
     "cheap": {
       "upstream": "openrouter",
-      "model": "deepseek/deepseek-v4-flash-0731",
-      "contextWindow": 1310720,
-      "maxOutputTokens": 943718,
+      "model": "poolside/laguna-s-2.1:free",
+      "contextWindow": 262144,
+      "maxOutputTokens": 32768,
       "capabilities": { "inputModalities": ["text"] },
-      "cost": { "input": 0.06, "output": 0.12, "cacheRead": 0.012 }
+      "cost": { "input": 0, "output": 0 }
     },
     "mid": {
       "upstream": "openrouter",
-      "model": "openai/gpt-5.6-luna",
-      "contextWindow": 1050000,
-      "maxOutputTokens": 128000,
-      "capabilities": { "inputModalities": ["text", "image", "file"] },
-      "cost": { "input": 0.2, "output": 1.2, "cacheRead": 0.02 }
+      "model": "dots-studio/dots-3-note-preview:free",
+      "contextWindow": 512000,
+      "maxOutputTokens": 460800,
+      "capabilities": { "inputModalities": ["text", "image"] },
+      "cost": { "input": 0, "output": 0 }
     },
     "strong": {
       "upstream": "openrouter",
-      "model": "anthropic/claude-sonnet-5",
+      "model": "nvidia/nemotron-3-ultra-550b-a55b:free",
       "contextWindow": 1000000,
-      "maxOutputTokens": 128000,
-      "capabilities": { "inputModalities": ["text", "image", "file"] },
-      "cost": { "input": 2, "output": 10, "cacheRead": 0.2 }
+      "maxOutputTokens": 65536,
+      "capabilities": { "inputModalities": ["text"] },
+      "cost": { "input": 0, "output": 0 }
     },
     "local": {
       "upstream": "ollama",
@@ -96,7 +97,7 @@
     "costPerMTokInput": 0.042
   },
   "harness": {
-    "provenance": "Command Code catalog ids, efforts and min plans verified 2026-09-18 against `cmd --list-models` and the bundled reference models.md. Used by the in-process mod adapter (harness keeps its own loop, no proxy, no key). The `models` tiers above are the separate BYOK proxy path and are unused while the mod is active. A tier must be a model the account can actually serve: `cmd --list-models` prints the whole catalog regardless of plan, and an out-of-plan model answers 403 MODEL_NOT_IN_PLAN and fails that round. The defaults are the strongest ids available from the Go plan up; docs/install.md lists Pro and Max presets. `contextWindow` is the largest verified window among the tiers (1M), used by the context-pressure rule. `inputModalities` mirror the CLI's own model registry, read from the shipped bundle on 2026-09-18: plain `deepseek-v4-flash` and `glm-5.3` are text-only while `gpt-5.6-luna` accepts images. The host strips images for a text-only model, so a tier that cannot read them is passed over for one that can.",
+    "provenance": "Command Code catalog ids, efforts and min plans verified 2026-09-18 against `cmd --list-models` and the bundled reference models.md. Used by the in-process mod adapter (harness keeps its own loop, no proxy, no key). This is the Command Code subscription catalog, not OpenRouter — the free-models-only rule above does not apply to it.",
     "tiers": {
       "cheap": {
         "model": "deepseek/deepseek-v4-flash",