lynkr 9.14.12 → 9.14.14

package/src/clients/databricks.js

@@ -10,6 +10,30 @@ const { createBulkhead } = require("./resilience");
 const logger = require("../logger");
 const { STANDARD_TOOLS, STANDARD_TOOL_NAMES } = require("./standard-tools");
 const { convertAnthropicToolsToOpenRouter } = require("./openrouter-utils");
+
+/**
+ * Capability-boundary guard (issue #114): a caller that sets
+ * tool_choice "none" grants no tools. Substituting STANDARD_TOOLS widens
+ * the grant to shell execution with zero caller-visible signal, so every
+ * injection site below must consult this first. Matches the convention
+ * already used by the OpenRouter ingress path.
+ */
+function toolsDeclined(body) {
+  const tc = body?.tool_choice;
+  if (typeof tc === 'string') return tc.toLowerCase() === 'none';
+  if (tc && typeof tc === 'object') return tc.type === 'none';
+  return false;
+}
+
+/**
+ * Carry the caller's tool_choice through where the target expresses it.
+ * Only "none" is forwarded verbatim (the safety-critical value — the model
+ * must not be offered tools the caller forbade); everything else keeps the
+ * historical "auto" default so exotic shapes never 400 strict providers.
+ */
+function forwardToolChoice(body) {
+  return toolsDeclined(body) ? 'none' : 'auto';
+}
 const {
   detectModelFamily
 } = require("./bedrock-utils");
@@ -190,8 +214,9 @@ async function invokeDatabricks(body, _incomingHeaders = {}) {
   // Create a copy of body to avoid mutating the original
   const databricksBody = { ...body };
 
-  // Inject standard tools if client didn't send any (passthrough mode)
-  if (!Array.isArray(databricksBody.tools) || databricksBody.tools.length === 0) {
+  // Inject standard tools if client didn't send any (passthrough mode).
+  // Never when the caller declined tools (issue #114).
+  if (!toolsDeclined(body) && (!Array.isArray(databricksBody.tools) || databricksBody.tools.length === 0)) {
     databricksBody.tools = STANDARD_TOOLS;
     logger.debug({
       injectedToolCount: STANDARD_TOOLS.length,
@@ -535,7 +560,7 @@ async function invokeOllama(body, _incomingHeaders = {}) {
 
   if (!supportsTools) {
     toolsToSend = null;
-  } else if (injectToolsOllama && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
+  } else if (!toolsDeclined(body) && injectToolsOllama && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
   }
@@ -827,7 +852,7 @@ async function invokeOpenRouter(body, _incomingHeaders = {}) {
   let toolsToSend = body.tools;
   let toolsInjected = false;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -844,6 +869,10 @@ async function invokeOpenRouter(body, _incomingHeaders = {}) {
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
       toolsInjected
     }, "Sending tools to OpenRouter");
+  } else if (toolsDeclined(body)) {
+    // Explicit none with nothing to offer: state it so the upstream never
+    // defaults into tool use (issue #114).
+    openRouterBody.tool_choice = "none";
   }
 
   // Same pre-return 429 check as invokeMoonshot/invokeBaidu — see the comment
@@ -904,7 +933,7 @@ async function invokeEdenAI(body, _incomingHeaders = {}) {
   let toolsToSend = body.tools;
   let toolsInjected = false;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -921,6 +950,10 @@ async function invokeEdenAI(body, _incomingHeaders = {}) {
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
       toolsInjected
     }, "Sending tools to Eden AI");
+  } else if (toolsDeclined(body)) {
+    // Explicit none with nothing to offer: state it so the upstream never
+    // defaults into tool use (issue #114).
+    edenAIBody.tool_choice = "none";
   }
 
   return performJsonRequest(endpoint, { headers, body: edenAIBody }, "EdenAI");
@@ -1009,7 +1042,7 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
   let toolsToSend = body.tools;
   let toolsInjected = false;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -1022,7 +1055,7 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
   if (Array.isArray(toolsToSend) && toolsToSend.length > 0) {
     azureBody.tools = convertAnthropicToolsToOpenRouter(toolsToSend);
     azureBody.parallel_tool_calls = true;
-    azureBody.tool_choice = "auto";  // Explicitly enable tool use (helps GPT models understand they should use tools)
+    azureBody.tool_choice = forwardToolChoice(body);  // Explicitly enable tool use (helps GPT models understand they should use tools)
     logger.debug({
       toolCount: toolsToSend.length,
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
@@ -1457,7 +1490,7 @@ async function invokeOpenAI(body, _incomingHeaders = {}) {
   let toolsToSend = body.tools;
   let toolsInjected = false;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -1470,7 +1503,7 @@ async function invokeOpenAI(body, _incomingHeaders = {}) {
   if (Array.isArray(toolsToSend) && toolsToSend.length > 0) {
     openAIBody.tools = convertAnthropicToolsToOpenRouter(toolsToSend);
     openAIBody.parallel_tool_calls = false;  // Disable parallel tool calls - GPT often makes duplicate calls
-    openAIBody.tool_choice = "auto";  // Let the model decide when to use tools
+    openAIBody.tool_choice = forwardToolChoice(body);  // Let the model decide when to use tools
     logger.debug({
       toolCount: toolsToSend.length,
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
@@ -1538,7 +1571,7 @@ async function invokeAtlas(body) {
 
   let toolsToSend = body.tools;
   let toolsInjected = false;
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
   }
@@ -1546,7 +1579,7 @@ async function invokeAtlas(body) {
   if (toolsToSend.length > 0) {
     atlasBody.tools = convertAnthropicToolsToOpenRouter(toolsToSend);
     atlasBody.parallel_tool_calls = false;
-    atlasBody.tool_choice = "auto";
+    atlasBody.tool_choice = forwardToolChoice(body);
   }
 
   logger.debug({
@@ -1681,7 +1714,7 @@ async function invokeLlamaCpp(body, _incomingHeaders = {}) {
   let toolsInjected = false;
 
   const injectToolsLlamacpp = process.env.INJECT_TOOLS_LLAMACPP !== "false";
-  if (injectToolsLlamacpp && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
+  if (!toolsDeclined(body) && injectToolsLlamacpp && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -1695,7 +1728,7 @@ async function invokeLlamaCpp(body, _incomingHeaders = {}) {
 
   if (Array.isArray(toolsToSend) && toolsToSend.length > 0) {
     llamacppBody.tools = convertAnthropicToolsToOpenRouter(toolsToSend);
-    llamacppBody.tool_choice = "auto";
+    llamacppBody.tool_choice = forwardToolChoice(body);
     logger.debug({
       toolCount: toolsToSend.length,
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
@@ -1779,7 +1812,7 @@ async function invokeLMStudio(body, _incomingHeaders = {}) {
   let toolsToSend = body.tools;
   let toolsInjected = false;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     toolsInjected = true;
     logger.debug({
@@ -1791,7 +1824,7 @@ async function invokeLMStudio(body, _incomingHeaders = {}) {
 
   if (Array.isArray(toolsToSend) && toolsToSend.length > 0) {
     lmstudioBody.tools = convertAnthropicToolsToOpenRouter(toolsToSend);
-    lmstudioBody.tool_choice = "auto";
+    lmstudioBody.tool_choice = forwardToolChoice(body);
     logger.debug({
       toolCount: toolsToSend.length,
       toolNames: toolsToSend.map(t => t.name || t.function?.name),
@@ -1938,7 +1971,7 @@ async function invokeBedrock(body, _incomingHeaders = {}) {
   // Inject standard tools if needed
   let toolsToSend = body.tools;
 
-  if (!Array.isArray(toolsToSend) || toolsToSend.length === 0) {
+  if (!toolsDeclined(body) && (!Array.isArray(toolsToSend) || toolsToSend.length === 0)) {
     toolsToSend = STANDARD_TOOLS;
     logger.debug({
       injectedToolCount: STANDARD_TOOLS.length,
@@ -2199,7 +2232,7 @@ async function invokeZai(body, _incomingHeaders = {}) {
       zaiBody.tools = tools;
       // Use "auto" to let the model decide when to use tools
       // "required" was forcing tools even for simple greetings
-      zaiBody.tool_choice = "auto";
+      zaiBody.tool_choice = forwardToolChoice(body);
       zaiBody.parallel_tool_calls = false;  // Disabled: duplicate-call risk
     }
 
@@ -2230,8 +2263,9 @@ async function invokeZai(body, _incomingHeaders = {}) {
     // that's a different bug — add zai to DEFAULT_OPENAI_SSE_PROVIDERS then,
     // don't reintroduce this override.
 
-    // Inject standard tools if client didn't send any (passthrough mode)
-    if (!Array.isArray(zaiBody.tools) || zaiBody.tools.length === 0) {
+    // Inject standard tools if client didn't send any (passthrough mode).
+    // Never when the caller declined tools (issue #114).
+    if (!toolsDeclined(body) && (!Array.isArray(zaiBody.tools) || zaiBody.tools.length === 0)) {
       zaiBody.tools = STANDARD_TOOLS;
       logger.debug({
         injectedToolCount: STANDARD_TOOLS.length,
@@ -2404,7 +2438,7 @@ async function invokeMoonshot(body, _incomingHeaders = {}) {
 
   if (Array.isArray(body.tools) && body.tools.length > 0) {
     moonshotBody.tools = convertAnthropicToolsToOpenRouter(body.tools);
-    moonshotBody.tool_choice = "auto";
+    moonshotBody.tool_choice = forwardToolChoice(body);
     moonshotBody.parallel_tool_calls = false;
   }
 
@@ -2558,7 +2592,7 @@ async function invokeBaidu(body, _incomingHeaders = {}) {
 
   if (Array.isArray(body.tools) && body.tools.length > 0) {
     baiduBody.tools = convertAnthropicToolsToOpenRouter(body.tools);
-    baiduBody.tool_choice = "auto";
+    baiduBody.tool_choice = forwardToolChoice(body);
     baiduBody.parallel_tool_calls = false;
   }
 
@@ -2696,7 +2730,7 @@ async function invokeFireworks(body, _incomingHeaders = {}) {
 
   if (Array.isArray(body.tools) && body.tools.length > 0) {
     fireworksBody.tools = convertAnthropicToolsToOpenRouter(body.tools);
-    fireworksBody.tool_choice = "auto";
+    fireworksBody.tool_choice = forwardToolChoice(body);
     fireworksBody.parallel_tool_calls = false;
   }
 
@@ -2956,7 +2990,7 @@ async function invokeOrcaRouter(body, _incomingHeaders = {}) {
 
   if (Array.isArray(body.tools) && body.tools.length > 0) {
     orcaBody.tools = convertAnthropicToolsToOpenRouter(body.tools);
-    orcaBody.tool_choice = "auto";
+    orcaBody.tool_choice = forwardToolChoice(body);
     orcaBody.parallel_tool_calls = false;
   }
 
@@ -3767,6 +3801,7 @@ async function invokeModel(body, options = {}) {
       candidates: routingResult.candidates ?? null,
       pinned: routingResult.pinned ? 1 : 0,
       switch_reason: routingResult.switch_reason ?? null,
+      ...telemetry.jevFields(routingResult),
       cache_decision: routingResult._cacheDecision ?? null,
       cache_read_tokens: result.json?.usage?.cache_read_input_tokens ?? null,
       cache_creation_tokens: result.json?.usage?.cache_creation_input_tokens ?? null,
@@ -4002,6 +4037,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      ...telemetry.jevFields(routingResult),
       cache_decision: routingResult._cacheDecision ?? null,
       });
 
@@ -4115,6 +4151,7 @@ async function invokeModel(body, options = {}) {
           candidates: routingResult.candidates ?? null,
           pinned: routingResult.pinned ? 1 : 0,
           switch_reason: routingResult.switch_reason ?? null,
+      ...telemetry.jevFields(routingResult),
           cache_decision: routingResult._cacheDecision ?? null,
         });
 
@@ -4212,6 +4249,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      ...telemetry.jevFields(routingResult),
       cache_decision: routingResult._cacheDecision ?? null,
       cache_read_tokens: fallbackResult.json?.usage?.cache_read_input_tokens ?? null,
       cache_creation_tokens: fallbackResult.json?.usage?.cache_creation_input_tokens ?? null,
@@ -4273,6 +4311,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      ...telemetry.jevFields(routingResult),
       cache_decision: routingResult._cacheDecision ?? null,
       });
 
@@ -4364,6 +4403,8 @@ function destroyHttpAgents() {
 
 module.exports = {
   invokeModel,
+  toolsDeclined,
+  forwardToolChoice,
   computeCostUsd,
   convertOpenAIToAnthropic,
   invokeAzureAnthropic,

package/src/clients/openai-format.js

@@ -69,12 +69,47 @@ function convertOpenAIToAnthropic(openaiRequest) {
           } else if (part.type === "image_url") {
             const url = part.image_url?.url || "";
             if (url.startsWith("data:")) {
-              const match = url.match(/^data:(image\/[^;]+);base64,(.+)$/);
+              // Accept base64 and base64url alphabets; anything else falls
+              // through to url-shape (provider validates downstream).
+              const match = url.match(/^data:([^;]+);base64,([A-Za-z0-9+/=_-]+)$/);
               if (match) {
-                return { type: "image", source: { type: "base64", media_type: match[1], data: match[2] } };
+                // Image payloads become Anthropic image blocks; anything
+                // else (e.g. application/pdf) becomes a document block so
+                // the bytes survive the translation (issue #115).
+                if (match[1].startsWith("image/")) {
+                  return { type: "image", source: { type: "base64", media_type: match[1], data: match[2] } };
+                }
+                return { type: "document", source: { type: "base64", media_type: match[1], data: match[2] } };
               }
             }
             return { type: "image", source: { type: "url", url } };
+          } else if (part.type === "file" && part.file) {
+            // OpenAI file part → Anthropic document block. file_data carries
+            // a data URL whose media type + base64 payload map directly
+            // (issue #115: previously forwarded unchanged → upstream 400).
+            const dataUrl = part.file.file_data || "";
+            const match = typeof dataUrl === "string" && dataUrl.match(/^data:([^;]+);base64,([A-Za-z0-9+/=_-]+)$/);
+            if (match) {
+              return { type: "document", source: { type: "base64", media_type: match[1], data: match[2] } };
+            }
+            const err = new Error(
+              `Cannot translate OpenAI file part "${part.file.filename || "unnamed"}" to Anthropic format: ` +
+              `file_data must be a base64 data: URL.`
+            );
+            err.statusCode = 400;
+            err.code = "unsupported_content_block";
+            err.isOperational = true;
+            throw err;
+          } else if (part.type === "input_audio") {
+            // No Anthropic equivalent — fail loudly naming the block rather
+            // than forwarding bytes the upstream rejects opaquely (issue #115).
+            const err = new Error(
+              "Cannot translate OpenAI input_audio content to Anthropic format: audio input is not supported."
+            );
+            err.statusCode = 400;
+            err.code = "unsupported_content_block";
+            err.isOperational = true;
+            throw err;
           } else if (part.type === "document" || part.type === "image") {
             return part;
           }

package/src/clients/openrouter-utils.js

@@ -208,6 +208,26 @@ function convertAnthropicMessagesToOpenRouter(anthropicMessages) {
         }
         let message;
         if (imageUrls.length === 0) {
+          // Fail loudly instead of emptying: an attachment-only message
+          // whose blocks have no OpenAI representation (document, file,
+          // video, audio) must error naming the block, not become "" and
+          // earn a confident 2xx answer about an attachment never received
+          // (issue #115). Thinking-only turns are exempt — thinking models
+          // legitimately send those.
+          const unconvertible = content
+            .filter((b) => b && typeof b === 'object'
+              && ['document', 'file', 'video', 'audio', 'input_audio'].includes(b.type))
+            .map((b) => b.type);
+          if (unconvertible.length > 0 && !textContent) {
+            const err = new Error(
+              `Cannot convert ${[...new Set(unconvertible)].join('/')} content block(s) to OpenAI format: ` +
+              `no equivalent representation exists.`
+            );
+            err.statusCode = 400;
+            err.code = 'unsupported_content_block';
+            err.isOperational = true;
+            throw err;
+          }
           message = { role: msg.role, content: textContent || '' };
         } else {
           const parts = [];

package/src/orchestrator/index.js

@@ -1,5 +1,5 @@
 const config = require("../config");
-const { invokeModel } = require("../clients/databricks");
+const { invokeModel, toolsDeclined } = require("../clients/databricks");
 const { appendTurnToSession } = require("../sessions/record");
 const { upsertSession } = require("../sessions/store");
 const policy = require("../policy");
@@ -1113,15 +1113,50 @@ function sanitizePayload(payload) {
     if (tools) clean.tools = tools;
     else delete clean.tools;
   } else if (providerType === "azure-anthropic") {
-    const tools = sanitiseAzureTools(clean.tools);
-    clean.tools =
-      tools && tools.length > 0
-        ? tools
-        : DEFAULT_AZURE_TOOLS.map((tool) => ({
-          name: tool.name,
-          input_schema: JSON.parse(JSON.stringify(tool.input_schema)),
-        }));
-    delete clean.tool_choice;
+    // toolsDeclined is imported top-level from ../clients/databricks
+    // alongside invokeModel — same module instance, no inline require
+    // needed (a guarded re-require would imply a failure mode that cannot
+    // occur without breaking everything else first).
+    // A caller that declined tools gets none — never substitute defaults
+    // (issue #114: substitution here turned tool_choice "none" into an
+    // unrelated tool set with the choice deleted).
+    if (toolsDeclined(clean)) {
+      delete clean.tools;
+      clean.tool_choice = "none";
+    } else {
+      const tools = sanitiseAzureTools(clean.tools);
+      if (Array.isArray(clean.tools) && clean.tools.length > 0 && (!tools || tools.length === 0)) {
+        // The caller declared tools and every one was rejected: substituting
+        // unrelated defaults would silently change the contract, so fail
+        // loudly naming the tools instead (issue #114).
+        const names = clean.tools
+          .map((t) => t?.name || t?.function?.name || "unnamed")
+          .filter(Boolean);
+        const err = new Error(
+          `azure-anthropic supports only built-in tools (WebSearch, WebFetch, Bash family); ` +
+          `rejected tool(s): ${names.join(", ")}. Remove them or route to a provider that serves them.`
+        );
+        err.statusCode = 400;
+        err.code = "unsupported_tools";
+        err.isOperational = true;
+        throw err;
+      }
+      const declaredNames = Array.isArray(clean.tools)
+        ? clean.tools.map((t) => t?.name || t?.function?.name).filter(Boolean)
+        : [];
+      clean.tools =
+        tools && tools.length > 0
+          ? tools
+          : DEFAULT_AZURE_TOOLS.map((tool) => ({
+            name: tool.name,
+            input_schema: JSON.parse(JSON.stringify(tool.input_schema)),
+          }));
+      const dropped = declaredNames.filter((n) => !(tools || []).some((k) => k.name === n));
+      if (dropped.length > 0) {
+        logger.debug({ dropped }, '[azure-anthropic] Partial tool substitution: unlisted tools dropped');
+      }
+      delete clean.tool_choice;
+    }
   } else if (providerType === "ollama") {
     // Always pass tools through to Ollama in Anthropic format when they exist.
     // Ollama (v0.14+ native /v1/messages) accepts the Anthropic tool shape; if
@@ -3249,6 +3284,8 @@ function trimLoopMessages(messages, max) {
 
 module.exports = {
   processMessage,
+  // Exported for unit testing of sanitizePayload tool handling.
+  sanitizePayload,
   // Exported for unit testing of response-metadata conversion.
   toAnthropicResponse,
   // Exported for unit testing of loop trimming (task-preservation contract).

package/src/prompts/system.js

@@ -73,61 +73,53 @@ function compressToolDescriptions(tools, mode = null) {
   // 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: input_schema.type || "object",
-        properties: {},
-        required: input_schema.required || [],
-      }
+  // Every other key on the function object (strict, and any future keywords)
+  // passes through untouched — an allowlist here silently drops enforceable
+  // constraints (issue #116).
+  tools = tools.map(tool => {
+    if (tool?.type !== "function" || !tool.function) return tool;
+    const { parameters, ...kept } = tool.function;
+    return {
+      ...kept,
+      input_schema: parameters || { type: "object", properties: {} },
     };
+  });
 
-    // Add minimal description only if it exists
-    if (tool.description) {
-      compressed.description = compressText(tool.description, 50);
+  return tools.map(tool => {
+    // Copy everything through; compression below targets description TEXT
+    // only, never schema shape (issue #116: an allowlist rebuild silently
+    // dropped strict/pattern/const/oneOf and misleveled additionalProperties).
+    const out = { ...tool };
+    if (typeof out.description === 'string' && out.description) {
+      out.description = compressText(out.description, 50);
     }
-
-    // Compress property descriptions
-    if (input_schema.properties) {
-      for (const [key, value] of Object.entries(input_schema.properties)) {
-        compressed.input_schema.properties[key] = {
-          type: value.type,
-        };
-
-        // Only include description if it's critical
-        if (value.description && !isObviousFromName(key)) {
-          compressed.input_schema.properties[key].description = compressText(value.description, 30);
-        }
-
-        // Preserve enum, format, and other critical constraints
-        if (value.enum) compressed.input_schema.properties[key].enum = value.enum;
-        if (value.format) compressed.input_schema.properties[key].format = value.format;
-        if (value.items) compressed.input_schema.properties[key].items = value.items;
-        if (value.additionalProperties !== undefined) {
-          compressed.input_schema.properties[key].additionalProperties = value.additionalProperties;
-        }
-      }
+    if (out.input_schema && typeof out.input_schema === 'object') {
+      out.input_schema = compressSchemaDescriptions(out.input_schema, null);
     }
+    return out;
+  });
+}
 
-    // Preserve additionalProperties if set
-    if (input_schema.additionalProperties !== undefined) {
-      compressed.input_schema.additionalProperties = input_schema.additionalProperties;
+/**
+ * Recursively compress `description` strings in a JSON Schema, preserving
+ * every other keyword byte-for-byte in shape. Descriptions obvious from the
+ * property name are dropped, the rest truncated — matching the historical
+ * minimal-mode behavior without an allowlist that lags the spec.
+ */
+function compressSchemaDescriptions(node, key) {
+  if (Array.isArray(node)) return node.map((v) => compressSchemaDescriptions(v, key));
+  if (node && typeof node === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+      if (k === 'description' && typeof v === 'string') {
+        if (!isObviousFromName(key)) out[k] = compressText(v, 30);
+      } else {
+        out[k] = compressSchemaDescriptions(v, k);
+      }
     }
-
-    return compressed;
-  });
+    return out;
+  }
+  return node;
 }
 
 /**

package/src/routing/affinity-store.js

@@ -59,9 +59,25 @@ function _db() {
       // 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.
+      // NOTE (2026-09-18): superseded by the dedicated session_cache_state
+      // table below. The column stays (and old blobs stay readable nowhere —
+      // loadCacheState reads the new table), but NOTHING writes it anymore:
+      // sharing the pins table let cache-only rows (no tier) be served as
+      // routing pins, permanently locking sessions with no escalation path.
       if (!cols.has("cache_state")) {
         db.exec("ALTER TABLE session_pins ADD COLUMN cache_state TEXT");
       }
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS session_cache_state (
+          session_id         TEXT PRIMARY KEY,
+          warm_prefix_tokens INTEGER NOT NULL,
+          provider           TEXT NOT NULL,
+          model              TEXT,
+          last_request_at    INTEGER NOT NULL,
+          ttl_ms             INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_cache_state_ts ON session_cache_state(last_request_at);
+      `);
       schemaEnsured = true;
     } catch (err) {
       degradation.record("feedback", err);
@@ -168,9 +184,10 @@ 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.
+ * Lives in its OWN table (session_cache_state), deliberately separate from
+ * session_pins: the old piggyback design wrote tier-less rows that got
+ * served as routing pins, locking sessions with no escalation path.
+ * Best-effort like everything else in this module.
  *
  * @param {string} sessionId
  * @param {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}} state
@@ -180,21 +197,25 @@ function saveCacheState(sessionId, state) {
   const db = _db();
   if (!db) return;
   try {
-    const json = JSON.stringify(state);
-    const res = _stmt(
+    _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);
-    }
+      "cache_state_upsert",
+      `INSERT INTO session_cache_state (session_id, warm_prefix_tokens, provider, model, last_request_at, ttl_ms)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         warm_prefix_tokens = excluded.warm_prefix_tokens,
+         provider = excluded.provider,
+         model = excluded.model,
+         last_request_at = excluded.last_request_at,
+         ttl_ms = excluded.ttl_ms`
+    ).run(
+      sessionId,
+      state.warmPrefixTokens ?? 0,
+      state.provider,
+      state.model ?? null,
+      state.lastRequestAt ?? Date.now(),
+      state.ttlMs ?? 5 * 60 * 1000
+    );
   } catch (err) {
     degradation.record("feedback", err);
   }
@@ -216,11 +237,16 @@ function loadCacheState(sessionId) {
     const row = _stmt(
       db,
       "cache_state_load",
-      "SELECT cache_state FROM session_pins WHERE session_id = ?"
+      "SELECT warm_prefix_tokens, provider, model, last_request_at, ttl_ms FROM session_cache_state 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;
+    if (!row) return null;
+    return {
+      warmPrefixTokens: Number(row.warm_prefix_tokens) || 0,
+      provider: row.provider,
+      model: row.model ?? null,
+      lastRequestAt: Number(row.last_request_at) || 0,
+      ttlMs: Number(row.ttl_ms) || 5 * 60 * 1000,
+    };
   } catch (err) {
     degradation.record("feedback", err);
     return null;