lynkr 9.14.1 → 9.14.3

package/src/context/compression.js

@@ -40,14 +40,50 @@ function compressHistory(messages, options = {}) {
     keepRecentTurns: options.keepRecentTurns ?? config.historyCompression?.keepRecentTurns ?? 10,
     summarizeOlder: options.summarizeOlder ?? config.historyCompression?.summarizeOlder ?? true,
     enabled: options.enabled ?? config.historyCompression?.enabled ?? true,
+    // Model token budget (e.g. effectiveMax from the orchestrator). When set,
+    // the verbatim-recent window grows to USE the budget instead of a fixed
+    // message count. Live incident: a 935-message session against a 128k
+    // model kept only 10 recent messages (~56k tokens) while 108.8k tokens
+    // of budget were available — ~50k tokens of context thrown away, giving
+    // the model amnesia about its own recent edits.
+    budgetTokens: options.budgetTokens ?? null,
   };
 
   if (!opts.enabled) {
     return messages; // Return uncompressed if disabled
   }
 
+  // Recent-window size: fixed count by default; budget-driven when a model
+  // token budget is provided. RECENT_BUDGET_FRACTION reserves the rest of
+  // the budget for the summary block, system prompt, tools, and the
+  // response itself.
+  const RECENT_BUDGET_FRACTION = 0.6;
+  const CHARS_PER_TOKEN = 4;
+  let keepRecent = opts.keepRecentTurns;
+  if (Number.isFinite(opts.budgetTokens) && opts.budgetTokens > 0) {
+    const targetChars = opts.budgetTokens * CHARS_PER_TOKEN * RECENT_BUDGET_FRACTION;
+    let accumulated = 0;
+    let count = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      accumulated += estimateMessagesSize([messages[i]]);
+      if (accumulated > targetChars) break;
+      count++;
+    }
+    keepRecent = Math.max(opts.keepRecentTurns, count);
+  }
+
   // Calculate split point
-  const splitIndex = Math.max(0, messages.length - opts.keepRecentTurns);
+  let splitIndex = Math.max(0, messages.length - keepRecent);
+
+  // Tool-exchange boundary alignment: never let the recent window START with
+  // a tool_result whose paired tool_use just got summarized away — providers
+  // reject orphaned tool_result blocks ("unexpected tool_use_id"). Pull the
+  // split earlier until the boundary is clean.
+  const startsWithToolResult = (msg) =>
+    Array.isArray(msg?.content) && msg.content.some((b) => b?.type === 'tool_result');
+  while (splitIndex > 0 && startsWithToolResult(messages[splitIndex])) {
+    splitIndex--;
+  }
 
   if (splitIndex === 0) {
     // All messages are recent, no compression needed
@@ -126,31 +162,56 @@ function summarizeOldHistory(messages) {
   let hasUserInput = false;
   let hasAssistantOutput = false;
 
+  // Index tool_result blocks by tool_use_id so each tool_use below can carry
+  // a one-line recap of what it actually found. Previously this summary kept
+  // only the tool NAME ("Assistant used tools: bash") and threw away the
+  // result entirely — which meant a long tool-calling session forgot its own
+  // diagnosis every time it aged past the recent-turns window and had to
+  // re-derive it from scratch (live symptom: an agent stuck re-reading the
+  // same file and re-fetching the same issue instead of ever writing a fix).
+  const resultByToolUseId = new Map();
+  for (const msg of messages) {
+    if (!Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block?.type === 'tool_result' && block.tool_use_id) {
+        resultByToolUseId.set(block.tool_use_id, extractResultSnippet(block));
+      }
+    }
+  }
+
   for (const msg of messages) {
     if (msg.role === 'user') {
       hasUserInput = true;
       const content = extractTextContent(msg);
-      if (content.length < 200) {
-        keyPoints.push(`User: ${content}`);
-      } else {
-        // Compress long user messages
-        keyPoints.push(`User: ${content.substring(0, 150)}...`);
+      if (content) {
+        // compressText keeps head AND tail (unlike a flat substring(0, N)),
+        // which matters here too: the actionable part of a long user
+        // message is often at the end ("...so please fix X and open a PR").
+        keyPoints.push(`User: ${compressText(content, 200)}`);
       }
     } else if (msg.role === 'assistant') {
       hasAssistantOutput = true;
       const content = extractTextContent(msg);
 
-      // Extract tool uses
-      const toolUses = extractToolUses(msg);
-      if (toolUses.length > 0) {
-        keyPoints.push(`Assistant used tools: ${toolUses.join(', ')}`);
+      // Extract tool uses WITH their outcome, not just the tool name.
+      const toolUseBlocks = extractToolUseBlocks(msg);
+      for (const use of toolUseBlocks) {
+        const argsSnippet = summarizeToolArgs(use.input);
+        const resultSnippet = resultByToolUseId.get(use.id);
+        keyPoints.push(
+          resultSnippet
+            ? `Assistant called ${use.name}(${argsSnippet}) → ${resultSnippet}`
+            : `Assistant called ${use.name}(${argsSnippet})`
+        );
       }
 
-      // Add assistant text if meaningful
-      if (content.length > 20 && content.length < 200) {
-        keyPoints.push(`Assistant: ${content}`);
-      } else if (content.length >= 200) {
-        keyPoints.push(`Assistant: ${content.substring(0, 150)}...`);
+      // Add assistant text if meaningful. compressText (head+tail) instead
+      // of a head-only substring(0, 150) — conclusions ("Cause: ...",
+      // "Findings: ...") are usually written at the END of a reasoning
+      // turn, so a head-only cut was silently discarding exactly the part
+      // that mattered for remembering what was already diagnosed.
+      if (content.length > 20) {
+        keyPoints.push(`Assistant: ${compressText(content, 300)}`);
       }
     }
   }
@@ -168,6 +229,51 @@ function summarizeOldHistory(messages) {
   };
 }
 
+/**
+ * Short, single-line recap of a tool_result's content — used so the
+ * compacted history shows what a tool call actually found, not just that it
+ * was called. Reuses compressText's head+tail truncation.
+ *
+ * @param {Object} block - tool_result block
+ * @returns {string} snippet, or '' if the result had no usable text
+ */
+function extractResultSnippet(block) {
+  const RESULT_SNIPPET_MAX = 160;
+  let text = '';
+  if (typeof block.content === 'string') {
+    text = block.content;
+  } else if (Array.isArray(block.content)) {
+    text = block.content
+      .filter(item => typeof item === 'string' || item?.type === 'text')
+      .map(item => (typeof item === 'string' ? item : item.text || ''))
+      .join(' ');
+  }
+  text = text.trim();
+  if (!text) return '';
+  const prefix = block.is_error ? 'error: ' : '';
+  return prefix + compressText(text, RESULT_SNIPPET_MAX);
+}
+
+/**
+ * Compact, single-line rendering of a tool_use's arguments for the summary
+ * (e.g. `Read(file_path=".../types.go", offset=390)`), not the full JSON.
+ *
+ * @param {Object} input - tool_use input object
+ * @returns {string}
+ */
+function summarizeToolArgs(input) {
+  const ARGS_SNIPPET_MAX = 80;
+  if (!input || typeof input !== 'object') return '';
+  try {
+    const flat = Object.entries(input)
+      .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+      .join(', ');
+    return compressText(flat, ARGS_SNIPPET_MAX);
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Compress a single message
  *
@@ -382,17 +488,19 @@ function extractTextContent(message) {
 }
 
 /**
- * Extract tool names used in message
+ * Extract tool_use blocks (id/name/input) from a message — the fuller
+ * counterpart to extractToolUses(), which only returns names. Used by
+ * summarizeOldHistory() to pair each call with its outcome.
  *
  * @param {Object} message - Message object
- * @returns {Array} Tool names
+ * @returns {Array<{id: string, name: string, input: Object}>}
  */
-function extractToolUses(message) {
+function extractToolUseBlocks(message) {
   if (!Array.isArray(message.content)) return [];
 
   return message.content
     .filter(block => block.type === 'tool_use')
-    .map(block => block.name);
+    .map(block => ({ id: block.id, name: block.name, input: block.input }));
 }
 
 /**

package/src/context/tool-result-compressor.js

@@ -696,7 +696,7 @@ function compressDirectoryListing(text, opts = {}) {
   // skips this check — real listings can contain names (spaces, unicode)
   // the shape regex would reject.
   if (!opts.trusted) {
-    const pathLines = lines.filter(l => /^[.\w\/-]+\.\w+$/.test(l.trim()) || /^[.\w\/-]+\/$/.test(l.trim()) || /^[-drwx]{10}/.test(l.trim()));
+    const pathLines = lines.filter(l => /^[.\w/-]+\.\w+$/.test(l.trim()) || /^[.\w/-]+\/$/.test(l.trim()) || /^[-drwx]{10}/.test(l.trim()));
     if (pathLines.length < lines.length * 0.6) return null;
   }
 
@@ -823,7 +823,7 @@ function compressLintOutput(text, opts = {}) {
   for (const line of clean.split("\n")) {
     // ESLint stylish prints each file as a standalone path line above its
     // issue block — track it so issues group per file.
-    if (/^\S+[\/\\]\S+\.\w+$/.test(line.trim()) && !line.includes(":")) {
+    if (/^\S+[/\\]\S+\.\w+$/.test(line.trim()) && !line.includes(":")) {
       currentFile = line.trim();
       continue;
     }
@@ -935,8 +935,6 @@ function compressLargeFile(text) {
 
   // Extract structural skeleton
   const skeleton = [];
-  let inBlock = false;
-  let braceDepth = 0;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -960,7 +958,7 @@ function compressLargeFile(text) {
     }
 
     // Keep decorators/attributes
-    if (/^[@#\[]/.test(trimmed)) {
+    if (/^[@#[]/.test(trimmed)) {
       skeleton.push(line);
       continue;
     }

package/src/dashboard/api.js

@@ -2,7 +2,6 @@ const config = require('../config');
 const telemetry = require('../routing/telemetry');
 const { getUsage } = require('../usage/aggregator');
 const metrics = require('../metrics');
-const { getMetricsCollector } = require('../observability/metrics');
 const { TIER_DEFINITIONS } = require('../routing/model-tiers');
 
 // Per-provider type + whether its credentials/endpoint are actually present.
@@ -18,6 +17,7 @@ function providerMeta() {
     'azure-openai':    { type: 'cloud', configured: !!(c.azureOpenAI?.endpoint && c.azureOpenAI?.apiKey) },
     vertex:            { type: 'cloud', configured: !!c.vertex?.projectId },
     moonshot:          { type: 'cloud', configured: !!c.moonshot?.apiKey },
+    fireworks:         { type: 'cloud', configured: !!c.fireworks?.apiKey },
     ollama:            { type: 'local', configured: !!c.ollama?.endpoint },
     llamacpp:          { type: 'local', configured: !!c.llamacpp?.endpoint },
     lmstudio:          { type: 'local', configured: !!c.lmstudio?.endpoint },

package/src/logger/oversized-error-stream.js

@@ -66,7 +66,7 @@ function createOversizedErrorStream(config) {
 		},
 		final(callback) {
 			// Close all open file handles when stream ends
-			for (const [sessionId, { writeStream }] of sessionFiles.entries()) {
+			for (const [_sessionId, { writeStream }] of sessionFiles.entries()) {
 				writeStream.end();
 			}
 			sessionFiles.clear();

package/src/memory/extractor.js

@@ -26,14 +26,14 @@ const EXTRACTION_PATTERNS = {
   ],
 
   entity: [
-    /(?:file|function|class|module|component|package|library)\s+['"`]?([A-Za-z0-9_./\-]+)['"`]?/gi,
-    /in\s+['"`]([A-Za-z0-9_./\-]+\.(?:js|ts|py|java|go|rs|cpp|c|h))['"`]/gi,
+    /(?:file|function|class|module|component|package|library)\s+['"`]?([A-Za-z0-9_./-]+)['"`]?/gi,
+    /in\s+['"`]([A-Za-z0-9_./-]+\.(?:js|ts|py|java|go|rs|cpp|c|h))['"`]/gi,
     /`([A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*)`/g, // Code references
   ],
 
   relationship: [
     /([A-Za-z0-9_]+)\s+(?:depends on|imports|uses|extends|implements|inherits from)\s+([A-Za-z0-9_]+)/gi,
-    /([A-Za-z0-9_./\-]+)\s+(?:calls|invokes|references)\s+([A-Za-z0-9_./\-]+)/gi,
+    /([A-Za-z0-9_./-]+)\s+(?:calls|invokes|references)\s+([A-Za-z0-9_./-]+)/gi,
   ],
 };
 

package/src/memory/search.js

@@ -30,7 +30,7 @@ function sanitizeKeyword(keyword) {
   
   // Remove ALL FTS5 special characters
   const sanitized = keyword
-    .replace(/[*()<>\-:\[\]{}|^~,.;!?'"@#$%&+=/\\\\]/g, ' ')
+    .replace(/[*()<>\-:[\]{}|^~,.;!?'"@#$%&+=/\\\\]/g, ' ')
     .replace(/\s+/g, ' ')
     .trim();
   
@@ -97,7 +97,7 @@ function prepareFTS5Query(query) {
   // - @ symbol → "syntax error near @"
   // - Quotes (") → can break string quoting
   // - Parentheses, brackets → break grouping syntax
-  cleaned = cleaned.replace(/[*()<>\-:\[\]{}|^~,.;!?'"@#$%&+=/\\\\]/g, ' ');
+  cleaned = cleaned.replace(/[*()<>\-:[\]{}|^~,.;!?'"@#$%&+=/\\\\]/g, ' ');
   cleaned = cleaned.replace(/\s+/g, ' ').trim();
 
   if (!cleaned) {

package/src/memory/store.js

@@ -122,12 +122,6 @@ const upsertEntityStmt = db.prepare(`
     properties = @properties
 `);
 
-const getEntityStmt = db.prepare(`
-  SELECT id, entity_type, entity_name, first_seen_at, last_seen_at, occurrence_count, properties
-  FROM memory_entities
-  WHERE entity_type = ? AND entity_name = ?
-`);
-
 const getAllEntitiesStmt = db.prepare(`
   SELECT id, entity_type, entity_name, first_seen_at, last_seen_at, occurrence_count, properties
   FROM memory_entities
@@ -176,19 +170,6 @@ function toMemory(row) {
   };
 }
 
-function toEntity(row) {
-  if (!row) return null;
-  return {
-    id: row.id,
-    entityType: row.entity_type,
-    entityName: row.entity_name,
-    firstSeenAt: row.first_seen_at,
-    lastSeenAt: row.last_seen_at,
-    occurrenceCount: row.occurrence_count ?? 1,
-    properties: parseJSON(row.properties, {}),
-  };
-}
-
 /**
  * Create a new memory
  */
@@ -400,16 +381,20 @@ function trackEntity(options) {
 }
 
 /**
- * Get an entity
+ * Get an entity by name, optionally scoped to a type. Names can collide
+ * across types (e.g. a "file" and a "topic" both named "router"), so
+ * without a type filter the most recently seen entity wins,
+ * deterministically.
  */
-function getEntity(name) {
-  // Since we only have the name, we need to search across all entity types
+function getEntity(name, type = null) {
   const stmt = db.prepare(`
     SELECT id, entity_type, entity_name, first_seen_at, last_seen_at, occurrence_count, properties
     FROM memory_entities
-    WHERE entity_name = ?
+    WHERE entity_name = ? ${type ? "AND entity_type = ?" : ""}
+    ORDER BY last_seen_at DESC
+    LIMIT 1
   `);
-  const row = stmt.get(name);
+  const row = type ? stmt.get(name, type) : stmt.get(name);
   if (!row) return null;
 
   return {

package/src/memory/tools.js

@@ -340,6 +340,19 @@ async function memory_stats(args, context = {}) {
       };
     }
 
+    // Surface tracked entities — the extractor writes them on every
+    // conversation, but until this they were collected and never readable.
+    let entities = [];
+    try {
+      entities = store.getAllEntities(10).map(e => ({
+        name: e.name,
+        type: e.type,
+        count: e.count,
+      }));
+    } catch (err) {
+      logger.debug({ err: err.message }, 'Entity stats unavailable');
+    }
+
     return {
       ok: true,
       content: JSON.stringify({
@@ -350,6 +363,7 @@ async function memory_stats(args, context = {}) {
         recentCount: stats.recentCount,
         importantCount: stats.importantCount,
         sessionId: stats.sessionId || 'global',
+        topEntities: entities,
       }, null, 2),
     };
   } catch (err) {

package/src/observability/metrics.js

@@ -1,6 +1,3 @@
-const config = require("../config");
-const logger = require("../logger");
-
 /**
  * High-performance metrics collection
  *
@@ -32,6 +29,20 @@ class MetricsCollector {
     this.budgetBlocks = 0;
     this.rateLimitBlocks = 0;
 
+    // Loop-guard interventions (cross-request tool dedup): warnings injected
+    // into model context and force-terminated turns. Non-zero numbers here
+    // mean Lynkr actively altered agent behavior — surfaced so operators
+    // don't need log forensics to discover it.
+    this.loopGuardWarnings = 0;
+    this.loopGuardTerminations = 0;
+
+    // History compression: how often and how hard conversations are being
+    // squeezed to fit the model's context window. A high maxPercentage means
+    // models are seeing a small fraction of their sessions.
+    this.historyCompressions = 0;
+    this.historyCompressionLastPct = 0;
+    this.historyCompressionMaxPct = 0;
+
     // API metrics
     this.databricksRequests = 0;
     this.databricksErrors = 0;
@@ -123,6 +134,28 @@ class MetricsCollector {
     this.rateLimitBlocks++;
   }
 
+  /**
+   * Record a loop-guard intervention.
+   * @param {'warn'|'terminate'} kind
+   */
+  recordLoopGuard(kind) {
+    // 'observed' is the only kind emitted since the guard went observe-only;
+    // 'terminate' is kept as a counter bucket for any historical dashboards.
+    if (kind === 'terminate') this.loopGuardTerminations++;
+    else this.loopGuardWarnings++;
+  }
+
+  /**
+   * Record a history-compression event.
+   * @param {number} percentage - percent of chars removed (0-100)
+   */
+  recordHistoryCompression(percentage) {
+    this.historyCompressions++;
+    const pct = Number(percentage) || 0;
+    this.historyCompressionLastPct = pct;
+    if (pct > this.historyCompressionMaxPct) this.historyCompressionMaxPct = pct;
+  }
+
   /**
    * Record Databricks API call
    */
@@ -225,6 +258,13 @@ class MetricsCollector {
       budget_blocks_total: this.budgetBlocks,
       rate_limit_blocks_total: this.rateLimitBlocks,
 
+      // Loop guard + history compression (context interventions)
+      loop_guard_warnings_total: this.loopGuardWarnings,
+      loop_guard_terminations_total: this.loopGuardTerminations,
+      history_compressions_total: this.historyCompressions,
+      history_compression_last_pct: this.historyCompressionLastPct,
+      history_compression_max_pct: this.historyCompressionMaxPct,
+
       // API
       databricks_requests_total: this.databricksRequests,
       databricks_errors_total: this.databricksErrors,
@@ -335,6 +375,15 @@ class MetricsCollector {
     metric("http_request_duration_ms", "summary", "HTTP request latency in ms", metrics.latency_ms.p95, { quantile: "0.95" });
     metric("http_request_duration_ms", "summary", "HTTP request latency in ms", metrics.latency_ms.p99, { quantile: "0.99" });
 
+    // OTel GenAI semantic-convention aliases (dots → underscores, per
+    // Prometheus conversion rules). Same underlying counters as above,
+    // named so semconv-aware dashboards/tooling find them.
+    metric("gen_ai_client_token_usage_total", "counter", "GenAI tokens consumed (OTel semconv)", metrics.tokens_input_total, { gen_ai_token_type: "input" });
+    metric("gen_ai_client_token_usage_total", "counter", "GenAI tokens consumed (OTel semconv)", metrics.tokens_output_total, { gen_ai_token_type: "output" });
+    metric("gen_ai_client_operation_duration_ms", "summary", "GenAI operation duration (OTel semconv)", metrics.latency_ms.median, { quantile: "0.5" });
+    metric("gen_ai_client_operation_duration_ms", "summary", "GenAI operation duration (OTel semconv)", metrics.latency_ms.p95, { quantile: "0.95" });
+    metric("gen_ai_client_operation_duration_ms", "summary", "GenAI operation duration (OTel semconv)", metrics.latency_ms.p99, { quantile: "0.99" });
+
     return lines.join("\n");
   }
 

package/src/observability/otel.js

@@ -0,0 +1,180 @@
+/**
+ * OpenTelemetry GenAI metrics export (ROUTING-NOTES §1 gap audit).
+ *
+ * Lynkr already tracks every number the OTel GenAI semantic conventions
+ * care about — this module gives them semconv-aligned names and an export
+ * path, WITHOUT adding the @opentelemetry/* dependency tree: OTLP/HTTP is
+ * just JSON over POST, and the payload below follows the OTLP 1.x
+ * ExportMetricsServiceRequest shape that any collector accepts.
+ *
+ * Enabled when OTEL_EXPORTER_OTLP_ENDPOINT (the standard env var) or
+ * LYNKR_OTEL_ENDPOINT is set. Pushes every LYNKR_OTEL_EXPORT_INTERVAL_MS
+ * (default 60s) to `<endpoint>/v1/metrics`. Optional headers via the
+ * standard OTEL_EXPORTER_OTLP_HEADERS ("key=value,key2=value2").
+ *
+ * Emitted metrics (GenAI semconv where one exists, lynkr.* where not):
+ *   gen_ai.client.token.usage      sum, attr gen_ai.token.type=input|output
+ *   gen_ai.client.operation.duration  gauge (p50/p95/p99, unit ms)
+ *   lynkr.cost.usd                 sum
+ *   lynkr.requests                 sum (+ lynkr.request.errors)
+ *
+ * @module observability/otel
+ */
+
+const logger = require('../logger');
+const { getMetricsCollector } = require('./metrics');
+
+const EXPORT_INTERVAL_MS = Number.parseInt(process.env.LYNKR_OTEL_EXPORT_INTERVAL_MS, 10) || 60_000;
+
+function _endpoint() {
+  const raw = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.LYNKR_OTEL_ENDPOINT || null;
+  if (!raw) return null;
+  return raw.replace(/\/+$/, '');
+}
+
+function _headers() {
+  const headers = { 'Content-Type': 'application/json' };
+  const raw = process.env.OTEL_EXPORTER_OTLP_HEADERS;
+  if (raw) {
+    for (const pair of raw.split(',')) {
+      const idx = pair.indexOf('=');
+      if (idx > 0) headers[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+    }
+  }
+  return headers;
+}
+
+function _sumPoint(value, attributes, startNanos, nowNanos) {
+  return {
+    attributes,
+    startTimeUnixNano: startNanos,
+    timeUnixNano: nowNanos,
+    asDouble: value,
+  };
+}
+
+/**
+ * Build an OTLP/HTTP ExportMetricsServiceRequest from the collector's
+ * current snapshot. Exposed for tests.
+ */
+function buildOtlpPayload(metrics, { startTimeMs, nowMs }) {
+  const startNanos = String(startTimeMs * 1e6);
+  const nowNanos = String(nowMs * 1e6);
+  const attr = (key, value) => ({ key, value: { stringValue: value } });
+
+  const sums = (name, unit, points) => ({
+    name,
+    unit,
+    sum: {
+      aggregationTemporality: 2, // CUMULATIVE
+      isMonotonic: true,
+      dataPoints: points,
+    },
+  });
+
+  const gauge = (name, unit, points) => ({ name, unit, gauge: { dataPoints: points } });
+
+  return {
+    resourceMetrics: [{
+      resource: {
+        attributes: [
+          attr('service.name', 'lynkr'),
+          attr('service.version', process.env.npm_package_version || 'unknown'),
+        ],
+      },
+      scopeMetrics: [{
+        scope: { name: 'lynkr.observability', version: '1' },
+        metrics: [
+          sums('gen_ai.client.token.usage', '{token}', [
+            _sumPoint(metrics.tokens_input_total, [attr('gen_ai.token.type', 'input')], startNanos, nowNanos),
+            _sumPoint(metrics.tokens_output_total, [attr('gen_ai.token.type', 'output')], startNanos, nowNanos),
+          ]),
+          gauge('gen_ai.client.operation.duration', 'ms', [
+            { attributes: [attr('quantile', '0.5')], timeUnixNano: nowNanos, asDouble: metrics.latency_ms.median },
+            { attributes: [attr('quantile', '0.95')], timeUnixNano: nowNanos, asDouble: metrics.latency_ms.p95 },
+            { attributes: [attr('quantile', '0.99')], timeUnixNano: nowNanos, asDouble: metrics.latency_ms.p99 },
+          ]),
+          sums('lynkr.cost.usd', 'usd', [
+            _sumPoint(metrics.cost_usd_total, [], startNanos, nowNanos),
+          ]),
+          sums('lynkr.requests', '{request}', [
+            _sumPoint(metrics.requests_total, [], startNanos, nowNanos),
+          ]),
+          sums('lynkr.request.errors', '{request}', [
+            _sumPoint(metrics.requests_errors_total, [], startNanos, nowNanos),
+          ]),
+        ],
+      }],
+    }],
+  };
+}
+
+class OtelExporter {
+  constructor() {
+    this.timer = null;
+    this.startTimeMs = Date.now();
+    this.stats = { exports: 0, failures: 0, lastExportAt: null };
+    this._warnedOnce = false;
+  }
+
+  start() {
+    const endpoint = _endpoint();
+    if (!endpoint || this.timer) return;
+    this.timer = setInterval(() => {
+      this.exportOnce().catch(() => {});
+    }, EXPORT_INTERVAL_MS);
+    this.timer.unref?.();
+    logger.info({ endpoint, intervalMs: EXPORT_INTERVAL_MS }, '[Otel] GenAI metrics export started');
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  async exportOnce() {
+    const endpoint = _endpoint();
+    if (!endpoint) return false;
+    const metrics = getMetricsCollector().getMetrics();
+    const payload = buildOtlpPayload(metrics, { startTimeMs: this.startTimeMs, nowMs: Date.now() });
+    try {
+      const response = await fetch(`${endpoint}/v1/metrics`, {
+        method: 'POST',
+        headers: _headers(),
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!response.ok) throw new Error(`OTLP export → ${response.status}`);
+      await response.arrayBuffer().catch(() => {});
+      this.stats.exports += 1;
+      this.stats.lastExportAt = Date.now();
+      this._warnedOnce = false;
+      return true;
+    } catch (err) {
+      this.stats.failures += 1;
+      // Warn once per failure streak, then stay quiet — a down collector
+      // must not spam logs at every interval.
+      if (!this._warnedOnce) {
+        this._warnedOnce = true;
+        logger.warn({ endpoint, error: err.message }, '[Otel] metrics export failing (will keep retrying quietly)');
+      }
+      return false;
+    }
+  }
+
+  getStatus() {
+    return { enabled: !!_endpoint(), running: !!this.timer, intervalMs: EXPORT_INTERVAL_MS, ...this.stats };
+  }
+}
+
+let exporter = null;
+
+/** @returns {OtelExporter} singleton */
+function getOtelExporter() {
+  if (!exporter) exporter = new OtelExporter();
+  return exporter;
+}
+
+module.exports = { getOtelExporter, buildOtlpPayload };