lynkr 9.4.6 → 9.6.0

package/src/clients/databricks.js

@@ -1104,6 +1104,64 @@ async function invokeLMStudio(body) {
   return performJsonRequest(endpoint, { headers, body: lmstudioBody }, "LM Studio");
 }
 
+/**
+ * Flatten an Anthropic-style content value into a plain string for the
+ * Bedrock Converse API.
+ *
+ * Prompt-cache injection (injectPromptCaching) rewrites string `system`
+ * fields and message `content` into arrays of `{ type, text, cache_control }`
+ * blocks. The Converse API has no `cache_control` concept and expects
+ * `system: [{ text: "<string>" }]` and message content blocks shaped as
+ * `{ text: "<string>" }`. Passing the injected array through unchanged would
+ * either drop the cache markers silently or nest an array under `text`,
+ * producing a ValidationException.
+ *
+ * @param {string|Array|undefined} value - String or array of content blocks
+ * @returns {string} Concatenated plain text
+ */
+function flattenContentToText(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value
+      .map(block => {
+        if (typeof block === "string") return block;
+        if (block && typeof block === "object") return block.text || block.content || "";
+        return "";
+      })
+      .join("");
+  }
+  return String(value);
+}
+
+/**
+ * Normalize a request body for the Bedrock Converse API.
+ *
+ * Strips `cache_control` markers and flattens any array-shaped `system` /
+ * message `content` (left behind by prompt-cache injection) back into the
+ * plain strings the Converse API expects. Returns a shallow copy with a
+ * normalized `messages` array; the original body is not mutated.
+ *
+ * @param {Object} body - Anthropic-format request body
+ * @returns {Object} Body safe for Converse request construction
+ */
+function normalizeBodyForConverse(body) {
+  const normalized = { ...body };
+
+  if (normalized.system !== undefined) {
+    normalized.system = flattenContentToText(normalized.system);
+  }
+
+  if (Array.isArray(normalized.messages)) {
+    normalized.messages = normalized.messages.map(msg => ({
+      ...msg,
+      content: flattenContentToText(msg.content),
+    }));
+  }
+
+  return normalized;
+}
+
 async function invokeBedrock(body) {
   // 1. Validate Bearer token
   if (!config.bedrock?.apiKey) {
@@ -1130,7 +1188,10 @@ async function invokeBedrock(body) {
     }, "=== INJECTING STANDARD TOOLS (Bedrock) ===");
   }
 
-  const bedrockBody = { ...body, tools: toolsToSend };
+  // Normalize away cache_control / array shapes that prompt-cache injection
+  // may have applied: the Converse API expects plain-string system and
+  // message content, not Anthropic cache_control blocks.
+  const bedrockBody = { ...normalizeBodyForConverse(body), tools: toolsToSend };
 
   // 4. Detect model family and convert format
   const modelId = body._tierModel || config.bedrock.modelId;
@@ -1506,10 +1567,16 @@ async function invokeMoonshot(body) {
     "claude-haiku-4-5-20251001": "kimi-k2-turbo-preview",
     "claude-haiku-4-5": "kimi-k2-turbo-preview",
     "claude-3-haiku": "kimi-k2-turbo-preview",
+    // moonshot-v1-auto 400s with "tokenization failed" (its server-side auto
+    // context-size pass fails on large tool-bearing payloads). Remap to a
+    // fixed model that's broadly available on api.moonshot.ai.
+    "moonshot-v1-auto": "moonshot-v1-128k",
   };
 
   const requestedModel = body._tierModel || body.model || config.moonshot.model;
-  const mappedModel = modelMap[requestedModel] || config.moonshot.model || "kimi-k2-turbo-preview";
+  let mappedModel = modelMap[requestedModel] || config.moonshot.model || "kimi-k2-turbo-preview";
+  // Guard against the deprecated auto model arriving via config too.
+  if (mappedModel === "moonshot-v1-auto") mappedModel = "moonshot-v1-128k";
 
   // Convert messages using existing utility
   const messages = convertAnthropicMessagesToOpenRouter(body.messages || []);
@@ -1522,12 +1589,18 @@ async function invokeMoonshot(body) {
     messages.unshift({ role: "system", content: systemContent });
   }
 
+  // kimi-k2.x (k2.5 / k2.6 …) are thinking models that only accept
+  // temperature: 1 — any other value 400s with "invalid temperature".
+  const isKimiThinking = /^kimi-k2/i.test(mappedModel);
+
   const moonshotBody = {
     model: mappedModel,
     messages,
     max_tokens: body.max_tokens || 16384,
-    temperature: body.temperature ?? 0.7,
-    top_p: body.top_p ?? 1.0,
+    // kimi-k2.x thinking models pin sampling params: temperature must be 1
+    // and top_p must be 0.95 — any other value 400s.
+    temperature: isKimiThinking ? 1 : (body.temperature ?? 0.7),
+    top_p: isKimiThinking ? 0.95 : (body.top_p ?? 1.0),
     stream: false,  // Force non-streaming - OpenAI SSE to Anthropic SSE conversion not implemented
   };
 
@@ -2027,6 +2100,65 @@ async function invokeCodex(body) {
   };
 }
 
+/**
+ * Compute request cost in USD from model pricing × token usage.
+ * Registry returns per-1M-token prices ({ input, output }); returns null when
+ * pricing is unknown so we don't record misleading zeros.
+ */
+const _unknownCostWarned = new Set();
+function computeCostUsd(model, inputTokens, outputTokens) {
+  try {
+    const { getModelRegistrySync } = require("../routing/model-registry");
+    const reg = getModelRegistrySync && getModelRegistrySync();
+    const cost = reg?.getCost?.(model);
+    if (!cost) return null;
+    // Unknown model → record null (not a fabricated default), warn once so the
+    // gap is visible and can be fixed via MODEL_PRICE_OVERRIDES.
+    if (cost.unknown) {
+      if (model && !_unknownCostWarned.has(model)) {
+        _unknownCostWarned.add(model);
+        logger.warn({ model }, "[Cost] No pricing for model — recording cost_usd=null. Set MODEL_PRICE_OVERRIDES to fix.");
+      }
+      return null;
+    }
+    if (cost.input == null && cost.output == null) return null;
+    const inUsd = ((inputTokens || 0) / 1e6) * (cost.input || 0);
+    const outUsd = ((outputTokens || 0) / 1e6) * (cost.output || 0);
+    return Number((inUsd + outUsd).toFixed(6));
+  } catch {
+    return null;
+  }
+}
+
+// Telemetry prompt/response text is always captured (truncated) to build the
+// routing ML training corpus. Stored locally in .lynkr/telemetry.db only.
+const TELEMETRY_TEXT_MAXLEN = 2000;
+
+/** Flatten the latest user message to plain text (for telemetry capture). */
+function captureRequestText(body) {
+  const messages = body?.messages;
+  if (!Array.isArray(messages)) return null;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== "user") continue;
+    let text = "";
+    if (typeof m.content === "string") text = m.content;
+    else if (Array.isArray(m.content)) {
+      text = m.content.filter((b) => b?.type === "text").map((b) => b.text || "").join(" ");
+    }
+    if (text) return text.slice(0, TELEMETRY_TEXT_MAXLEN);
+  }
+  return null;
+}
+
+/** Flatten an Anthropic response's text blocks to plain text (for telemetry). */
+function captureResponseText(resultJson) {
+  const content = resultJson?.content;
+  if (!Array.isArray(content)) return null;
+  const text = content.filter((b) => b?.type === "text").map((b) => b.text || "").join(" ");
+  return text ? text.slice(0, TELEMETRY_TEXT_MAXLEN) : null;
+}
+
 async function invokeModel(body, options = {}) {
   const { determineProviderSmart, isFallbackEnabled, getFallbackProvider } = require("./routing");
   const metricsCollector = getMetricsCollector();
@@ -2053,6 +2185,13 @@ async function invokeModel(body, options = {}) {
   const { injectPromptCaching } = require('./prompt-cache-injection');
   injectPromptCaching(body, initialProvider);
 
+  // Always-on markdown formatting guard. Stops formatting-weak backends
+  // (Moonshot/Kimi, Ollama, etc.) from emitting mangled ASCII box-drawing
+  // "diagrams". Keyed off the routing-resolved provider/model; skipped for
+  // Claude-family backends which already format cleanly.
+  const { injectFormatGuard } = require('../context/output-format-guard');
+  injectFormatGuard(body, { provider: initialProvider, model: tierSelectedModel });
+
   // Build routing decision object for response headers
   const routingDecision = {
     provider: initialProvider,
@@ -2233,6 +2372,9 @@ async function invokeModel(body, options = {}) {
       circuit_breaker_state: breaker.state,
       quality_score: qualityScore,
       tokens_per_second: outputTokens && latency > 0 ? outputTokens / (latency / 1000) : null,
+      cost_usd: computeCostUsd(routingDecision.model || body._tierModel, inputTokens, outputTokens),
+      request_text: captureRequestText(body),
+      response_text: captureResponseText(result.json),
     });
 
     // Return result with provider info and routing decision for headers
@@ -2249,6 +2391,71 @@ async function invokeModel(body, options = {}) {
     healthTracker.recordFailure(initialProvider, err, err.status);
     getLatencyTracker().record(initialProvider, routingDecision?.model, failLatency);
 
+    // Tier-aware escalate-then-demote fallback (TIER_FALLBACK_ENABLED).
+    // On failure, try a MORE capable tier first (climb toward REASONING); only
+    // if every higher tier is unavailable do we fall downward to SIMPLE/local.
+    // Runs before the flat global fallback below and is never silent.
+    if (config.tierFallback?.enabled && !options._tierFallbackInner && routingDecision.tier) {
+      const { getFallbackChain } = require("../routing/tier-fallback");
+      const chain = getFallbackChain(routingDecision.tier);
+      for (const cand of chain) {
+        try {
+          logger.warn({
+            fromTier: routingDecision.tier,
+            fromProvider: initialProvider,
+            toTier: cand.tier,
+            toProvider: cand.provider,
+            toModel: cand.model,
+            direction: cand.direction,
+          }, "[TierFallback] Primary tier failed — attempting tier fallback");
+
+          const attempt = await invokeModel(
+            { ...body, _tierModel: cand.model },
+            {
+              forceProvider: cand.provider,
+              _tierFallbackInner: true,
+              disableFallback: true,
+              _cascadeInner: true,
+              workspace,
+              tenantPolicy,
+            }
+          );
+
+          metricsCollector.recordFallbackAttempt(initialProvider, cand.provider, "tier_fallback");
+          logger.warn({
+            servedTier: cand.tier,
+            servedProvider: cand.provider,
+            fromTier: routingDecision.tier,
+            direction: cand.direction,
+          }, "[TierFallback] Served by tier fallback");
+
+          return {
+            ...attempt,
+            actualProvider: cand.provider,
+            routingDecision: {
+              ...routingDecision,
+              provider: cand.provider,
+              model: cand.model,
+              servedTier: cand.tier,
+              fromTier: routingDecision.tier,
+              fallback: true,
+              fallbackDirection: cand.direction,
+              method: "tier_fallback",
+            },
+          };
+        } catch (innerErr) {
+          logger.warn(
+            { toProvider: cand.provider, error: innerErr.message },
+            "[TierFallback] Candidate failed, trying next"
+          );
+        }
+      }
+      logger.warn(
+        { fromTier: routingDecision.tier },
+        "[TierFallback] All tier candidates exhausted — falling through"
+      );
+    }
+
     // Check if we should fallback (any provider can fall back, not just ollama)
     const shouldFallback =
       isFallbackEnabled() &&
@@ -2394,6 +2601,9 @@ async function invokeModel(body, options = {}) {
           { status_code: 200, output_tokens: fbOutputTokens, tool_calls_made: fbToolCalls, was_fallback: true, retry_count: 0, latency_ms: Date.now() - startTime }
         ),
         tokens_per_second: fbOutputTokens && fallbackLatency > 0 ? fbOutputTokens / (fallbackLatency / 1000) : null,
+        cost_usd: computeCostUsd(routingDecision.model || body._tierModel, fbInputTokens, fbOutputTokens),
+        request_text: captureRequestText(body),
+        response_text: captureResponseText(fallbackResult.json),
       });
 
       // Return result with actual provider used (fallback provider) and routing decision
@@ -2502,4 +2712,5 @@ function destroyHttpAgents() {
 module.exports = {
   invokeModel,
   destroyHttpAgents,
+  normalizeBodyForConverse,
 };

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,33 +147,24 @@ 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".
+  // This happens when a turn had only non-text blocks (thinking / image /
+  // stripped content) and flattened to "". Replace empty/whitespace-only
+  // content with a single space — but never touch an assistant message that
+  // carries tool_calls, where content: null is intentional and required.
+  for (const m of converted) {
+    if (m.role === 'tool') continue;
+    const hasToolCalls = Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+    if (hasToolCalls) continue;
+    if (typeof m.content !== 'string' || m.content.trim() === '') {
+      m.content = ' ';
     }
   }
 

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,6 +174,9 @@ 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;
   return injectAnthropicCacheBreakpoints(body);
 }
 
@@ -137,4 +185,5 @@ module.exports = {
   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

@@ -208,6 +208,11 @@ const tokenBudgetWarning = Number.parseInt(process.env.TOKEN_BUDGET_WARNING ?? "
 const tokenBudgetMax = Number.parseInt(process.env.TOKEN_BUDGET_MAX ?? "180000", 10);
 const tokenBudgetEnforcement = process.env.TOKEN_BUDGET_ENFORCEMENT !== "false"; // default true
 
+// Caveman terse-output injection (opt-in, off by default)
+const cavemanEnabled = process.env.CAVEMAN_ENABLED === "true";
+const cavemanLevel = (process.env.CAVEMAN_LEVEL ?? "lite").toLowerCase();
+
+
 // TOON payload compression (opt-in)
 const toonEnabled = process.env.TOON_ENABLED === "true"; // default false
 const toonMinBytes = Number.parseInt(process.env.TOON_MIN_BYTES ?? "4096", 10);
@@ -513,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");
@@ -641,6 +652,10 @@ var config = {
   toolResultCompression: {
     enabled: true,
   },
+  caveman: {
+    enabled: cavemanEnabled,
+    level: cavemanLevel,
+  },
   server: {
     jsonLimit: process.env.REQUEST_JSON_LIMIT ?? "1gb",
   },
@@ -766,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,