lynkr 9.14.2 → 9.14.7

package/src/api/openai-router.js

@@ -28,6 +28,32 @@ const clientProfiles = require("../routing/client-profiles");
 
 const router = express.Router();
 
+/**
+ * Served-model decision headers for the OpenAI-compat ingress.
+ *
+ * The Anthropic ingress has carried X-Lynkr-* decision headers for a long
+ * time; this path never did — the same single-ingress gap as issue #100.
+ * X-Lynkr-Context-Window is the served model's REAL context window (the
+ * workweave pattern): behind a virtual model name, tier routing serves
+ * models with different windows per request, and this header is the
+ * client's authoritative per-turn compaction budget. Omitted (never
+ * guessed) for models the registry doesn't know.
+ *
+ * Safe on streaming paths: no-op once headers have flushed.
+ *
+ * @param {object} res - Express response
+ * @param {string|null} servedModel - model from the orchestrator result body
+ */
+function setServedModelHeaders(res, servedModel) {
+  if (!servedModel || res.headersSent) return;
+  try {
+    res.set("X-Lynkr-Model", servedModel);
+    const { contextWindowFor } = require("../routing/model-registry");
+    const contextWindow = contextWindowFor(servedModel);
+    if (contextWindow) res.set("X-Lynkr-Context-Window", String(contextWindow));
+  } catch { /* headers are best-effort — never fail a response over them */ }
+}
+
 /**
  * Resolve the model name for OpenAI responses.
  * In OpenClaw mode, returns the actual provider/model from routing metadata.
@@ -568,6 +594,35 @@ router.post("/chat/completions", async (req, res) => {
       logger.debug({ err: err.message }, "[OpenAI Router] client profile detection failed");
     }
 
+    // Explicit model/effort pin: Codex's model picker (or any OpenAI-format
+    // caller) can name a real OpenAI model + reasoning.effort combo that
+    // resolveTierForOpenAIModel recognizes. Mirrors router.js's model-id-pin
+    // block for the Anthropic /v1/messages route — this one is needed
+    // separately because these OpenAI-shaped handlers call
+    // orchestrator.processMessage() directly and never go through router.js's
+    // pin/classifier code at all. See ../routing/openai-model-slots.js.
+    try {
+      const { resolveTierForOpenAIModel } = require("../routing/openai-model-slots");
+      const _effort = req.body?.reasoning?.effort ?? req.body?.reasoning_effort ?? null;
+      const _pinTier = resolveTierForOpenAIModel(req.body?.model, _effort);
+      if (_pinTier) {
+        const { getModelTierSelector } = require("../routing");
+        const _sel = getModelTierSelector().selectModel(_pinTier, null);
+        anthropicRequest._forceProvider = _sel.provider;
+        if (_sel.model) anthropicRequest._tierModel = _sel.model;
+        anthropicRequest._tierName = _pinTier;
+        anthropicRequest._forcedMethod = "openai_model_effort_pin";
+        logger.debug({
+          model: req.body?.model,
+          effort: _effort,
+          tier: _pinTier,
+          provider: _sel.provider,
+        }, "[OpenAI Router] Explicit model/effort pin — scoring bypassed");
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, "[OpenAI Router] model/effort pin failed");
+    }
+
     const session = getSession(sessionId);
 
     if (req.body.stream) {
@@ -591,9 +646,11 @@ router.post("/chat/completions", async (req, res) => {
           session: session,
           options: {
             maxSteps: req.body?.max_steps,
-            clientWantsStream: true
+            clientWantsStream: true,
+            tenantPolicy: res.locals?.tenantPolicy || null
           }
         });
+        setServedModelHeaders(res, result?.body?.model);
 
         // Phase 2b live stream: reshape Anthropic SSE events into OpenAI
         // chat.completion.chunk events in flight — first token reaches the
@@ -768,6 +825,25 @@ router.post("/chat/completions", async (req, res) => {
 
         logger.debug({ chunk: "finish", finishReason: openaiResponse.choices[0].finish_reason }, "Sending finish chunk");
         res.write(`data: ${JSON.stringify(finishChunk)}\n\n`);
+
+        // Trailing usage chunk (choices: [], usage populated) — same shape
+        // as the Phase 2b live-stream path above. Previously this buffered
+        // synthesis only ever logged openaiResponse.usage (see below) and
+        // never wrote it to the client, so streaming clients on this path
+        // saw zero token/context usage too.
+        if (openaiResponse.usage) {
+          const usageChunk = {
+            id: openaiResponse.id,
+            object: "chat.completion.chunk",
+            created: openaiResponse.created,
+            model: streamModel,
+            system_fingerprint: "fp_lynkr",
+            choices: [],
+            usage: openaiResponse.usage,
+          };
+          res.write(`data: ${JSON.stringify(usageChunk)}\n\n`);
+        }
+
         res.write("data: [DONE]\n\n");
 
         logger.debug({ contentLength: content.length, contentPreview: content.substring(0, 50) }, "=== SSE STREAM COMPLETE ===");
@@ -811,9 +887,11 @@ router.post("/chat/completions", async (req, res) => {
         headers: req.headers,
         session: session,
         options: {
-          maxSteps: req.body?.max_steps
+          maxSteps: req.body?.max_steps,
+          tenantPolicy: res.locals?.tenantPolicy || null
         }
       });
+      setServedModelHeaders(res, result?.body?.model);
 
       logger.debug({
         resultKeys: Object.keys(result || {}),
@@ -1065,6 +1143,19 @@ function getConfiguredProviders() {
     });
   }
 
+  if (config.fireworks?.apiKey) {
+    providers.push({
+      name: "fireworks",
+      type: "fireworks-ai",
+      models: [
+        config.fireworks.model || "accounts/fireworks/models/kimi-k2-instruct-0905",
+        "accounts/fireworks/models/kimi-k2-instruct-0905",
+        "accounts/fireworks/models/glm-5p2",
+        "accounts/fireworks/models/deepseek-v3p1"
+      ]
+    });
+  }
+
   if (config.vertex?.projectId) {
     providers.push({
       name: "vertex",
@@ -1831,6 +1922,32 @@ router.post("/responses", async (req, res) => {
       logger.debug({ err: err.message }, "[OpenAI Router] client profile detection failed");
     }
 
+    // Explicit model/effort pin — see the identical block in /chat/completions
+    // above for the full rationale. This is the route Codex Desktop actually
+    // uses (wire_api="responses"), so this is the one that matters for its
+    // model picker specifically.
+    try {
+      const { resolveTierForOpenAIModel } = require("../routing/openai-model-slots");
+      const _effort = req.body?.reasoning?.effort ?? req.body?.reasoning_effort ?? null;
+      const _pinTier = resolveTierForOpenAIModel(req.body?.model, _effort);
+      if (_pinTier) {
+        const { getModelTierSelector } = require("../routing");
+        const _sel = getModelTierSelector().selectModel(_pinTier, null);
+        anthropicRequest._forceProvider = _sel.provider;
+        if (_sel.model) anthropicRequest._tierModel = _sel.model;
+        anthropicRequest._tierName = _pinTier;
+        anthropicRequest._forcedMethod = "openai_model_effort_pin";
+        logger.debug({
+          model: req.body?.model,
+          effort: _effort,
+          tier: _pinTier,
+          provider: _sel.provider,
+        }, "[OpenAI Router] Explicit model/effort pin (responses) — scoring bypassed");
+      }
+    } catch (err) {
+      logger.debug({ err: err.message }, "[OpenAI Router] model/effort pin failed (responses)");
+    }
+
     const session = getSession(sessionId);
 
     if (req.body.stream) {
@@ -1855,9 +1972,11 @@ router.post("/responses", async (req, res) => {
             headers: req.headers,
             session: session,
             options: {
-              maxSteps: req.body?.max_steps
+              maxSteps: req.body?.max_steps,
+              tenantPolicy: res.locals?.tenantPolicy || null
             }
           });
+          setServedModelHeaders(res, result?.body?.model);
         } finally {
           clearInterval(keepalive);
         }
@@ -2192,9 +2311,11 @@ router.post("/responses", async (req, res) => {
         headers: req.headers,
         session: session,
         options: {
-          maxSteps: req.body?.max_steps
+          maxSteps: req.body?.max_steps,
+          tenantPolicy: res.locals?.tenantPolicy || null
         }
       });
+      setServedModelHeaders(res, result?.body?.model);
 
       const chatResponse = convertAnthropicToOpenAI(result.body, resolveResponseModel(result.body, req.body.model));
       const responsesResponse = convertChatToResponses(chatResponse);

package/src/api/providers-handler.js

@@ -237,6 +237,22 @@ function getConfiguredProviders() {
     });
   }
 
+  // Check Fireworks AI (serverless open models)
+  if (config.fireworks?.apiKey) {
+    providers.push({
+      name: "fireworks",
+      type: "fireworks-ai",
+      baseUrl: config.fireworks.endpoint || "https://api.fireworks.ai/inference/v1",
+      enabled: true,
+      models: [
+        { id: config.fireworks.model || "accounts/fireworks/models/kimi-k2-instruct-0905", name: "Configured Model" },
+        { id: "accounts/fireworks/models/kimi-k2-instruct-0905", name: "Kimi K2 Instruct" },
+        { id: "accounts/fireworks/models/glm-5p2", name: "GLM 5.2" },
+        { id: "accounts/fireworks/models/deepseek-v3p1", name: "DeepSeek V3.1" },
+      ]
+    });
+  }
+
   // Check Vertex AI (Google Cloud)
   if (config.vertex?.projectId) {
     const region = config.vertex.region || "us-east5";

package/src/api/router.js

@@ -7,7 +7,9 @@ const logger = require("../logger");
 const { createRateLimiter } = require("./middleware/rate-limiter");
 const openaiRouter = require("./openai-router");
 const providersRouter = require("./providers-handler");
+const claudeDesktopGatewayRouter = require("./claude-desktop-gateway");
 const { getRoutingHeaders, getRoutingStats, analyzeComplexity, getModelTierSelector, analyzeRisk, checkSessionPin, writeSessionPin, checkPinScoreDrift } = require("../routing");
+const { resolveTierForModelId } = require("../routing/model-slots");
 
 // Upstream streams can die without a clean end (reader.read() never
 // resolves on a dropped socket), hanging the client forever. Every
@@ -36,7 +38,7 @@ const { detectClient } = require("../routing/client-profiles");
 const { buildInteractionBlock } = require("../routing/interaction");
 const { validateCwd } = require("../workspace");
 const { renderText } = require("../utils/markdown-ansi");
-const { classifyAuthMode } = require("../auth-mode");
+const { classifyAuthMode, isFirstPartyAnthropicClient } = require("../auth-mode");
 
 const router = express.Router();
 
@@ -306,21 +308,16 @@ async function handleOauthPassthrough(req, res, opts = {}) {
   const upstream = process.env.LYNKR_OAUTH_PASSTHROUGH_URL
     || "https://api.anthropic.com/v1/messages";
 
-  // === Optional: memory injection at last-user-message tail ===
-  // Headroom's P0-1 pattern: append memory context to the latest user
-  // message's first text block. NEVER touches system prompt or frozen-prefix
-  // messages, so the cache-hot zone Anthropic fingerprints stays intact.
-  // Opt-in via LYNKR_OAUTH_MEMORY_INJECTION=true since any body mutation on
-  // a subscription request has nonzero anti-abuse risk.
+  // NO body mutation on the passthrough — deliberate policy (2026-09). The
+  // memory-injection option that lived here (LYNKR_OAUTH_MEMORY_INJECTION)
+  // was removed: this function's whole contract is byte-for-byte fidelity
+  // to what the first-party client sent, and any mutation of subscription
+  // traffic both breaks that claim and carries anti-abuse risk. Memory
+  // injection remains available on the orchestrator paths, where Lynkr is
+  // openly transforming requests. The only change made below is stripping
+  // Lynkr-internal underscore-prefixed fields, which Anthropic would reject
+  // as unknown keys — protocol necessity, not content mutation.
   let bodyToSend = req.body;
-  if (process.env.LYNKR_OAUTH_MEMORY_INJECTION === 'true' && config.memory?.enabled !== false) {
-    try {
-      bodyToSend = maybeInjectMemoryIntoUserTail(req.body);
-    } catch (err) {
-      logger.debug({ err: err.message }, "Memory injection skipped (non-fatal)");
-      bodyToSend = req.body;
-    }
-  }
 
   // === Observability: start ===
   const startedAt = Date.now();
@@ -390,8 +387,13 @@ async function handleOauthPassthrough(req, res, opts = {}) {
   // Lynkr's own decision headers so callers can see which model answered.
   res.set("X-Lynkr-Provider", "azure-anthropic-passthrough");
   if (opts.tier?.tier) res.set("X-Lynkr-Tier", opts.tier.tier);
-  if (req.body?.model) res.set("X-Lynkr-Model", req.body.model);
-  res.set("X-Lynkr-Routing-Method", "oauth-subscription-stealth");
+  if (req.body?.model) {
+    res.set("X-Lynkr-Model", req.body.model);
+    const { contextWindowFor } = require("../routing/model-registry");
+    const contextWindow = contextWindowFor(req.body.model);
+    if (contextWindow) res.set("X-Lynkr-Context-Window", String(contextWindow));
+  }
+  res.set("X-Lynkr-Routing-Method", "oauth-subscription-passthrough");
 
   // Capture the response (buffered or streamed) so we can do observability hooks
   // on the way back without changing what the client sees.
@@ -730,86 +732,8 @@ function extractAnthropicMessageFromSSE(sseText) {
   return result;
 }
 
-/**
- * Append relevant memories to the FIRST TEXT BLOCK of the LATEST USER MESSAGE.
- *
- * Headroom's P0-1 pattern (`_append_context_to_latest_non_frozen_user_turn`).
- * The cache hot zone (system + frozen prefix) is NEVER touched. Mutating only
- * the latest user message — which is the request's "live zone" — keeps the
- * prompt-cache identity stable and avoids Anthropic anti-abuse fingerprint
- * divergence for subscription tokens.
- *
- * Returns the body unchanged if:
- *   - Memory is disabled
- *   - No memories retrieved
- *   - Latest message is not a user turn (could be tool_result, assistant)
- *
- * Returns a new body with appended context otherwise. Original body never
- * mutated (returns a shallow-cloned messages array).
- */
-function maybeInjectMemoryIntoUserTail(body) {
-  if (!body || !Array.isArray(body.messages) || body.messages.length === 0) return body;
-
-  const lastIdx = body.messages.length - 1;
-  const lastMsg = body.messages[lastIdx];
-  if (!lastMsg || lastMsg.role !== "user") return body;
-
-  const { retrieveRelevantMemories, formatMemoriesForContext, extractQueryFromMessage } =
-    require("../memory/retriever");
-  const query = extractQueryFromMessage(lastMsg);
-  if (!query || query.length < 10) return body; // too short to be a useful query
-
-  const memories = retrieveRelevantMemories(query, {
-    limit: Math.min(parseInt(process.env.MEMORY_RETRIEVAL_LIMIT, 10) || 5, 10),
-    sessionId: body._sessionId || null,
-    includeGlobal: process.env.MEMORY_INCLUDE_GLOBAL !== "false",
-  });
-  if (!memories || memories.length === 0) return body;
-
-  const formatted = formatMemoriesForContext(memories);
-  if (!formatted) return body;
-
-  const contextText = `\n\n## Relevant context from earlier sessions:\n${formatted}`;
-
-  // Bound the injection size (Headroom uses a MemoryInjectionBudget; we use
-  // a simpler char cap — ~1024 tokens * 4 chars/token = 4096 chars).
-  const MAX_INJECTION_CHARS = 4096;
-  const boundedContext = contextText.length > MAX_INJECTION_CHARS
-    ? contextText.slice(0, MAX_INJECTION_CHARS) + "\n…"
-    : contextText;
-
-  // Clone messages array (shallow) so we don't mutate the caller's body.
-  const newMessages = body.messages.slice();
-
-  if (typeof lastMsg.content === "string") {
-    newMessages[lastIdx] = { ...lastMsg, content: lastMsg.content + boundedContext };
-  } else if (Array.isArray(lastMsg.content) && lastMsg.content.length > 0) {
-    // Append to the FIRST text block, preserving every other block (images,
-    // tool_use, etc.) untouched.
-    const newContent = [];
-    let appended = false;
-    for (const block of lastMsg.content) {
-      if (!appended && block && typeof block === "object" && block.type === "text") {
-        newContent.push({ ...block, text: (block.text || "") + boundedContext });
-        appended = true;
-      } else {
-        newContent.push(block);
-      }
-    }
-    if (!appended) return body; // no text block to append to
-    newMessages[lastIdx] = { ...lastMsg, content: newContent };
-  } else {
-    return body;
-  }
-
-  logger.debug({
-    memoryCount: memories.length,
-    appendedChars: boundedContext.length,
-  }, "Memory injected into last-user-message tail");
-
-  return { ...body, messages: newMessages };
-}
-
+// (maybeInjectMemoryIntoUserTail was removed with the passthrough
+// memory-injection option — the passthrough is byte-for-byte by contract.)
 /**
  * Estimate token count for messages.
  *
@@ -1092,7 +1016,7 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     //
     // All three paths now share window-scored intent tier picking
     // (`pickTierByIntent`). Subscription still has the additional
-    // azure-anthropic passthrough fork for anti-abuse stealth; everything
+    // azure-anthropic passthrough fork (first-party clients only); everything
     // else just falls through to the orchestrator with the picked tier
     // pinned via _forceProvider/_tierModel. The reason all paths share the
     // scorer is that determineProviderSmart's full-body analysis inflates
@@ -1117,6 +1041,37 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     // in a session skip the whole window-scored intent pipeline.
     let tier;
     const pinCheck = checkSessionPin(req.body);
+
+    // Explicit model-id pin: Claude Desktop's model picker (or any Anthropic-
+    // format caller) can name one of the fixed ids claude-desktop-gateway.js
+    // advertises (see ../routing/model-slots.js). Unlike every signal below,
+    // this one is EXPLICIT user intent, not an inference — it wins over
+    // session pins, side-request detection, and content scoring alike.
+    // "Lynkr Auto" (claude-fable-5) and any unrecognized id resolve to null
+    // and fall through to the existing cascade unchanged.
+    const modelPinTier = resolveTierForModelId(req.body?.model);
+    if (modelPinTier) {
+      const _sel = getModelTierSelector().selectModel(modelPinTier, null);
+      tier = {
+        tier: modelPinTier,
+        provider: _sel.provider,
+        model: _sel.model || null,
+        score: null,
+        method: 'model_id_pin',
+        reason: 'client_selected_model',
+        base_tier: null,
+        escalation_source: null,
+        pinned: false,
+        switch_reason: null,
+        propensity: 1.0,
+        candidates: [{ provider: _sel.provider, model: _sel.model || null }],
+      };
+      logger.debug({
+        model: req.body.model,
+        tier: modelPinTier,
+        provider: _sel.provider,
+      }, "[Routing] Explicit model-id pin — scoring bypassed");
+    } else {
     // Side-request detection. Claude Code fires internal background calls
     // (title generation, summarization, memory extraction, suggestion-mode
     // autocomplete) that REPLAY the conversation — so they share the
@@ -1343,11 +1298,13 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
         }, "OAuth intent — side request (no tools), pin write skipped");
       }
     }
+    } // end else — no explicit model-id pin, scored normally above
 
-    // Subscription-only fork: anti-abuse stealth passthrough when the picked
-    // tier resolves to azure-anthropic. Bypasses the orchestrator entirely
-    // so the inbound bytes hit api.anthropic.com unchanged (Anthropic
-    // fingerprints subscription clients; any mutation gets flagged).
+    // Subscription-only fork: byte-for-byte passthrough to api.anthropic.com
+    // when the picked tier resolves to azure-anthropic — FIRST-PARTY
+    // Anthropic clients only (Claude Code / Claude Desktop wrapping their
+    // own traffic; see auth-mode.js for the policy). Gated here at the
+    // dispatch point, not just in classification, so the two can't drift.
     // Passthrough forwards the CLIENT's credentials; GUI harnesses that
     // spawn claude headless inject placeholder keys ("dummy") that Anthropic
     // 401s. Placeholder auth ⇒ serve REASONING via the provider's own
@@ -1357,13 +1314,14 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     const _placeholderAuth =
       !_clientAuthHdr &&
       (['dummy', 'test', 'placeholder', 'none', 'x', 'sk-dummy'].includes(_clientApiKey) || _clientApiKey.length < 8);
+    const _firstParty = isFirstPartyAnthropicClient(req.headers);
     if (_placeholderAuth && authMode === 'subscription' && tier.provider === 'azure-anthropic') {
       logger.info({
         reqNumber: messagesRequestCount,
         xApiKeyShape: _clientApiKey.slice(0, 12),
       }, 'Placeholder client auth — skipping passthrough, serving REASONING via provider credentials');
     }
-    if (authMode === 'subscription' && tier.provider === 'azure-anthropic' && !_placeholderAuth) {
+    if (authMode === 'subscription' && tier.provider === 'azure-anthropic' && !_placeholderAuth && _firstParty) {
       logger.debug({
         reqNumber: messagesRequestCount,
         authMode,
@@ -2090,6 +2048,12 @@ router.get("/api/tokens/stats", (req, res) => {
   }
 });
 
+// Claude Desktop third-party gateway: intercepts GET /v1/models for
+// Anthropic-API clients (anthropic-version header) and advertises Lynkr's
+// tiers as Claude model families. Mounted BEFORE openaiRouter so the
+// intercept wins; non-Anthropic callers fall through unchanged.
+router.use("/v1", claudeDesktopGatewayRouter);
+
 // Mount OpenAI-compatible endpoints for Cursor IDE support
 router.use("/v1", openaiRouter);
 

package/src/auth-mode.js

@@ -47,15 +47,34 @@
  * @module auth-mode
  */
 
+// FIRST-PARTY Anthropic clients only (deliberate policy, 2026-09): the
+// subscription classification — and with it the api.anthropic.com
+// passthrough — is for Claude Code and Claude Desktop wrapping their OWN
+// traffic. Third-party harness prefixes (codex-cli/, cursor/,
+// github-copilot/, antigravity/) were removed: classifying them as
+// 'subscription' handed the passthrough to exactly the harness category
+// Anthropic's ToS enforcement targets. Those clients still work through
+// Lynkr — they classify by token shape ('oauth'/'payg') and route through
+// the orchestrator with the operator's configured providers.
+//
+// BREAKING CHANGE for anyone who had Cursor/Codex/Copilot riding the
+// subscription path: that traffic now routes via configured tiers.
+//
+// If Claude Desktop's own requests carry a UA not listed here (capture one
+// via the desktop gateway before assuming), add THAT — never a third-party
+// harness. This is a UA check: it defines intended use, not cryptographic
+// attestation.
 const SUBSCRIPTION_UA_PREFIXES = [
   'claude-cli/',
   'claude-code/',
-  'codex-cli/',
-  'cursor/',
   'claude-vscode/',
-  'github-copilot/',
   'anthropic-cli/',
-  'antigravity/',
+  // Claude Desktop (Electron app). Captured from a real gateway request:
+  // "Mozilla/5.0 (...) Claude/1.46388.1 Chrome/148... Electron/42..." —
+  // the app identifies as "Claude/<version>" inside a browser-style UA.
+  // Deliberately 'claude/' (with slash): no third-party harness UA carries
+  // that token, and the first-party ids above don't collide with it.
+  'claude/',
 ];
 
 /**
@@ -110,7 +129,24 @@ function classifyAuthMode(headers) {
   return 'payg';
 }
 
+/**
+ * Is this request from a first-party Anthropic client (Claude Code / Claude
+ * Desktop family)? Used as the explicit gate at the api.anthropic.com
+ * passthrough dispatch fork — the security decision lives at the point of
+ * dispatch, not only in classification, so the two can't silently drift
+ * apart. Same UA semantics as classifyAuthMode's subscription check.
+ *
+ * @param {object} headers
+ * @returns {boolean}
+ */
+function isFirstPartyAnthropicClient(headers) {
+  const ua = getHeader(headers, 'user-agent').toLowerCase();
+  if (!ua) return false;
+  return SUBSCRIPTION_UA_PREFIXES.some((prefix) => ua.includes(prefix));
+}
+
 module.exports = {
   classifyAuthMode,
+  isFirstPartyAnthropicClient,
   SUBSCRIPTION_UA_PREFIXES,
 };

package/src/budget/index.js

@@ -75,6 +75,12 @@ class BudgetManager {
         minute_window_start INTEGER,
         hour_window_start INTEGER
       );
+
+      CREATE TABLE IF NOT EXISTS token_rate (
+        user_id TEXT PRIMARY KEY,
+        tokens_minute INTEGER NOT NULL DEFAULT 0,
+        minute_window_start INTEGER NOT NULL
+      );
     `);
 
     this.stmts = {
@@ -114,6 +120,86 @@ class BudgetManager {
     };
   }
 
+  /**
+   * Token-aware (TPM) rate limiting (ROUTING-NOTES §1 gap: request-count
+   * only). Off unless LYNKR_TPM_LIMIT is set — same "off unless configured"
+   * convention as the loop guard.
+   *
+   * Estimate → true-up pattern (the one every serious gateway converged on):
+   * the pre-flight check gates on the window's ACTUAL consumption plus the
+   * current request's cheap estimate; real usage lands in the window
+   * post-response via recordTokenUsage(). Soft admission control, not a hard
+   * ceiling — concurrent in-flight requests can overshoot by roughly one
+   * request's worth, by design.
+   *
+   * @param {string} userId
+   * @param {number} estimatedTokens — cheap pre-flight estimate for THIS request
+   * @returns {{allowed: boolean, reason?: string, limit?: number, current?: number, resetInMs?: number}}
+   */
+  checkTokenRate(userId, estimatedTokens = 0) {
+    if (!this.enabled) return { allowed: true };
+    const limit = Number.parseInt(process.env.LYNKR_TPM_LIMIT, 10);
+    if (!limit || limit <= 0 || Number.isNaN(limit)) return { allowed: true };
+
+    const now = Date.now();
+    const minuteWindow = 60 * 1000;
+    const row = this.db.prepare('SELECT * FROM token_rate WHERE user_id = ?').get(userId);
+    let tokensMinute = row?.tokens_minute ?? 0;
+    let windowStart = row?.minute_window_start ?? now;
+    if (now - windowStart >= minuteWindow) {
+      tokensMinute = 0;
+      windowStart = now;
+      this.db.prepare(`
+        INSERT INTO token_rate (user_id, tokens_minute, minute_window_start)
+        VALUES (?, 0, ?)
+        ON CONFLICT(user_id) DO UPDATE SET tokens_minute = 0, minute_window_start = excluded.minute_window_start
+      `).run(userId, windowStart);
+    }
+
+    if (tokensMinute + estimatedTokens > limit) {
+      return {
+        allowed: false,
+        reason: 'token_rate_limit_minute',
+        limit,
+        current: tokensMinute,
+        estimated: estimatedTokens,
+        resetInMs: minuteWindow - (now - windowStart),
+      };
+    }
+    return { allowed: true };
+  }
+
+  /**
+   * True-up: add ACTUAL token consumption to the user's TPM window after the
+   * response completes. No-op when TPM limiting is disabled.
+   * @param {string} userId
+   * @param {number} totalTokens — actual input+output tokens consumed
+   */
+  recordTokenUsage(userId, totalTokens) {
+    if (!this.enabled || !totalTokens || totalTokens <= 0) return;
+    const limit = Number.parseInt(process.env.LYNKR_TPM_LIMIT, 10);
+    if (!limit || limit <= 0 || Number.isNaN(limit)) return;
+    const now = Date.now();
+    const minuteWindow = 60 * 1000;
+    try {
+      const row = this.db.prepare('SELECT * FROM token_rate WHERE user_id = ?').get(userId);
+      const stale = !row || now - row.minute_window_start >= minuteWindow;
+      this.db.prepare(`
+        INSERT INTO token_rate (user_id, tokens_minute, minute_window_start)
+        VALUES (@user_id, @tokens, @window_start)
+        ON CONFLICT(user_id) DO UPDATE SET
+          tokens_minute = ${stale ? '@tokens' : 'tokens_minute + @tokens'},
+          minute_window_start = @window_start
+      `).run({
+        user_id: userId,
+        tokens: totalTokens,
+        window_start: stale ? now : row.minute_window_start,
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Budget] token usage record failed');
+    }
+  }
+
   checkRateLimit(userId) {
     if (!this.enabled) return { allowed: true };