lynkr 9.10.0 → 9.12.0

package/src/memory/wiki.js

@@ -0,0 +1,171 @@
+/**
+ * Wiki — Large-Block Content Registry (TencentDB-Agent-Memory inspired)
+ *
+ * Registers large content blocks (docs, configs, big tool outputs) the
+ * first time they appear in old conversation history, then replaces later
+ * near-duplicates with a short reference + summary instead of resending
+ * the full block. Entries persist in the memories table (type='wiki') so
+ * dedup works across sessions.
+ */
+
+const store = require("./store");
+const distill = require("../context/distill");
+const config = require("../config");
+const logger = require("../logger");
+
+const CHARS_PER_TOKEN = 4;
+const MAX_CACHED_ENTRIES = 500;
+const MAX_SIGNATURE_LINES = 200;
+
+// In-memory entry cache: [{ id, summary, signature: Set<string> }]
+let entryCache = null;
+
+function wikiConfig() {
+  return config.memory?.wiki ?? {};
+}
+
+function minChars() {
+  return (wikiConfig().minTokens ?? 500) * CHARS_PER_TOKEN;
+}
+
+/**
+ * Load persisted wiki entries into the in-memory cache (lazy, once).
+ */
+function loadCache() {
+  if (entryCache) return entryCache;
+
+  entryCache = [];
+  try {
+    const rows = store.getMemoriesByType("wiki", MAX_CACHED_ENTRIES);
+    for (const row of rows) {
+      const meta = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
+      if (!meta?.signatureLines?.length) continue;
+      entryCache.push({
+        id: row.id,
+        summary: row.content,
+        signature: new Set(meta.signatureLines),
+      });
+    }
+  } catch (err) {
+    logger.warn({ err }, "[wiki] Failed to load wiki entries, starting empty");
+  }
+  return entryCache;
+}
+
+/**
+ * Build a one-line summary for a content block: first heading or first
+ * meaningful line, plus a size note.
+ */
+function makeSummary(text) {
+  const lines = distill.normalizeText(text).split("\n").filter(Boolean);
+  const heading = lines.find(l => /^#{1,4}\s|^[A-Z][^a-z]*$/.test(l.trim()));
+  const first = (heading || lines[0] || "").trim().slice(0, 120);
+  return `${first} (${lines.length} lines, ~${Math.ceil(text.length / CHARS_PER_TOKEN)} tokens)`;
+}
+
+/**
+ * Register a large block, or return a compact reference if a similar
+ * block is already known.
+ *
+ * @param {string} text - Content block from old history
+ * @returns {{ref: string, id: number, saved: number}|null} Reference when a
+ *   similar entry exists; null when the block was registered or is too small
+ */
+function registerOrDereference(text) {
+  if (wikiConfig().enabled === false) return null;
+  if (!text || text.length < minChars()) return null;
+
+  const threshold = wikiConfig().similarityThreshold ?? 0.85;
+  const signature = distill.extractSignature(text);
+  const cache = loadCache();
+
+  for (const entry of cache) {
+    const sim = distill.jaccardSimilarity(signature, entry.signature);
+    if (sim >= threshold) {
+      const ref = `[wiki:${entry.id} — ${(sim * 100).toFixed(0)}% match] ${entry.summary}`;
+      return { ref, id: entry.id, saved: text.length - ref.length };
+    }
+  }
+
+  // No match — register for future dedup
+  try {
+    const summary = makeSummary(text);
+    const memory = store.createMemory({
+      sessionId: null, // wiki entries are global
+      content: summary,
+      type: "wiki",
+      category: "reference",
+      importance: 0.3,
+      metadata: {
+        signatureLines: Array.from(signature).slice(0, MAX_SIGNATURE_LINES),
+        originalChars: text.length,
+      },
+    });
+    cache.push({ id: memory.id, summary, signature });
+    if (cache.length > MAX_CACHED_ENTRIES) cache.shift();
+  } catch (err) {
+    logger.warn({ err }, "[wiki] Failed to register wiki entry");
+  }
+
+  return null;
+}
+
+/**
+ * Replace large repeated blocks inside old-history messages with wiki
+ * references. Only text and tool_result content is touched.
+ *
+ * @param {Array} messages - Old (about-to-be-summarized) messages
+ * @returns {{messages: Array, stats: {registered: number, dereferenced: number, charsSaved: number}}}
+ */
+function dereferenceMessages(messages) {
+  const stats = { registered: 0, dereferenced: 0, charsSaved: 0 };
+  if (wikiConfig().enabled === false || !messages?.length) {
+    return { messages: messages || [], stats };
+  }
+
+  const processText = (text) => {
+    const before = loadCache().length;
+    const result = registerOrDereference(text);
+    if (result) {
+      stats.dereferenced++;
+      stats.charsSaved += result.saved;
+      return result.ref;
+    }
+    if (loadCache().length > before) stats.registered++;
+    return text;
+  };
+
+  const processed = messages.map(msg => {
+    if (typeof msg.content === "string") {
+      if (msg.content.length < minChars()) return msg;
+      return { ...msg, content: processText(msg.content) };
+    }
+    if (!Array.isArray(msg.content)) return msg;
+
+    const newContent = msg.content.map(block => {
+      if (block.type === "text" && block.text?.length >= minChars()) {
+        return { ...block, text: processText(block.text) };
+      }
+      if (block.type === "tool_result" && typeof block.content === "string" &&
+          block.content.length >= minChars()) {
+        return { ...block, content: processText(block.content) };
+      }
+      return block;
+    });
+    return { ...msg, content: newContent };
+  });
+
+  return { messages: processed, stats };
+}
+
+/** Reset the in-memory cache (test support). */
+function resetCache() {
+  entryCache = null;
+}
+
+module.exports = {
+  registerOrDereference,
+  dereferenceMessages,
+  makeSummary,
+  resetCache,
+};

package/src/orchestrator/index.js

@@ -21,6 +21,7 @@ const crypto = require("crypto");
 const { getSemanticCache, isSemanticCacheEnabled } = require("../cache/semantic");
 const { areSimilarToolCalls } = require("../clients/gpt-utils");
 const { getModelRegistrySync } = require("../routing/model-registry");
+const sessionAffinity = require("../routing/session-affinity");
 
 /**
  * Get destination URL for audit logging based on provider type
@@ -433,7 +434,7 @@ function injectToolLoopStopInstruction(messages, threshold = 5) {
     // Inject instruction to stop tool calls and provide a final answer
     const stopInstruction = {
       role: "user",
-      content: `⚠️ IMPORTANT: You have already executed ${toolResultCount} tool calls in this conversation. This is likely an infinite loop. STOP calling tools immediately and provide a direct text response to the user based on the information you have gathered. If you cannot complete the task, explain why. DO NOT call any more tools.`,
+      content: `⚠️ IMPORTANT: You have already executed ${toolResultCount} tool calls in this conversation. This is likely an infinite loop. STOP calling tools immediately and provide a direct text response to the user based on the information you have gathered. If you cannot complete the task, explain why. DO NOT call any more tools. Your response must contain your actual findings — NOT an acknowledgment or restatement of this warning.`,
     };
 
     return [...messages, stopInstruction];
@@ -452,6 +453,23 @@ const DEDUP_MAX_SIGNATURES = 50;
 const DEDUP_WARN_THRESHOLD = 5;
 const DEDUP_TERMINATE_THRESHOLD = 8;
 
+/**
+ * State-management tools are called repeatedly with similar args BY DESIGN —
+ * that's their job, not a loop. Opencode calls `todowrite` after every step;
+ * Claude Code uses `TodoWrite`; OpenWorker uses `todo_write`/`propose_plan`.
+ * Counting them in the dedup tracker produced false-positive loop warnings
+ * and force-terminations on healthy agent sessions (live incident: an
+ * opencode analysis run was force-terminated into a raw tool-result dump
+ * because its todo updates hit the terminate threshold).
+ * @param {Object} toolCall - tool_use block
+ * @returns {boolean}
+ */
+function isDedupExemptTool(toolCall) {
+  const raw = toolCall?.function?.name ?? toolCall?.name ?? '';
+  const name = String(raw).toLowerCase().replace(/[_-]/g, '');
+  return name.includes('todo') || name === 'updateplan' || name === 'proposeplan';
+}
+
 /**
  * Initialise session.metadata.toolCallDedup if missing.
  * @param {Object} session
@@ -462,6 +480,7 @@ function ensureDedupStructure(session) {
     session.metadata.toolCallDedup = {
       signatures: {},
       similarGroups: {},
+      seenIds: {},
       lastResetAt: Date.now(),
       warningInjected: false,
     };
@@ -476,9 +495,26 @@ function ensureDedupStructure(session) {
  */
 function recordCrossRequestToolCall(session, toolCall) {
   if (!session?.metadata) return;
+  if (isDedupExemptTool(toolCall)) return; // repeat-by-design tools never count toward loop detection
   ensureDedupStructure(session);
 
   const dedup = session.metadata.toolCallDedup;
+
+  // Stateless HTTP agents (opencode, Cursor, OpenWorker) replay the FULL
+  // conversation history on every agent-loop step, so the same tool_use block
+  // arrives again on step 2, 3, 4… Counting each replay made counts grow
+  // quadratically with turn length — any exploration past ~5 steps hit the
+  // terminate threshold regardless of what it was doing (live incident:
+  // a 7-step opencode code-trace was force-terminated as a "loop").
+  // Each tool_use block carries a unique id: count each id exactly once.
+  const blockId = toolCall?.id;
+  if (blockId) {
+    if (!dedup.seenIds) dedup.seenIds = {};
+    if (dedup.seenIds[blockId]) return; // already counted this exact call
+    dedup.seenIds[blockId] = 1;
+    // Bounded: reset wipes this on each new user question; cap as a backstop.
+    if (Object.keys(dedup.seenIds).length > 500) dedup.seenIds = { [blockId]: 1 };
+  }
   const signature = getToolCallSignature(toolCall);
   const toolName = toolCall.function?.name ?? toolCall.name ?? 'unknown';
   const args = toolCall.function?.arguments ?? toolCall.input;
@@ -620,6 +656,7 @@ function resetDedupTracking(session) {
   session.metadata.toolCallDedup = {
     signatures: {},
     similarGroups: {},
+    seenIds: {},
     lastResetAt: Date.now(),
     warningInjected: false,
   };
@@ -1421,6 +1458,30 @@ async function runAgentLoop({
 
 
     if (steps === 1 && agentTimer) agentTimer.mark("preCompression");
+
+    // === CONVERSATION DISTILLATION (TencentDB-inspired L0-L3 pipeline) ===
+    // Long conversations collapse older turns into one distilled block
+    // (persona + scenario summary) before history compression runs.
+    if (steps === 1 && config.memory?.enabled !== false && config.memory?.distillation?.enabled !== false) {
+      try {
+        const distiller = require('../memory/distiller');
+        if (distiller.needsDistillation(cleanPayload.messages)) {
+          const result = distiller.distillMessages(cleanPayload.messages, {
+            sessionId: session?.id,
+          });
+          if (result.applied) {
+            cleanPayload.messages = result.messages;
+            logger.debug({
+              sessionId: session?.id ?? null,
+              ...result.stats,
+            }, '[distiller] Conversation distillation applied');
+          }
+        }
+      } catch (err) {
+        logger.warn({ err, sessionId: session?.id }, 'Distillation failed, continuing with full history');
+      }
+    }
+
     if (steps === 1 && config.historyCompression?.enabled !== false) {
       try {
         if (historyCompression.needsCompression(cleanPayload.messages)) {
@@ -1883,6 +1944,28 @@ IMPORTANT TOOL USAGE RULES:
     }
   }
 
+  // Cache-aware routing (Phase 1): persist the session's warm-prefix state
+  // from the response's cache counters so the router can price a mid-session
+  // model switch against the live cache clock. Best-effort — never blocks
+  // the response path.
+  if (session?.id && actualUsage) {
+    try {
+      // Prefer the ROUTED provider/model over the request-level default:
+      // the tier router inside invokeModel may have diverged from
+      // providerType, and the cache lives with whoever actually served
+      // (verified live: databricks default label on ollama-served turns).
+      const served = databricksResponse.routingDecision || {};
+      sessionAffinity.recordCacheUsage(session.id, {
+        provider: served.provider || providerType,
+        model: served.model || cleanPayload.model,
+        cacheReadTokens: actualUsage.cacheReadTokens,
+        cacheCreationTokens: actualUsage.cacheCreationTokens,
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, "[Orchestrator] cache-state update failed");
+    }
+  }
+
   if (auditLogger.enabled) {
     const latencyMs = Date.now() - start;
 
@@ -2879,7 +2962,7 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
         if (Array.isArray(payload?.messages)) {
           payload.messages.push({
             role: "user",
-            content: `⚠️ CRITICAL SYSTEM WARNING: You have called the "${dedupToolName}" tool ${maxCount} times with identical or similar parameters across multiple requests. This IS an infinite loop. STOP calling this tool immediately. You MUST now provide a direct text response based on the results you have received. If the tool returned "no results" or empty output, that IS the final answer - do not retry. Summarize your findings and respond.`,
+            content: `⚠️ CRITICAL SYSTEM WARNING: You have called the "${dedupToolName}" tool ${maxCount} times with identical or similar parameters across multiple requests. This IS an infinite loop. STOP calling this tool immediately. You MUST now provide a direct text response based on the results you have received. If the tool returned "no results" or empty output, that IS the final answer - do not retry. Your response must contain your actual findings from the tool results gathered so far — NOT an acknowledgment or restatement of this warning. Do not mention this warning in your response.`,
           });
         }
       }

package/src/orchestrator/sse-transformer.js

@@ -20,9 +20,14 @@
  */
 const logger = require("../logger");
 
-// Upstreams whose streaming wire format is OpenAI Chat Completions SSE.
-// ollama is excluded (own format + buffering quirks), moonshot/zai are
-// excluded (their invoke fns convert buffered responses to Anthropic).
+// Upstreams whose streaming streaming wire format is OpenAI Chat Completions SSE.
+// ollama is excluded (own format + buffering quirks); zai is excluded (its
+// invoke fn converts buffered responses to Anthropic, and its Anthropic-format
+// endpoint has the native passthrough path instead). moonshot joined the list
+// once invokeMoonshot learned to return the raw stream (its old forced
+// stream:false predated this transformer). Caveat: reasoning_content deltas
+// (kimi thinking) are not reshaped — thinking text is dropped from streamed
+// responses; the buffered path still lifts it into thinking blocks.
 const DEFAULT_OPENAI_SSE_PROVIDERS = [
   "openai",
   "azure-openai",
@@ -30,6 +35,7 @@ const DEFAULT_OPENAI_SSE_PROVIDERS = [
   "databricks",
   "lmstudio",
   "llamacpp",
+  "moonshot",
 ];
 
 function _transformProviders() {

package/src/prompts/system.js

@@ -70,13 +70,27 @@ function compressToolDescriptions(tools, mode = null) {
     return tools; // Return unmodified if not in minimal mode
   }
 
+  // Normalize to Anthropic shape: OpenAI-format callers (OpenWorker, aisuite,
+  // any OpenAI SDK) send {type:"function", function:{name, description, parameters}}.
+  // Unwrap once here so the compression logic below can assume input_schema exists.
+  tools = tools.map(tool =>
+    tool?.type === "function" && tool.function
+      ? {
+          name: tool.function.name,
+          description: tool.function.description,
+          input_schema: tool.function.parameters || { type: "object", properties: {} },
+        }
+      : tool
+  );
+
   return tools.map(tool => {
+    const input_schema = tool.input_schema || { type: "object", properties: {} };
     const compressed = {
       name: tool.name,
       input_schema: {
-        type: tool.input_schema.type,
+        type: input_schema.type || "object",
         properties: {},
-        required: tool.input_schema.required || [],
+        required: input_schema.required || [],
       }
     };
 
@@ -86,8 +100,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Compress property descriptions
-    if (tool.input_schema.properties) {
-      for (const [key, value] of Object.entries(tool.input_schema.properties)) {
+    if (input_schema.properties) {
+      for (const [key, value] of Object.entries(input_schema.properties)) {
         compressed.input_schema.properties[key] = {
           type: value.type,
         };
@@ -108,8 +122,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Preserve additionalProperties if set
-    if (tool.input_schema.additionalProperties !== undefined) {
-      compressed.input_schema.additionalProperties = tool.input_schema.additionalProperties;
+    if (input_schema.additionalProperties !== undefined) {
+      compressed.input_schema.additionalProperties = input_schema.additionalProperties;
     }
 
     return compressed;

package/src/routing/affinity-store.js

@@ -56,6 +56,12 @@ function _db() {
       if (!cols.has("has_tool_history")) {
         db.exec("ALTER TABLE session_pins ADD COLUMN has_tool_history INTEGER DEFAULT 0");
       }
+      // Additive migration for cache-aware routing (Phase 1): JSON blob
+      // holding {warmPrefixTokens, provider, model, lastRequestAt, ttlMs},
+      // updated after every upstream response that reports cache usage.
+      if (!cols.has("cache_state")) {
+        db.exec("ALTER TABLE session_pins ADD COLUMN cache_state TEXT");
+      }
       schemaEnsured = true;
     } catch (err) {
       degradation.record("feedback", err);
@@ -160,6 +166,67 @@ function save(sessionId, pin) {
   }
 }
 
+/**
+ * Persist per-session prompt-cache state (Phase 1, cache-aware routing).
+ * Piggybacks on the session_pins row; creates a minimal row when the session
+ * has no pin yet (possible when sticky sessions are disabled but tracking
+ * is on). Best-effort like everything else in this module.
+ *
+ * @param {string} sessionId
+ * @param {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}} state
+ */
+function saveCacheState(sessionId, state) {
+  if (!sessionId || !state?.provider) return;
+  const db = _db();
+  if (!db) return;
+  try {
+    const json = JSON.stringify(state);
+    const res = _stmt(
+      db,
+      "cache_state_update",
+      "UPDATE session_pins SET cache_state = ? WHERE session_id = ?"
+    ).run(json, sessionId);
+    if (res.changes === 0) {
+      _stmt(
+        db,
+        "cache_state_insert",
+        `INSERT INTO session_pins (session_id, provider, model, ts, cache_state)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(session_id) DO UPDATE SET cache_state = excluded.cache_state`
+      ).run(sessionId, state.provider, state.model ?? null, Date.now(), json);
+    }
+  } catch (err) {
+    degradation.record("feedback", err);
+  }
+}
+
+/**
+ * Load per-session cache state. Returns null when absent, unparsable, or the
+ * DB is unavailable — callers treat null as "no cache signal for this
+ * session" (provider doesn't report cache usage, or no response seen yet).
+ *
+ * @param {string} sessionId
+ * @returns {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}|null}
+ */
+function loadCacheState(sessionId) {
+  if (!sessionId) return null;
+  const db = _db();
+  if (!db) return null;
+  try {
+    const row = _stmt(
+      db,
+      "cache_state_load",
+      "SELECT cache_state FROM session_pins WHERE session_id = ?"
+    ).get(sessionId);
+    if (!row?.cache_state) return null;
+    const parsed = JSON.parse(row.cache_state);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (err) {
+    degradation.record("feedback", err);
+    return null;
+  }
+}
+
 /**
  * Remove a pin.
  * @param {string} sessionId
@@ -205,4 +272,4 @@ function _clear() {
   } catch { /* best-effort */ }
 }
 
-module.exports = { load, save, remove, cleanup, _clear };
+module.exports = { load, save, remove, cleanup, saveCacheState, loadCacheState, _clear };

package/src/routing/agentic-detector.js

@@ -224,13 +224,21 @@ class AgenticDetector {
     const agentType = this._classifyAgentType(score, signals);
     const isAgentic = score >= 25;
 
+    // AGENTIC_DISABLE_FLOOR=1 bypasses the per-agent-type minTier — the raw
+    // complexity score decides the tier without the tools-based bump. Useful
+    // for demos/tests where tool-heavy clients (OpenWorker, aisuite) send 25+
+    // tools on every request and otherwise floor everything to MEDIUM+.
+    const flooredMinTier = process.env.AGENTIC_DISABLE_FLOOR === '1'
+      ? 'SIMPLE'
+      : AGENT_TYPES[agentType].minTier;
+
     const result = {
       isAgentic,
       agentType,
       confidence: Math.min(score / 100, 1),
       score,
       signals,
-      minTier: AGENT_TYPES[agentType].minTier,
+      minTier: flooredMinTier,
       scoreBoost: AGENT_TYPES[agentType].scoreBoost,
       description: AGENT_TYPES[agentType].description,
       clientProfile: profile?.name ?? null,

package/src/routing/cache-economics.js

@@ -0,0 +1,123 @@
+/**
+ * Per-provider prompt-cache economics.
+ *
+ * Single resolution point for "what does the prompt cache cost on this
+ * provider/model": read price, write price, TTL, and mechanism. The
+ * switch-cost math in `cache-switch-cost.js` and the cache-state tracker in
+ * `session-affinity.js` read from here — decision code never hardcodes
+ * per-model numbers.
+ *
+ * Resolution order per field:
+ *   1. model-registry entry (models.dev carries absolute cacheRead/cacheWrite
+ *      $/1M for many models)
+ *   2. provider-type fallback table below (multipliers of the model's input
+ *      price), researched Aug 2026.
+ *
+ * Mechanisms:
+ *   - 'explicit'  — cache_control breakpoints, paid writes (Anthropic-style).
+ *     TTL refreshes on every read, so lastRequestAt + ttlMs is a live clock.
+ *   - 'automatic' — provider caches transparently, writes are free
+ *     (OpenAI/DeepSeek/Gemini-style). TTL is best-effort.
+ *   - 'local'     — no dollar cost at all; the "cost" of a cold prefix is
+ *     prefill latency, handled separately in cache-switch-cost.js.
+ *
+ * @module routing/cache-economics
+ */
+
+const logger = require('../logger');
+
+// Fallback economics keyed by Lynkr provider type. `readMult`/`writeMult`
+// are multipliers of the model's per-1M input price.
+const PROVIDER_CACHE_DEFAULTS = {
+  // Anthropic-hosted (explicit cache_control, 1.25x write for the 5-min TTL,
+  // TTL refreshed on every read).
+  'azure-anthropic': { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  bedrock:           { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  databricks:        { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+
+  // OpenAI automatic prefix caching: writes free, ~5-10 min idle eviction.
+  openai:         { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+  'azure-openai': { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+
+  // Gemini implicit caching / GLM / Kimi / aggregators: free automatic
+  // caching, best-effort TTL. Aggregators (openrouter/edenai) depend on the
+  // underlying model; models.dev per-model data wins when present.
+  vertex:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  zai:        { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  moonshot:   { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  openrouter: { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  edenai:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  // DeepSeek direct (via aggregators today, kept for model-level matches):
+  deepseek:   { readMult: 0.02, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+
+  // Local runtimes: no dollars; KV cache lives as long as the model stays
+  // loaded (ollama keep_alive default ~5 min).
+  ollama:   { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  llamacpp: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  lmstudio: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+};
+
+const GENERIC_DEFAULT = { readMult: 0.1, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' };
+
+/**
+ * Fallback cache economics for a provider type (no model lookup).
+ * @param {string|null} providerType
+ * @returns {{readMult:number, writeMult:number, ttlMs:number, mechanism:string}}
+ */
+function getProviderCacheDefaults(providerType) {
+  return PROVIDER_CACHE_DEFAULTS[providerType] || GENERIC_DEFAULT;
+}
+
+/**
+ * Resolve full cache economics for a provider/model pair.
+ *
+ * @param {string|null} providerType - Lynkr provider type (e.g. 'databricks')
+ * @param {string|null} model - model name for registry lookup
+ * @returns {{
+ *   inputPerM:number, outputPerM:number,
+ *   cacheReadPerM:number, cacheWritePerM:number,
+ *   ttlMs:number, mechanism:string, unknownPricing:boolean
+ * }} All prices are USD per 1M tokens.
+ */
+function resolveCacheEconomics(providerType, model) {
+  const defaults = getProviderCacheDefaults(providerType);
+
+  let cost = null;
+  try {
+    const { getModelRegistrySync } = require('./model-registry');
+    cost = model ? getModelRegistrySync().getCost(model) : null;
+  } catch (err) {
+    logger.debug({ err: err.message }, '[CacheEconomics] registry lookup failed');
+  }
+
+  const inputPerM = typeof cost?.input === 'number' ? cost.input : 0;
+  const outputPerM = typeof cost?.output === 'number' ? cost.output : 0;
+
+  // Registry cacheTtlMs/cacheMechanism (Phase 4 entries) win over the
+  // provider fallback; models.dev absolute cache prices win over multipliers.
+  const mechanism = cost?.cacheMechanism || defaults.mechanism;
+  const ttlMs = typeof cost?.cacheTtlMs === 'number' ? cost.cacheTtlMs : defaults.ttlMs;
+
+  const cacheReadPerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheRead === 'number' ? cost.cacheRead : inputPerM * defaults.readMult);
+  const cacheWritePerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheWrite === 'number' ? cost.cacheWrite : inputPerM * defaults.writeMult);
+
+  return {
+    inputPerM,
+    outputPerM,
+    cacheReadPerM,
+    cacheWritePerM,
+    ttlMs,
+    mechanism,
+    unknownPricing: !!cost?.unknown,
+  };
+}
+
+module.exports = {
+  PROVIDER_CACHE_DEFAULTS,
+  getProviderCacheDefaults,
+  resolveCacheEconomics,
+};