lynkr 9.14.2 → 9.14.7

package/src/clients/databricks.js

@@ -77,11 +77,26 @@ function _stripInternalFields(body) {
   return cleaned || body;
 }
 
-async function performJsonRequest(url, { headers = {}, body, retryableStatusesOverride, maxRetriesOverride }, providerLabel) {
+async function performJsonRequest(url, { headers = {}, body, retryableStatusesOverride, maxRetriesOverride, timeoutMs }, providerLabel) {
   const agent = url.startsWith('https:') ? httpsAgent : httpAgent;
   body = _stripInternalFields(body);
   const isStreaming = body.stream === true;
 
+  // Optional per-call abort timeout (opt-in via timeoutMs) — most callers
+  // omit it and keep the historical unbounded-fetch behavior. Added for
+  // llama.cpp (see invokeLlamaCpp): a dead upstream that accepts the TCP
+  // connection but never answers at the application layer hangs fetch()
+  // indefinitely — live-observed at ~75s, riding an incidental OS/tunnel
+  // socket timeout rather than any deliberate bound. This makes the
+  // already-configured (but previously unused) LLAMACPP_TIMEOUT_MS real.
+  // A fresh signal is created per attempt below (not hoisted here) —
+  // AbortSignal.timeout()'s clock starts at construction, so one signal
+  // shared across withRetry's attempts would leave later retries with a
+  // shrinking (or already-expired) budget instead of a full timeout each.
+  const makeSignal = () => (typeof timeoutMs === "number" && timeoutMs > 0
+    ? AbortSignal.timeout(timeoutMs)
+    : undefined);
+
   // Streaming requests can't be retried, so handle them directly
   if (isStreaming) {
     const response = await fetch(url, {
@@ -89,6 +104,7 @@ async function performJsonRequest(url, { headers = {}, body, retryableStatusesOv
       headers,
       body: JSON.stringify(body),
       agent,
+      signal: makeSignal(),
     });
 
     logger.debug({
@@ -122,6 +138,7 @@ async function performJsonRequest(url, { headers = {}, body, retryableStatusesOv
       headers,
       body: JSON.stringify(body),
       agent,
+      signal: makeSignal(),
     });
     const text = await response.text();
 
@@ -829,7 +846,21 @@ async function invokeOpenRouter(body, _incomingHeaders = {}) {
     }, "Sending tools to OpenRouter");
   }
 
-  return performJsonRequest(endpoint, { headers, body: openRouterBody }, "OpenRouter");
+  // Same pre-return 429 check as invokeMoonshot/invokeBaidu — see the comment
+  // on invokeOpenAI's equivalent check for why this matters for streaming.
+  const response = await performJsonRequest(endpoint, {
+    headers,
+    body: openRouterBody,
+    retryableStatusesOverride: [500, 502, 503, 504],
+  }, "OpenRouter");
+
+  if (!response.ok && response.status === 429) {
+    const err = new Error(`OpenRouter rate-limited: ${String(response.json?.error?.message || '').slice(0, 120)}`);
+    err.status = 429;
+    throw err;
+  }
+
+  return response;
 }
 
 // Eden AI is an OpenAI-compatible gateway (provider/model naming, EU/GDPR).
@@ -1085,7 +1116,7 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
         originalMessageCount: (body.messages || []).length,
         convertedMessageCount: azureBody.messages.length,
         messageRoles: (body.messages || []).map(m => m.role),
-      }, "=== CONTINUATION REQUEST DETECTED - using minimal system prompt to avoid Azure content filter ===");
+      }, "Continuation request — system prompt PRESERVED, system-reminder blocks stripped uniformly (the filter trigger was the reminders, not the prompt; see system-message handling below)");
     } else {
       logger.debug({
         hasToolResults: false,
@@ -1229,17 +1260,34 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
       // the conversation's first user message — stable across every turn of
       // the same task. Keep per-key traffic under ~15 req/min.
       ...(isGpt5 ? { prompt_cache_key: derivePromptCacheKey(body) } : {}),
-      stream: false
+      stream: body.stream ?? false
     };
     logger.debug({
       format: "responses",
       inputCount: responsesBody.input?.length,
       model: responsesBody.model,
-      hasTools: !!responsesBody.tools
+      hasTools: !!responsesBody.tools,
+      streaming: responsesBody.stream,
     }, "Using Responses API format");
 
     const result = await performJsonRequest(endpoint, { headers, body: responsesBody }, "Azure OpenAI Responses");
 
+    // Streaming: hand back a synthetic OpenAI-Chat-Completions-shaped SSE
+    // stream (see src/orchestrator/azure-responses-sse.js for why that shape
+    // rather than Anthropic SSE directly) so the orchestrator's existing
+    // sseTransform.openaiToAnthropicSSE call site — already wired for
+    // moonshot/baidu/openai's raw streams — handles this one identically,
+    // with zero changes needed there. Skips the whole buffered
+    // output-array/dedup/usage-remap conversion below entirely; that logic
+    // only makes sense for a complete, already-materialized response.
+    if (result.stream) {
+      const { azureResponsesToOpenAIChunks } = require("../orchestrator/azure-responses-sse");
+      return {
+        ...result,
+        stream: azureResponsesToOpenAIChunks(result.stream, { model: responsesBody.model }),
+      };
+    }
+
     // Convert Responses API response to Chat Completions format
     if (result.ok && result.json?.output) {
       const outputArray = result.json.output || [];
@@ -1306,6 +1354,8 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
         toolCallNames: toolCalls.map(tc => tc.function.name)
       }, "Parsing Responses API output");
 
+      const _rawUsage = result.json.usage;
+
       result.json = {
         id: result.json.id,
         object: "chat.completion",
@@ -1322,15 +1372,15 @@ async function invokeAzureOpenAI(body, _incomingHeaders = {}) {
         }],
         // Responses API usage is {input,output}_tokens; downstream reads
         // Chat Completions' {prompt,completion}_tokens.
-        usage: result.json.usage ? {
-          prompt_tokens: result.json.usage.prompt_tokens ?? result.json.usage.input_tokens ?? 0,
-          completion_tokens: result.json.usage.completion_tokens ?? result.json.usage.output_tokens ?? 0,
-          total_tokens: result.json.usage.total_tokens
-            ?? ((result.json.usage.input_tokens ?? 0) + (result.json.usage.output_tokens ?? 0)),
+        usage: _rawUsage ? {
+          prompt_tokens: _rawUsage.prompt_tokens ?? _rawUsage.input_tokens ?? 0,
+          completion_tokens: _rawUsage.completion_tokens ?? _rawUsage.output_tokens ?? 0,
+          total_tokens: _rawUsage.total_tokens
+            ?? ((_rawUsage.input_tokens ?? 0) + (_rawUsage.output_tokens ?? 0)),
           // Provider-side prompt-cache hits (Responses API: input_tokens_details,
           // Chat Completions: prompt_tokens_details) — telemetry reads this name.
-          cache_read_input_tokens: result.json.usage.input_tokens_details?.cached_tokens
-            ?? result.json.usage.prompt_tokens_details?.cached_tokens
+          cache_read_input_tokens: _rawUsage.input_tokens_details?.cached_tokens
+            ?? _rawUsage.prompt_tokens_details?.cached_tokens
             ?? null,
         } : undefined
       };
@@ -1437,7 +1487,23 @@ async function invokeOpenAI(body, _incomingHeaders = {}) {
     max_tokens: openAIBody.max_tokens,
   }, "=== OPENAI REQUEST ===");
 
-  return performJsonRequest(endpoint, { headers, body: openAIBody }, "OpenAI");
+  // Same pre-return 429 check as invokeMoonshot/invokeBaidu: performJsonRequest's
+  // streaming branch never throws on a bad status (retry is skipped entirely for
+  // stream:true), so without this a 429 was silently handed back as a "successful"
+  // stream/response and tier-fallback never got a chance to climb.
+  const response = await performJsonRequest(endpoint, {
+    headers,
+    body: openAIBody,
+    retryableStatusesOverride: [500, 502, 503, 504],
+  }, "OpenAI");
+
+  if (!response.ok && response.status === 429) {
+    const err = new Error(`OpenAI rate-limited: ${String(response.json?.error?.message || '').slice(0, 120)}`);
+    err.status = 429;
+    throw err;
+  }
+
+  return response;
 }
 
 async function invokeAtlas(body) {
@@ -1495,12 +1561,26 @@ async function invokeAtlas(body) {
 
   // Chat completions are billable POSTs, so Atlas requests are never replayed
   // automatically. Callers can retry explicitly with their own idempotency policy.
-  return performJsonRequest(endpoint, {
+  // maxRetriesOverride/retryableStatusesOverride stay at 0/[] — this does NOT
+  // retry the Atlas request itself, it only decides whether invokeModel's
+  // caller escalates to a DIFFERENT provider/tier on 429, same as
+  // invokeMoonshot/invokeBaidu/invokeOpenAI/invokeOpenRouter already do.
+  // Without this, a 429 here was silently handed back as a "successful"
+  // response and tier-fallback never got a chance to climb.
+  const response = await performJsonRequest(endpoint, {
     headers,
     body: atlasBody,
     maxRetriesOverride: 0,
     retryableStatusesOverride: [],
   }, "Atlas Cloud");
+
+  if (!response.ok && response.status === 429) {
+    const err = new Error(`Atlas Cloud rate-limited: ${String(response.json?.error?.message || '').slice(0, 120)}`);
+    err.status = 429;
+    throw err;
+  }
+
+  return response;
 }
 
 async function invokeLlamaCpp(body, _incomingHeaders = {}) {
@@ -1580,10 +1660,18 @@ async function invokeLlamaCpp(body, _incomingHeaders = {}) {
     }, 'llama.cpp: Removed consecutive duplicate roles from message sequence');
   }
 
+  // max_tokens floor: reasoning-capable local models (live-confirmed on this
+  // deployment's GPT-OSS build) can spend their entire budget on
+  // `reasoning_content` before writing any visible answer — a caller-
+  // supplied tiny budget (e.g. the caveman probe's max_tokens:1 seen in
+  // production logs) then returns finish_reason:"length" with zero visible
+  // text. Same fix already shipped for Ollama as LYNKR_OLLAMA_MIN_MAX_TOKENS;
+  // mirrored here rather than inventing a different mechanism.
+  const llamacppMinMaxTokens = Number(process.env.LYNKR_LLAMACPP_MIN_MAX_TOKENS) || 1536;
   const llamacppBody = {
     messages: deduplicated,
     temperature: body.temperature ?? 0.7,
-    max_tokens: body.max_tokens ?? 16384,
+    max_tokens: Math.max(body.max_tokens ?? 16384, llamacppMinMaxTokens),
     top_p: body.top_p ?? 1.0,
     stream: body.stream ?? false
   };
@@ -1633,7 +1721,11 @@ async function invokeLlamaCpp(body, _incomingHeaders = {}) {
     }))
   }, "=== LLAMA.CPP REQUEST ===");
 
-  const result = await performJsonRequest(endpoint, { headers, body: llamacppBody }, "llama.cpp");
+  const result = await performJsonRequest(
+    endpoint,
+    { headers, body: llamacppBody, timeoutMs: config.llamacpp.timeout },
+    "llama.cpp",
+  );
 
   // Context overflow is a CAPACITY error, not a request error: the local
   // model's slot is simply too small for this conversation (llama-server
@@ -2063,11 +2155,23 @@ async function invokeZai(body, _incomingHeaders = {}) {
     zaiBody = { ...body };
     zaiBody.model = mappedModel;
 
-    // Force buffered mode: with stream:true this endpoint returns ANTHROPIC
-    // SSE, but the downstream transformer parses OPENAI SSE — every chunk is
-    // unreadable and the client receives an empty completion. Buffered JSON
-    // converts correctly; the router synthesizes client-side SSE as usual.
-    zaiBody.stream = false;
+    // Honor body.stream as-is here. The ONLY caller that ever sets it true
+    // for this branch is passthrough-stream.js's handleNativeStream — zai
+    // isn't in sse-transformer.js's DEFAULT_OPENAI_SSE_PROVIDERS, so the
+    // normal buffered orchestrator (orchestrator/index.js) always sets
+    // cleanPayload.stream=false before invoking any provider not on that
+    // allowlist, and never reaches this branch with stream:true itself.
+    // Forcing false unconditionally (as this used to do) broke exactly that
+    // caller: _anthropicNative() advertises this endpoint as native-passthrough
+    // eligible, handleNativeStream sets stream:true and expects real
+    // Anthropic SSE bytes back, but got a buffered JSON body instead —
+    // handleNativeStream then saw no `.stream` field, silently gave up, and
+    // fell back to the buffered orchestrator path, which called zai AGAIN.
+    // Every native-passthrough request to this endpoint was double-invoking
+    // the real API. If a future caller other than handleNativeStream ever
+    // needs stream:true routed through the OpenAI-SSE transformer instead,
+    // 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) {
@@ -2222,12 +2326,18 @@ async function invokeMoonshot(body, _incomingHeaders = {}) {
   // Only the moonshot-v1-* models accept caller-supplied values.
   const isKimiPinned = /^kimi-k/i.test(mappedModel);
 
+  const { resolveThinkingParam } = require("./provider-capabilities");
   const moonshotBody = {
     model: mappedModel,
     messages,
     max_tokens: body.max_tokens || 16384,
     temperature: isKimiPinned ? 1 : (body.temperature ?? 0.7),
     top_p: isKimiPinned ? 0.95 : (body.top_p ?? 1.0),
+    // kimi-k3 emits verbose reasoning_content by default, sharing the same
+    // token budget as the answer — without this, reasoning alone can (and
+    // did, live-confirmed) consume the whole max_tokens before any answer
+    // is written. See resolveThinkingParam's doc comment for the full story.
+    thinking: resolveThinkingParam(body),
     // Streaming honored since the Phase-2b sse-transformer landed: the raw
     // OpenAI SSE stream is returned below and reshaped in flight by the
     // orchestrator (moonshot is in DEFAULT_OPENAI_SSE_PROVIDERS). Buffered
@@ -2371,12 +2481,18 @@ async function invokeBaidu(body, _incomingHeaders = {}) {
     messages.unshift({ role: "system", content: systemContent });
   }
 
+  const { resolveThinkingParam } = require("./provider-capabilities");
   const baiduBody = {
     model: mappedModel,
     messages,
     max_tokens: body.max_tokens || 16384,
     temperature: body.temperature ?? 0.7,
     top_p: body.top_p ?? 1.0,
+    // glm-5.2 emits verbose reasoning_content by default, sharing the same
+    // token budget as the answer — without this, reasoning alone can (and
+    // did, live-confirmed) consume the whole max_tokens before any answer
+    // is written. See resolveThinkingParam's doc comment for the full story.
+    thinking: resolveThinkingParam(body),
     // Streaming honored once "baidu" is added to DEFAULT_OPENAI_SSE_PROVIDERS
     // (sse-transformer.js) and confirmed to match OpenAI SSE shape. Buffered
     // requests use the Anthropic conversion path below regardless.
@@ -2436,6 +2552,147 @@ async function invokeBaidu(body, _incomingHeaders = {}) {
   return response;
 }
 
+/**
+ * Fireworks AI Provider (serverless inference)
+ *
+ * Fireworks exposes an OpenAI-compatible Chat Completions API
+ * (https://api.fireworks.ai/inference/v1/chat/completions, bearer-token
+ * auth). Modeled on invokeBaidu: request side reuses the shared
+ * openrouter-utils converters, response is converted to Anthropic shape
+ * locally so the orchestrator branch is a plain passthrough.
+ *
+ * Model ids are long-form serverless paths
+ * (accounts/fireworks/models/<slug>, accounts/fireworks/routers/<slug>).
+ * The modelMap below covers bare Anthropic names; tier-selected Fireworks
+ * ids (e.g. TIER_COMPLEX=fireworks:accounts/fireworks/models/glm-5p2)
+ * reach the wire unchanged.
+ *
+ * NOTE (E2E-unverified as of this addition, same caveat Baidu shipped
+ * with): sampling quirks, reasoning_content emission on reasoning models,
+ * finish_reason shape on tool calls, and 429 retryability are best-effort
+ * from public docs, not yet probed against a live key. Revisit once real
+ * traffic surfaces 400s — see Moonshot's kimi-k* precedent for the shape
+ * such fixes take.
+ */
+async function invokeFireworks(body, _incomingHeaders = {}) {
+  if (!config.fireworks?.apiKey) {
+    throw new Error("Fireworks API key is not configured. Set FIREWORKS_API_KEY in your .env file.");
+  }
+
+  const {
+    convertAnthropicToolsToOpenRouter,
+    convertAnthropicMessagesToOpenRouter
+  } = require("./openrouter-utils");
+
+  const endpoint = config.fireworks.endpoint || "https://api.fireworks.ai/inference/v1/chat/completions";
+
+  // Model mapping: Anthropic names → Fireworks serverless ids.
+  const modelMap = {
+    "claude-sonnet-4-5-20250929": "accounts/fireworks/models/kimi-k2-instruct-0905",
+    "claude-sonnet-4-5": "accounts/fireworks/models/kimi-k2-instruct-0905",
+    "claude-sonnet-4.5": "accounts/fireworks/models/kimi-k2-instruct-0905",
+    "claude-3-5-sonnet": "accounts/fireworks/models/kimi-k2-instruct-0905",
+    "claude-opus-4-5": "accounts/fireworks/models/glm-5p2",
+    "claude-opus-4.5": "accounts/fireworks/models/glm-5p2",
+    "claude-3-opus": "accounts/fireworks/models/glm-5p2",
+    "claude-haiku-4-5-20251001": "accounts/fireworks/models/llama-3.1-8b-instruct",
+    "claude-haiku-4-5": "accounts/fireworks/models/llama-3.1-8b-instruct",
+    "claude-3-haiku": "accounts/fireworks/models/llama-3.1-8b-instruct",
+  };
+
+  const requestedModel = body._tierModel || body.model || config.fireworks.model;
+
+  // Honor tier-selected Fireworks ids instead of silently swapping in the
+  // .env default model. Accepts full serverless paths as well as well-known
+  // open-weight family slugs hosted on Fireworks.
+  const FIREWORKS_ID_RE = /^(accounts\/|kimi-|glm-|deepseek-|qwen|llama-|mistral-|mixtral-|phi-|gemma-|grok-|solar-|yi-|fireworks-)/i;
+  const mappedModel = modelMap[requestedModel]
+    || (FIREWORKS_ID_RE.test(requestedModel || "") ? requestedModel : null)
+    || config.fireworks.model
+    || "accounts/fireworks/models/kimi-k2-instruct-0905";
+
+  const messages = convertAnthropicMessagesToOpenRouter(body.messages || []);
+
+  // Fireworks supports the system role natively.
+  if (body.system) {
+    const systemContent = Array.isArray(body.system)
+      ? body.system.map(s => s.text || s).join("\n")
+      : body.system;
+    messages.unshift({ role: "system", content: systemContent });
+  }
+
+  const { resolveThinkingParam } = require("./provider-capabilities");
+  const fireworksBody = {
+    model: mappedModel,
+    messages,
+    max_tokens: body.max_tokens || 16384,
+    temperature: body.temperature ?? 0.7,
+    top_p: body.top_p ?? 1.0,
+    // Reasoning models (R1/GLM) share the answer budget with thinking output;
+    // the buffered path lifts reasoning_content into thinking blocks.
+    thinking: resolveThinkingParam(body),
+    // Streaming honored once "fireworks" joins DEFAULT_OPENAI_SSE_PROVIDERS
+    // (sse-transformer.js). Buffered requests use the Anthropic conversion
+    // path below regardless.
+    stream: body.stream ?? false,
+  };
+
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    fireworksBody.tools = convertAnthropicToolsToOpenRouter(body.tools);
+    fireworksBody.tool_choice = "auto";
+    fireworksBody.parallel_tool_calls = false;
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${config.fireworks.apiKey}`,
+  };
+
+  logger.debug({
+    endpoint,
+    model: fireworksBody.model,
+    originalModel: requestedModel,
+    messageCount: fireworksBody.messages?.length || 0,
+    hasTools: !!fireworksBody.tools,
+    toolCount: fireworksBody.tools?.length || 0,
+  }, "=== Fireworks REQUEST ===");
+
+  // No retryableStatusesOverride: Fireworks serverless 429s are standard
+  // per-minute rate limits (unlike Moonshot's persistent org quotas), so the
+  // default retry-with-backoff applies. A 429 that survives retries throws
+  // below with status set so tier-fallback climbs instead of hanging.
+  const response = await performJsonRequest(endpoint, {
+    headers,
+    body: fireworksBody,
+  }, "Fireworks");
+
+  if (!response.ok && response.status === 429) {
+    const err = new Error(`Fireworks rate-limited: ${String(response.json?.error?.message || '').slice(0, 120)}`);
+    err.status = 429;
+    throw err;
+  }
+
+  // Streaming request: hand the raw stream to the orchestrator's stream
+  // branch. The Anthropic conversion below is buffered-only.
+  if (response?.stream) {
+    return response;
+  }
+
+  if (response?.ok && response?.json) {
+    const anthropicJson = convertOpenAIToAnthropic(response.json);
+    return {
+      ok: response.ok,
+      status: response.status,
+      json: anthropicJson,
+      text: JSON.stringify(anthropicJson),
+      contentType: "application/json",
+      headers: response.headers,
+    };
+  }
+
+  return response;
+}
+
 /**
  * Convert OpenAI response to Anthropic format
  */
@@ -3028,6 +3285,7 @@ const PROVIDER_INVOKERS = {
   moonshot: invokeMoonshot,
   codex: invokeCodex,
   baidu: invokeBaidu,
+  fireworks: invokeFireworks,
 };
 
 function invokeProvider(provider, body, incomingHeaders) {
@@ -3289,6 +3547,7 @@ async function invokeModel(body, options = {}) {
       base_tier: routingResult.base_tier ?? null,
       escalation_source: routingResult.escalation_source ?? null,
       propensity: routingResult.propensity ?? null,
+      context: routingResult._banditContext ?? null,
       candidates: routingResult.candidates ?? null,
       pinned: routingResult.pinned ? 1 : 0,
       switch_reason: routingResult.switch_reason ?? null,
@@ -3523,6 +3782,7 @@ async function invokeModel(body, options = {}) {
         base_tier: routingResult.base_tier ?? null,
         escalation_source: routingResult.escalation_source ?? null,
         propensity: routingResult.propensity ?? null,
+      context: routingResult._banditContext ?? null,
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
@@ -3635,6 +3895,7 @@ async function invokeModel(body, options = {}) {
           base_tier: routingResult.base_tier ?? null,
           escalation_source: routingResult.escalation_source ?? null,
           propensity: routingResult.propensity ?? null,
+      context: routingResult._banditContext ?? null,
           candidates: routingResult.candidates ?? null,
           pinned: routingResult.pinned ? 1 : 0,
           switch_reason: routingResult.switch_reason ?? null,
@@ -3731,6 +3992,7 @@ async function invokeModel(body, options = {}) {
         base_tier: routingResult.base_tier ?? null,
         escalation_source: routingResult.escalation_source ?? null,
         propensity: routingResult.propensity ?? null,
+      context: routingResult._banditContext ?? null,
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
@@ -3791,6 +4053,7 @@ async function invokeModel(body, options = {}) {
         base_tier: routingResult.base_tier ?? null,
         escalation_source: routingResult.escalation_source ?? null,
         propensity: routingResult.propensity ?? null,
+      context: routingResult._banditContext ?? null,
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
@@ -3892,6 +4155,7 @@ module.exports = {
   invokeOllama,
   invokeMoonshot,
   invokeBaidu,
+  invokeFireworks,
   invokeAtlas,
   PROVIDER_INVOKERS,
   stripLynkrBadges,

package/src/clients/gpt-utils.js

@@ -38,6 +38,45 @@ function stringSimilarity(s1, s2) {
   return union.size > 0 ? intersection.size / union.size : 0;
 }
 
+// Common argument keys a Read-style tool might carry its target path under,
+// across different clients/harnesses.
+const FILE_PATH_ARG_KEYS = ['file_path', 'path', 'filePath', 'filename', 'file'];
+
+/**
+ * Pull a file-path argument out of a (possibly stringified) args object,
+ * trying the common key spellings different clients use.
+ * @param {string|Object} args
+ * @returns {string|null}
+ */
+function extractFilePathArg(args) {
+  let obj = args;
+  if (typeof obj === 'string') {
+    try { obj = JSON.parse(obj); } catch { return null; }
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  for (const key of FILE_PATH_ARG_KEYS) {
+    if (typeof obj[key] === 'string' && obj[key]) return obj[key];
+  }
+  return null;
+}
+
+/**
+ * Extract a read window [start, end) from read-tool args (offset/limit in
+ * lines, the convention Claude Code, opencode, and Cursor all share).
+ * Missing offset → 0; missing limit → open-ended (whole rest of the file).
+ * @param {string|Object} args
+ * @returns {{ start: number, end: number }}
+ */
+function extractReadWindow(args) {
+  let obj = args;
+  if (typeof obj === 'string') {
+    try { obj = JSON.parse(obj); } catch { obj = null; }
+  }
+  const start = Number.isFinite(obj?.offset) ? obj.offset : 0;
+  const limit = Number.isFinite(obj?.limit) && obj.limit > 0 ? obj.limit : Infinity;
+  return { start, end: start + limit };
+}
+
 /**
  * Check if two tool calls are semantically similar
  * @param {Object} call1 - First tool call {name, arguments}
@@ -59,17 +98,53 @@ function areSimilarToolCalls(call1, call2) {
 
   if (argsStr1 === argsStr2) return true;
 
+  const toolName = (name1 || '').toLowerCase();
+
+  // Read-style tools: NOT Jaccard-fuzzy-matched (see below for why), and NOT
+  // matched on path alone either. This rule has flip-flopped through two live
+  // incidents, so the history matters:
+  //
+  //   1. Jaccard on paths merged reads of DIFFERENT files (repo paths share
+  //      nearly every token) → fixed by exact path equality.
+  //   2. Exact-args-only let an agent re-read one file at OVERLAPPING offsets
+  //      ~10 times, restating the same conclusion, without ever tripping the
+  //      guard → fixed by counting any same-path read as similar.
+  //   3. That overcorrected: paging through DISJOINT regions of one large
+  //      file is exactly how a coding agent works on it (live incident: a
+  //      4,000-line settings.rs read at offsets 975/3485/3800 tripped the
+  //      warn threshold, and the injected "STOP calling this tool" order
+  //      killed the work turn — repeatedly).
+  //
+  // The rule that satisfies all three: same file + OVERLAPPING (or identical)
+  // windows → similar (re-reading content you already have); same file +
+  // DISJOINT windows → paging, not a loop. Whole-file reads (no offset/limit)
+  // have an open-ended window, so they overlap everything in that file —
+  // repeated whole-file re-reads still count, incident #2 stays fixed.
+  if (toolName.includes('read')) {
+    const path1 = extractFilePathArg(args1);
+    const path2 = extractFilePathArg(args2);
+    if (path1 && path2 && path1 === path2) {
+      const w1 = extractReadWindow(args1);
+      const w2 = extractReadWindow(args2);
+      const overlaps = w1.start < w2.end && w2.start < w1.end;
+      if (overlaps) {
+        logger.debug({ tool: name1, path: path1, w1, w2 }, "Same-file overlapping re-read detected");
+        return true;
+      }
+      return false;
+    }
+    return false;
+  }
+
   // Only search-style tools get fuzzy matching; mutating tools with
   // near-identical args may be intentional repeats.
-  // 'read' is deliberately NOT fuzzy-matched: its argument is a file path, and
-  // absolute paths in one repo share nearly every Jaccard token
-  // (/Users/x/project/src/…), so reads of DIFFERENT files scored ≥0.8 and
-  // merged into one "repeated call" signature (live incident: an opencode
+  // 'read' is handled above, deliberately NOT via Jaccard: its argument is a
+  // file path, and absolute paths in one repo share nearly every Jaccard
+  // token (/Users/x/project/src/…), so reads of DIFFERENT files scored ≥0.8
+  // and merged into one "repeated call" signature (live incident: an opencode
   // code-trace reading server.js, openai-router.js and orchestrator/index.js
-  // was flagged as a loop). A genuine re-read of the same file is caught by
-  // the exact-match branch above.
+  // was flagged as a loop).
   const searchTools = ['grep', 'glob', 'search', 'find', 'bash', 'shell'];
-  const toolName = (name1 || '').toLowerCase();
   const isSearchTool = searchTools.some(t => toolName.includes(t));
 
   if (isSearchTool) {
@@ -91,4 +166,5 @@ function areSimilarToolCalls(call1, call2) {
 
 module.exports = {
   areSimilarToolCalls,
+  extractReadWindow,
 };