lynkr 9.7.3 → 9.9.0

package/src/orchestrator/index.js

@@ -12,6 +12,7 @@ const systemPrompt = require("../prompts/system");
 const historyCompression = require("../context/compression");
 const tokenBudget = require("../context/budget");
 const { applyToonCompression } = require("../context/toon");
+const { applyGcfCompression } = require("../context/gcf");
 const { classifyRequestType, selectToolsSmartly } = require("../tools/smart-selection");
 const { compressMessages: headroomCompress, isEnabled: isHeadroomEnabled } = require("../headroom");
 const { createAuditLogger } = require("../logger/audit-logger");
@@ -20,7 +21,6 @@ const { getShuttingDown } = require("../api/health");
 const { tryPreflight, buildSatisfiedResponse: buildPreflightResponse } = require("./preflight");
 const { detectBypass, buildBypassResponse } = require("./bypass");
 const crypto = require("crypto");
-const { asyncClone, asyncTransform, getPoolStats } = require("../workers/helpers");
 const { getSemanticCache, isSemanticCacheEnabled } = require("../cache/semantic");
 const lazyLoader = require("../tools/lazy-loader");
 const { areSimilarToolCalls } = require("../clients/gpt-utils");
@@ -43,6 +43,8 @@ function getDestinationUrl(providerType) {
       return config.azureOpenAI?.endpoint ?? 'unknown';
     case 'openrouter':
       return config.openrouter?.endpoint ?? 'unknown';
+    case 'edenai':
+      return config.edenai?.endpoint ?? 'unknown';
     case 'openai':
       return 'https://api.openai.com/v1/chat/completions';
     case 'llamacpp':
@@ -235,10 +237,18 @@ function normaliseTools(tools) {
 function ensureAnthropicToolFormat(tools) {
   if (!Array.isArray(tools) || tools.length === 0) return undefined;
   return tools.map((tool) => {
+    // Shape-detect: unwrap OpenAI-format tools rather than fabricating
+    // "unnamed_tool" from their absent top-level fields.
+    if (tool?.type === "function" && tool.function) {
+      tool = {
+        name: tool.function.name,
+        description: tool.function.description,
+        input_schema: tool.function.parameters,
+      };
+    }
     // Ensure input_schema has required 'type' field
     let input_schema = tool.input_schema || { type: "object", properties: {} };
 
-    // If input_schema exists but missing 'type', add it
     if (input_schema && !input_schema.type) {
       input_schema = { type: "object", ...input_schema };
     }
@@ -468,7 +478,6 @@ function injectToolLoopStopInstruction(messages, threshold = 5) {
       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.`,
     };
 
-    // Add to end of messages
     return [...messages, stopInstruction];
   }
 
@@ -550,7 +559,6 @@ function recordCrossRequestToolCall(session, toolCall) {
     }
 
     if (!mergedInto) {
-      // New unique signature
       dedup.signatures[signature] = {
         count: 1,
         toolName,
@@ -610,7 +618,6 @@ function getMaxDedupCount(session) {
 function extractToolUseFromCurrentTurn(messages) {
   if (!Array.isArray(messages)) return [];
 
-  // Find last user text message
   let lastUserTextIndex = -1;
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
@@ -731,7 +738,6 @@ function parseExecutionContent(content) {
               if (block.type === 'text' && typeof block.text === 'string') {
                 return block.text;
               }
-              // Handle other block types gracefully
               if (block.text) return block.text;
               if (block.content) return typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
               return null;
@@ -922,7 +928,6 @@ function normaliseToolChoice(choice) {
 function stripThinkingBlocks(text) {
   if (typeof text !== "string") return text;
 
-  // Split into lines
   const lines = text.split("\n");
   const cleanedLines = [];
   let inThinkingBlock = false;
@@ -947,15 +952,12 @@ function stripThinkingBlocks(text) {
       continue;
     }
 
-    // Reset empty line counter
     consecutiveEmptyLines = 0;
 
-    // Skip lines that are part of thinking block
     if (inThinkingBlock) {
       continue;
     }
 
-    // Keep this line
     cleanedLines.push(line);
   }
 
@@ -1318,8 +1320,8 @@ function sanitizePayload(payload) {
     if (Array.isArray(clean.tools) && clean.tools.length > 0) {
       clean.tools = ensureAnthropicToolFormat(clean.tools);
     }
-  } else if (providerType === "openrouter") {
-    // OpenRouter supports tools - keep them as-is
+  } else if (providerType === "openrouter" || providerType === "edenai") {
+    // OpenRouter / Eden AI (OpenAI-compatible) support tools - keep them as-is.
     // Tools are already in Anthropic format and will be converted by openrouter-utils
     if (!Array.isArray(clean.tools) || clean.tools.length === 0) {
       delete clean.tools;
@@ -1330,7 +1332,6 @@ function sanitizePayload(payload) {
     if (!Array.isArray(clean.tools) || clean.tools.length === 0) {
       delete clean.tools;
     } else {
-      // Ensure tools are in Anthropic format
       clean.tools = ensureAnthropicToolFormat(clean.tools);
     }
   } else if (providerType === "vertex") {
@@ -1348,6 +1349,15 @@ function sanitizePayload(payload) {
     } else {
       clean.tools = ensureAnthropicToolFormat(clean.tools);
     }
+  } else if (providerType === "azure-openai" || providerType === "openai") {
+    // Azure OpenAI / OpenAI support tools — keep Anthropic format; the
+    // client converts to Chat Completions / Responses format. Without this
+    // branch the unknown-provider catch-all below deletes the tools.
+    if (!Array.isArray(clean.tools) || clean.tools.length === 0) {
+      delete clean.tools;
+    } else {
+      clean.tools = ensureAnthropicToolFormat(clean.tools);
+    }
   } else if (Array.isArray(clean.tools)) {
     // Unknown provider - remove tools for safety
     delete clean.tools;
@@ -1431,9 +1441,14 @@ function sanitizePayload(payload) {
 
   // Optional TOON conversion for large JSON message payloads (prompt context only).
   // Run this BEFORE message coalescing to preserve parseable JSON boundaries.
-  applyToonCompression(clean, config.toon, { logger });
+  // GCF takes precedence when enabled; otherwise TOON. Both are opt-in and mutually exclusive.
+  if (config.gcf && config.gcf.enabled) {
+    applyGcfCompression(clean, config.gcf, { logger });
+  } else {
+    applyToonCompression(clean, config.toon, { logger });
+  }
 
-  // FIX: Handle consecutive messages with the same role (causes llama.cpp 400 error)
+  // Handle consecutive messages with the same role (causes llama.cpp 400 error)
   // Strategy: Merge consecutive same-role messages, but NEVER merge messages
   // that contain tool_use or tool_result blocks — they must stay intact for
   // the provider's tool-call protocol.
@@ -1640,17 +1655,21 @@ async function runAgentLoop({
       "Agent loop step",
     );
 
-    // Trim messages when they grow too large to prevent OOM.
-    // Keep the first message (system/user) and the last MAX_LOOP_MESSAGES.
-    const MAX_LOOP_MESSAGES = 40;
-    if (cleanPayload.messages && cleanPayload.messages.length > MAX_LOOP_MESSAGES) {
-      const excess = cleanPayload.messages.length - MAX_LOOP_MESSAGES;
-      // Keep first 2 messages (system context + initial user) and trim from the middle
-      cleanPayload.messages.splice(2, excess);
-      logger.debug(
-        { trimmed: excess, remaining: cleanPayload.messages.length },
-        "Trimmed intermediate messages to prevent memory growth",
-      );
+    // Trim over-long loop conversations to prevent OOM, keeping the head,
+    // THE CURRENT TASK (latest user message with real typed text), and the
+    // recent tail — a head+tail-only trim discards the ask itself when the
+    // session opened with a greeting, and the model answers the greeting.
+    // Tunable: LYNKR_MAX_LOOP_MESSAGES (default 40; 0 disables trimming
+    // entirely). Disabling trades flat per-frame cost/latency for full
+    // context fidelity — on weak models expect coherence loss on very long
+    // loops (their competence degrades before their context window fills),
+    // and on paid models expect per-frame input cost to grow with session
+    // length. The task-preservation fix makes the default cap safe.
+    const MAX_LOOP_MESSAGES = Number.isFinite(Number(process.env.LYNKR_MAX_LOOP_MESSAGES))
+      ? Number(process.env.LYNKR_MAX_LOOP_MESSAGES)
+      : 40;
+    if (MAX_LOOP_MESSAGES > 0 && cleanPayload.messages && cleanPayload.messages.length > MAX_LOOP_MESSAGES) {
+      cleanPayload.messages = trimLoopMessages(cleanPayload.messages, MAX_LOOP_MESSAGES);
     }
 
     // Debug: Log payload before sending to Azure
@@ -1717,7 +1736,6 @@ async function runAgentLoop({
                 memoriesRetrieved: relevantMemories.length,
               }, 'Injecting long-term memories into context');
 
-              // Inject memories into system prompt
               const injectedSystem = memoryRetriever.injectMemoriesIntoSystem(
                 cleanPayload.system,
                 relevantMemories,
@@ -1924,9 +1942,9 @@ IMPORTANT TOOL USAGE RULES:
   // 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']),
+    'anthropic': new Set(['azure-anthropic', 'bedrock', 'vertex', 'openrouter', 'edenai']),
+    'openai':    new Set(['azure-openai', 'openai', 'openrouter', 'edenai']),
+    'google':    new Set(['vertex', 'openrouter', 'edenai']),
   };
   const headroomProvider = process.env.HEADROOM_PROVIDER || 'anthropic';
   const headroomSafeProviders = headroomProviderMap[headroomProvider] || new Set();
@@ -1985,7 +2003,6 @@ IMPORTANT TOOL USAGE RULES:
   // Generate correlation ID for request/response pairing
   const correlationId = `req_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
 
-  // Log LLM request before invocation
   if (auditLogger.enabled) {
     auditLogger.logLlmRequest({
       correlationId,
@@ -2049,6 +2066,7 @@ IMPORTANT TOOL USAGE RULES:
     'bedrock',
     'vertex',
     'openrouter',
+    'edenai',
     'ollama',
     'openai',
     'azure-openai',
@@ -2107,7 +2125,6 @@ IMPORTANT TOOL USAGE RULES:
     throw modelError;
   }
 
-  // Extract and log actual token usage
   const actualUsage = databricksResponse.ok && config.tokenTracking?.enabled !== false
     ? tokens.extractUsageFromResponse(databricksResponse.json)
     : null;
@@ -2121,12 +2138,10 @@ IMPORTANT TOOL USAGE RULES:
     }
   }
 
-  // Log LLM response after invocation
   if (auditLogger.enabled) {
     const latencyMs = Date.now() - start;
 
     if (databricksResponse.stream) {
-      // Log streaming response (no content, just metadata)
       auditLogger.logLlmResponse({
         correlationId,
         sessionId: session?.id ?? null,
@@ -2139,7 +2154,6 @@ IMPORTANT TOOL USAGE RULES:
         streamingNote: 'Content streamed directly to client, not captured in audit log',
       });
     } else if (databricksResponse.ok && databricksResponse.json) {
-      // Log successful non-streaming response
       const message = databricksResponse.json;
       const assistantMessage = message.content ?? message.choices?.[0]?.message;
 
@@ -2158,7 +2172,6 @@ IMPORTANT TOOL USAGE RULES:
         status: databricksResponse.status,
       });
     } else {
-      // Log error response
       auditLogger.logLlmResponse({
         correlationId,
         sessionId: session?.id ?? null,
@@ -2333,7 +2346,11 @@ IMPORTANT TOOL USAGE RULES:
         ? (databricksResponse.json?.content ?? []).some(b => b?.type === "text" && String(b.text || "").trim().length > 0)
         : (typeof message.content === "string" && message.content.trim().length > 0);
 
-      if (!hasTextContent && steps < settings.maxSteps - 1) {
+      // The artifact redirect is an open-design (SERVER-mode) feature; in
+      // client mode, drop the hallucinated calls and return whatever text
+      // exists — never instruct the model to emit artifacts.
+      const _clientOwnsOutput = config.toolExecutionMode === "client" || config.toolExecutionMode === "passthrough";
+      if (!hasTextContent && steps < settings.maxSteps - 1 && !_clientOwnsOutput) {
         logger.info({
           sessionId: session?.id ?? null,
           step: steps,
@@ -2362,7 +2379,6 @@ IMPORTANT TOOL USAGE RULES:
         const contentBlocks = [];
         let toolCallIdx = 0;
 
-        // Add text content if present
         if (message.content && typeof message.content === 'string' && message.content.trim()) {
           contentBlocks.push({
             type: "text",
@@ -2370,12 +2386,10 @@ IMPORTANT TOOL USAGE RULES:
           });
         }
 
-        // Add tool_use blocks from tool_calls
         for (const toolCall of toolCalls) {
           const func = toolCall.function || {};
           let input = {};
 
-          // Parse arguments string to object
           if (func.arguments) {
             try {
               input = typeof func.arguments === "string"
@@ -2448,15 +2462,18 @@ IMPORTANT TOOL USAGE RULES:
 
       cleanPayload.messages.push(assistantToolMessage);
 
-      // Check if tool execution should happen on client side
       const executionMode = config.toolExecutionMode || "server";
 
-      // IMPORTANT: Task tools (subagents) and Web Search tools ALWAYS execute server-side, regardless of execution mode to ensure reliability
-      // Separate Server-side tools from Client-side tools
+      // Server-side tool split: in SERVER mode task/web tools run on Lynkr.
+      // In CLIENT mode the client owns ALL its tools — its "Task" (subagent
+      // spawner) and WebSearch collide with Lynkr's same-named internal
+      // tools, which have entirely different semantics.
       const serverSideToolCalls = [];
       const clientSideToolCalls = [];
 
-      const SERVER_SIDE_TOOLS = new Set(["task", "Task", "web_search", "web_fetch", "websearch", "webfetch", "web_agent", "WebSearch", "WebFetch", "WebAgent"]);
+      const SERVER_SIDE_TOOLS = (executionMode === "passthrough" || executionMode === "client")
+        ? new Set()
+        : new Set(["task", "Task", "web_search", "web_fetch", "websearch", "webfetch", "web_agent", "WebSearch", "WebFetch", "WebAgent"]);
 
       for (const call of toolCalls) {
         const toolName = (call.function?.name ?? call.name ?? "").toLowerCase();
@@ -2608,7 +2625,6 @@ IMPORTANT TOOL USAGE RULES:
         }, "Executing multiple Task tools in parallel");
 
         try {
-          // Execute all Task tools in parallel
           const taskExecutions = await Promise.all(
             taskCalls.map(({ call }) => executeToolCall(call, {
               session,
@@ -2618,7 +2634,6 @@ IMPORTANT TOOL USAGE RULES:
             }))
           );
 
-          // Process results and add to messages
           taskExecutions.forEach((execution, index) => {
             const call = taskCalls[index].call;
             toolCallsExecuted += 1;
@@ -2782,7 +2797,6 @@ IMPORTANT TOOL USAGE RULES:
 
           cleanPayload.messages.push(toolResultMessage);
 
-          // Convert to Anthropic format for session storage
           let sessionToolResult;
           if (providerType === "azure-anthropic") {
             sessionToolResult = toolResultMessage.content;
@@ -2815,7 +2829,6 @@ IMPORTANT TOOL USAGE RULES:
 
         toolCallsExecuted += 1;
 
-        // Check if we've exceeded the max tool calls limit
         if (settings.maxToolCallsPerRequest && toolCallsExecuted > settings.maxToolCallsPerRequest) {
           logger.error(
             {
@@ -2913,7 +2926,6 @@ IMPORTANT TOOL USAGE RULES:
 
         cleanPayload.messages.push(toolMessage);
 
-        // Convert to Anthropic format for session storage
         let sessionToolResultContent;
         if (providerType === "azure-anthropic") {
           // Azure Anthropic already has content in correct format
@@ -3009,7 +3021,6 @@ IMPORTANT TOOL USAGE RULES:
             `Tool call loop detected - same tool called ${loopThreshold} times with identical/similar parameters`,
           );
 
-          // Inject warning message to model
           loopWarningInjected = true;
           const warningMessage = {
             role: "user",
@@ -3107,7 +3118,7 @@ IMPORTANT TOOL USAGE RULES:
       if (Array.isArray(anthropicPayload?.content)) {
         anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
       }
-    } else if (actualProvider === "openrouter") {
+    } else if (actualProvider === "openrouter" || actualProvider === "edenai") {
       const { convertOpenRouterResponseToAnthropic } = require("../clients/openrouter-utils");
 
       // Validate OpenRouter response has choices array before conversion
@@ -3246,7 +3257,6 @@ IMPORTANT TOOL USAGE RULES:
         };
       }
 
-      // Log OpenAI raw response
       logger.info({
         hasChoices: !!databricksResponse.json?.choices,
         choiceCount: databricksResponse.json?.choices?.length || 0,
@@ -3296,7 +3306,6 @@ IMPORTANT TOOL USAGE RULES:
         };
       }
 
-      // Log llama.cpp raw response
       logger.info({
         hasChoices: !!databricksResponse.json?.choices,
         choiceCount: databricksResponse.json?.choices?.length || 0,
@@ -3321,10 +3330,6 @@ IMPORTANT TOOL USAGE RULES:
       anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
     } else if (actualProvider === "zai") {
       // Z.AI responses are already converted to Anthropic format in invokeZai
-      logger.info({
-        hasJson: !!databricksResponse.json,
-        jsonContent: JSON.stringify(databricksResponse.json?.content)?.substring(0, 200),
-      }, "=== ZAI ORCHESTRATOR DEBUG ===");
       anthropicPayload = databricksResponse.json;
       if (Array.isArray(anthropicPayload?.content)) {
         anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
@@ -3337,10 +3342,6 @@ IMPORTANT TOOL USAGE RULES:
       }
     } else if (actualProvider === "moonshot") {
       // Moonshot responses are already converted to Anthropic format in invokeMoonshot
-      logger.info({
-        hasJson: !!databricksResponse.json,
-        jsonContent: JSON.stringify(databricksResponse.json?.content)?.substring(0, 300),
-      }, "=== MOONSHOT ORCHESTRATOR DEBUG ===");
       anthropicPayload = databricksResponse.json;
       if (Array.isArray(anthropicPayload?.content)) {
         anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
@@ -3351,6 +3352,12 @@ IMPORTANT TOOL USAGE RULES:
       if (Array.isArray(anthropicPayload?.content)) {
         anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
       }
+    } else if (databricksResponse.json?.type === "message" && Array.isArray(databricksResponse.json?.content)) {
+      // Shape-detected: already Anthropic (some clients convert upstream).
+      // Re-converting via toAnthropicResponse reads the absent choices[]
+      // and empties the content.
+      anthropicPayload = databricksResponse.json;
+      anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
     } else {
       anthropicPayload = toAnthropicResponse(
         databricksResponse.json,
@@ -3366,7 +3373,10 @@ IMPORTANT TOOL USAGE RULES:
       (item) => item.type === "text" && needsWebFallback(item.text),
     );
 
-    if (fallbackCandidate && !fallbackPerformed) {
+    // Web fallback is SERVER-mode only: in client mode the client owns
+    // WebSearch/WebFetch, and a server-side fetch would duplicate it.
+    const _clientOwnsWeb = config.toolExecutionMode === "client" || config.toolExecutionMode === "passthrough";
+    if (fallbackCandidate && !fallbackPerformed && !_clientOwnsWeb) {
       if (providerType === "azure-anthropic") {
         anthropicPayload.content.push({
           type: "text",
@@ -3486,7 +3496,6 @@ IMPORTANT TOOL USAGE RULES:
 
           cleanPayload.messages.push(assistantToolMessage);
 
-          // Convert to Anthropic format for session storage
           let sessionFallbackContent;
           if (providerType === "azure-anthropic") {
             // Already in Anthropic format
@@ -3501,7 +3510,6 @@ IMPORTANT TOOL USAGE RULES:
               });
             }
 
-            // Add tool_use blocks from tool_calls
             if (Array.isArray(assistantToolMessage.tool_calls)) {
               for (const tc of assistantToolMessage.tool_calls) {
                 const func = tc.function || {};
@@ -3555,7 +3563,6 @@ IMPORTANT TOOL USAGE RULES:
 
           cleanPayload.messages.push(toolResultMessage);
 
-          // Convert to Anthropic format for session storage
           let sessionFallbackToolResult;
           if (providerType === "azure-anthropic") {
             // Already in Anthropic format
@@ -3589,7 +3596,6 @@ IMPORTANT TOOL USAGE RULES:
 
           toolCallsExecuted += 1;
 
-          // Check if we've exceeded the max tool calls limit
           if (settings.maxToolCallsPerRequest && toolCallsExecuted > settings.maxToolCallsPerRequest) {
             logger.error(
               {
@@ -3641,6 +3647,7 @@ IMPORTANT TOOL USAGE RULES:
         provider: databricksResponse.routingDecision.provider,
         model: databricksResponse.routingDecision.model,
         tier: databricksResponse.routingDecision.tier,
+        score: databricksResponse.routingDecision.score ?? null,
       };
     }
 
@@ -3859,11 +3866,6 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
 
   // === TOOL LOOP GUARD (EARLY CHECK) ===
   // Check BEFORE sanitization since sanitizePayload removes conversation history
-  // All providers use threshold 2 to catch loops early
-  const providerType = config.modelProvider?.type ?? "databricks";
-  const toolLoopThreshold = 2;
-  const { toolResultCount, toolUseCount } = countToolCallsInHistory(payload?.messages);
-
   const executionMode = config.toolExecutionMode || "server";
   const isClientMode = executionMode === "client" || executionMode === "passthrough";
 
@@ -4009,7 +4011,6 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
   const cleanPayload = sanitizePayload(payload);
   pTimer.mark("sanitizePayload");
 
-  // Proactively load tools based on prompt content (lazy loading)
   try {
     const { loaded } = lazyLoader.ensureToolsForPrompt(cleanPayload.messages);
     if (loaded.length > 0) {
@@ -4039,8 +4040,7 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
     cacheKey = key;
     if (entry?.value) {
       try {
-        // Use worker pool for large cached responses
-        cachedResponse = await asyncClone(entry.value);
+        cachedResponse = structuredClone(entry.value);
       } catch {
         cachedResponse = entry.value;
       }
@@ -4048,11 +4048,14 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
   }
 
   if (cachedResponse) {
-    const anthropicPayload = toAnthropicResponse(
-      cachedResponse.json,
-      requestedModel,
-      wantsThinking,
-    );
+    // Same shape guard as the live path: cached json may already be Anthropic.
+    const anthropicPayload = (cachedResponse.json?.type === "message" && Array.isArray(cachedResponse.json?.content))
+      ? cachedResponse.json
+      : toAnthropicResponse(
+          cachedResponse.json,
+          requestedModel,
+          wantsThinking,
+        );
     anthropicPayload.content = policy.sanitiseContent(anthropicPayload.content);
 
     const promptTokens = cachedResponse.json?.usage?.prompt_tokens ?? 0;
@@ -4069,6 +4072,7 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
         provider: cachedResponse.routingDecision.provider,
         model: cachedResponse.routingDecision.model,
         tier: cachedResponse.routingDecision.tier,
+        score: cachedResponse.routingDecision.score ?? null,
       };
     }
 
@@ -4095,7 +4099,6 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
     };
   }
 
-  // Semantic cache lookup (fuzzy matching based on embedding similarity)
   let semanticLookupResult = null;
   const semanticCache = getSemanticCache();
   if (semanticCache.isEnabled()) {
@@ -4123,7 +4126,12 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
 
         return {
           status: 200,
-          body: cachedBody,
+          // Spread so the marker never mutates the stored cache entry.
+          // Anthropic clients ignore unknown top-level fields; benchmarks
+          // and dashboards use this to attribute cache hits honestly —
+          // previously a hit was indistinguishable from a full-price call
+          // in the response body (usage echoed the cached values).
+          body: { ...cachedBody, lynkr_semantic_cache: { hit: true, similarity: semanticLookupResult.similarity ?? null } },
           terminationReason: "completion",
         };
       }
@@ -4132,9 +4140,6 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
     }
   }
 
-  // NOTE: Tool loop guard moved to BEFORE sanitizePayload() since sanitization
-  // removes conversation history (consecutive same-role messages)
-
   pTimer.mark("preAgentLoop");
   const loopResult = await runAgentLoop({
     cleanPayload,
@@ -4150,7 +4155,6 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
   pTimer.mark("agentLoopDone");
   pTimer.done();
 
-  // Store successful responses in semantic cache for future fuzzy matching
   if (semanticCache.isEnabled() && semanticLookupResult && !semanticLookupResult.hit) {
     if (loopResult.response?.status === 200 && loopResult.response?.body) {
       try {
@@ -4164,8 +4168,39 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
   return loopResult.response;
 }
 
+/**
+ * Trim an over-long agent-loop conversation while ALWAYS preserving the
+ * current task: the latest user message with real typed text. Keeps the
+ * 2-message head (opening context), the task message (re-inserted if it
+ * would fall in the trimmed middle), and the most recent tail. Boundary
+ * orphans (tool_results whose tool_use was trimmed) are handled by the
+ * converters' existing orphan-droppers.
+ */
+function trimLoopMessages(messages, max) {
+  const { extractCleanUserText } = require("../routing/intent-score");
+  let taskIdx = -1;
+  for (let i = messages.length - 1; i >= 2; i--) {
+    if (messages[i]?.role === "user" && extractCleanUserText({ messages: [messages[i]] })) {
+      taskIdx = i;
+      break;
+    }
+  }
+  const head = messages.slice(0, 2);
+  const keepTail = max - head.length - 1;
+  const tailStart = messages.length - keepTail;
+  const taskMsg = taskIdx >= 2 && taskIdx < tailStart ? [messages[taskIdx]] : [];
+  const trimmed = [...head, ...taskMsg, ...messages.slice(tailStart)];
+  logger.debug(
+    { trimmed: messages.length - trimmed.length, remaining: trimmed.length, taskKept: taskMsg.length > 0 || taskIdx >= tailStart || taskIdx < 2 },
+    "Trimmed intermediate messages to prevent memory growth",
+  );
+  return trimmed;
+}
+
 module.exports = {
   processMessage,
   // Exported for unit testing of response-metadata conversion.
   toAnthropicResponse,
+  // Exported for unit testing of loop trimming (task-preservation contract).
+  trimLoopMessages,
 };