lynkr 9.5.0 → 9.7.0

package/src/clients/openrouter-utils.js

@@ -1,4 +1,5 @@
 const logger = require("../logger");
+const { repairToolCallIds } = require("./tool-call-repair");
 
 /**
  * Convert Anthropic tool format to OpenAI/OpenRouter format
@@ -146,35 +147,11 @@ function convertAnthropicMessagesToOpenRouter(anthropicMessages) {
     }
   }
 
-  // Fix tool_call_id mismatches: ensure every tool message's tool_call_id
-  // matches the id in the preceding assistant's tool_calls array.
-  // IDs can drift when multiple conversion layers (Anthropic↔OpenAI) each
-  // generate their own IDs.
-  for (let i = 0; i < converted.length; i++) {
-    const msg = converted[i];
-    if (msg.role !== 'tool') continue;
-
-    // Find the nearest preceding assistant with tool_calls
-    for (let j = i - 1; j >= 0; j--) {
-      const prev = converted[j];
-      if (prev.role === 'user') break;
-      if (prev.role === 'assistant' && Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0) {
-        if (!prev.tool_calls.some(tc => tc.id === msg.tool_call_id)) {
-          // Mismatch — pick the first unmatched tool_call id
-          const usedIds = new Set();
-          for (let k = j + 1; k < converted.length; k++) {
-            if (converted[k].role === 'tool' && k !== i) usedIds.add(converted[k].tool_call_id);
-          }
-          const available = prev.tool_calls.find(tc => !usedIds.has(tc.id));
-          if (available) {
-            logger.info({ from: msg.tool_call_id, to: available.id }, "Fixed tool_call_id mismatch");
-            msg.tool_call_id = available.id;
-          }
-        }
-        break;
-      }
-    }
-  }
+  // Repair tool_call_id linkage before handing to OpenAI-compatible providers:
+  // backfill blank assistant tool_call ids, re-link drifted/blank tool_call_ids
+  // to the nearest preceding assistant tool_call, and drop orphan tool results.
+  // Moonshot/Kimi (and others) hard-400 on any empty or unmatched tool_call_id.
+  repairToolCallIds(converted);
 
   // Kimi/Moonshot (and some OpenAI-compatible APIs) reject a message whose
   // content is an empty string with "Invalid request: tokenization failed".

package/src/clients/prompt-cache-injection.js

@@ -119,6 +119,51 @@ function needsCacheInjection(provider) {
   return EXPLICIT_CACHE_PROVIDERS.has(provider);
 }
 
+// Model families that do NOT support cache_control breakpoints. cache_control
+// is an Anthropic construct; on aggregating providers (Bedrock, OpenRouter) it
+// only applies to models that natively understand it (Claude, and Gemini via
+// proxy). Injecting markers onto these families produces request shapes the
+// upstream model rejects or silently ignores.
+const NON_CACHE_MODEL_PATTERNS = [
+  /(^|[./-])titan/i,
+  /(^|[./-])nova/i,
+  /(^|[./-])llama/i,
+  /(^|[./-])mistral/i,
+  /(^|[./-])mixtral/i,
+  /(^|[./-])cohere/i,
+  /(^|[./-])command/i, // cohere command-*
+  /(^|[./-])j2/i,      // ai21 jurassic
+  /(^|[./-])jamba/i,
+  /(^|[./-])deepseek/i,
+  /(^|[./-])qwen/i,
+  /(^|[./-])gpt/i,
+  /(^|[./-])openai/i,
+];
+
+/**
+ * Determine whether the model targeted by this request supports cache_control.
+ *
+ * Some providers in EXPLICIT_CACHE_PROVIDERS (notably bedrock and openrouter)
+ * route to many model families, only some of which understand cache_control.
+ * This guard inspects the resolved model id and blocks injection for families
+ * that are known not to support it. When the model id is absent or
+ * unrecognized, injection is allowed (fail-open) — Claude/Gemini-style ids and
+ * Anthropic-only providers fall through to true.
+ *
+ * @param {Object} body - Request body (may carry the resolved model id)
+ * @param {string} provider - Provider name
+ * @returns {boolean}
+ */
+function modelSupportsCacheControl(body, provider) {
+  // Providers that only ever route to Anthropic models always support it.
+  if (provider === 'azure-anthropic' || provider === 'databricks') return true;
+
+  const modelId = body && (body._tierModel || body.model);
+  if (!modelId || typeof modelId !== 'string') return true; // unknown → fail open
+
+  return !NON_CACHE_MODEL_PATTERNS.some(re => re.test(modelId));
+}
+
 /**
  * Inject provider-side prompt caching into the request body.
  * Call this before sending to the provider.
@@ -129,12 +174,31 @@ function needsCacheInjection(provider) {
  */
 function injectPromptCaching(body, provider) {
   if (!needsCacheInjection(provider)) return 0;
+  // Gate on model capability: a provider may support cache_control in general
+  // while the specific routed model does not.
+  if (!modelSupportsCacheControl(body, provider)) return 0;
+  // If the client (e.g. Claude Code) already attached cache_control breakpoints,
+  // don't add more. Anthropic caps at 4 breakpoints per request and stacking ours
+  // on top has caused 400/429 errors on OAuth subscription requests.
+  if (hasExistingCacheControl(body)) return 0;
   return injectAnthropicCacheBreakpoints(body);
 }
 
+function hasExistingCacheControl(body) {
+  if (!body) return false;
+  const scan = (obj) => {
+    if (!obj || typeof obj !== 'object') return false;
+    if (Array.isArray(obj)) return obj.some(scan);
+    if (obj.cache_control) return true;
+    return Object.values(obj).some(scan);
+  };
+  return scan(body.system) || scan(body.messages) || scan(body.tools);
+}
+
 module.exports = {
   injectPromptCaching,
   injectAnthropicCacheBreakpoints,
   injectGeminiCacheBreakpoints,
   needsCacheInjection,
+  modelSupportsCacheControl,
 };

package/src/clients/responses-format.js

@@ -8,6 +8,7 @@
  */
 
 const logger = require("../logger");
+const { repairToolCallIds } = require("./tool-call-repair");
 
 /**
  * Map client tool names back to Lynkr tool names
@@ -203,6 +204,12 @@ function convertResponsesToChat(responsesRequest) {
         return cleaned;
       });
 
+    // Repair tool_call_id linkage now, before anything downstream consumes the
+    // converted array. Codex bundled-plugin (Browser/Computer-use) calls and
+    // synthetic tool outputs can arrive without a usable call_id, which
+    // otherwise flattens to a blank tool_call_id and 400s at the provider.
+    repairToolCallIds(messages);
+
     logger.info({
       originalCount: input.length,
       filteredCount: messages.length,

package/src/clients/tool-call-repair.js

@@ -0,0 +1,130 @@
+/**
+ * Tool-call id repair for OpenAI-format message arrays.
+ *
+ * OpenAI-compatible providers (Moonshot/Kimi, OpenAI, OpenRouter, …) reject a
+ * request with `Invalid request: tool_call_id <x> is not found` whenever a
+ * `tool` message references an id that has no matching entry in a preceding
+ * assistant `tool_calls` array. This happens in practice when:
+ *
+ *   1. A `tool` message's tool_call_id is empty/missing — e.g. Codex Desktop's
+ *      bundled-plugin (Browser/Computer-use) function_call_output items, and
+ *      synthetic "unsupported call: shell" outputs, arrive without a usable
+ *      `call_id`, so both the assistant tool_call id and the tool_call_id
+ *      flatten to "". (The error shows a blank id: "tool_call_id  is not found".)
+ *   2. An assistant tool_calls entry has an empty/missing id.
+ *   3. Ids drift across multiple conversion layers (Responses↔Chat↔Anthropic),
+ *      leaving a `tool` message pointing at an id no assistant ever issued.
+ *
+ * This helper repairs all three in place: it backfills synthetic ids onto
+ * assistant tool_calls that lack one, re-links each `tool` message to an unused
+ * tool_call id on the nearest preceding assistant, and drops any `tool` message
+ * that has no assistant tool_call to attach to (a dangling result is a hard
+ * 400 at the provider, so dropping it is strictly safer than forwarding it).
+ *
+ * @module clients/tool-call-repair
+ */
+
+const logger = require("../logger");
+
+function isBlankId(id) {
+  return !id || String(id).trim() === "";
+}
+
+/**
+ * Repair tool_call_id linkage in an OpenAI chat-format message array, in place.
+ *
+ * @param {Array} messages - OpenAI chat-format messages (role/content, with
+ *   assistant `tool_calls` and `tool` `tool_call_id`). Mutated in place.
+ * @returns {Array} the same array reference, with orphan tool messages removed.
+ */
+function repairToolCallIds(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+
+  let synthCounter = 0;
+  const nextSyntheticId = () => `call_auto_${synthCounter++}`;
+
+  // Pass 1 — guarantee every assistant tool_call has a non-empty id.
+  for (const msg of messages) {
+    if (msg && msg.role === "assistant" && Array.isArray(msg.tool_calls)) {
+      for (const tc of msg.tool_calls) {
+        if (tc && isBlankId(tc.id)) {
+          tc.id = nextSyntheticId();
+          logger.info({ assignedId: tc.id }, "Backfilled missing assistant tool_call id");
+        }
+      }
+    }
+  }
+
+  // Pass 2 — relink (or drop) every tool message.
+  const repaired = [];
+  let dropped = 0;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!msg || msg.role !== "tool") {
+      repaired.push(msg);
+      continue;
+    }
+
+    // Nearest preceding assistant that carries tool_calls (stop at a user turn).
+    let assistant = null;
+    for (let j = i - 1; j >= 0; j--) {
+      const prev = messages[j];
+      if (!prev) continue;
+      if (prev.role === "user") break;
+      if (prev.role === "assistant" && Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0) {
+        assistant = prev;
+        break;
+      }
+    }
+
+    const matches =
+      assistant &&
+      !isBlankId(msg.tool_call_id) &&
+      assistant.tool_calls.some((tc) => tc.id === msg.tool_call_id);
+
+    if (matches) {
+      repaired.push(msg);
+      continue;
+    }
+
+    if (assistant) {
+      // Pick the first tool_call id not already consumed by an earlier result.
+      const usedIds = new Set(
+        repaired.filter((r) => r && r.role === "tool" && r.tool_call_id).map((r) => r.tool_call_id)
+      );
+      const available = assistant.tool_calls.find((tc) => !usedIds.has(tc.id));
+      if (available) {
+        logger.info(
+          { from: isBlankId(msg.tool_call_id) ? "(blank)" : msg.tool_call_id, to: available.id },
+          "Repaired tool_call_id linkage"
+        );
+        msg.tool_call_id = available.id;
+        repaired.push(msg);
+        continue;
+      }
+    }
+
+    // No assistant tool_call to attach to — drop the orphan rather than let it
+    // 400 the whole request at the provider.
+    dropped++;
+    logger.warn(
+      {
+        tool_call_id: isBlankId(msg.tool_call_id) ? "(blank)" : msg.tool_call_id,
+        contentPreview: typeof msg.content === "string" ? msg.content.slice(0, 80) : "",
+      },
+      "Dropped orphan tool message with no matching tool_call"
+    );
+  }
+
+  if (dropped > 0) {
+    logger.info({ dropped, before: messages.length, after: repaired.length }, "Removed orphan tool messages");
+  }
+
+  // Rewrite the array contents in place so callers holding this reference see
+  // the repaired result.
+  messages.length = 0;
+  for (const m of repaired) messages.push(m);
+  return messages;
+}
+
+module.exports = { repairToolCallIds, isBlankId };

package/src/config/index.js

@@ -518,6 +518,12 @@ const agentsDefaultModel = process.env.AGENTS_DEFAULT_MODEL ?? "haiku";
 const agentsMaxSteps = Number.parseInt(process.env.AGENTS_MAX_STEPS ?? "15", 10);
 const agentsTimeout = Number.parseInt(process.env.AGENTS_TIMEOUT ?? "120000", 10);
 
+// Task decomposition configuration (opt-in; builds on the agents subsystem).
+// Single env toggle; everything else is hardcoded below.
+const taskDecompositionEnabled = process.env.TASK_DECOMPOSITION_ENABLED === "true";
+
+// Tier-aware fallback (escalate-then-demote) is always on (hardcoded).
+
 // LLM Audit logging configuration
 const auditEnabled = process.env.LLM_AUDIT_ENABLED === "true"; // default false
 const auditLogFile = process.env.LLM_AUDIT_LOG_FILE ?? path.join(process.cwd(), "logs", "llm-audit.log");
@@ -775,6 +781,23 @@ var config = {
     maxSteps: Number.isNaN(agentsMaxSteps) ? 15 : agentsMaxSteps,
     timeout: Number.isNaN(agentsTimeout) ? 120000 : agentsTimeout,
   },
+  taskDecomposition: {
+    enabled: taskDecompositionEnabled, // only env-driven knob (TASK_DECOMPOSITION_ENABLED)
+    // Hardcoded defaults — tune here if needed.
+    shadow: false,
+    planModel: "sonnet",
+    synthModel: "sonnet",
+    minConfidence: 0.5,
+    gate: {
+      minComplexity: 60,
+      minTokens: 3000,
+      maxSubtasks: 6,
+      minIndependentUnits: 2,
+    },
+  },
+  tierFallback: {
+    enabled: true, // always on (hardcoded): escalate-then-demote on provider failure; floor = SIMPLE
+  },
   tests: {
     defaultCommand: testDefaultCommand ? testDefaultCommand.trim() : null,
     defaultArgs: testDefaultArgs,

package/src/context/output-format-guard.js

@@ -0,0 +1,99 @@
+/**
+ * Output Format Guard
+ *
+ * Appends a short formatting instruction to the system prompt so weaker
+ * backends (Moonshot/Kimi, Ollama, etc.) stop emitting mangled ASCII/Unicode
+ * box-drawing "diagrams" that render as garbage in clients. The actual backend
+ * is decided by tier routing — so even when the client asks for "claude-opus",
+ * the request may be served by a model that formats poorly. This normalizes the
+ * presentation without changing which model serves the request.
+ *
+ * Always-on (no env flag). It is skipped only for Claude-family backends, which
+ * already produce clean GitHub-flavored markdown — injecting there would just
+ * waste tokens. The skip biases toward injecting: if we can't tell, we inject
+ * (a false-inject is harmless ~50 tokens; a false-skip leaves the garble).
+ *
+ * Keyed off the ROUTING-RESOLVED provider/model, never the client's requested
+ * body.model (which is just a label once tier routing is on).
+ *
+ * @module context/output-format-guard
+ */
+
+const logger = require("../logger");
+
+const MARKER = "[fmt-guard]";
+
+// Model names that already produce clean markdown.
+const CLEAN_FORMATTER_RE = /\b(claude|sonnet|opus|haiku)\b/i;
+// Providers that are always Claude-backed.
+const CLEAN_PROVIDERS = new Set(["azure-anthropic"]);
+
+const GUARD_TEXT =
+  `${MARKER} Formatting rules for your response: use plain GitHub-flavored markdown only. ` +
+  "Do NOT draw diagrams or boxes with ASCII or Unicode line-drawing characters " +
+  "(such as ┌ ─ │ └ ├ ┤ ┬ ┴ ╔ ═ ║), and do NOT wrap headings or code in decorative borders. " +
+  "Represent structure and relationships with normal markdown headings, nested bullet lists, " +
+  "numbered lists, or tables. Use standard triple-backtick fenced code blocks for code. " +
+  "Keep code, file paths, commands, and URLs exact.";
+
+/**
+ * Whether the resolved backend already formats cleanly (→ skip injection).
+ * @param {string} provider - routing-resolved provider
+ * @param {string} model - routing-resolved model (NOT the client's requested model)
+ * @returns {boolean}
+ */
+function producesCleanMarkdown(provider, model) {
+  if (CLEAN_PROVIDERS.has(String(provider || "").toLowerCase())) return true;
+  if (model && CLEAN_FORMATTER_RE.test(String(model))) return true;
+  return false;
+}
+
+/**
+ * Append the guard text to a system prompt that may be a string or an array of
+ * Anthropic content blocks. Idempotent via MARKER. Pure — returns the new value.
+ */
+function appendToSystem(system, text) {
+  // String (or empty) system prompt.
+  if (system == null || typeof system === "string") {
+    const base = system || "";
+    if (base.includes(MARKER)) return base;
+    return base ? `${base}\n\n${text}` : text;
+  }
+  // Anthropic array-of-blocks system prompt.
+  if (Array.isArray(system)) {
+    const already = system.some(
+      (b) => typeof b?.text === "string" && b.text.includes(MARKER)
+    );
+    if (already) return system;
+    return [...system, { type: "text", text }];
+  }
+  return system;
+}
+
+/**
+ * Inject the formatting guard into body.system in place, unless the resolved
+ * backend already formats cleanly. Always-on; idempotent.
+ *
+ * @param {object} body - request body (mutated in place)
+ * @param {object} [opts]
+ * @param {string} [opts.provider] - routing-resolved provider
+ * @param {string} [opts.model] - routing-resolved model
+ * @returns {object} body
+ */
+function injectFormatGuard(body, opts = {}) {
+  if (!body) return body;
+  const { provider, model } = opts;
+  if (producesCleanMarkdown(provider, model)) return body;
+
+  body.system = appendToSystem(body.system, GUARD_TEXT);
+  logger.debug({ provider, model }, "[FormatGuard] Injected markdown formatting guard");
+  return body;
+}
+
+module.exports = {
+  injectFormatGuard,
+  producesCleanMarkdown,
+  appendToSystem,
+  MARKER,
+  GUARD_TEXT,
+};

package/src/orchestrator/index.js

@@ -965,22 +965,48 @@ function stripThinkingBlocks(text) {
 /**
  * Convert legacy Ollama /api/chat response to Anthropic Messages format.
  * Used when Ollama < v0.14.0 (no native Anthropic endpoint).
+ *
+ * Critical for MiniMax M2/M2.5 (and other interleaved-thinking models):
+ * preserve <think>...</think> from message.content AND Ollama's native
+ * message.thinking field as Anthropic thinking blocks. Dropping them breaks
+ * the model's long-horizon agent loop — vendor-quantified at Tau^2 -35.9%,
+ * BrowseComp -40.1% (https://www.minimax.io/news/why-is-interleaved-thinking-important-for-m2).
  */
 function ollamaToAnthropicResponse(ollamaResponse, requestedModel) {
   const message = ollamaResponse?.message ?? {};
-  const rawContent = message.content || "";
+  const rawContent = typeof message.content === "string" ? message.content : "";
+  const nativeThinking = typeof message.thinking === "string" ? message.thinking : "";
   const toolCalls = message.tool_calls || [];
 
+  // Extract <think>...</think> blocks from content (concatenate if multiple).
+  // What remains becomes the text body.
+  const thinkRegex = /<think>([\s\S]*?)<\/think>/g;
+  const thinkMatches = [];
+  let textBody = rawContent;
+  let m;
+  while ((m = thinkRegex.exec(rawContent)) !== null) {
+    thinkMatches.push(m[1]);
+  }
+  textBody = textBody.replace(thinkRegex, "").trim();
+
+  const combinedThinking = [nativeThinking, ...thinkMatches]
+    .map(s => (s || "").trim())
+    .filter(Boolean)
+    .join("\n\n");
+
   const contentItems = [];
 
-  if (typeof rawContent === "string" && rawContent.trim()) {
-    const cleanedContent = stripThinkingBlocks(rawContent);
-    if (cleanedContent) {
-      contentItems.push({ type: "text", text: cleanedContent });
-    }
+  // 1. Thinking block FIRST (Mini-Agent reference order: thinking → text → tool_use)
+  if (combinedThinking) {
+    contentItems.push({ type: "thinking", thinking: combinedThinking });
   }
 
-  // Convert tool calls from OpenAI function-calling format to Anthropic tool_use
+  // 2. Text body (after <think> tags removed)
+  if (textBody) {
+    contentItems.push({ type: "text", text: textBody });
+  }
+
+  // 3. Tool calls converted to Anthropic tool_use
   if (Array.isArray(toolCalls) && toolCalls.length > 0) {
     for (const toolCall of toolCalls) {
       const func = toolCall.function || {};
@@ -1008,6 +1034,9 @@ function ollamaToAnthropicResponse(ollamaResponse, requestedModel) {
   const inputTokens = ollamaResponse.prompt_eval_count ?? 0;
   const outputTokens = ollamaResponse.eval_count ?? 0;
 
+  // stop_reason derived from tool_calls presence, NOT done_reason.
+  // Ollama emits done_reason="stop" even when tool_calls are present
+  // (ollama/ollama#12557) — naive mapping would falsely halt Claude Code's loop.
   return {
     id: `msg_${Date.now()}`,
     type: "message",
@@ -1104,7 +1133,16 @@ function toAnthropicResponse(openai, requestedModel, wantsThinking) {
 
 function sanitizePayload(payload) {
   const { clonePayloadSmart } = require("../utils/payload");
-  const providerType = config.modelProvider?.type ?? "databricks";
+  // Honor a forceProvider marker (set by the OAuth tier-routing path) so the
+  // tool-format / system-flatten / strip-thinking branches downstream match
+  // the actual destination provider, not the static MODEL_PROVIDER default.
+  // Without this, a TIER_SIMPLE=ollama:... user gets the "databricks" branch
+  // running normaliseTools — which wraps tools in OpenAI {type:"function",...}
+  // shape, leaving Ollama with tools named "function" and a model that
+  // (correctly) reports no real tools available.
+  const providerType = payload?._forceProvider
+    || config.modelProvider?.type
+    || "databricks";
   const willFlatten = providerType !== "azure-anthropic";
   const clean = clonePayloadSmart(payload ?? {}, { willFlatten });
   const requestedModel =
@@ -1260,55 +1298,16 @@ function sanitizePayload(payload) {
         }));
     delete clean.tool_choice;
   } else if (providerType === "ollama") {
-    // Check if model supports tools
-    const { modelNameSupportsTools } = require("../clients/ollama-utils");
-    const modelSupportsTools = modelNameSupportsTools(config.ollama?.model);
-
-    // Check if this is a simple conversational message (no tools needed)
-    const isConversational = (() => {
-      if (!Array.isArray(clean.messages) || clean.messages.length === 0) {
-        return false;
-      }
-      const lastMessage = clean.messages[clean.messages.length - 1];
-      if (lastMessage?.role !== "user") {
-        return false;
-      }
-
-      const content = typeof lastMessage.content === "string"
-        ? lastMessage.content
-        : "";
-
-      const trimmed = content.trim().toLowerCase();
-
-      // Simple greetings
-      if (/^(hi|hello|hey|good morning|good afternoon|good evening|howdy|greetings)[\s\.\!\?]*$/.test(trimmed)) {
-        return "greeting";
-      }
-
-      // Conversational phrases that don't need tools (thanks, farewells, acknowledgements)
-      if (/^(thanks|thank you|thx|ty|bye|goodbye|see you|ok|okay|cool|nice|great|awesome|sure|got it|sounds good|no worries|np|cheers)[\s\.\!\?]*$/.test(trimmed)) {
-        return "conversational";
-      }
-
-      return false;
-    })();
-
-    if (isConversational) {
-      // Strip all tools for simple conversational messages
-      delete clean.tools;
-      delete clean.tool_choice;
-      logger.debug({
-        model: config.ollama?.model,
-        reason: isConversational,
-      }, "Ollama conversational mode - tools removed");
-    } else if (modelSupportsTools && Array.isArray(clean.tools) && clean.tools.length > 0) {
-      // Keep all tools — Ollama receives them in Anthropic format (native API)
-      // or they get converted to OpenAI format in invokeOllama (legacy API)
+    // Always pass tools through to Ollama in Anthropic format when they exist.
+    // Ollama (v0.14+ native /v1/messages) accepts the Anthropic tool shape; if
+    // the underlying model doesn't actually emit tool_use blocks, the model
+    // simply responds conversationally — which is the correct fallback. Don't
+    // strip the tools array based on heuristics about user intent or a
+    // hardcoded "model supports tools" check, both of which produce
+    // tool-blind responses ("I don't have file system access") when the
+    // client (Claude Code) is clearly in an agentic session.
+    if (Array.isArray(clean.tools) && clean.tools.length > 0) {
       clean.tools = ensureAnthropicToolFormat(clean.tools);
-    } else {
-      // Remove tools for models without tool support
-      delete clean.tools;
-      delete clean.tool_choice;
     }
   } else if (providerType === "openrouter") {
     // OpenRouter supports tools - keep them as-is
@@ -1902,8 +1901,29 @@ IMPORTANT TOOL USAGE RULES:
     }, 'Estimated token usage before model call');
   }
 
-  // Apply Headroom compression if enabled
-  if (isHeadroomEnabled() && cleanPayload.messages && cleanPayload.messages.length > 0) {
+  // Apply Headroom compression if enabled.
+  //
+  // Headroom is configured for a single provider (HEADROOM_PROVIDER, default
+  // 'anthropic'). Its Tool Crusher rewrites tool results compactly, Cache
+  // Aligner restructures messages to maximize that provider's prompt-cache
+  // hit pattern, and Smart Crusher does semantic compression — all tuned for
+  // Anthropic. Sending the compressed output to a different model family
+  // (Ollama, OpenAI, etc.) yields output the receiver reads as "garbled tool
+  // result" and the agent loop stalls.
+  //
+  // Gate Headroom on providers matching HEADROOM_PROVIDER. By default that's
+  // Claude-family; an operator who switches HEADROOM_PROVIDER=openai gets the
+  // analogous gate.
+  const headroomProviderMap = {
+    'anthropic': new Set(['azure-anthropic', 'bedrock', 'vertex', 'openrouter']),
+    'openai':    new Set(['azure-openai', 'openai', 'openrouter']),
+    'google':    new Set(['vertex', 'openrouter']),
+  };
+  const headroomProvider = process.env.HEADROOM_PROVIDER || 'anthropic';
+  const headroomSafeProviders = headroomProviderMap[headroomProvider] || new Set();
+  const headroomCompatible = headroomSafeProviders.has(providerType);
+
+  if (isHeadroomEnabled() && headroomCompatible && cleanPayload.messages && cleanPayload.messages.length > 0) {
     try {
       const compressionResult = await headroomCompress(
         cleanPayload.messages,
@@ -1945,6 +1965,12 @@ IMPORTANT TOOL USAGE RULES:
     } catch (headroomErr) {
       logger.warn({ err: headroomErr, sessionId: session?.id ?? null }, 'Headroom compression failed, using original messages');
     }
+  } else if (isHeadroomEnabled() && !headroomCompatible) {
+    logger.debug({
+      providerType,
+      headroomProvider,
+      reason: 'provider_mismatch',
+    }, 'Headroom skipped — provider does not match HEADROOM_PROVIDER family');
   }
 
   // Generate correlation ID for request/response pairing
@@ -2003,15 +2029,49 @@ IMPORTANT TOOL USAGE RULES:
 
   // Caveman terse-output injection (opt-in): nudge the model toward shorter
   // responses to reduce output tokens.
-  if (config.caveman?.enabled === true) {
+  //
+  // Default safe-set is the Claude-family + capable instruction-following
+  // models. Operators can override via LYNKR_CAVEMAN_SAFE_PROVIDERS=a,b,c.
+  // (Some smaller / older models read "respond like a terse caveman" too
+  // literally and produce broken telegraphic English — keep them out of the
+  // set if you see that degradation.)
+  const DEFAULT_CAVEMAN_SAFE = [
+    'azure-anthropic',
+    'bedrock',
+    'vertex',
+    'openrouter',
+    'ollama',
+    'openai',
+    'azure-openai',
+    'moonshot',
+    'zai',
+    'databricks',
+  ];
+  const cavemanSafeEnv = process.env.LYNKR_CAVEMAN_SAFE_PROVIDERS;
+  const CAVEMAN_SAFE_PROVIDERS = new Set(
+    cavemanSafeEnv
+      ? cavemanSafeEnv.split(',').map(s => s.trim()).filter(Boolean)
+      : DEFAULT_CAVEMAN_SAFE
+  );
+  if (config.caveman?.enabled === true && CAVEMAN_SAFE_PROVIDERS.has(providerType)) {
     const { injectCaveman } = require("../context/caveman");
     cleanPayload.system = injectCaveman(cleanPayload.system);
+  } else if (config.caveman?.enabled === true) {
+    logger.debug({ providerType }, 'Caveman injection skipped (provider not in safe set)');
   }
 
   if (agentTimer) agentTimer.mark("preInvokeModel");
   let databricksResponse;
+  // Honor a body-level forceProvider marker (set by the OAuth tier-routing
+  // path in the router) so the orchestrator's internal tier router can't
+  // re-pick a different provider mid-flight.
+  const invokeOpts = { headers };
+  if (cleanPayload._forceProvider) {
+    invokeOpts.forceProvider = cleanPayload._forceProvider;
+    delete cleanPayload._forceProvider;
+  }
   try {
-    databricksResponse = await invokeModel(cleanPayload);
+    databricksResponse = await invokeModel(cleanPayload, invokeOpts);
     if (agentTimer) agentTimer.mark("invokeModel");
   } catch (modelError) {
     const isConnectionError = modelError.cause?.code === 'ECONNREFUSED'