lynkr 9.9.1 → 9.11.0

package/src/orchestrator/sse-transformer.js

@@ -0,0 +1,408 @@
+/**
+ * Phase 2b — cross-format SSE streaming transform.
+ *
+ * When the client speaks Anthropic but the tier-resolved upstream speaks
+ * OpenAI Chat Completions, the buffered path costs a full generation of
+ * latency before the client sees a single token. This module reshapes the
+ * upstream's SSE deltas into Anthropic Messages events in flight.
+ *
+ * The hard part is tool calls: OpenAI streams tool_calls[i].function.arguments
+ * as unparseable JSON slivers spread across chunks. The transformer
+ * accumulates fragments per tool index and emits one clean
+ * content_block_start + content_block_delta(input_json_delta) +
+ * content_block_stop per COMPLETE tool_use, at stream end — matching the
+ * shape Lynkr's buffered synthesis has always sent, so clients see no
+ * difference in event structure.
+ *
+ * Default on; kill switch LYNKR_STREAM_TRANSFORM=false. The buffered path
+ * stays for body.stream === false and for hallucination-recovery re-prompts
+ * (which require a parsed, buffered response).
+ */
+const logger = require("../logger");
+
+// Upstreams whose streaming wire format is OpenAI Chat Completions SSE.
+// ollama is excluded (own format + buffering quirks), moonshot/zai are
+// excluded (their invoke fns convert buffered responses to Anthropic).
+const DEFAULT_OPENAI_SSE_PROVIDERS = [
+  "openai",
+  "azure-openai",
+  "openrouter",
+  "databricks",
+  "lmstudio",
+  "llamacpp",
+];
+
+function _transformProviders() {
+  const env = process.env.LYNKR_STREAM_TRANSFORM_PROVIDERS;
+  return new Set(
+    env ? env.split(",").map((s) => s.trim()).filter(Boolean) : DEFAULT_OPENAI_SSE_PROVIDERS,
+  );
+}
+
+function shouldTransform(clientWantsStream, provider) {
+  // Default ON since 2026-07-21 (E2E-verified against live upstreams);
+  // LYNKR_STREAM_TRANSFORM=false is the kill switch, mirroring
+  // LYNKR_NATIVE_PASSTHROUGH. Kill switches stay on streaming paths because
+  // past the first byte a stream cannot be retried — reverting behavior via
+  // env + restart beats reverting code during an incident.
+  if (process.env.LYNKR_STREAM_TRANSFORM === "false") return false;
+  if (clientWantsStream !== true) return false;
+  return _transformProviders().has(provider);
+}
+
+function _sse(event, data) {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+function _mapFinishReason(reason) {
+  switch (reason) {
+    case "tool_calls":
+    case "function_call":
+      return "tool_use";
+    case "length":
+      return "max_tokens";
+    case "stop":
+    default:
+      return "end_turn";
+  }
+}
+
+/** Normalize a web ReadableStream or Node Readable into an async iterator of Buffers. */
+async function* _iterateStream(stream) {
+  if (typeof stream.getReader === "function") {
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) return;
+        yield value;
+      }
+    } finally {
+      try { reader.releaseLock(); } catch { /* released */ }
+    }
+  } else {
+    yield* stream;
+  }
+}
+
+/** Split an SSE byte stream into `data:` payload strings. */
+async function* _sseDataLines(stream) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of _iterateStream(stream)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("data:")) yield trimmed.slice(5).trim();
+    }
+  }
+  const trimmed = buffer.trim();
+  if (trimmed.startsWith("data:")) yield trimmed.slice(5).trim();
+}
+
+/**
+ * Core transform: OpenAI Chat Completions SSE → Anthropic Messages SSE.
+ * Yields Anthropic SSE event strings. `stats` accumulates for the onClose
+ * finalizer: tool names/arg sizes and usage, gathered DURING the stream so
+ * telemetry needs no second pass.
+ */
+async function* _openaiToAnthropicEvents(upstream, opts = {}) {
+  const fallbackModel = opts.model || "unknown";
+  const stats = {
+    toolCalls: [], // { name, argBytes }
+    usage: { input_tokens: null, output_tokens: null },
+    stopReason: null,
+  };
+
+  let started = false;
+  let messageId = null;
+  let model = fallbackModel;
+  let nextIndex = 0;
+  let textIndex = null; // open text block index, null when closed
+  let finishReason = null;
+  const toolAcc = new Map(); // openai tool index -> { id, name, args }
+
+  const startMessage = function* () {
+    if (started) return;
+    started = true;
+    yield _sse("message_start", {
+      type: "message_start",
+      message: {
+        id: messageId || `msg_${Date.now()}`,
+        type: "message",
+        role: "assistant",
+        content: [],
+        model,
+        stop_reason: null,
+        stop_sequence: null,
+        usage: { input_tokens: 0, output_tokens: 1 },
+      },
+    });
+    // LYNKR_VISIBLE_ROUTING badge — a clean first text block, before any
+    // upstream content. Unlike the byte-pipe passthrough, the transformer
+    // owns the indices, so the badge slots in properly.
+    if (opts.badgeText) {
+      const index = nextIndex++;
+      yield _sse("content_block_start", { type: "content_block_start", index, content_block: { type: "text", text: "" } });
+      yield _sse("content_block_delta", { type: "content_block_delta", index, delta: { type: "text_delta", text: opts.badgeText } });
+      yield _sse("content_block_stop", { type: "content_block_stop", index });
+    }
+  };
+
+  const closeTextBlock = function* () {
+    if (textIndex === null) return;
+    yield _sse("content_block_stop", { type: "content_block_stop", index: textIndex });
+    textIndex = null;
+  };
+
+  const flushToolBlocks = function* () {
+    for (const [, tool] of [...toolAcc.entries()].sort((a, b) => a[0] - b[0])) {
+      const index = nextIndex++;
+      const args = tool.args || "{}";
+      yield _sse("content_block_start", {
+        type: "content_block_start",
+        index,
+        content_block: {
+          type: "tool_use",
+          id: tool.id || `toolu_${Date.now()}_${index.toString(36)}`,
+          name: tool.name || "unknown",
+          input: {},
+        },
+      });
+      yield _sse("content_block_delta", {
+        type: "content_block_delta",
+        index,
+        delta: { type: "input_json_delta", partial_json: args },
+      });
+      yield _sse("content_block_stop", { type: "content_block_stop", index });
+      stats.toolCalls.push({ name: tool.name || "unknown", argBytes: args.length });
+    }
+    toolAcc.clear();
+  };
+
+  try {
+    for await (const payload of _sseDataLines(upstream)) {
+      if (payload === "[DONE]") break;
+
+      let chunk;
+      try {
+        chunk = JSON.parse(payload);
+      } catch {
+        continue; // partial/garbled chunk — skip, never crash the stream
+      }
+
+      if (chunk.id && !messageId) messageId = chunk.id;
+      if (chunk.model) model = chunk.model;
+      if (chunk.usage) {
+        if (chunk.usage.prompt_tokens != null) stats.usage.input_tokens = chunk.usage.prompt_tokens;
+        if (chunk.usage.completion_tokens != null) stats.usage.output_tokens = chunk.usage.completion_tokens;
+      }
+
+      const choice = chunk.choices?.[0];
+      if (!choice) continue;
+      if (choice.finish_reason) finishReason = choice.finish_reason;
+      const delta = choice.delta || {};
+
+      yield* startMessage();
+
+      // Text deltas are straightforward: open a block on first text, then
+      // emit a text_delta per chunk.
+      if (typeof delta.content === "string" && delta.content.length > 0) {
+        if (textIndex === null) {
+          textIndex = nextIndex++;
+          yield _sse("content_block_start", {
+            type: "content_block_start",
+            index: textIndex,
+            content_block: { type: "text", text: "" },
+          });
+        }
+        yield _sse("content_block_delta", {
+          type: "content_block_delta",
+          index: textIndex,
+          delta: { type: "text_delta", text: delta.content },
+        });
+      }
+
+      // Tool-call fragments: accumulate per OpenAI tool index. Fragments of
+      // function.arguments are NOT parseable individually — only the full
+      // concatenation is valid JSON, so blocks are emitted at stream end.
+      if (Array.isArray(delta.tool_calls)) {
+        yield* closeTextBlock();
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index ?? 0;
+          if (!toolAcc.has(idx)) toolAcc.set(idx, { id: null, name: null, args: "" });
+          const acc = toolAcc.get(idx);
+          if (tc.id) acc.id = tc.id;
+          if (tc.function?.name) acc.name = (acc.name || "") + tc.function.name;
+          if (typeof tc.function?.arguments === "string") acc.args += tc.function.arguments;
+        }
+      }
+    }
+  } catch (err) {
+    logger.warn({ err: err.message }, "[SSETransform] Upstream stream failed mid-flight");
+    yield* startMessage();
+    yield* closeTextBlock();
+    yield _sse("error", {
+      type: "error",
+      error: { type: "overloaded_error", message: `Lynkr: upstream stream failed — retry (${err.message})` },
+    });
+    stats.stopReason = "stream_error";
+    if (opts.onClose) { try { opts.onClose(stats); } catch { /* non-fatal */ } }
+    return;
+  }
+
+  // Normal end of stream ([DONE] or upstream EOF).
+  yield* startMessage();
+  yield* closeTextBlock();
+  yield* flushToolBlocks();
+
+  const stopReason = _mapFinishReason(finishReason);
+  stats.stopReason = stopReason;
+  yield _sse("message_delta", {
+    type: "message_delta",
+    delta: { stop_reason: stopReason, stop_sequence: null },
+    usage: { output_tokens: stats.usage.output_tokens ?? 0 },
+  });
+  yield _sse("message_stop", { type: "message_stop" });
+
+  if (opts.onClose) { try { opts.onClose(stats); } catch { /* non-fatal */ } }
+}
+
+/**
+ * OpenAI SSE → Anthropic SSE. Returns a web ReadableStream (exposes
+ * getReader(), matching what the router's stream-forwarding path expects).
+ */
+function openaiToAnthropicSSE(upstream, opts = {}) {
+  const generator = _openaiToAnthropicEvents(upstream, 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 */ }
+    },
+  });
+}
+
+/**
+ * Anthropic SSE → OpenAI SSE. The symmetric direction — unused by Lynkr's
+ * current routes (OpenAI-speaking clients get buffered conversion) but kept
+ * so both directions live and are tested together.
+ */
+async function* _anthropicToOpenaiEvents(upstream, opts = {}) {
+  const model = opts.model || "unknown";
+  let id = `chatcmpl_${Date.now()}`;
+  let usage = null;
+  let stopReason = null;
+  const blockTypes = new Map(); // anthropic block index -> type
+  let toolOrdinal = -1; // openai tool_calls array index
+
+  const chunk = (delta, finish = null) => ({
+    id,
+    object: "chat.completion.chunk",
+    model,
+    choices: [{ index: 0, delta, finish_reason: finish }],
+    ...(usage && finish ? { usage } : {}),
+  });
+
+  for await (const payload of _sseDataLines(upstream)) {
+    let evt;
+    try {
+      evt = JSON.parse(payload);
+    } catch {
+      continue;
+    }
+
+    switch (evt.type) {
+      case "message_start":
+        if (evt.message?.id) id = evt.message.id;
+        if (evt.message?.usage?.input_tokens != null) {
+          usage = { prompt_tokens: evt.message.usage.input_tokens, completion_tokens: 0, total_tokens: evt.message.usage.input_tokens };
+        }
+        yield `data: ${JSON.stringify(chunk({ role: "assistant", content: "" }))}\n\n`;
+        break;
+      case "content_block_start":
+        blockTypes.set(evt.index, evt.content_block?.type);
+        if (evt.content_block?.type === "tool_use") {
+          toolOrdinal += 1;
+          yield `data: ${JSON.stringify(chunk({
+            tool_calls: [{
+              index: toolOrdinal,
+              id: evt.content_block.id,
+              type: "function",
+              function: { name: evt.content_block.name, arguments: "" },
+            }],
+          }))}\n\n`;
+        }
+        break;
+      case "content_block_delta":
+        if (evt.delta?.type === "text_delta") {
+          yield `data: ${JSON.stringify(chunk({ content: evt.delta.text }))}\n\n`;
+        } else if (evt.delta?.type === "input_json_delta") {
+          yield `data: ${JSON.stringify(chunk({
+            tool_calls: [{ index: toolOrdinal, function: { arguments: evt.delta.partial_json } }],
+          }))}\n\n`;
+        }
+        break;
+      case "message_delta":
+        if (evt.delta?.stop_reason) stopReason = evt.delta.stop_reason;
+        if (evt.usage?.output_tokens != null) {
+          usage = usage || { prompt_tokens: 0 };
+          usage.completion_tokens = evt.usage.output_tokens;
+          usage.total_tokens = (usage.prompt_tokens || 0) + evt.usage.output_tokens;
+        }
+        break;
+      case "message_stop": {
+        const finish = stopReason === "tool_use" ? "tool_calls" : stopReason === "max_tokens" ? "length" : "stop";
+        yield `data: ${JSON.stringify(chunk({}, finish))}\n\n`;
+        yield "data: [DONE]\n\n";
+        break;
+      }
+      default:
+        break; // ping, content_block_stop — no OpenAI equivalent needed
+    }
+  }
+}
+
+function anthropicToOpenaiSSE(upstream, opts = {}) {
+  const generator = _anthropicToOpenaiEvents(upstream, 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 */ }
+    },
+  });
+}
+
+module.exports = {
+  shouldTransform,
+  openaiToAnthropicSSE,
+  anthropicToOpenaiSSE,
+  // Exported for unit tests.
+  _openaiToAnthropicEvents,
+  _anthropicToOpenaiEvents,
+};

package/src/prompts/system.js

@@ -70,13 +70,27 @@ function compressToolDescriptions(tools, mode = null) {
     return tools; // Return unmodified if not in minimal mode
   }
 
+  // Normalize to Anthropic shape: OpenAI-format callers (OpenWorker, aisuite,
+  // any OpenAI SDK) send {type:"function", function:{name, description, parameters}}.
+  // Unwrap once here so the compression logic below can assume input_schema exists.
+  tools = tools.map(tool =>
+    tool?.type === "function" && tool.function
+      ? {
+          name: tool.function.name,
+          description: tool.function.description,
+          input_schema: tool.function.parameters || { type: "object", properties: {} },
+        }
+      : tool
+  );
+
   return tools.map(tool => {
+    const input_schema = tool.input_schema || { type: "object", properties: {} };
     const compressed = {
       name: tool.name,
       input_schema: {
-        type: tool.input_schema.type,
+        type: input_schema.type || "object",
         properties: {},
-        required: tool.input_schema.required || [],
+        required: input_schema.required || [],
       }
     };
 
@@ -86,8 +100,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Compress property descriptions
-    if (tool.input_schema.properties) {
-      for (const [key, value] of Object.entries(tool.input_schema.properties)) {
+    if (input_schema.properties) {
+      for (const [key, value] of Object.entries(input_schema.properties)) {
         compressed.input_schema.properties[key] = {
           type: value.type,
         };
@@ -108,8 +122,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Preserve additionalProperties if set
-    if (tool.input_schema.additionalProperties !== undefined) {
-      compressed.input_schema.additionalProperties = tool.input_schema.additionalProperties;
+    if (input_schema.additionalProperties !== undefined) {
+      compressed.input_schema.additionalProperties = input_schema.additionalProperties;
     }
 
     return compressed;

package/src/routing/affinity-store.js

@@ -49,6 +49,19 @@ function _db() {
       if (!cols.has("score")) {
         db.exec("ALTER TABLE session_pins ADD COLUMN score REAL");
       }
+      // Additive migration for the side-channel detector's Signal 2 —
+      // once a session has ever carried tool_use/tool_result blocks, this
+      // flag stays 1 for the pin's lifetime. Payloads that arrive later
+      // without tool blocks in a flagged session are side-channel replays.
+      if (!cols.has("has_tool_history")) {
+        db.exec("ALTER TABLE session_pins ADD COLUMN has_tool_history INTEGER DEFAULT 0");
+      }
+      // Additive migration for cache-aware routing (Phase 1): JSON blob
+      // holding {warmPrefixTokens, provider, model, lastRequestAt, ttlMs},
+      // updated after every upstream response that reports cache usage.
+      if (!cols.has("cache_state")) {
+        db.exec("ALTER TABLE session_pins ADD COLUMN cache_state TEXT");
+      }
       schemaEnsured = true;
     } catch (err) {
       degradation.record("feedback", err);
@@ -81,7 +94,7 @@ function load(sessionId, ttlMs) {
     const row = _stmt(
       db,
       "load",
-      "SELECT provider, model, tier, score, message_count, prompt_tokens_est, ts FROM session_pins WHERE session_id = ?"
+      "SELECT provider, model, tier, score, message_count, prompt_tokens_est, has_tool_history, ts FROM session_pins WHERE session_id = ?"
     ).get(sessionId);
     if (!row) return null;
     if (ttlMs && Date.now() - row.ts > ttlMs) {
@@ -98,6 +111,7 @@ function load(sessionId, ttlMs) {
       score: row.score,
       messageCount: row.message_count,
       promptTokensEst: row.prompt_tokens_est,
+      hasToolHistory: !!row.has_tool_history,
       ts: row.ts,
     };
   } catch (err) {
@@ -121,8 +135,12 @@ function save(sessionId, pin) {
     _stmt(
       db,
       "upsert",
-      `INSERT INTO session_pins (session_id, provider, model, tier, score, message_count, prompt_tokens_est, ts)
-       VALUES (@session_id, @provider, @model, @tier, @score, @message_count, @prompt_tokens_est, @ts)
+      // has_tool_history is sticky-true: once the session has ever carried
+      // tool blocks it stays flagged for the pin's lifetime. Use MAX so an
+      // update from a tool-less request (e.g. compaction refresh) can never
+      // clear the flag once set.
+      `INSERT INTO session_pins (session_id, provider, model, tier, score, message_count, prompt_tokens_est, has_tool_history, ts)
+       VALUES (@session_id, @provider, @model, @tier, @score, @message_count, @prompt_tokens_est, @has_tool_history, @ts)
        ON CONFLICT(session_id) DO UPDATE SET
          provider = excluded.provider,
          model = excluded.model,
@@ -130,6 +148,7 @@ function save(sessionId, pin) {
          score = excluded.score,
          message_count = excluded.message_count,
          prompt_tokens_est = excluded.prompt_tokens_est,
+         has_tool_history = MAX(has_tool_history, excluded.has_tool_history),
          ts = excluded.ts`
     ).run({
       session_id: sessionId,
@@ -139,6 +158,7 @@ function save(sessionId, pin) {
       score: typeof pin.score === 'number' ? pin.score : null,
       message_count: pin.messageCount ?? null,
       prompt_tokens_est: pin.promptTokensEst ?? null,
+      has_tool_history: pin.hasToolHistory ? 1 : 0,
       ts: pin.ts ?? Date.now(),
     });
   } catch (err) {
@@ -146,6 +166,67 @@ function save(sessionId, pin) {
   }
 }
 
+/**
+ * Persist per-session prompt-cache state (Phase 1, cache-aware routing).
+ * Piggybacks on the session_pins row; creates a minimal row when the session
+ * has no pin yet (possible when sticky sessions are disabled but tracking
+ * is on). Best-effort like everything else in this module.
+ *
+ * @param {string} sessionId
+ * @param {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}} state
+ */
+function saveCacheState(sessionId, state) {
+  if (!sessionId || !state?.provider) return;
+  const db = _db();
+  if (!db) return;
+  try {
+    const json = JSON.stringify(state);
+    const res = _stmt(
+      db,
+      "cache_state_update",
+      "UPDATE session_pins SET cache_state = ? WHERE session_id = ?"
+    ).run(json, sessionId);
+    if (res.changes === 0) {
+      _stmt(
+        db,
+        "cache_state_insert",
+        `INSERT INTO session_pins (session_id, provider, model, ts, cache_state)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(session_id) DO UPDATE SET cache_state = excluded.cache_state`
+      ).run(sessionId, state.provider, state.model ?? null, Date.now(), json);
+    }
+  } catch (err) {
+    degradation.record("feedback", err);
+  }
+}
+
+/**
+ * Load per-session cache state. Returns null when absent, unparsable, or the
+ * DB is unavailable — callers treat null as "no cache signal for this
+ * session" (provider doesn't report cache usage, or no response seen yet).
+ *
+ * @param {string} sessionId
+ * @returns {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}|null}
+ */
+function loadCacheState(sessionId) {
+  if (!sessionId) return null;
+  const db = _db();
+  if (!db) return null;
+  try {
+    const row = _stmt(
+      db,
+      "cache_state_load",
+      "SELECT cache_state FROM session_pins WHERE session_id = ?"
+    ).get(sessionId);
+    if (!row?.cache_state) return null;
+    const parsed = JSON.parse(row.cache_state);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (err) {
+    degradation.record("feedback", err);
+    return null;
+  }
+}
+
 /**
  * Remove a pin.
  * @param {string} sessionId
@@ -191,4 +272,4 @@ function _clear() {
   } catch { /* best-effort */ }
 }
 
-module.exports = { load, save, remove, cleanup, _clear };
+module.exports = { load, save, remove, cleanup, saveCacheState, loadCacheState, _clear };

package/src/routing/agentic-detector.js

@@ -224,13 +224,21 @@ class AgenticDetector {
     const agentType = this._classifyAgentType(score, signals);
     const isAgentic = score >= 25;
 
+    // AGENTIC_DISABLE_FLOOR=1 bypasses the per-agent-type minTier — the raw
+    // complexity score decides the tier without the tools-based bump. Useful
+    // for demos/tests where tool-heavy clients (OpenWorker, aisuite) send 25+
+    // tools on every request and otherwise floor everything to MEDIUM+.
+    const flooredMinTier = process.env.AGENTIC_DISABLE_FLOOR === '1'
+      ? 'SIMPLE'
+      : AGENT_TYPES[agentType].minTier;
+
     const result = {
       isAgentic,
       agentType,
       confidence: Math.min(score / 100, 1),
       score,
       signals,
-      minTier: AGENT_TYPES[agentType].minTier,
+      minTier: flooredMinTier,
       scoreBoost: AGENT_TYPES[agentType].scoreBoost,
       description: AGENT_TYPES[agentType].description,
       clientProfile: profile?.name ?? null,