@vizuh/sabi 0.1.5 → 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,4 +1,4 @@
-// @vizuh/sabi 0.1.5 — 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
@@ -163,8 +163,8 @@ function normalizeTrajectoryEvidence(value, fallbackGeneration = 0) {
   };
 }
 function boundTrajectoryEvidence(values, maxItems = MAX_EVIDENCE_ITEMS) {
-  const result = [];
-  if (maxItems <= 0) return result;
+  const result2 = [];
+  if (maxItems <= 0) return result2;
   const seen = /* @__PURE__ */ new Set();
   for (const value of values ?? []) {
     const item = normalizeTrajectoryEvidence(value);
@@ -172,10 +172,10 @@ function boundTrajectoryEvidence(values, maxItems = MAX_EVIDENCE_ITEMS) {
     const key = JSON.stringify(item);
     if (seen.has(key)) continue;
     seen.add(key);
-    result.push(item);
-    if (result.length >= Math.max(0, Math.min(maxItems, MAX_EVIDENCE_ITEMS))) break;
+    result2.push(item);
+    if (result2.length >= Math.max(0, Math.min(maxItems, MAX_EVIDENCE_ITEMS))) break;
   }
-  return result;
+  return result2;
 }
 function countScope(value) {
   if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0 ? { count: value } : {};
@@ -591,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";
@@ -770,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)) {
@@ -1115,6 +1208,7 @@ function sanitizeDecisionRecord(record, config) {
     upstreamModel: record.upstreamModel,
     stream: record.stream,
     state,
+    cache: record.cache,
     judge: record.judge,
     usage: record.usage,
     cost: record.cost,
@@ -1211,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 {
@@ -1219,13 +1327,31 @@ function planRound(state, policy, tiers, options = {}) {
     effort: chosen.effort,
     rule,
     reason,
-    state: withWindow
+    state: withWindow,
+    cache
   };
 }
 
 // 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";
@@ -1243,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
   };
 }
@@ -1311,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;
     },
@@ -1327,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,
@@ -1341,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 };
@@ -1367,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, {
@@ -1410,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.5",
+  "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",