lynkr 9.14.2 → 9.14.7

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 };

package/src/orchestrator/azure-responses-sse.js

@@ -0,0 +1,223 @@
+/**
+ * Azure OpenAI Responses API — streaming adapter.
+ *
+ * The Responses API's streaming event vocabulary (response.created,
+ * response.output_item.added, response.content_part.added,
+ * response.output_text.delta/.done, response.function_call_arguments.delta/
+ * .done, response.output_item.done, response.completed) is structurally
+ * different from OpenAI Chat Completions' generic `choices[0].delta` chunk
+ * shape, which is what sse-transformer.js's `_openaiToAnthropicEvents`
+ * understands.
+ *
+ * Rather than duplicate that function's Anthropic-SSE emission logic (badge
+ * injection, message_start/message_stop, the mid-stream-error and
+ * no-finish-reason safety branches, usage extraction) for a second wire
+ * format, this module translates Responses-API events into SYNTHETIC OpenAI
+ * Chat-Completions SSE TEXT (`data: {"choices":[...]}\n\n`) and hands that
+ * off unchanged to the existing, already-tested transformer. Net effect:
+ * `invokeAzureOpenAI` returns a stream from this module exactly the way
+ * invokeMoonshot/invokeBaidu/invokeOpenAI already return a raw upstream
+ * stream — the orchestrator's existing `sseTransform.openaiToAnthropicSSE`
+ * call site needs zero changes to consume it.
+ *
+ * Verified against two live captures from this deployment's actual Azure
+ * endpoint (2026-08-26, api-version=2025-04-01-preview, model gpt-5.6-sol):
+ * one plain-text response, one forced tool-call response. Re-verify against
+ * a live capture if Azure's preview API version changes this shape.
+ *
+ * Tool-call dedup: the buffered Responses-API conversion in databricks.js
+ * (invokeAzureOpenAI) filters out exact duplicate {name, arguments}
+ * function-call signatures within one response (an observed GPT-5.x quirk).
+ * To preserve that guarantee here without needing the FULL response in hand
+ * first, this module buffers a function_call's argument fragments locally
+ * (never emitting them) until that call's response.function_call_arguments.done
+ * fires, checks the signature, and only then emits the accumulated deltas —
+ * as one burst — or silently drops them if it's a repeat. This means
+ * function-call arguments have a small, per-call delay (between that call's
+ * first and last argument fragment) while text streams fully live with zero
+ * delay — a deliberate tradeoff to keep the existing dedup guarantee, not an
+ * oversight.
+ */
+
+const logger = require("../logger");
+const { _sseDataLines } = require("./sse-transformer");
+
+/**
+ * @param {ReadableStream|AsyncIterable} rawResponsesStream - raw Azure
+ *   Responses API SSE byte stream (stream:true was set on the request).
+ * @param {Object} [opts]
+ * @param {string} [opts.model] - fallback model id for synthesized chunks.
+ * @returns {ReadableStream} synthetic OpenAI Chat-Completions SSE byte stream.
+ */
+function azureResponsesToOpenAIChunks(rawResponsesStream, opts = {}) {
+  const generator = _toOpenAIChunkText(rawResponsesStream, opts);
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { value, done } = await generator.next();
+        if (done) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(encoder.encode(value));
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+    async cancel() {
+      try { await generator.return(); } catch { /* already finished */ }
+    },
+  });
+}
+
+async function* _toOpenAIChunkText(rawResponsesStream, opts) {
+  const id = `chatcmpl-azresp-${Date.now()}`;
+  const created = Math.floor(Date.now() / 1000);
+  const model = opts.model || "gpt-5.6-sol";
+
+  const chunk = (delta, extra = {}) => `data: ${JSON.stringify({
+    id, object: "chat.completion.chunk", created, model,
+    choices: [{ index: 0, delta, finish_reason: null }],
+    ...extra,
+  })}\n\n`;
+
+  const finishChunk = (finishReason, usage) => `data: ${JSON.stringify({
+    id, object: "chat.completion.chunk", created, model,
+    choices: [{ index: 0, delta: {}, finish_reason: finishReason }],
+    ...(usage ? { usage } : {}),
+  })}\n\n`;
+
+  // output_index -> {kind: "message"|"function_call", openaiToolIndex,
+  //   name, callId, argBuf: string}. argBuf only used for function_call.
+  const items = new Map();
+  let nextToolIndex = 0;
+  const seenToolSignatures = new Set();
+  let sawFunctionCall = false;
+  let sawAnyOutput = false;
+
+  try {
+    for await (const payload of _sseDataLines(rawResponsesStream)) {
+      if (payload === "[DONE]") break;
+      let ev;
+      try { ev = JSON.parse(payload); } catch { continue; }
+
+      switch (ev.type) {
+        case "response.output_item.added": {
+          const item = ev.item || {};
+          if (item.type === "function_call") {
+            items.set(ev.output_index, {
+              kind: "function_call",
+              openaiToolIndex: nextToolIndex++,
+              name: item.name || "",
+              callId: item.call_id || item.id || "",
+              argBuf: "",
+            });
+          } else {
+            items.set(ev.output_index, { kind: "message" });
+          }
+          break;
+        }
+
+        case "response.output_text.delta": {
+          sawAnyOutput = true;
+          if (ev.delta) yield chunk({ content: ev.delta });
+          break;
+        }
+
+        case "response.function_call_arguments.delta": {
+          const state = items.get(ev.output_index);
+          if (state && state.kind === "function_call") {
+            state.argBuf += ev.delta || "";
+          }
+          break;
+        }
+
+        case "response.function_call_arguments.done": {
+          const state = items.get(ev.output_index);
+          if (!state || state.kind !== "function_call") break;
+          sawAnyOutput = true;
+          sawFunctionCall = true;
+          const finalArgs = typeof ev.arguments === "string" ? ev.arguments : state.argBuf;
+          const signature = `${state.name}:${finalArgs}`;
+          if (seenToolSignatures.has(signature)) {
+            logger.warn({
+              name: state.name,
+              argsPreview: finalArgs.slice(0, 120),
+            }, "[AzureResponsesSSE] Filtered duplicate streamed tool call");
+            break;
+          }
+          seenToolSignatures.add(signature);
+          // First delta for this tool carries id/name (empty arguments);
+          // second carries the complete arguments as one fragment — matches
+          // real OpenAI streaming shape, which sse-transformer.js's toolAcc
+          // merge logic already expects (id/name first-non-null-wins, args
+          // concatenated across fragments).
+          yield chunk({
+            tool_calls: [{
+              index: state.openaiToolIndex,
+              id: state.callId,
+              type: "function",
+              function: { name: state.name, arguments: "" },
+            }],
+          });
+          yield chunk({
+            tool_calls: [{
+              index: state.openaiToolIndex,
+              function: { arguments: finalArgs },
+            }],
+          });
+          break;
+        }
+
+        case "response.completed": {
+          const usageRaw = ev.response?.usage;
+          const usage = usageRaw ? {
+            prompt_tokens: usageRaw.input_tokens ?? 0,
+            completion_tokens: usageRaw.output_tokens ?? 0,
+            total_tokens: usageRaw.total_tokens
+              ?? ((usageRaw.input_tokens ?? 0) + (usageRaw.output_tokens ?? 0)),
+            prompt_tokens_details: {
+              cached_tokens: usageRaw.input_tokens_details?.cached_tokens ?? 0,
+            },
+          } : undefined;
+          const finishReason = sawFunctionCall ? "tool_calls" : "stop";
+          yield finishChunk(finishReason, usage);
+          yield "data: [DONE]\n\n";
+          return;
+        }
+
+        case "response.failed":
+        case "response.incomplete": {
+          logger.warn({
+            type: ev.type,
+            error: ev.response?.error || ev.error || null,
+          }, "[AzureResponsesSSE] Upstream reported failure mid-stream");
+          // No finish_reason chunk, no [DONE] — matches sse-transformer.js's
+          // own no-finish-reason safety branch (its EOF-without-finish_reason
+          // case), which synthesizes an Anthropic error event rather than a
+          // false-success message_stop when downstream sees the SSE end here.
+          return;
+        }
+
+        default:
+          break; // response.created/.in_progress, content_part.*, output_item.done — no chunk needed
+      }
+    }
+  } catch (err) {
+    logger.warn({ err: err.message }, "[AzureResponsesSSE] Upstream stream failed mid-flight");
+    return;
+  }
+
+  // Stream ended without response.completed and without sawAnyOutput ever
+  // firing a finish — same "don't fake success" discipline as above.
+  if (!sawAnyOutput) {
+    logger.warn("[AzureResponsesSSE] Upstream stream ended with no output and no response.completed");
+  }
+}
+
+module.exports = {
+  azureResponsesToOpenAIChunks,
+  // Exported for unit tests.
+  _toOpenAIChunkText,
+};